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

# Fork for what-ifs

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

A fork lets an agent ask *"what would happen if…"* and get an exact answer, because the
[same systems run on the fork](/concepts/forks) as on the main world. This guide walks a
complete what-if end to end.

<Note>
  Start a local server first — see the [Quickstart](/quickstart). All commands target
  `http://localhost:3917` and every `POST` sends `Content-Type: application/json`.
</Note>

## The question

We have a mover on team 1 heading along +x and we want to know: **will it pass `x = 3`
within 200 ticks — without advancing the real run?**

## 1. Set up the world

```bash theme={null}
# A Kinematic mover at the origin, 1 unit/s along +x.
curl -s -X POST http://localhost:3917/spawn \
  -H 'Content-Type: application/json' \
  -d '{"position":[0,1,0],"velocity":{"linear":[1,0,0]},"physics_body":"Kinematic","health":100,"team":1}'
# { "entity_id": 1, "entity_generation": 0 }

# Advance the real run a little so "now" is a non-trivial tick.
curl -s -X POST http://localhost:3917/step \
  -H 'Content-Type: application/json' -d '{"ticks":30}'
# { "ticks_advanced": 30, "new_tick": 30, "entity_count": 2 }
```

## 2. Fork the present

```bash theme={null}
curl -s -X POST http://localhost:3917/fork \
  -H 'Content-Type: application/json' -d '{"fork_id":"reach-x3"}'
# { "ok": true, "fork_id": "reach-x3", "parent_tick": 30 }
```

The fork is a full copy of the world at tick 30. Anything you do to it from here is invisible
to the main run.

## 3. Run the scenario on the fork

```bash theme={null}
# Advance ONLY the fork by 200 ticks.
curl -s -X POST http://localhost:3917/fork/reach-x3/step \
  -H 'Content-Type: application/json' -d '{"ticks":200}'
# { "ok": true, "fork_id": "reach-x3", "start_tick": 30, "new_tick": 230, "ticks_advanced": 200, "entity_count": 2 }

# Read the fork's state and check the mover's x.
curl -s http://localhost:3917/fork/reach-x3/observe
# → the mover (id 1) is at "position": [3.8333303928375244, 1.0, 0.0] at tick 230
```

At tick 230 the mover has travelled `230 × 1/60 ≈ 3.83` units along +x — so **yes**, it passes
`x = 3`. (At the parent tick 30 it was at `x ≈ 0.5`.)

## 4. Confirm the real run is untouched, then drop the fork

```bash theme={null}
# Main world is still at tick 30 — the what-if changed nothing.
curl -s -X POST http://localhost:3917/observe        # → "tick": 30

# Discard the fork.
curl -s -X DELETE http://localhost:3917/fork/reach-x3
# { "ok": true, "deleted": "reach-x3" }
```

<Check>
  You answered a forward-looking question against the exact dynamics of your world and left
  the real run exactly where it was. That is the difference between a fork and just stepping:
  the fork is a throwaway copy, not the timeline.
</Check>

## Patterns

<CardGroup cols={2}>
  <Card title="Compare several options" icon="layer-group">
    Create one fork per candidate action (`one-if-left`, `one-if-right`, …), step each, and
    compare the outcomes — a one-step decision tree over real dynamics.
  </Card>

  <Card title="Intervene, don't just wait" icon="wand-magic-sparkles">
    Before stepping a fork, edit it (`/entities/{id}/components`, `/rule/create`) to test a
    change, not just the passage of time.
  </Card>

  <Card title="List and clean up" icon="broom">
    `GET /fork/list` shows active forks; `DELETE /fork/{id}` drops one. Forks are cheap but
    not free — drop the ones you are done with.
  </Card>

  <Card title="Exact answer keys" icon="key">
    For grading world models, the action-conditioned version of this is the
    [evaluation track](/evaluation/overview).
  </Card>
</CardGroup>