> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eucaengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Datasets & ground-truth channels

> Read the machine-readable world state over HTTP, understand the state digest that backs replay and eval, and learn which ground-truth channels are render/dataset-extraction features rather than bare HTTP routes.

`euca-dataset` is the **data face** of the engine: it extracts the world's exact state as structured,
canonical data, hashes it for reproducibility, and — through the render path — emits aligned
ground-truth channels. Because the truth is read from the authoritative CPU state, generated appearance
never changes it, which is what lets Euca double as a world-model [answer key](/evaluation/overview).
This page reads what's visible over the [local server](/quickstart), then explains the offline pieces
that aren't HTTP routes — with the boundary drawn honestly. Every command is real and runnable, with
output captured from one server.

## Read the machine-readable state

`POST /observe` returns the full world as a flat table of entities and their typed components — the
structured form behind the [`observe` verb](/concepts/query-verbs). Reset (a fresh server holds one
component-less bootstrap entity), build a small typed world, and read it:

```bash theme={null}
curl -s -X POST http://localhost:3917/reset
# {"ok":true,"message":"Reset: despawned 1 entities. Tick: 0"}

curl -s -X POST http://localhost:3917/spawn -H 'Content-Type: application/json' \
  -d '{"position":[3,1,0],"health":600,"team":1,"role":"hero"}'
curl -s -X POST http://localhost:3917/spawn -H 'Content-Type: application/json' \
  -d '{"position":[-3,1,0],"health":300,"team":2,"role":"minion"}'
curl -s -X POST http://localhost:3917/step -H 'Content-Type: application/json' -d '{"ticks":1}'

curl -s -X POST http://localhost:3917/observe
# {"tick":1,"entity_count":2,"entities":[
#   {"id":0,"generation":1,"transform":{"position":[3.0,1.0,0.0], ...},"health":[600.0,600.0],"team":1,"role":"Hero"},
#   {"id":1,"generation":0,"transform":{"position":[-3.0,1.0,0.0], ...},"health":[300.0,300.0],"team":2,"role":"Minion"}]}
```

Every value is exact and typed — positions, `[current, max]` health, team, role — not a rendered
approximation. For a higher-level rollup, `GET /game/summary` aggregates the same state by team, role,
and phase without a snapshot:

```bash theme={null}
curl -s http://localhost:3917/game/summary
# {"ok":true,"entity_count":2,"summary":{
#   "entity_counts_by_role":{"Hero":1,"Minion":1},"game_phase":"none","match_time":0.0,"total_dead":0,
#   "teams":[{"team":1,"entity_count":1,"heroes_alive":1,"towers_alive":0,"score":0},
#            {"team":2,"entity_count":1,"heroes_alive":0,"towers_alive":0,"score":0}]},
#  "assertions":[]}
```

## The state digest — replay and eval

The reproducibility oracle is the **state digest**: a 64-bit FNV-1a hash over the observable state in a
canonical ordering (entities by id, components by name, fields in declaration order). **Equal digests ⇔
equal observable state** — so two AI-generated visual skins of the same world produce a byte-identical
digest, and a replay is verified by digest equality rather than pixel comparison. This is the mechanism
behind [Determinism](/concepts/determinism).

The digest is computed in-process from the `WorldStateGraph` (`euca-dataset`'s object-centric
`state_t`); it is **not** a bare HTTP route on the local server:

```bash theme={null}
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3917/state_digest
# 404
```

What the HTTP server *does* expose for replay-style handoffs is labeled snapshots and structural diffs.
Capture a snapshot, advance, capture another, and diff them:

```bash theme={null}
curl -s -X POST http://localhost:3917/snapshot -H 'Content-Type: application/json' -d '{"label":"before"}'
# {"ok":true,"snapshot":{"label":"before","entity_count":2,
#   "summary":{"entity_counts_by_role":{"Hero":1,"Minion":1},"game_phase":"none", ...}, ...}}
curl -s -X POST http://localhost:3917/step -H 'Content-Type: application/json' -d '{"ticks":5}'
curl -s -X POST http://localhost:3917/snapshot -H 'Content-Type: application/json' -d '{"label":"after"}'

curl -s "http://localhost:3917/snapshot/diff?from=before&to=after"
# {"ok":true,"from":"before","to":"after","entity_delta":0,"from_entities":2,"to_entities":2,
#  "phase_changed":false,"role_changes":[],"assertion_changes":[]}
```

Snapshots summarize state (counts, roles, phase, assertion verdicts); the byte-exact digest lives in the
in-process dataset path described next.

## Ground-truth modalities

When rendered, the [render path](/systems/camera-and-rendering) emits aligned ground-truth channels into
`euca-dataset` — not the color image, but exact labels:

* **Shipped** — **Entity-id segmentation** — a per-pixel entity index (`index + 1`; `0` = background),
  so a pixel maps deterministically to an `entity_id`.
* **Shipped** — **Metric depth** — a per-pixel depth in world units.

These are a **render/dataset-extraction** feature, produced by the GPU render path into the dataset
crate — **not** something the bare headless HTTP server exposes as a route. The broader spatial suite —
semantic segmentation, surface normals, camera pose, optical flow, multi-camera — is the Tier-1 build
target and is **not** all present yet; don't assume the full modality set.

## Aligned bundles

The offline data face exports a deterministic rollout as **aligned layers** — video plus object / field
/ graph / causal projections, actions, and counterfactuals — each example addressable by
`(episode_id | stream_id, tick, entity_id)`, with deterministic tick↔frame and pixel→entity mappings.
The structured projection, causal projection, counterfactual harness, action logging, and
Parquet/manifest export are in place; the full GT modality suite and a few adapters are still being
built.

<Note>
  Bundle extraction and the digest are primarily an **offline / in-process** capability (see the
  `world_model_capabilities` and experiment examples in the repo), not plain `:3917` HTTP routes. Over
  HTTP you read the live structured state (`/observe`, `/game/summary`) and snapshot/diff; the digest
  and aligned bundles are produced from `euca-dataset` in-process. The **online** path — a live world an
  agent learns against step by step — is covered in [Evaluation](/evaluation/overview).
</Note>

## Endpoints

| Method | Path             | Description                                                                    |
| ------ | ---------------- | ------------------------------------------------------------------------------ |
| `POST` | `/observe`       | Full machine-readable world state (all entities, all components, current tick) |
| `GET`  | `/game/summary`  | Live rollup by team, role, and phase — no snapshot needed                      |
| `POST` | `/snapshot`      | Capture a labeled snapshot (counts, roles, phase, assertion verdicts)          |
| `GET`  | `/snapshot/diff` | Structural diff between two snapshots (`?from=&to=`)                           |

The byte-exact `state_digest` and aligned-bundle export are in-process `euca-dataset` APIs, not HTTP
routes.

## Status

* **Shipped** — `WorldStateGraph`, canonical JSON, `state_digest` (FNV-1a), entity-id segmentation +
  metric depth channels, aligned-bundle export (object/causal projection, counterfactuals, actions,
  Parquet/manifest). HTTP exposes `/observe`, `/game/summary`, and snapshot/diff.
* **Partial** — the full spatial GT suite (normals, semantic-seg, camera pose, optical flow,
  multi-camera) and some scoring adapters are in progress. The digest and bundles are in-process, not
  HTTP routes.

<Card title="Evaluation" icon="flask" href="/evaluation/overview" horizontal>
  How exact state + the answer key become a model score.
</Card>