Versioning

PaindaProtocol is designed to evolve. To prevent horrible desync bugs when clients and servers run different versions, the protocol enforces strict version checks at the handshake and frame levels.

1. Wire Protocol Versioning

Every binary frame sent over the network includes a 2-byte Version Header. If an old client connects to a new server (or vice versa) and the major wire protocol versions don't match, the connection is instantly rejected with a clear error.

// Client attempts to connect
client.on("disconnect", (reason) => {
  if (reason.includes("Invalid Protocol Version")) {
    console.error("Please refresh your browser. We pushed an update!");
  }
});

2. Application Schema Versioning

Even if the wire protocol matches, your own game's packet schema might change (e.g., adding a "Z" axis to player movement). PaindaProtocol's PPSchemaRegistry supports built-in versioning for your custom payloads.

When registering a schema, the second augment is the version.

// Server-side (Game v2)
registry.register("player_move", 2, structSerializer([
  { name: "x", type: "float32" },
  { name: "y", type: "float32" },
  { name: "z", type: "float32" }, // NEW FIELD
]));

// When an old v1 client sends a "player_move" frame, 
// the server detects the ID/Version mismatch and discards or downgrades it safely,
// rather than reading out-of-bounds memory.

3. Dealing with Breaking Changes

Best practices for deploying updates to a live PaindaProtocol app:

• Soft Updates: Add new optional fields to your JSON payloads. Older clients ignore them.
• Hard Schema Updates: Bump the version number in registry.register("name", VERSION, ...). Old payloads will be ignored.
• Force Refresh: You can use a generic "version_check" event on connection to tell old clients to call location.reload(true).