Skip to content
cogreanPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

toyengine

Deterministic toy game engine (C++17, Lua 5.4 scripts through sol2) for the script-to-engine refactoring agent described in plan.md.

Build and run

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 different

Sanitizer build for verifying generated C++:

cmake -S . -B build-asan -DTOY_SANITIZE=ON -DCMAKE_BUILD_TYPE=Debug && cmake --build build-asan -j

toyengine exits 0 on a clean run, 1 if it could not run, 2 if any script raised an error.

Live feed

python3 tools/live_feed.py scenarios/teamfight.lua           # 30 ticks/s
python3 tools/live_feed.py scenarios/stress.lua --rate 60 --scripts path/to/scripts

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

Refactoring agent

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 model

One run does everything, narrating each step in the terminal as it happens, and ends with a printed summary:

  1. Builds the baseline engine, records a baseline replay for every test, and pins the replays and the protected sources by hash.
  2. Ranks candidate patterns: engine-call n-grams found in at least three scripts, weighted by profiler cost (agent/candidates.py).
  3. Runs the refactoring agent against a staged copy, through an MCP server (agent/server.py).
  4. Verifies outside the agent: clean optimised and ASan/UBSan builds, every test replayed in a sandbox and compared with its pinned baseline.
  5. 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.
  6. Writes result.json and 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

What the agent can and cannot do

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-exec with no network, writes confined to the run's output folder, and no read access to the baselines (or to heldout/ 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_regression reruns 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 primitives

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

Layout

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

Sample scripts

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 GetUnitsInRange and comparing GetTeam.
  • A timed stat change is AddBuff + ModifyStat + a CreateTimer that undoes it.
  • A stun is the buff stunned plus speed set to zero; every OnCast starts by returning if the caster has it. A root is the buff rooted, which does not block casts.

Held-out rule

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

Coverage

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

showcase.lua plus teamfight.lua reach every executable line of every script in their set, for both the visible and the held-out set.

Determinism

  • 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, dofile and loadfile are not available to scripts.
  • Tick order: recorded inputs, due timers (in creation order), buff expiry, movement, OnTick for 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 (self fields) 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.

Scripts

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

Script API

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.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages