Skip to main content
A fork lets an agent ask “what would happen if…” and get an exact answer, because the same systems run on the fork as on the main world. This guide walks a complete what-if end to end.
Start a local server first — see the Quickstart. All commands target http://localhost:3917 and every POST sends Content-Type: application/json.

​
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

# 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

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

# 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

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

​
Patterns

Compare several options

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.

Intervene, don't just wait

Before stepping a fork, edit it (/entities/{id}/components, /rule/create) to test a change, not just the passage of time.

List and clean up

GET /fork/list shows active forks; DELETE /fork/{id} drops one. Forks are cheap but not free — drop the ones you are done with.

Exact answer keys

For grading world models, the action-conditioned version of this is the evaluation track.