Documentation improvement suggestions
-
https://docs.colyseus.io/server/client/#sendtype-message
send(type, message)
I suggest not to call this "type" because "type" has a meaning in JavaScript/TypeScript (pun intended, proving my point). Maybe call it "messageId", similar to "roomId" or "clientId".
// // sending message with string type // client.send("powerup", { type: "ammo" }); // // sending message with number type // client.send(1, { type: "ammo"});
Regarding
{ type: "ammo" }
I suggest not to call this "type" because of the very same reason and because it currently can be mistaked for the "type" mentioned above. Maybe call it "poweruptype" or "category" or any other synonym for "type".class MyMessage extends Schema { @type("string") message: string; } const data = new MyMessage(); data.message = "Hello world!"; client.send(data);
Why does
client.send
have no "type" (in the sense of "messageId") as the first parameter?https://docs.colyseus.io/client/room/#onmessage
C# exampleclass PowerUpMessage { string type; } room.OnMessage<PowerUpMessage>("powerup", (message) => { Debug.Log ("message received from server"); Debug.Log(message); }); /** * Handling schema-encoded messages: */ room.OnMessage("powerup", (message) => { if (message is MyMessage) { Debug.Log ("MyMessage type has been received"); Debug.Log(message); } else if (message is AnotherMessage) { // ... } });
In both
room.OnMessage
functions there actually is a "type" (in the sense of "messageId") as first parameter.In general I am missing TypeScript examples in the client documentation. In the server documentation there are plenty of those.
This being said the whole documentation is quite good in my opinion. Nevertheless there are some details which could be clearer, for example those mentioned here.
-
Hi @teeteehaa, thanks for your suggestions. I think using
type
as a key for the message payload may have been confusing! I've replacedtype
withkind
in the docs, so the nomenclature does not collide. The message payload accepts anything really.Here's the PR with changes based on your suggestions https://github.com/colyseus/docs/pull/54, and here's the preview link:
- https://deploy-preview-54--colyseus-docs.netlify.app/server/client/#sendtype-message
- https://deploy-preview-54--colyseus-docs.netlify.app/client/room/#onmessage
I've removed the "schema-based" messages from the documentation, as it is also confusing, and it was introduced basically to improve the C# experience, and now we have other alternatives for C# users (https://github.com/colyseus/schema/pull/68)
Please let me know if you have any other suggestion, or anything to add! Cheers!
-
Thank you for your fast and positive response, @endel. I suggest the following additional changes to make the documentation fully consistent within in itself:
send(type, message)
I think this should be:
send(identifier, message)
Send message a type of message to the client.
I think this should be:
Send message withidentifier
and payloadmessage
to the client.The
type
can be either astring
or anumber
.
I think this should be:
Theidentifier
can be either astring
or anumber
.// sending message with string type
I think this should be:
// sending message with string identifier
Because it should be consistent with:
// sending message with number identifier
The green "Tip - See how to handle these messages on client-side." was removed. I'm not sure whether this was intentional. I think it should come back.