# Euca Engine

> The agent-native game engine — an ECS-first engine in Rust where agents build, play, and experiment through one typed API, on a deterministic world they can read, change, fork, and replay exactly.

## Docs

- [attach an animation state machine to an entity](https://docs.eucaengine.com/api-reference/animation/attach-an-animation-state-machine-to-an-entity.md): attach an animation state machine to an entity
- [list loaded animation clips](https://docs.eucaengine.com/api-reference/animation/list-loaded-animation-clips.md): list loaded animation clips
- [load a glTF file with animations](https://docs.eucaengine.com/api-reference/animation/load-a-gltf-file-with-animations.md): load a glTF file with animations
- [play a blended montage on an entity](https://docs.eucaengine.com/api-reference/animation/play-a-blended-montage-on-an-entity.md): play a blended montage on an entity
- [start animation on an entity](https://docs.eucaengine.com/api-reference/animation/start-animation-on-an-entity.md): start animation on an entity
- [stop animation on an entity](https://docs.eucaengine.com/api-reference/animation/stop-animation-on-an-entity.md): stop animation on an entity
- [define a new assertion](https://docs.eucaengine.com/api-reference/assertions-&-manifest/define-a-new-assertion.md): The `condition` accepts either a shorthand string (`"entity-exists"`, `"entity-count"`, `"game-phase"`, `"field-check"`, …) with sibling parameters (`filter`, `min`, `max`, `phase`, `field`, `op`, `value`), or a full structured `AssertCondition` JSON object. `severity` is one of `"error"`, `"warning…
- [get last evaluation results without re-evaluating](https://docs.eucaengine.com/api-reference/assertions-&-manifest/get-last-evaluation-results-without-re-evaluating.md): get last evaluation results without re-evaluating
- [list all registered assertions](https://docs.eucaengine.com/api-reference/assertions-&-manifest/list-all-registered-assertions.md): list all registered assertions
- [read the manifest with assertion evaluation inlined](https://docs.eucaengine.com/api-reference/assertions-&-manifest/read-the-manifest-with-assertion-evaluation-inlined.md): read the manifest with assertion evaluation inlined
- [remove an assertion](https://docs.eucaengine.com/api-reference/assertions-&-manifest/remove-an-assertion.md): remove an assertion
- [run all assertions and return results](https://docs.eucaengine.com/api-reference/assertions-&-manifest/run-all-assertions-and-return-results.md): run all assertions and return results
- [set or update the game manifest](https://docs.eucaengine.com/api-reference/assertions-&-manifest/set-or-update-the-game-manifest.md): set or update the game manifest
- [update a single feature's status](https://docs.eucaengine.com/api-reference/assertions-&-manifest/update-a-single-features-status.md): update a single feature's status
- [check the status of a generation task](https://docs.eucaengine.com/api-reference/assets/check-the-status-of-a-generation-task.md): Polls the provider for updated status. Runs on a blocking thread because `service.update()` calls `provider.poll()` which uses `reqwest::blocking`.
- [list all generation tasks](https://docs.eucaengine.com/api-reference/assets/list-all-generation-tasks.md): Read-only — no provider I/O, safe to run on tokio thread. Still uses spawn_blocking for ensure_service consistency.
- [list available AI generation providers](https://docs.eucaengine.com/api-reference/assets/list-available-ai-generation-providers.md): list available AI generation providers.
- [start a new AI 3D generation task](https://docs.eucaengine.com/api-reference/assets/start-a-new-ai-3d-generation-task.md): Runs on a blocking thread because `service.start()` may call `provider.generate()` which uses `reqwest::blocking`.
- [list active audio sources](https://docs.eucaengine.com/api-reference/audio/list-active-audio-sources.md): list active audio sources
- [load and play a sound file](https://docs.eucaengine.com/api-reference/audio/load-and-play-a-sound-file.md): load and play a sound file
- [stop an audio source by entity ID](https://docs.eucaengine.com/api-reference/audio/stop-an-audio-source-by-entity-id.md): stop an audio source by entity ID
- [check current session (hosted deployments only)](https://docs.eucaengine.com/api-reference/auth/check-current-session-hosted-deployments-only.md): Optional and used only by hosted deployments that enable authentication; the local self-hosted server is unauthenticated and requires no login. Reports whether the `Authorization: Bearer <token>` header carries a valid session.
- [optional session login (hosted deployments only)](https://docs.eucaengine.com/api-reference/auth/optional-session-login-hosted-deployments-only.md): Optional and used only by hosted deployments that enable authentication. The local self-hosted server is unauthenticated and requires no login. Exchanges a login payload for a session token.
- [apply a named quality preset](https://docs.eucaengine.com/api-reference/camera-&-render/apply-a-named-quality-preset.md): apply a named quality preset
- [apply a named view preset (top, front, right, etc.)](https://docs.eucaengine.com/api-reference/camera-&-render/apply-a-named-view-preset-top-front-right-etc.md): apply a named view preset (top, front, right, etc.)
- [capture 3D viewport as PNG](https://docs.eucaengine.com/api-reference/camera-&-render/capture-3d-viewport-as-png.md): capture 3D viewport as PNG
- [focus camera on a specific entity](https://docs.eucaengine.com/api-reference/camera-&-render/focus-camera-on-a-specific-entity.md): focus camera on a specific entity
- [get current camera state](https://docs.eucaengine.com/api-reference/camera-&-render/get-current-camera-state.md): get current camera state
- [get current post-processing settings](https://docs.eucaengine.com/api-reference/camera-&-render/get-current-post-processing-settings.md): get current post-processing settings
- [get current volumetric fog settings](https://docs.eucaengine.com/api-reference/camera-&-render/get-current-volumetric-fog-settings.md): get current volumetric fog settings
- [set camera position and target](https://docs.eucaengine.com/api-reference/camera-&-render/set-camera-position-and-target.md): set camera position and target
- [set material properties on an entity](https://docs.eucaengine.com/api-reference/camera-&-render/set-material-properties-on-an-entity.md): set material properties on an entity
- [update post-processing settings](https://docs.eucaengine.com/api-reference/camera-&-render/update-post-processing-settings.md): update post-processing settings
- [update volumetric fog settings](https://docs.eucaengine.com/api-reference/camera-&-render/update-volumetric-fog-settings.md): update volumetric fog settings
- [legacy component/endpoint summary](https://docs.eucaengine.com/api-reference/discovery-&-ops/legacy-componentendpoint-summary.md): Returns a legacy, hand-maintained summary of component types and endpoints. It is superseded by this OpenAPI document, which is the authoritative reference for the API surface.
- [report GPU backend and capability information](https://docs.eucaengine.com/api-reference/discovery-&-ops/report-gpu-backend-and-capability-information.md): report GPU backend and capability information.
- [return frame timing breakdown](https://docs.eucaengine.com/api-reference/discovery-&-ops/return-frame-timing-breakdown.md): return frame timing breakdown
- [scan all entities and report problems](https://docs.eucaengine.com/api-reference/discovery-&-ops/scan-all-entities-and-report-problems.md): scan all entities and report problems
- [show networking state](https://docs.eucaengine.com/api-reference/discovery-&-ops/show-networking-state.md): show networking state
- [show pending events this frame](https://docs.eucaengine.com/api-reference/discovery-&-ops/show-pending-events-this-frame.md): show pending events this frame
- [advance the fork and evaluate assertions in a single atomic call](https://docs.eucaengine.com/api-reference/forks/advance-the-fork-and-evaluate-assertions-in-a-single-atomic-call.md): advance the fork and evaluate assertions in a single atomic call. Mirrors the shape of `/probe` but operates on the named fork instead of the main world.
- [advance the fork by N ticks](https://docs.eucaengine.com/api-reference/forks/advance-the-fork-by-n-ticks.md): advance the fork by N ticks.
- [create a new fork by deep-cloning the main world](https://docs.eucaengine.com/api-reference/forks/create-a-new-fork-by-deep-cloning-the-main-world.md): create a new fork by deep-cloning the main world.
- [drop a fork](https://docs.eucaengine.com/api-reference/forks/drop-a-fork.md): drop a fork.
- [list all active fork ids](https://docs.eucaengine.com/api-reference/forks/list-all-active-fork-ids.md): list all active fork ids.
- [read the fork's entities](https://docs.eucaengine.com/api-reference/forks/read-the-forks-entities.md): read the fork's entities. Mirrors `/observe` but scoped to the named fork.
- [activate an ability on an entity](https://docs.eucaengine.com/api-reference/gameplay/activate-an-ability-on-an-entity.md): activate an ability on an entity
- [apply damage to an entity](https://docs.eucaengine.com/api-reference/gameplay/apply-damage-to-an-entity.md): apply damage to an entity
- [create a match with config](https://docs.eucaengine.com/api-reference/gameplay/create-a-match-with-config.md): create a match with config
- [create a trigger zone entity](https://docs.eucaengine.com/api-reference/gameplay/create-a-trigger-zone-entity.md): create a trigger zone entity
- [get match state and scores](https://docs.eucaengine.com/api-reference/gameplay/get-match-state-and-scores.md): get match state and scores
- [heal an entity](https://docs.eucaengine.com/api-reference/gameplay/heal-an-entity.md): heal an entity
- [list entity's abilities, cooldowns, mana](https://docs.eucaengine.com/api-reference/gameplay/list-entitys-abilities-cooldowns-mana.md): list entity's abilities, cooldowns, mana
- [set AI behavior on an entity](https://docs.eucaengine.com/api-reference/gameplay/set-ai-behavior-on-an-entity.md): set AI behavior on an entity
- [spawn a projectile](https://docs.eucaengine.com/api-reference/gameplay/spawn-a-projectile.md): spawn a projectile
- [apply a hero template to an existing entity](https://docs.eucaengine.com/api-reference/heroes/apply-a-hero-template-to-an-existing-entity.md): Request body: `{ "entity_id": 0, "hero_name": "Dragon Knight" }`
- [list all available heroes from the HeroRegistry](https://docs.eucaengine.com/api-reference/heroes/list-all-available-heroes-from-the-heroregistry.md): list all available heroes from the HeroRegistry.
- [register a hero definition in the HeroRegistry](https://docs.eucaengine.com/api-reference/heroes/register-a-hero-definition-in-the-heroregistry.md): If the registry resource doesn't exist yet, creates it. If a hero with the same name already exists, overwrites it.
- [bind a key to an action](https://docs.eucaengine.com/api-reference/input/bind-a-key-to-an-action.md): bind a key to an action
- [list all key bindings](https://docs.eucaengine.com/api-reference/input/list-all-key-bindings.md): list all key bindings
- [pop the top input context](https://docs.eucaengine.com/api-reference/input/pop-the-top-input-context.md): pop the top input context
- [push an input context](https://docs.eucaengine.com/api-reference/input/push-an-input-context.md): push an input context
- [remove a key binding](https://docs.eucaengine.com/api-reference/input/remove-a-key-binding.md): remove a key binding
- [API reference](https://docs.eucaengine.com/api-reference/introduction.md): The typed HTTP API for the agent-native game engine — JSON over HTTP on localhost:3917.
- [add items to an entity's inventory](https://docs.eucaengine.com/api-reference/inventory-&-economy/add-items-to-an-entitys-inventory.md): add items to an entity's inventory
- [buy an item (or combine via recipe) for an entity](https://docs.eucaengine.com/api-reference/inventory-&-economy/buy-an-item-or-combine-via-recipe-for-an-entity.md): buy an item (or combine via recipe) for an entity.
- [equip an item from inventory into a named slot](https://docs.eucaengine.com/api-reference/inventory-&-economy/equip-an-item-from-inventory-into-a-named-slot.md): equip an item from inventory into a named slot
- [list all items from the ItemRegistry with their costs](https://docs.eucaengine.com/api-reference/inventory-&-economy/list-all-items-from-the-itemregistry-with-their-costs.md): list all items from the ItemRegistry with their costs.
- [list entity's inventory and equipment](https://docs.eucaengine.com/api-reference/inventory-&-economy/list-entitys-inventory-and-equipment.md): list entity's inventory and equipment
- [register a new item definition](https://docs.eucaengine.com/api-reference/inventory-&-economy/register-a-new-item-definition.md): register a new item definition
- [sell an item from inventory for 50% gold](https://docs.eucaengine.com/api-reference/inventory-&-economy/sell-an-item-from-inventory-for-50%-gold.md): sell an item from inventory for 50% gold.
- [build navmesh from scene colliders](https://docs.eucaengine.com/api-reference/navigation/build-navmesh-from-scene-colliders.md): build navmesh from scene colliders
- [compute A* path between two points](https://docs.eucaengine.com/api-reference/navigation/compute-a*-path-between-two-points.md): compute A* path between two points
- [set pathfinding goal on an entity](https://docs.eucaengine.com/api-reference/navigation/set-pathfinding-goal-on-an-entity.md): set pathfinding goal on an entity
- [create a particle emitter entity](https://docs.eucaengine.com/api-reference/particles/create-a-particle-emitter-entity.md): create a particle emitter entity
- [deactivate a particle emitter](https://docs.eucaengine.com/api-reference/particles/deactivate-a-particle-emitter.md): deactivate a particle emitter
- [list active particle emitters](https://docs.eucaengine.com/api-reference/particles/list-active-particle-emitters.md): list active particle emitters
- [create a game rule](https://docs.eucaengine.com/api-reference/rules/create-a-game-rule.md): create a game rule
- [list all rules](https://docs.eucaengine.com/api-reference/rules/list-all-rules.md): list all rules. Phase 5b cutover: reads the unified [`euca_gameplay::RuleSet`] instead of querying for legacy rule components. Each entry's `id` is the rule's index in the RuleSet (the same id rule_create returned); `type` is inferred from the rule's Condition shape via the same legacy-style tags th…
- [apply a scenario to a fork](https://docs.eucaengine.com/api-reference/scenes-&-scenarios/apply-a-scenario-to-a-fork.md): apply a scenario to a fork. Wipes the fork's current state and loads the scenario fresh; the main world is untouched.
- [apply a scenario to the main world](https://docs.eucaengine.com/api-reference/scenes-&-scenarios/apply-a-scenario-to-the-main-world.md): apply a scenario to the main world. Wipes the current main world and loads the scenario fresh.
- [export the current main world as a scenario JSON](https://docs.eucaengine.com/api-reference/scenes-&-scenarios/export-the-current-main-world-as-a-scenario-json.md): export the current main world as a scenario JSON.
- [load a level definition from a JSON file](https://docs.eucaengine.com/api-reference/scenes-&-scenarios/load-a-level-definition-from-a-json-file.md): load a level definition from a JSON file.
- [load scene from JSON file](https://docs.eucaengine.com/api-reference/scenes-&-scenarios/load-scene-from-json-file.md): load scene from JSON file
- [save current world state as JSON](https://docs.eucaengine.com/api-reference/scenes-&-scenarios/save-current-world-state-as-json.md): save current world state as JSON
- [save current world state to a level JSON file](https://docs.eucaengine.com/api-reference/scenes-&-scenarios/save-current-world-state-to-a-level-json-file.md): save current world state to a level JSON file.
- [attach a Lua script to an entity](https://docs.eucaengine.com/api-reference/scripting/attach-a-lua-script-to-an-entity.md): attach a Lua script to an entity
- [list entities with scripts attached](https://docs.eucaengine.com/api-reference/scripting/list-entities-with-scripts-attached.md): list entities with scripts attached
- [advance simulation](https://docs.eucaengine.com/api-reference/simulation/advance-simulation.md): advance simulation
- [pause simulation](https://docs.eucaengine.com/api-reference/simulation/pause-simulation.md): pause simulation
- [start simulation](https://docs.eucaengine.com/api-reference/simulation/start-simulation.md): start simulation
- [advance simulation and evaluate assertions](https://docs.eucaengine.com/api-reference/snapshots-&-probes/advance-simulation-and-evaluate-assertions.md): Body: {   "ticks": 300,              // how many ticks to advance (0 = evaluate at current state)   "assertions": ["hero-alive", "towers-attack"],  // optional: only evaluate named assertions   "snapshot_before": true,   // optional: capture a snapshot before advancing   "snapshot_after": true,    /…
- [capture a labeled snapshot](https://docs.eucaengine.com/api-reference/snapshots-&-probes/capture-a-labeled-snapshot.md): capture a labeled snapshot
- [compare two snapshots](https://docs.eucaengine.com/api-reference/snapshots-&-probes/compare-two-snapshots.md): compare two snapshots
- [get the most recent snapshot with full summary](https://docs.eucaengine.com/api-reference/snapshots-&-probes/get-the-most-recent-snapshot-with-full-summary.md): get the most recent snapshot with full summary
- [list all snapshots (labels only)](https://docs.eucaengine.com/api-reference/snapshots-&-probes/list-all-snapshots-labels-only.md): list all snapshots (labels only)
- [apply a status effect to an entity](https://docs.eucaengine.com/api-reference/status-effects/apply-a-status-effect-to-an-entity.md): apply a status effect to an entity
- [list active status effects on an entity](https://docs.eucaengine.com/api-reference/status-effects/list-active-status-effects-on-an-entity.md): list active status effects on an entity
- [remove effects matching a tag filter](https://docs.eucaengine.com/api-reference/status-effects/remove-effects-matching-a-tag-filter.md): remove effects matching a tag filter
- [define a named entity template](https://docs.eucaengine.com/api-reference/templates-&-prefabs/define-a-named-entity-template.md): define a named entity template
- [instantiate a template at a position](https://docs.eucaengine.com/api-reference/templates-&-prefabs/instantiate-a-template-at-a-position.md): instantiate a template at a position
- [list all defined templates](https://docs.eucaengine.com/api-reference/templates-&-prefabs/list-all-defined-templates.md): list all defined templates
- [list registered prefabs](https://docs.eucaengine.com/api-reference/templates-&-prefabs/list-registered-prefabs.md): list registered prefabs
- [spawn a named prefab at a position](https://docs.eucaengine.com/api-reference/templates-&-prefabs/spawn-a-named-prefab-at-a-position.md): spawn a named prefab at a position
- [create a flat heightmap terrain](https://docs.eucaengine.com/api-reference/terrain-&-foliage/create-a-flat-heightmap-terrain.md): create a flat heightmap terrain
- [list scattered foliage layers](https://docs.eucaengine.com/api-reference/terrain-&-foliage/list-scattered-foliage-layers.md): list scattered foliage layers
- [raise/lower/flatten/smooth at a position](https://docs.eucaengine.com/api-reference/terrain-&-foliage/raiselowerflattensmooth-at-a-position.md): raise/lower/flatten/smooth at a position
- [scatter instanced foliage across an area](https://docs.eucaengine.com/api-reference/terrain-&-foliage/scatter-instanced-foliage-across-an-area.md): scatter instanced foliage across an area
- [add a bar to HUD](https://docs.eucaengine.com/api-reference/ui-&-hud/add-a-bar-to-hud.md): add a bar to HUD
- [add text to HUD](https://docs.eucaengine.com/api-reference/ui-&-hud/add-text-to-hud.md): add text to HUD
- [list current HUD elements](https://docs.eucaengine.com/api-reference/ui-&-hud/list-current-hud-elements.md): list current HUD elements
- [remove all HUD elements](https://docs.eucaengine.com/api-reference/ui-&-hud/remove-all-hud-elements.md): remove all HUD elements
- [add or remove tags on an entity](https://docs.eucaengine.com/api-reference/world/add-or-remove-tags-on-an-entity.md): Body: `{ "entity_id": 5, "add": ["stealth"], "remove": ["revealed"] }`
- [add/update components on an entity](https://docs.eucaengine.com/api-reference/world/addupdate-components-on-an-entity.md): add/update components on an entity
- [create entity with optional components](https://docs.eucaengine.com/api-reference/world/create-entity-with-optional-components.md): create entity with optional components
- [engine status](https://docs.eucaengine.com/api-reference/world/engine-status.md): engine status
- [get high-level game state summary (no snapshot required)](https://docs.eucaengine.com/api-reference/world/get-high-level-game-state-summary-no-snapshot-required.md): get high-level game state summary (no snapshot required)
- [query full world state, optionally filtered by viewer visibility](https://docs.eucaengine.com/api-reference/world/query-full-world-state-optionally-filtered-by-viewer-visibility.md): query full world state, optionally filtered by viewer visibility.
- [query single entity](https://docs.eucaengine.com/api-reference/world/query-single-entity.md): query single entity
- [remove an entity](https://docs.eucaengine.com/api-reference/world/remove-an-entity.md): remove an entity
- [reset the world (preserves Persistent entities like ground/lights)](https://docs.eucaengine.com/api-reference/world/reset-the-world-preserves-persistent-entities-like-groundlights.md): reset the world (preserves Persistent entities like ground/lights)
- [set visibility rules on an observer entity](https://docs.eucaengine.com/api-reference/world/set-visibility-rules-on-an-observer-entity.md): Body: `{ "entity_id": 5, "rules": ["within:8", "same-team"] }`
- [Engine capabilities](https://docs.eucaengine.com/concepts/capabilities.md): Everything the engine exposes through the one typed API — the build / play / experiment surface, in full.
- [Determinism & replay](https://docs.eucaengine.com/concepts/determinism.md): One canonical seeded RNG drives the whole engine, so the same seed and inputs reproduce the same run — byte for byte.
- [Engine internals](https://docs.eucaengine.com/concepts/engine-internals.md): What's under the hood — the archetype ECS, the real-time PBR renderer, and the custom physics solver. An honest map of what's implemented.
- [Forks & counterfactuals](https://docs.eucaengine.com/concepts/forks.md): Fork the live world, intervene on the copy, diff the outcome against the original, and drop it — what-ifs that never touch the real run.
- [Networking](https://docs.eucaengine.com/concepts/networking.md): Euca's networking library — server-authoritative snapshot/delta replication with client-side prediction. A library, not yet wired into a shipping game.
- [Performance](https://docs.eucaengine.com/concepts/performance.md): Real, measured benchmark numbers from the repo — the parallel-ECS throughput, physics tick cost, and how to reproduce them.
- [Rules as data](https://docs.eucaengine.com/concepts/rules-as-data.md): A rule is an inspectable, serializable value — when X, do Y — not a compiled callback. You can list it, diff it, edit it mid-run, and ship it in a scenario.
- [The euca CLI](https://docs.eucaengine.com/concepts/the-cli.md): Drive the engine from a shell — the euca CLI maps 1:1 to the HTTP API, and is self-describing so an agent can learn the surface at runtime.
- [The world as a table](https://docs.eucaengine.com/concepts/world-as-table.md): Euca's world is a flat table: each row is an entity, each column a typed component. An agent reads and edits it as plain data — no object graph, no GUI.
- [World-model evaluation](https://docs.eucaengine.com/evaluation/overview.md): Use Euca as an exact answer key to grade external world models — prequential regret, in nats, against the engine's true next-step distribution.
- [Build a scene](https://docs.eucaengine.com/guides/build-a-scene.md): Assemble a world by spawning entities with typed components, step it so transforms settle, and read the assembled scene back.
- [Data-driven rules](https://docs.eucaengine.com/guides/data-driven-rules.md): Add rules to a running world, list them, change them mid-run, and ship them in a scenario — game logic as inspectable data, not compiled code.
- [Deterministic replay](https://docs.eucaengine.com/guides/deterministic-replay.md): Export a world as a scenario document and rebuild it exactly — the data-level half of Euca's byte-for-byte determinism.
- [Fork for what-ifs](https://docs.eucaengine.com/guides/fork-for-what-ifs.md): Answer a what-if question by forking the world, running the scenario on the copy, and reading the answer off the fork — without disturbing the real run.
- [Snapshots & diffs](https://docs.eucaengine.com/guides/snapshots.md): Capture labeled snapshots of a run and diff two of them to read off exactly what changed between two moments.
- [The agent-native game engine](https://docs.eucaengine.com/index.md): An ECS-first engine in Rust where agents build, play, and experiment through one typed API — on a deterministic world they can read, change, fork, and replay exactly.
- [Quickstart](https://docs.eucaengine.com/quickstart.md): Bring up a local server and run the full agent loop — build a world, play it, and experiment on it — in a few minutes.

## OpenAPI Specs

- [openapi](https://docs.eucaengine.com/openapi.json)