Trouble Decoding Schema in C++

[Nika0000]

Hi,

I’m working on decoding Colyseus schema (CPP) and wanted to verify the meaning of a specific structure received from a patch.

Here is the original schema that I decode from the full message:

{
  something: "This attribute won't be sent to the client-side",
  score: 50,
  players: {
    "RuihdGARE": {
      x: 7,
      y: 341,
      name: "player name"
    },
    "hktXKo-i3": {
      x: 369,
      y: 138,
      name: "player name"
    }
  }
}

Full Schema Hex Decoding:

0e                                      // Protocol

80 d9 2f                                // Field index 0x80 (0): str8, 0x2f (47 bytes)
   5468697...65                         // "This attribute won't be sent to the client-side"
81 32                                   // Field index 0x81 (1): uint8, score = 50
82 01                                   // Field index 0x82 (2): value = 1 (e.g., "players" presence flag or count)
ff 01                                   // SWITCH_TO_STRUCTURE (1 entry in map)
  80 00                                 // Field index 0x80 = 0 (possibly structure marker / unused value)
  a9 527569686447415245                 // FixStr (9 bytes): "RuihdGARE" → player ID
02                                      // marker/separator between map key and structure
ff 03                                   // SWITCH_TO_STRUCTURE (3 fields in nested structure)
  80 07                                 // index 0x80 = x = 7
  81 cd 0155                            // index 0x81 = y = uint16 = 0x0155 = 341
  82 ab 706c61796572206e616d65          // index 0x82 = string (str, 11 bytes) = "player name"

Later, I received this Patch fragment:

0f                                     // Protocol

ff 01                                  // SWITCH_TO_STRUCTURE (1 entry in map)
  80 01                                // Field index 0x80 = 1 (possibly structure marker / unused value)
  a9 686b74584b6f2d6933                // FixStr (9 bytes): "hktXKo-i3" → player ID
03                                     // Marker/separator (could be structure/field boundary)
ff 03                                  // SWITCH_TO_STRUCTURE (3 fields in nested structure)
  80 cd 7101                           // Field index 0x80 = x = uint16 = 0x0171 = 369
  81 cc 8a                             // Field index 0x81 = y = uint8 = 0x8a = 138
  82 ab 706c61796572206e616d65         // Field index 0x82 = string (11 bytes) = "player name"

I’m assuming this patch is updating the players map (adding or updating a new player structure), but I’d like to confirm:

• Is the 0x82 field in the full schema definitively how players is indicated?
• Is this fragment structure the correct way to detect and parse a MapSchema<Player> from a patch?

Thanks in advance!

[endel]

Hi @Nika0000 👋 I'm happy to see you're interested in making the C++ schema decoder compatible with latest version.

I highly suggest taking a look at the C# implementation for reference: https://github.com/colyseus/colyseus-unity-sdk/blob/master/Assets/Colyseus/Runtime/Colyseus/Serializer/Schema/Decoder.cs

This latest version extracts the decode callbacks from Schema structures themselves.

The 0x82 means an ADD operation (128) at index 2 of the structure.

• Here's how it is encoded
• See all operations

The binary protocol is not formally documented yet. Feel free to reach out to me personally on Discord or email if you have any other questions about the internals of decoding schema structures. I'd love to see the C++ SDK come to life!