Realtime protocol

The Phase 0 realtime service runs authoritative rooms at 60 ticks per second and broadcasts validated snapshots at 20 updates per second.

Local use

corepack pnpm dev:stack

Open http://127.0.0.1:5173/?network=1. The service listens on ws://127.0.0.1:8787/rooms; its health endpoint is http://127.0.0.1:8787/healthz.

Session sequence

connect
  -> join(protocolVersion, roomId, physics, optional resumeToken)
  <- welcome(connectionId, playerEntityId, resumeToken, seed, physics, snapshot)
  -> input(sequence, horizontal, optional vertical, jump, optional dash/interact/attack/choice)
  <- snapshot(acknowledgedInput, authoritative world)
  <- presence(accepted visible friends only)
  -> social(fixed phrase or emote)
  <- social_event(server event id, fixed content, recipient-bound report evidence)

Input sequences are positive and strictly increasing. The room acknowledges an input only after consuming it during an authoritative simulation tick. The browser restores the server snapshot, removes acknowledged inputs, and replays the remaining prediction buffer.

If the socket closes, the server holds the player slot for a short grace period. The client reconnects with its opaque resume token and retransmits inputs the server has not acknowledged.

Protocol v23 includes the physics adapter identifier/version, four-direction and advanced-controller input, interaction choices, Attack intent, authoritative scene identity, controller/interaction/quest/combat/equipment/round state, and bounded player-attributed events such as portal, scene transition, checkpoint, respawn, dialogue, inventory, equipment, loot, crafting, projectile spawn, damage, death, team score, and round phase. It also gates clients that understand bounded HUD, explicit persistent-save project data, friends-only named Nexus presence, predefined social actions, and presentation-only Audio Source play/stop and named effect events. Audio events carry an entity ID and fixed action—not a URL or creator payload. Scene, loot, crafting, equipment, team, spawn, round, and save outcomes are server-selected; the browser cannot supply them. Persistence travels only over private service boundaries. The client refuses to predict with a different protocol or adapter. Set PIXELRIFTS_PHYSICS=rapier on the server and use /?network=1&physics=rapier in the browser to test the Rapier path.

Social safety

• Guests and accounts with private presence remain unnamed.
• Only accepted, unblocked friends can receive a handle mapping or fixed phrase/emote.
• There is no arbitrary text, attachment, voice, creator payload, or browser-selected sender identity.
• Realtime rate-limits actions and issues recipient-bound, ten-minute report evidence for the exact fixed event.
• The player UI provides persistent mute, account block, fixed-category report, and explicit leave controls.

Trust boundary

• Clients send input intentions, never positions, scores, rewards, hits, health, projectiles, AI targets, or entity destruction.
• The server validates protocol messages and input ranges.
• The authoritative room owns world simulation and creator capability effects.
• RiftScript has shared instruction and command fuel per tick plus fixed stack and memory ceilings. Source recursion and loop syntax fail compilation; forged bytecode cycles halt at the runtime meter.
• An unexpected simulation failure quarantines only the affected room. Other rooms and the realtime health service continue running.
• Binary messages and oversized payloads are rejected.
• Resume tokens are temporary in-memory Phase 0 credentials, not production account sessions.

Latency testing

Set PIXELRIFTS_SIMULATED_LATENCY_MS on the realtime process to delay outbound messages by up to 2,000 ms. Automated tests verify a deterministic minimum delay and reconnect continuity.