Datasets & ground-truth channels

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. This page reads what’s visible over the local server, 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. Reset (a fresh server holds one component-less bootstrap entity), build a small typed world, and read it:

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:

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. 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:

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:

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 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.

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.

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.

Evaluation

How exact state + the answer key become a model score.

Get started

Core concepts

Build a world

Simulate & play

Render & present

Experiment & verify

Platform & tools

Datasets & ground-truth channels

Read the machine-readable state

The state digest — replay and eval

Ground-truth modalities

Aligned bundles

Endpoints

Status

Evaluation

​Read the machine-readable state

​The state digest — replay and eval

​Ground-truth modalities

​Aligned bundles

​Endpoints

​Status

Evaluation

Read the machine-readable state

The state digest — replay and eval

Ground-truth modalities

Aligned bundles

Endpoints

Status