Skip to main content
A template is a saved SpawnRequest — a name plus the same fields you’d pass to /spawn (mesh, color, health, team, collider, physics body, …) — that /template/spawn replays to create entities. A prefab is the static cousin: a blueprint registered in the scene layer’s PrefabRegistry, instantiated by name. Both live behind a registry resource on the world. The mental model that matters most here: a bare headless host does not register them — so this page shows you both the working loop and the exact silent no-op you get without them. Every command is real and runnable against a local server; the outputs below are captured from one.

​
Define a template and spawn from it

1. Create a template. Post a name plus any spawn fields. The handler runs and reports success:
2. List the templates — and watch the trap spring. On a bare headless host the list is empty, even though step 1 returned ok:true:
The template was never stored. /template/create only inserts into the registry if one exists (if let Some(registry) = w.resource_mut::<TemplateRegistry>()), and a bare headless host never registers it. The ok:true means “the handler ran,” not “the template landed.” 3. Spawn from it. With nothing stored, the spawn reports the template missing — and entity_count on GET / does not move:
On a host that registers a TemplateRegistry (the editor and the full game hosts do), the same three commands close the loop: template/list returns {"count":1,"templates":["red-cube"]}, and each template/spawn returns a fresh {"ok":true,"entity_id":N,"template":"red-cube"} — one new entity per call from the stored blueprint, with the optional position overriding placement.

​
Prefabs work the same way

Prefabs read from euca_scene::PrefabRegistry. On a bare headless host it’s absent, so listing is empty and spawning fails — but, unlike templates, the call shape is honest about it:
A host that populates the PrefabRegistry makes /prefab/list enumerate its names and /prefab/spawn return {"ok":true,"entity_id":9,"entity_generation":0,"name":"tower"}.

​
Behavior and gotchas

The things you only find out by running it:
  • ok:true from /template/create does not mean stored. Without a TemplateRegistry resource the insert is silently dropped and the handler still reports success. Trust /template/list, not the create response — an empty list after a create means no registry is installed.
  • Templates and prefabs differ in failure honesty. template/create returns ok:true even when it no-ops; prefab/spawn returns ok:false with a clear “not found in registry”. Same root cause (missing registry), opposite-looking responses.
  • The create body must parse as a SpawnRequest. A missing name returns {"ok":false,"error":"Template name required"}; a body that fails to deserialize returns {"ok":false,"error":"Invalid template: …"}. The whole body (minus name) is stored and replayed.
  • /template/spawn takes a position override. The stored blueprint’s position is replaced by the [x, y, z] you pass, so one template seeds many entities at different spots.
  • No /step needed. Templates and prefabs build entities synchronously on the call; the new entity shows up in entity_count immediately, with no tick in between.

​
Endpoints

For the spawn fields a template stores, see the quickstart; for the rule-driven spawning these compose with, see rules.

​
Status

  • Shipped — the template store/replay logic, the SpawnRequest field set, and prefab instantiation from the scene registry. All headless.
  • Host-dependent — the registries themselves. A bare headless host registers neither TemplateRegistry nor PrefabRegistry, so on it /template/spawn and /prefab/spawn report “not found” and /template/create is a silent no-op. A host that registers the registry (the editor, full game hosts) makes the create→list→spawn loop work end to end.

Template & prefab endpoints

Every template and prefab endpoint, with request and response schemas.