Multiplayer and data
Online play is optional. The design follows four principles:
- Sync only inside a zone (64 m cell) — do not send the whole map to everyone.
- Thin server, no full physics engine; the client predicts, the server validates.
- Runs without a server by default (single-player). Online is an optional module.
- No dependency on a specific service: the
transportandpersistencelayers are adapters.
Architecture
Client A ─┐
Client B ─┼── WebSocket ──► Gateway ──► Zone hub ──► Persistence
Client C ─┘ (auth) (interest) (Redis/PG/Supabase)
- Gateway: validates the token, rate-limits, attaches
playerId. - Zone hub: keeps the list of players per zone; each tick it filters by interest, then sends deltas.
- Persistence: stores only durable data (inventory, progress), not the position every frame.
Zone & interest management
Zone = 64 m (the same size as a render chunk — one concept, two uses).
import { zoneKey, neighborKeys, filterByInterest } from 'risejs-core';
zoneKey(70, 130); // "1,2"
neighborKeys(70, 130, 64, 1); // 9 zones: "0,1" … "2,3"
filterByInterest(players, 70, 130, 64, 1);
Send rules:
| Event | Sent to |
|---|---|
| Player enters a zone | Players in the 3×3 around that zone |
| Player leaves a zone | Players who could see it (send leave) |
| Position snapshot | Only subscribers of the current zone + neighbors |
| Chat | Current zone (or a global channel if you want) |
With 3×3 zones of 64 m, a player receives data for at most about 200 m × 200 m.
Protocol
Input, chat and events are JSON messages. Position snapshots are binary (src/shared/snapshot.js, shared by client and server):
Header: [type u8 = 1][self u16][tick u16][count u16] 7 bytes
Entity: [nid u16][x i16][y i16][z i16][yaw u8][seq u16] 11 bytes per player
Coordinates are quantized in 1 cm steps (±327 m).
Ticks
| Component | Rate | Notes |
|---|---|---|
| Server simulation | 20 Hz | 50 ms steps, enough for first-person movement |
| Snapshots | 20 Hz | 11 bytes per player |
| Client input | 20 Hz | {type:'input', seq, mx, mz, yaw} |
| Prediction | local | the client runs its own player and snaps to the server position when it drifts more than 0.75 m |
Remote players are created when they first appear in a snapshot and removed on leave. Players do not collide with each other.
Client API (net pack)
import { netPlugin } from 'risejs-core/packs/net';
app.use(netPlugin, {
url: 'wss://game.example',
room: 'city-01',
name: 'player',
token: '<token from POST /api/auth>',
map: 'arena', // optional: server-side collision map
});
// app.net is the NetClient. It connects after 'app:ready' and reconnects by itself.
app.events.on('net:status', (status) => {});
app.events.on('net:chat', (msg) => {});
app.events.on('net:hit', (msg) => {});
app.events.on('net:wallet', (msg) => {});
app.net.fire('rifle'); // the server keeps ammo/rpm and computes hits
app.net.reload('rifle');
app.net.loot('crate-17', 'crate'); // the server rolls; idempotent
The pack sends player input every tick and applies snapshots (remote players, corrections) by itself.
The pack is optional: a game that does not install it runs offline.
Server-authoritative combat & economy
| Task | Client does | Server does |
|---|---|---|
| Shooting | sends {type:'fire', weapon} |
WeaponState (ammo/rpm/reload) + resolveShot (range/angle/LOS) |
| Damage | does not send | picks by weapon id, broadcasts hit |
| Loot | sends crateId |
rolls seed player:crateId, writes the wallet, returns loot |
| Wallet | reads GET /api/wallet/:game/:player |
D1 ledger keyed by (game,player,key) |
The collision map uses a single source: src/games/<game>/map.js → the client builds the geometry (world.js) and the
server
loads it from the map=arena request parameter of the WebSocket URL (CollisionMap). npm run make:map exports public/maps/*.json.
// WebSocket request parameters sent to the server; an unknown map does not exist ⇒ blocks nothing (fail-open), no error
const ws = new WebSocket(`${base}/ws?room=arena&map=arena&x=0&z=8`);
Persistent data
Rise ships two storage paths: SaveSlot (localStorage, in the core) and the persistence pack (HTTP, against the example
server). For anything else, write an adapter with this shape:
export class Storage {
async load(gameId, playerId) {}
async save(gameId, playerId, patch) {}
}
| Backend | When to use | Notes |
|---|---|---|
localStorage (SaveSlot) |
default, single-player | synchronous, limited to ~5 MB |
HTTP (persistence pack or your own) |
game with its own backend | fetch + token, batch writes |
| Redis | realtime server, hot sessions | TTL, hash per player |
| Postgres | long-term data, queries | JSONB for state |
| Supabase | want realtime + auth out of the box | Realtime channel per zone |
| Firebase | similar, Google ecosystem | Firestore + presence |
Principle: do not write position to the DB. Write only when: changing zone, completing an objective, leaving the game.
Choosing a realtime backend
| Option | Pros | Cons |
|---|---|---|
Custom WebSocket (Node ws) + Redis pub/sub |
light, full control, no per-message cost, scales to multiple nodes | you handle scaling, auth, deploy |
| Managed realtime service | auth + DB + broadcast out of the box, quick to prototype | latency/message limits, hard to get an exact 20 Hz tick |
| Cloudflare Durable Objects | 1 object = 1 zone, scales automatically | locked in to Cloudflare |
The example server in the repository uses Durable Objects.
Reference deployment (optional, not a dependency)
server/ in the repository is a runnable example on Cloudflare, used for testing. It is not part of the npm package. The framework imports nothing from it:
if your game does not install the net pack (app.use(netPlugin, { url })) and you do not deploy server/, Rise still runs offline as before.
| Endpoint | Binding | Purpose |
|---|---|---|
GET /api/health |
— | Liveness check |
POST /api/admin/migrate |
D1 | Creates the saves, events tables (dev) |
GET/PUT /api/save/:game/:player |
D1 | Save/read state |
POST/GET /api/events |
D1 | Anti-cheat telemetry |
PUT/GET /api/blob/:key |
R2 | Replays, images, blobs |
GET /ws?room= |
Durable Object | Realtime per zone |
Run locally
npm run server # wrangler dev --local --port 8787
npm run server:test # protocol test: welcome / peers / zone / chat
On Windows, if D1/R2 return 500 with the default path (the path is too long), use
--persist-to C:\tmp\rise-state — the npm run server script already sets it.
Prediction and reconciliation
- Client at 20 Hz:
{type:'input', seq, mx, mz, yaw};mx/mzis the intended direction in world space. - The server simulates in 50 ms steps using
src/shared/sim.js(shared by client/server) and returns a 20 Hz snapshot{type:'snapshot', tick, self, players:[{id,x,z,yaw,seq,name,color}]}. - The client predicts with the real
Player(with collisions); when a snapshot arrives, it compares the server position with the position stored at thatseq. Drift > 0.75 m → snap to the server and countstats.corrections. - Server-side collision is optional: when the connection names a collision map, the server blocks movement through walls and checks
line of sight with
CollisionMap. Without a map the server does not simulate colliders; the client blocks itself near walls and any drift is fixed by the snap.
Auth, HTTP save, chat
POST /api/auth {player}returns an expiring tokenv1.<player>.<exp>.<sig>signed with HMAC-SHA256 (AUTH_SECRET). Enable checking with--var AUTH_REQUIRED:1; a missing/wrong token → 401.- Client:
app.use(persistencePlugin, { base, game, player })→app.remote.auth(),.read(),.write(),.event(). - Chat UI in the
netpack: T opens, Enter sends, Esc closes; keys are blocked from reaching the game while typing.
Limits: there is no token refresh endpoint; chat has no moderation beyond the word filter and rate limit; AUTH_REQUIRED defaults to 0 for development.
Per-zone shards (Durable Objects)
- Each zone is its own DO:
idFromName("<room>:<zx>:<zz>"). - The client connects with
zx, zz, x, z; the server simulates and sendsrezoneif the player leaves the zone → the client reconnects to the correct new zone by itself. - Every 200 ms, each DO pushes its player list to the 8 neighboring zones through a DO-to-DO
fetch(/internal/relay), cached with an 800 ms TTL. - Snapshot = local players + players from neighboring zones that are still fresh.
Redis or another pub/sub is not needed for this setup. If you deploy across several geographic regions, replace the relay with Redis Streams or Workers Queues.
Security and anti-cheat
What the example server does (details in anticheat):
- Tokens are signed and expire; the server verifies the signature and does not trust a player id sent by the client.
- Rate limits: 120 messages per second per session, 5 chat messages per 5 seconds.
- Moves faster than 9.5 m/s or longer than 6 m in one tick are rejected and rolled back; hits are computed by the server.
- Data outside the interest area is not sent, which limits wallhacks at the data level.
Lobby and chat
- Chat has 3 channels (
zone/all/dm):zoneis sent only within the 3×3 neighboring zones (adjacent). - Lobby:
POST /api/roomswritesroom:<name>to KV (TTL 60 s),GET /api/roomsreturns{ rooms, total, open }. Client:lobbypack, L opens it, Q quick match (pickRoom). - Client-side chat filtering:
maskWords(masks banned words),SpamGuard(blocks repeated messages),IgnoreList. - Server-side chat rate limit:
ChatGuard5 messages / 5 s / player.