Deterministic toy game engine (C++17, Lua 5.4 scripts through sol2) for the script-to-engine refactoring agent described in plan.md.
Needs CMake, a C++17 compiler and Lua 5.4 (brew install lua). sol2 is fetched by CMake.
cmake -S . -B build && cmake --build build -j
./build/toyengine scenarios/teamfight.lua --out a.log --profile a.tsv
./build/toyengine scenarios/teamfight.lua --scripts path/to/rewritten --out b.log
./build/replay_diff a.log b.log # exit 0 identical, 1 differentSanitizer build for verifying generated C++:
cmake -S . -B build-asan -DTOY_SANITIZE=ON -DCMAKE_BUILD_TYPE=Debug && cmake --build build-asan -jtoyengine exits 0 on a clean run, 1 if it could not run, 2 if any script raised an error.
python3 tools/live_feed.py scenarios/teamfight.lua # 30 ticks/s
python3 tools/live_feed.py scenarios/stress.lua --rate 60 --scripts path/to/scriptsRuns the engine paced with --rate, and opens a pop-out window showing the tick counter, state hash, unit health and the event stream as it happens. Needs Python 3 (standard library only). The replay of the latest run is written to live.log. Stop with Ctrl-C.
python3 -m venv .venv && .venv/bin/pip install "anthropic[mcp]"
export ANTHROPIC_API_KEY=...
.venv/bin/python -m agent.run # Claude Sonnet 5.5, capped at an estimated $15
.venv/bin/python -m agent.run --driver scripted:agent/fixtures/reference/plan.json # no modelOne run does everything, narrating each step in the terminal as it happens, and ends with a printed summary:
- Builds the baseline engine, records a baseline replay for every test, and pins the replays and the protected sources by hash.
- Ranks candidate patterns: engine-call n-grams found in at least three scripts, weighted by profiler cost (
agent/candidates.py). - Runs the refactoring agent against a staged copy, through an MCP server (
agent/server.py). - Verifies outside the agent: clean optimised and ASan/UBSan builds, every test replayed in a sandbox and compared with its pinned baseline.
- Runs the held-out checks: the original held-out scripts on the new engine, then a separate porter agent rewrites the held-out scripts with the primitives.
- Writes
result.jsonand prints the summary.
Terminal output. During a run you see, in order: each baseline replay with its hash, the ranked candidates, every model message, tool call and tool result (including refused calls and replay diffs), each verification replay on both builds, per-script coverage, each performance run, and the held-out checks. The summary at the end has the verdict, the before and after numbers, the new API with its documentation, the verification table, the held-out results, and the agent's cost and closing summary. Colour is used on a terminal only; set NO_COLOR to turn it off.
| Command | Purpose |
|---|---|
python -m agent.run |
The whole pipeline. --model, --effort, --max-usd, --max-minutes, --max-turns, --skip-port; --adopt <run-id> skips the agent sessions and verifies an earlier run's output live (about 15 s); --pace <s> and --brief make the output easier to record |
python -m agent.summary <id> [--diffs] |
Reprint a run's summary; --diffs adds every script and C++ diff |
python -m agent.playback <id> |
Replay a recorded run in the terminal |
python -m agent.demo <id> <script.lua> |
Check a new champion written with the primitives against demo/leona_old.lua |
python -m agent.promote <id> --approve |
Copy a verified run into the repository. Always needs --approve; refuses a run that did not verify |
The agent has no shell and no file paths. Its MCP tools address a fixed table of names:
| Tool | Refactor agent | Porter agent |
|---|---|---|
list_files, read_file |
Staged scripts, engine headers and sources, API docs, candidates | Staged held-out scripts, primitives source and docs |
write_script |
The 8 sample champions | The 4 held-out champions |
write_cpp, write_api_doc, compile |
Yes (primitives.cpp only) |
Not available |
list_tests, run_scenario, diff_replays, run_regression |
Sample suite | Held-out suite |
- Not addressable by either agent: scenarios, baseline replays, the diff tool, the engine core and the harness. The refactor agent also cannot name anything under
heldout/. - Sandboxed runs: every engine run goes through
sandbox-execwith no network, writes confined to the run's output folder, and no read access to the baselines (or toheldout/for the refactor agent). This matters because the binary contains agent-written C++. macOS only; elsewhere runs are unsandboxed and the run output says so. - Regression test selection:
run_regressionreruns a test only when the primitives or a script that test spawns changed since it last passed. - Checkpoints: the staged state is saved whenever every test is green. If the final state does not verify, the last checkpoint is verified instead.
- Every call is logged to
tool_log.jsonl, including refused ones.
engine/src/primitives.cpp is the one engine file the agent may change. ScriptHost gives it bind (expose a function to Lua and to the profiler), dealDamage (damage plus OnDamaged/OnDeath, as the Lua DealDamage does), addTimer (same queue and ordering as Lua CreateTimer) and world().
| Path | Contents |
|---|---|
engine/src/world.* |
Units, buffs, movement, damage, seeded RNG, state hash |
engine/src/script_host.* |
Lua state, script API bindings, timers, engine-call profiler |
engine/src/scenario.* |
Scenario loader |
engine/src/main.cpp |
Tick loop, replay log and profile output |
engine/tools/replay_diff.cpp |
Replay comparison |
tools/live_feed.py, tools/live_feed.html |
Live feed server and page |
tools/coverage.py |
Lua line coverage report |
engine/src/primitives.cpp |
Engine primitives; empty until a run is promoted |
agent/ |
Candidate finder, MCP server, harness, pipeline, terminal summary, playback, demo check |
agent/fixtures/reference/ |
Hand-written primitives and rewrites for testing the pipeline without a model |
demo/, DEMO.md |
Demo champion, scenario and runbook |
work/ |
Run directories and builds (generated) |
scripts/samples/ |
Champion scripts the agent works on |
scenarios/ |
showcase.lua (coverage), teamfight.lua (4v4), stress.lua (400 units) |
heldout/ |
Champion scripts and scenarios the agent must never see |
The engine is C++ and the scripts are Lua; there is no C# anywhere. The kits are written from the champions' published abilities, not ported from any codebase. They are simplified to what the engine supports: skillshots become targeted or area casts, shields and invulnerability become resistances, and there are no cooldowns, mana or basic attacks. Numbers are approximate.
| Set | Champions | Location |
|---|---|---|
| Visible to the agent | Garen, Veigar, Taric, Annie, Sona, Morgana, Darius, Lux | scripts/samples/ |
| Held out | Amumu, Soraka, Malphite, Alistar | heldout/scripts/ |
Both sets also contain dummy.lua (1000 health, logs hits) and minion.lua (60 health, for on-kill branches).
The scripts share conventions that no engine function enforces, which is the duplication the agent is meant to find:
- Damage is mitigated by hand:
raw * 100 / (100 + resist). - Enemies or allies are picked by looping over
GetUnitsInRangeand comparingGetTeam. - A timed stat change is
AddBuff+ModifyStat+ aCreateTimerthat undoes it. - A stun is the buff
stunnedplus speed set to zero; everyOnCaststarts by returning if the caster has it. A root is the buffrooted, which does not block casts.
Nothing under heldout/ may be shown to the refactoring agent: not the scripts, the scenarios, or replays and profiles produced from them. The agent's file tools must be rooted at scripts/samples/ and scenarios/ and refuse any other path. The held-out set is used once the agent has finished, to check that the primitives it invented also fit champions it never saw.
./build/toyengine heldout/scenarios/teamfight.lua --scripts heldout/scripts --out h.logA replay comparison only says something about code the scenario runs. --coverage records the Lua lines executed, and tools/coverage.py reports the lines no scenario reached (needs luac on PATH):
./build/toyengine scenarios/showcase.lua --coverage a.cov
./build/toyengine scenarios/teamfight.lua --coverage b.cov
python3 tools/coverage.py scripts/samples a.cov b.covshowcase.lua plus teamfight.lua reach every executable line of every script in their set, for both the visible and the held-out set.
- Simulation state is integer fixed-point (1/1000). Scripts pass and receive doubles; the engine rounds at the API boundary.
- One seeded RNG, reachable only through
RandomInt.math.random,os,io,dofileandloadfileare not available to scripts. - Tick order: recorded inputs, due timers (in creation order), buff expiry, movement,
OnTickfor each living unit by id, state hash. - The state hash covers the tick, RNG state and every unit. It does not cover Lua-side script state (
selffields) or pending timers. - Scripts must not let
pairs()order affect engine calls.
replay_diff compares each tick's events as a sorted set plus the state hash, so reordering inside a tick passes. --strict also requires the same event order.
A script returns a table with a stats table (hp, ad, ap, armor, mr, speed) and optional handlers. self is a per-unit table with self.id.
| Handler | Called when |
|---|---|
OnSpawn(self) |
The unit is created |
OnTick(self) |
Every tick while alive |
OnCast(self, slot, target, x, y) |
A recorded cast input; target, x, y may be nil |
OnDamaged(self, source, amount, type) |
After damage is applied to the unit |
OnDeath(self, killer) |
The unit dies |
Distances and positions are in world units, durations in ticks (30 per second).
| Function | Notes |
|---|---|
GetUnitsInRange(x, y, r) |
Ids of living units of any team, ascending |
GetPosition(id) |
Returns x, y |
GetTeam(id), GetHealth(id), GetMaxHealth(id), IsAlive(id) |
|
GetStat(id, name), ModifyStat(id, name, delta) |
name is ad, ap, armor, mr or speed |
DealDamage(src, dst, amount, type) |
type is physical, magic or true. The amount is applied as given: no mitigation |
Heal(src, dst, amount) |
Returns the amount applied |
AddBuff(target, name, ticks, source) |
A marker with a duration; re-adding refreshes it. No stat effect |
HasBuff(id, name), RemoveBuff(id, name) |
|
MoveTo(id, x, y), Teleport(id, x, y) |
|
CreateTimer(ticks, fn) |
Runs fn after ticks (at least 1) |
RandomInt(lo, hi) |
Inclusive |
GetTick(), LogEvent(text) |
To add an engine primitive, bind it in engine/src/primitives.cpp with host.bind("Name", lambda); that also registers it with the profiler. toyengine --list-api prints every bound function.