euca-studio --headless): it runs the
project’s full game logic, but has no GPU and registers only the engine-level resources — anything a
subsystem needs beyond that (a script VM, a template registry, an input action map, an audio device, a
GPU) must come from the project’s game or the host. Here are the common ones, each verified against a
running server.
”I set the camera / a material, but nothing renders”
The camera pose is plain CPU state, so the headless host serves it:GET /camera returns the pose and
POST /camera / view / focus mutate it. What’s missing is the GPU edge — there is no renderer, so
POST /material/set returns ok but draws nothing, and /screenshot returns 503 (no ScreenshotChannel).
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 noTemplateRegistry, 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”
NoActionMap 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 — noScriptEngine resource. Fix: register a ScriptEngine
— see Scripting (Lua).
”Audio calls succeed but I hear nothing”
Audio needs an OS audio device (Kira); the headless host 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 withobserve rather than counting event reads.
”POST returns ‘missing Content-Type’ or a parse error”
All POSTs requireContent-Type: application/json. Empty-body POSTs should send {}.
Configuration
Ports, limits, and what the headless host registers.