playtest-audit
Skill0 starsChanged 5 months agoMITView on GitHub
Use to empirically verify a playable Godot game is actually WINNABLE, FAIR, and PROGRESSABLE — by driving the REAL game loop with a headless competent-player bot that asserts playability invariants (can earn/progress/clear, the first goal is reachable, no death-spiral) and reports balance metrics. The gate the logic/UI self-tests structurally cannot be.
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Every other gate is blind to balance:
- Distinctive: line 87
If a competent, cautious player cannot earn / progress / survive, the tuning is broken — that is the finding.
- Distinctive: line 90
Keep the bot's competence honest: a deliberately weak bot false-fails good games.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
playtest-audit
Prove the game can actually be played to a good outcome, not just that its rules are
correct. Emit games/<id>/playtest.gd: a headless bot that drives the real game loop
with a competent policy and asserts the title is winnable, fair, and lets a player make
progress. Prints per-step metrics then exactly PLAYTEST OK (exit 0) or
PLAYTEST FAIL: <reason> (exit 1).
Why this exists (the gap it closes)
Every other gate is blind to balance:
selftestproves rules by driving the engine directly — and that is exactly its blind spot. diver-0001's selftest "proved" a cautious dive banks by callingcollect()at depth 0, asserting the economy in the abstract. It never simulated the spatial reality: treasure spawned 270m below the diver, past a crush line at 200m, so a real player physically could not reach a treasure and return alive — the game was 100% unwinnable and every logic/UI gate was green. The owner found it in ten seconds of play.uitestproves a tap reaches a handler.visual-auditproves the screen reads.- the
deependesign-depth audit reads the code and reasons on paper — it judged diver "deeper, not bigger" while the same build was unwinnable, because it never played it.
Winnability/fairness/economy-solvency are emergent properties of the assembled loop (spawn geometry × collision × resource drain × difficulty ramp). The only way to see them is to play the real loop. That is this skill.
Loop position
A validation gate, like selftest/uitest — run it after builder and after every
deepen pass (tuning is exactly what deepen changes). builder/deepen emit
playtest.gd; the validator runs it and fails the build on PLAYTEST FAIL. It records
nothing to the manifest — its outputs are the pass/fail gate + a balance-metrics report
(and any code/tuning fixes that follow).
Discovery vs. confirmation — where this gate sits relative to generate-and-verify. When a
game generates discrete content instances (puzzle boards, procedural maps, wave compositions,
shop economies), builder's generate-and-verify gate already guarantees each instance is
solvable at creation via an in-game solver (make_verified + Solver). For those games this
bot is confirmation, not discovery: it verifies the per-instance guarantee survived
assembly — that collision × resource-drain × the difficulty ramp didn't make a
provably-solvable instance unwinnable in practice. It stays a hard gate regardless. Where no
such upstream gate exists (winnability is a pure tuning/spatial property of the assembled loop
— diver-0001's crush line vs. treasure depth), this bot remains the only place winnability
is checked, and is in full discovery mode. Either way: a PLAYTEST FAIL is a tuning/generator
bug, never license to weaken selftest or Solver.
The harness — drive the REAL loop, deterministically
A SceneTree script that instantiates the actual scene and steps it by hand so the bot
sees real spawns, real collision, real resource math:
extends SceneTree
var main
func _initialize() -> void: _run()
func _run() -> void:
var scene: PackedScene = load("res://Main.tscn")
main = scene.instantiate()
root.add_child(main)
await process_frame # let _ready() run
main.set_process(false) # WE drive _process at a fixed dt — deterministic, no engine variance
var DT := 1.0 / 60.0
while main.<active> and guard < CAP:
<set the bot's intent on the real input surface, e.g. main.target_x = ...>
main._process(DT) # the real spawn/move/collide/tick, stepped by us
# read real state off main.<state> and assert invariants- Step the real
_processyourself with a fixeddtafterset_process(false)— never rely on engine frame timing (variabledt, non-determinism). Seed every RNG; with a fixed seed + fixeddtthe whole playthrough is reproducible. - The bot acts through the real input surface the game already exposes (the steer target, the action methods) — not by reaching past the rules. If you must poke private state to set up a scenario, do it sparingly and say so.
- Reuse the genre's existing headless boot assumptions (no autoloads under
--script,preloaddata layers — same gotchas asselftest/uitest).
The bot — COMPETENT, not optimal
Model a reasonable player, not a theoretical-best solver and not a random flailer:
- A simple greedy-but-cautious policy (head for the nearest reward; retreat when the resource budget only just covers a safe exit, with a margin).
- If a competent, cautious player cannot earn / progress / survive, the tuning is broken — that is the finding. (diver's bot turned back at a safe margin and still banked 0, because nothing was reachable.)
- Keep the bot's competence honest: a deliberately weak bot false-fails good games; an
optimal one hides difficulty. When the bot is weaker than a human at a sub-skill (precise
dodging/aiming), REPORT what it couldn't do rather than
FAILon it — flag it for the human playtest instead of gating on it (diver: the crude lerp-steering bot couldn't grab the sparse Trench treasures, so deep-commission fill is reported, not failed).
Invariants to assert (instantiate per genre)
Gate on the ones that mean "a player can succeed":
- Solvency / winnable. A competent run reaches a good outcome at least sometimes: earns positive currency, clears the encounter, survives a wave, scores above zero. The anti-unwinnable gate. (diver: a careful rig-0 dive banks > 0.)
- First goal reachable. The first objective/commission/boss/quota is achievable from the starting loadout — not gated behind a resource you can only get by doing it (a deadlock).
- Fairness / no death-spiral. The player never dies on a turn where they played safely (no unavoidable hit, no spawn you cannot react to); a setback is recoverable, not terminal.
- Progression solvency. Across several sessions (buying upgrades / advancing), resources accumulate and the next tier is affordable — measured as gross earnings, not net balance (a bot that spends on upgrades has a low balance while clearly progressing).
- No trivial dominant win. A single repeated cheap action does not run the score to
infinity (the inverse failure — the loop is solved). Pairs with
deepen's dominant-strategy test.
Metrics to report (every run, pass or fail)
Print enough to tune from, not just a verdict: earnings/clear per session, the minimum resource margin seen (how close to death a careful player runs), depth/wave/turn reached, time-to-first-upgrade, commission/objective fill rate. These numbers are how the owner sets difficulty — surface them even when the run passes.
Machine-readable contract (the tuning signal). In addition to the human lines and the
PLAYTEST OK/FAIL verdict, print exactly one final line PLAYTEST METRICS {json} carrying
the numbers above plus the invariant booleans (solvent, first_goal_reachable,
no_death_spiral, no_trivial_dominant) so they coincide with the gate verdict. This line is
the contract deepen's balance-search (tools/balance.mjs) consumes: it aggregates the metrics
across K seeds, hard-rejects configs whose invariants are false, and scores the rest against
target bands. The metrics are not just a human dump — they are the tuning oracle. Nothing new is
simulated to produce the line; it serialises what the bot already computed.
Honest reporting
Gate on the winnability invariants; report (don't FAIL) anything that's a bot-skill
limitation rather than a game flaw, and say which is which. A PLAYTEST OK must mean "a
competent player can succeed," and the metrics must name any difficulty the bot only barely
cleared — never let a silent cap read as "fully balanced."
Gotchas (carry these)
- A logic self-test that drives the engine directly cannot see spatial/economic
winnability — that is precisely why this gate exists. Do not "fix" a
PLAYTEST FAILby weakeningselftest; fix the tuning (spawn geometry, gate depths, costs, the ramp). - Stepping
_processmanually while the engine also auto-runs it double-ticks the world —set_process(false)first. - Manual stepping means
_drawnever runs, so RNG used only in_draw(shake/parallax) won't desync the spawn RNG — keep spawn RNG in_processfor a reproducible run. - Clear any
user://save at start AND end (a persisted economy leaks across runs and makes "can a fresh player win?" non-deterministic).
Dogfood lesson (diver-0001)
The bug that motivated this skill: crush line (200m) shallower than both the commission zone
(Reef@240m) and the nearest treasure spawn (332m), so banking anything was impossible while
every logic/UI/design gate stayed green. The bot caught it on the first run (earned 0 across
8 dives). The fix was pure tuning — collectible treasure pre-seeded into safe water, the
rig-0 safe depth raised to cover the Shallows + first commission, deeper zones pulled up —
verified by re-running until PLAYTEST OK (dive 1 banks 168 incl. a filled commission).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

