@genex-ai/authority-dev

中文文档
0.1.8发布于 2026/11/15MITES Module近 30 天下载 2098

Local server-authoritative room server for Genex games: runs a game's room module on 127.0.0.1 with bots and an impaired link, and validates a module before it is published.

原始使用文档
文档目录3 节
  1. start
  2. validate
  3. replay

@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.

OptionDefault
--module <file>requiredthe room module (.js or .ts)
--root <dir>the module's folderevery file the bundle reads must be inside it
--port <n>0 (any free port)
--bots <n>0bots 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>0one-way delay added by a proxy in front of the server; the fast channel's datagrams pay it too
--stable-identityoffa 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-fastchannel onthe 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 / 1000print REPORT lines
--duration <s>until SIGINT/SIGTERM
--physics-backend <auto|native|wasm>autothe 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-closeoffstop 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.

版本与发布记录

@genex-ai/authority-dev 共发布 10 个版本,首次发布于 2026/11/06;过去 12 个月发布了 10 个版本。

版本发布日期距今
0.1.8latest2026/11/15今天
0.1.72026/11/105 天前
0.1.62026/11/105 天前
0.1.52026/11/097 天前
0.1.42026/11/087 天前
0.1.32026/11/087 天前

关于 @genex-ai/authority-dev 的常见问题

@genex-ai/authority-dev 是什么?

Local server-authoritative room server for Genex games: runs a game's room module on 127.0.0.1 with bots and an impaired link, and validates a module before it is published.

如何安装 @genex-ai/authority-dev?

在项目目录运行 npm install @genex-ai/authority-dev,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 genex-authority-dev,可以用 npx genex-authority-dev 直接运行。

@genex-ai/authority-dev 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/genex-ai__authority-dev 是否存在。

@genex-ai/authority-dev 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@genex-ai/authority-dev 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=24。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@genex-ai/authority-dev 可以商用吗?

@genex-ai/authority-dev 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@genex-ai/authority-dev 的下载量有多少?

根据 npm 官方下载统计,@genex-ai/authority-dev 在 2026/10/16 – 2026/11/14 这 30 天内被下载 2,098 次,日均约 70 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@genex-ai/authority-dev 还在维护吗?

最新版本 0.1.8 发布于 2026/11/15(今天);至今共发布 10 个版本,其中过去 12 个月发布了 10 个;首次发布于 2026/11/06。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。