Skip to main content
Industry & SpecializedGame Production30 lines

Deterministic Lua Simulation Tests

Isolate Lua game logic, pass in controlled clocks and random choices, and compare reproducible simulation traces without launching the game engine.

Quick Summary7 lines
Choose one logic layer with observable outputs, such as cooldowns, spawn scheduling or settlement. Extract the state transition from renderer, timers, engine callbacks and storage. Pass the elapsed simulation interval or simulation clock and necessary input events into the module. Keep engine adapters thin so integration tests can separately verify how the runtime invokes the same behavior.

## Key Points

- [Lua 5.4 reference manual](https://www.lua.org/manual/5.4/manual.html)
skilldb get game-production-skills/lua-simulation-testingFull skill: 30 lines
Paste into your CLAUDE.md or agent config

Deterministic Lua Simulation Tests

Choose one logic layer with observable outputs, such as cooldowns, spawn scheduling or settlement. Extract the state transition from renderer, timers, engine callbacks and storage. Pass the elapsed simulation interval or simulation clock and necessary input events into the module. Keep engine adapters thin so integration tests can separately verify how the runtime invokes the same behavior.

Fix inputs and ordering

Represent inputs as an explicit ordered list. When two events have the same timestamp, define how the order is resolved and preserve that policy in tests. Avoid relying on table traversal for a sequence whose order affects the result. Pass a deterministic random-choice function to the transition. A queue of test values is useful when the test needs to force one rare decision. For seeded runs, retain the seed and Lua version. Lua 5.4 documents reproducibility from equal seeds, but versions and runtimes may differ.

Inject time as ticks or a documented time unit. Keep the simulation state separate from observed wall clock. For each transition, record important counters and emitted events. Prefer an invariant or a compact trace over a complete snapshot that will change with incidental fields.

Exercise edge cases

Test an event just before the boundary, exactly on it and one unit after it. For a cooldown example, a repeat event at tick 9 should remain ineligible when the next permitted tick is 10. At tick 10, the transition emits exactly one eligible action. Specify how a second identical event is handled. Test a long elapsed interval with several scheduled events and compare against advancing one tick at a time if the contract promises those paths match.

Check that the tests fail when the injected sequence is exhausted, when an event arrives out of order, and when the implementation accidentally uses ambient random state. Use runtime-compatible syntax. A fixture running in standard Lua does not establish compatibility with a customized host API or coroutine scheduler.

Run and retain evidence

Execute the suite with the project's pinned interpreter and record input fixture, random seed or sequence and first divergent step. Rerun the same case twice and compare outputs. Keep one integration test per engine adapter that exercises an actual callback and confirms the sequence expected by the simulation module.

Sources

Install this skill directly: skilldb add game-production-skills

Get CLI access →