@genex-ai/authority-dev
Run a Genex game's server-authoritative room module on your own machine, play it with bots at a real ping, and check it before you publish it.
npx genex-authority-dev start --module server/room.js --bots 3 --latency 75 --report
npx genex-authority-dev validate --module server/room.ts --out report.json
npx genex-authority-dev replay --module server/room.js
The module is the same file the Genex servers run (export default defineRoom({...}), see
@genex-ai/multiplayer/authority/module), bundled by the same function with the same pinned
esbuild, so its sha256 is the one the servers verify.
start
Serves the module on 127.0.0.1 only (any other --host is refused): the production room core in
a QuickJS-WASM sandbox, with the servers' limits scaled to QuickJS. There are no tokens: every join
is its own local player, every player (whatever game id it sends) meets the bots in one room, and a
browser page that is not served from this machine is refused.
Connect a game to the printed url (a page opened with ?genex_local_test=1&genex_authority_url=<url>
does it through @genex-ai/embed-sdk).
It serves the fast channel (fast@1, UDP) by default, on the production endpoint, on 127.0.0.1
only: a native client that asks for it plays locally on the transport players get. Behind --latency
the seats are told a datagram proxy, so one ping covers both channels. FAST says whether it is on and
where, and REPORT's fast line counts its seats (bound: those a datagram reached) and what it dropped.
If no UDP socket can be had on any free port the server still starts, on the WebSocket, and FAST says
bind_failed. A browser page gets the binding but no WebTransport relay here, so it stays on the WebSocket.
A local room lets its clients draw other players up to 250 ms behind, the most a server may allow, and
your module's config.interpolation: { maxDelayMs } (100 to 250) lowers that. A Genex server may run with
this setting off: there the same room keeps every client at the fixed 100 ms.
A local room sends its state after every K-th tick, never on a timer: as often as your module's
config.patchHz asks (10, 15, 20, 30, 60 or 120 a second), else what its genre says (the contact
policy's preset: 120 for vehicle-arena, 60 for the others), else 60, and never faster than it ticks.
The local server has no cap of its own. A Genex server may set one (AUTHORITY_PATCH_HZ_MAX), so the
same room can send less often there than it does here. As on a Genex server, a room takes this rate
only when the client whose join created it claims rate@1 (an SDK that draws correctly at any rate;
the bots do): a room opened by a game built on an older SDK patches 20 times a second, as it always
did, until the game is rebuilt on one that claims it.
| Option | Default | |
|---|---|---|
--module <file> | required | the room module (.js or .ts) |
--root <dir> | the module's folder | every file the bundle reads must be inside it |
--port <n> | 0 (any free port) | |
--bots <n> | 0 | bots that join, wander, aim at the nearest player and fire |
--bot-match-key <key> | none (the game's one pool) | the pool the bots join, as a client's matchKey: a test client that asks for the same key shares their room |
--latency <ms> / --jitter <ms> | 0 | one-way delay added by a proxy in front of the server; the fast channel's datagrams pay it too |
--stable-identity | off | a join's embed token names its player, as an account does on the servers: the same token is the same uid and seat (a newer session supersedes), across rooms and restarts, so a returning player can be tested. No token: a fresh guest. The embed SDK's local:test placeholder is one token, so pages using it are one player |
--no-fast | channel on | the off switch: the server offers no fast channel, so every seat is on the WebSocket |
--fast-port <n> | 0 (any free port) | the fast channel's UDP port. A named port that is taken is listen_failed, as a taken --port is |
--report / --report-every <ms> | off / 1000 | print REPORT lines |
--duration <s> | until SIGINT/SIGTERM | |
--physics-backend <auto|native|wasm> | auto | the physics core a physics module's rooms run on, as a server's GENEX_PHYSICS_BACKEND: native a process per room (Linux x64, macOS arm64; refused if its checks fail), wasm a WebAssembly instance per room, auto native where it passes, else WebAssembly |
--stop-on-stdin-close | off | stop with a final REPORT when stdin closes: on Windows a parent's kill() ends the process on the spot, so this is the one way a parent can stop it cleanly |
stdout carries one protocol line per event; messages for people go to stderr:
LISTEN ws://127.0.0.1:<port>
FAST {"state":"on","url":"udp://127.0.0.1:<port>"} | {"state":"off","reason","detail"}
REPORT {"rooms","players","maxPlayers","perRoom":[{"id","seats","players","bots"}],"tick":{"p50Ms","p99Ms","maxMs","budgetMs"},"budgetBreaches","strikes","faults","lastFault","hostStalls":{"kept","ended"},"corrections":{"reconciles","visible","peak"},"physics":{"backend","buildId","cpuMeanMs","cpuMaxMs","strikes"}|null,"fast":{"state","url","seats","bound","received","accepted","sent","dropped"}|{"state","reason"},...}
LOG {"room","line"}
ERROR {"reason","detail"}
maxPlayers is the seats a room of this module holds (its own maxPlayers within the protocol's
cap, as on the servers), known from the load before listening. A full room opens another for the next
join: perRoom lists each running room by id (a session's code) with its seats, its players and
how many of them are bots, so a split is visible. rooms and players are the totals across rooms.
ERROR reasons: a validate reason when the module cannot bundle or load, listen_failed (exit 1),
usage or not_loopback (exit 2). A module that asks for physics runs on @genex-ai/physics, the
WebAssembly core this package depends on at its pinned version. That core needs Node 24, so this
package does too. @genex-ai/physics-native is not on npm: without it auto runs WebAssembly (one
line on stderr says why) and --physics-backend native answers physics_unavailable.
validate
Bundles the module, fuzzes it for 30 simulated seconds with random and adversarial players
(joins, leaves, input floods, hostile values, a full room), checks invariants after every tick,
holds the p99 of the CPU each tick's module call is charged to the local CPU budget (a world's steps apart:
world_cost warns of those by a count every machine agrees on, a warning to you and no protection for a host,
which its own CPU limits give), judges a physics room's physics by the servers' meter (a breach is module_fault
with code physics_budget, and physicsTick in the report says what it read), and replays the run twice to prove
it is deterministic.
Exit 0 = passed. --out writes the report (passed, moduleSha256, typed failures) that a
publish uploads with the module. Failure reasons: build_failed, outside_root, too_large,
unavailable_global, global_object, load_failed, module_ended, module_fault,
nondeterministic, tick_budget, world_cost, shot_world_cost, shot_world_missing, orphan_entity, log_flood, short_run, and host_stall
(a sandbox with a wall-clock backstop cut a call off while the module's CPU stayed under its limit:
no verdict on the module, run it again; the local QuickJS sandbox stops calls on CPU alone and never
reports it).
replay
Prints REPLAY {"hash","repeatHash","equal",...}: the module's state hash over the same fuzz run
validate plays, computed twice. Equal hashes mean the module is deterministic.
For a physics module it also prints its physics CPU a tick (physicsCpu: mean and max, ms) on this
machine. That is information, never a verdict: the replay meters nothing, and a server scales its
physics bound by its own host factor.