agent-playtesting.md

Agent Playtesting

This project now exposes a headless JSON interface intended for automation, scripted debugging, and agent-driven playtesting. The Bevy client remains the human-facing tool; app_headless is the machine-facing tool.

Goals

• let an agent inspect authoritative sim state without scraping UI text
• let an agent apply deterministic simulation commands in batch form
• let debugging and replay flows use the same structured data contract

Entry Points

List scenarios:

cargo run -p app_headless -- --list-scenarios --json

Observe a scenario after advancing ticks:

cargo run -p app_headless -- --scenario first_slice --ticks 20 --json

Observe a thinner summary-only payload:

cargo run -p app_headless -- --scenario first_slice --ticks 20 --json --json-profile summary

Inspect a specific part from a save:

cargo run -p app_headless -- --load /tmp/three_d_systems_debug_save.json --inspect-part 12 --json

Run a scripted batch and emit a per-step trace:

cargo run -p app_headless -- \
  --scenario first_slice \
  --command-file /tmp/agent-script.json \
  --emit-trace /tmp/agent-trace.jsonl \
  --json

JSON Output

--json emits a top-level object with these fields:

• ok: whether the run completed without a scripted or inspection error
• error: first user-level execution error, if any
• source: scenario id or save path used to seed the run
• steps: compact outcomes for scripted steps and convenience tick actions
• summary: aggregated machine-readable world summary
• inspect: optional detailed inspection for --inspect-part
• world: the full validated save snapshot shape

--json-profile controls payload size:

• summary: summary/checkpoints only, no top-level inspect or full world snapshot
• inspect: keep inspect data, omit the full world snapshot
• full: current complete payload, including the validated world snapshot

summary includes:

• tick
• state_hash
• size
• parts
• objective
• contamination
• produced_total
• build_inventory
• part_state_counts

inspect and scripted inspect_part steps include:

• the full part state
• sim-owned status
• port_links
• filtered active item_traces
• connected_power_parts
• connected_item_parts

Command Files

--command-file accepts either:

• a JSON array of steps
• an object of shape { "steps": [ ... ] }

Supported step types:

• apply_command
• tick
• until_victory
• inspect_part

apply_command uses the serialized sim_core::Command shape. Example:

[
  {
    "type": "apply_command",
    "command": {
      "type": "place_part",
      "def_id": "frame_block",
      "origin": { "x": 1, "y": 1, "z": 1 },
      "facing": "north"
    }
  },
  {
    "type": "apply_command",
    "command": {
      "type": "place_part",
      "def_id": "wire",
      "origin": { "x": 2, "y": 1, "z": 1 },
      "facing": "north"
    }
  },
  {
    "type": "tick",
    "ticks": 8
  },
  {
    "type": "inspect_part",
    "part_id": 1
  }
]

Supported command variants:

• place_part
• remove_part
• rotate_part
• set_machine_enabled
• set_machine_recipe
• set_build_recipe

Trace Output

--emit-trace <path> writes newline-delimited JSON records.

Each record captures:

• stage: initial, step, or final
• step_index
• step
• ok
• error
• summary
• optional inspection

This is intended for:

• agent training/evaluation traces
• regression debugging
• scripted scenario analysis without re-parsing terminal text

Notes

• The JSON interface is derived from authoritative sim reports, not Bevy-only state.
• world can be large because it includes the full save snapshot.
• Use --json-profile summary or --json-profile inspect when you want lighter automated tooling payloads.
• Human-readable mode remains the default when --json is omitted.
• Script execution stops on the first failing step, but still returns the current world snapshot and failure metadata.