GitHub Documentation

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# example

    class 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.


  • administrator

    Hi @teeteehaa, thanks for your suggestions. I think using type as a key for the message payload may have been confusing! I've replaced type with kind 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:

    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 with identifier and payload message to the client.

    The type can be either a string or a number.
    I think this should be:
    The identifier can be either a string or a number.

    // 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.


 

© 2021 Lucid Sight, Inc