Migrating to version 0.14 (from 0.13)¶
As a result from colyseus/schema#75 - the Colyseus version 0.14
introduces a few breaking changes on the usage of MapSchema
, and schema callbacks on the client-side, as both the Schema encoder and decoder have been reworked.
New feature @filterChildren()
, and better @filter()
support! Read more about how filters work here.
Upgrading the server:
Upgrading the client:
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
Use .assign({})
instead of constructor()
¶
If you're sharing your concrete schema implementation with the client-side and have the constructor()
implemented, some error may happen because the decoder is not going to provide any arguments during initialization of that structure.
With the addition of the .assign({})
method, it is recommended to use it instead of providing arguments to constructor()
for setting initial data in your structures:
MapSchema
breaking changes¶
MapSchema
used to be treated as a plain JavaScript object ({}
). Now, it uses the built-in Map
internally.
By using the built-in Map
, issues regarding the order of map keys are gone (#51 and #70).
There are a few breaking changes, which you should fix in your project, though.
Iterating through all items¶
Previous version:
New version:
Alternatively, you may iterate through the map's keys, or values alone, by using the iterators map.keys()
or map.values()
.
Getting the total number of items¶
Previous version:
New version:
Getting the keys of a MapSchema¶
Previous version:
New version:
Getting and setting on MapSchema
¶
This is not a breaking change! You can still use the bracket accessors to get and set values on MapSchema
. It is recommended to use the new Map
-like methods instead, though.
Previous version:
// get with bracket accessor
// (the type of "entry" here is "any")
const entry = yourMap["key"];
// set with bracket accessor
yourMap["key"] = "value";
New version:
// get with .get() method
// (the type of "entry" matches the type definition)
const entry = yourMap.get("key");
// set with .set() method
yourMap.set("key", "value");
Client-side: Schema callbacks¶
TLDR: Double-check all your onChange
callbacks in the client-side. You may need to add more onChange
callbacks for children structures.
onChange
on Schema references¶
Previous version: Whenever a change happens on deeper children, the field of the parent container is triggered as a change.
// Server-side
state.player.position.x = 10;
// Client-side
state.player.onChange = function(changes) {
changes[0].field // "position" is here!
}
New version: Now, changes are not propagated to parent Schema instances anymore. If you need to listen for a change on player.position
(and .position
is of type of Schema
), you need to attach a onChange
callback to the .position
instance as well.
// Server-side
state.player.position.x = 10;
// Client-side
state.player.position.onChange = function(changes) {
changes[0].field // "x" is here!
}
onChange
on collections (ArraySchema, MapSchema, etc.)¶
Similarly as on the previous example, onChange
is not triggered anymore if the children of the collection is an Schema instance. onChange
is only triggered for primitive values.
Previous version:
state.arrayOfSchemas.onChange = function(value, key) {
console.log(value, "has changed at", key);
}
state.arrayOfPrimitives.onChange = function(value, key) {
console.log(value, "has changed at", key);
}
New version:
state.arrayOfSchemas.onAdd = function(value, key) {
value.onChange = function(changes) {
console.log("List of changes", changes);
}
}
state.arrayOfSchemas.onChange = function(value, key) {
// you can remove this callback, as it is never going to be called.
}
state.arrayOfPrimitives.onChange = function(value, key) {
// here remains the same for primitive values (string, number, boolean)
console.log(value, "has changed at", key);
}