Skip to content

Migrating to version 0.13.x (from 0.12.x)

Version 0.13.x introduces major breaking changes on:

Please install the latest version of the server, as well as the client:

Upgrading the server:

npm install colyseus@^0.13.0 --save

Upgrading the client:

npm install colyseus.js@^0.13.0 --save

If you're using Unity or other client, please check on its respective repository on GitHub. If you have questions feel free to ask on Discord

onMessage() has been reworked

On all previous versions of Colyseus, you would need to manually detect the type of message being sent by your own particular rules.

Server-side

// 0.12.x (old)

class MyRoom extends Room {
  onMessage(client, message) {
    //
    // handle message
    //
  }
}

With the rework of onMessage(), you can trigger a specific callback based on a message type sent by the client.

The first argument can be either a string or a number. (See full onMessage docs here)

// 0.13.x (new)

class MyRoom extends Room {
  onCreate(options) {
    this.onMessage("message_type_1", (client, message) => {
      //
      // handle 'message_type_1' here
      //
    });

    this.onMessage("message_type_2", (client, message) => {
      //
      // handle 'message_type_2' here
      //
    });

  }
}

this.broadcast(message) is now this.broadcast(type, message)

As every message now needs a type, the this.broadcast() method has been changed, too:

// 0.12.x (old)
this.broadcast({ foo: { bar: "baz" } });

// 0.13.x (new)
this.broadcast("foo", { bar: "baz" });

this.send(client, message) is now client.send(type, message)

The this.send() method has been deprecated. As every message now needs a type, you can now use client.send(type, message):

// 0.12.x (old)
this.send(client, { foo: { bar: "baz" } });

// 0.13.x (new)
client.send("foo", { bar: "baz" });

Client-side

// 0.12.x (old)
room.send({ type: "xxx", anything: "your data" });

// 0.13.x (new)
room.send("xxx", { anything: "your data" });
// 0.12.x (old)
room.Send(new { type = "xxx", anything = "your data" });

// 0.13.x (new)
room.Send("xxx", new { anything = "your data" });
-- 0.12.x
room:send({ type = "xxx", anything = "your data" })

-- 0.13.x
room:send("xxx", { anything = "your data" })
// 0.12.x (old)
room.send({ type: "xxx", anything: "your data" });

// 0.13.x (new)
room.send("xxx", { anything: "your data" });
// 0.12.x (old)
room.send({{"type", "xxx"}, {"anything", "your data"}});

// 0.13.x (new)
room.send("xxx", {{"anything", "your data"}});

onError() and matchmaking errors

Matchmaking errors now include error code.

The matchmaking errors now include an error code.

// 0.12.x (old)
try {
  const room = await client.joinOrCreate("battle");

} catch (e) {
  console.log("Error message:", e);
}
// 0.13.x (new)
try {
  const room = await client.joinOrCreate("battle");

} catch (e) {
  console.log("Error code:", e.code);
  console.log("Error message:", e.message);
}

onError() now has code and message.

The onError() callback in the client-side now has a code and message available, instead of just a message.

// 0.12.x (old)
room.onError((message) => {
  console.log("oops, error ocurred:");
  console.log(message);
});

// 0.13.x (new)
room.onError((code, message) => {
  console.log("oops, error ocurred:");
  console.log(message);
});
// 0.12.x (old)
room.OnError += (message) => {
  Debug.Log ("oops, error ocurred:");
  Debug.Log(message);
}

// 0.13.x (new)
room.OnError += (code, message) => {
  Debug.Log ("oops, error ocurred:");
  Debug.Log(message);
}
-- 0.12.x
room:on("error", function(message)
  print("oops, error ocurred:")
  print(message)
end)

-- 0.13.x
room:on("error", function(code, message)
  print("oops, error ocurred:")
  print(message)
end)
// 0.12.x (old)
room.onError += function(message) {
  trace("oops, error ocurred:");
  trace(message);
};

// 0.13.x (new)
room.onError += function(code, message) {
  trace("oops, error ocurred:");
  trace(message);
};
// 0.12.x (old)
room.onError = [=] (std::string message) => void {
  std::cout << "oops, error ocurred: " << message << std::endl;
};

// 0.13.x (new)
room.onError = [=] (int code, std::string message) => void {
  std::cout << "oops, error ocurred: " << message << std::endl;
};