Troubleshooting

Most surprises come from the reference headless_server being a minimal world: it runs the simulation, gameplay, and rules, but doesn’t register every subsystem’s resource, and it has no GPU. Here are the common ones, each verified against a running server.

​

”I set the camera / a material, but nothing renders”

The headless server has no renderer or camera. GET /camera returns {"error":"No camera"}, and POST /camera / POST /material/set return ok but draw nothing. Fix: run on a GPU/render host — see Camera & rendering. GET /engine/gpu returns an error in headless mode by design.

​

”/template/create returns ok but /template/spawn says ‘not found’”

The default server registers no TemplateRegistry, and the create handler only stores if let Some(registry). So create no-ops (still returns ok) and the template never exists. Fix: register a TemplateRegistry/PrefabRegistry on your server build — see Templates & prefabs.

​

”/input/bind does nothing and /input/list is empty”

No ActionMap is registered by default, so bind silently no-ops. The context stack (/input/context/*) does work. Fix: register an ActionMap — see Input.

​

”/script/load returns ‘No ScriptEngine resource in world’”

Lua isn’t enabled on the default server — no ScriptEngine resource. Fix: register a ScriptEngine — see Scripting (Lua).

​

”Audio calls succeed but I hear nothing”

Audio needs an OS audio device (Kira); the headless example doesn’t run one. The route logic is headless, but playback is client-side — see Audio.

​

”Entity positions read [0,0,0] right after spawning”

GlobalTransform propagates on /step. Fix: POST /step once after spawning before reading positions. A velocity also only integrates if the entity has a physics_body.

​

”Save → load didn’t restore my world exactly”

/scene/save + /scene/load (and the scenario world→spawn extraction) restore only position, scale, health, team — they drop velocity, rotation, and gameplay state. Fix: for exact reproducibility use snapshots and the state_digest; use scene/level files for authoring/layout. See Scenes & levels.

​

”An injected event seems to apply on two consecutive steps”

Events are double-buffered; an event injected over HTTP can be read on the tick it’s sent and the next before the buffer swaps. Within a single tick each event is applied once. Step deterministically and read state with observe rather than counting event reads.

​

”POST returns ‘missing Content-Type’ or a parse error”

All POSTs require Content-Type: application/json. Empty-body POSTs should send {}.