[nnunley]

Adds docs/balancing-tools.md, a one-page guide to the dev tools for balance and tuning work:

• Balance harness (xsofy/balance.lg), by @nnunley
• Scenario test, map viewer + audit, lighting testbed, native bench, and dev console, by @mparrett

Each tool was run on current main (let-go 1.13):

• scenariotest --check on both scenarios; web-trample also played through in tmux
• mapgen for a single seed and a multi-seed run (audit floating=0 unreach=0)
• bench/native.lg (all four fixtures, about 9 ms/turn)
• balance_explore.lg and the doc's REPL snippet
• lighttest (move, radius, render-mode cycle, quit)
• Dev console with XSOFY_DEV=1: (help), (player), (location), (seed), (replay), (bench)

Two fixes to docs/balance-harness.md, found during verification:

• Replay was wrong. dispatch/replay builds from the default starting kit rather than the loadout, so replaying a harness run crashed. Replay from make-loadout-world instead; that matched the live run's turn, depth, and HP in 3 of 3 runs I tried.
• Turn cost was stale. It is now about 9–10 ms/turn natively, not 20–25 ms.

Docs only; no code changes.

🤖 Generated with Claude Code

[mparrett]

I can't remember offhand, does ?mode=admin also permit the console?

[mparrett]

Checked - disconfirmed. admin mode does NOT permit the console. (I wonder why?)

[nnunley]

Leaving as written, per your check: only ?mode=dev and XSOFY_DEV gate the console.

[mparrett]

Another comment just for awareness. If I recall, there's a sugar/convenience path that allows bare commands with no args, like help to be treated as (help).

[mparrett]

Confirmed, see comment.

[nnunley]

Added in 0795542: "Commands that take no arguments also work bare: seed is the same as (seed)." under the console table.

[mparrett]

@nnunley - Much needed, and nicely done. Thanks for picking it up.

[mparrett]

Drafted by Claude for @mparrett; follows the three inline comments above.

Approving. I checked the claims about the tools against current main and they hold: the console whitelist and dev gate, the scenario keys and defaults, mapgen/mapaudit, the lighttest e cycle, and the bench fixtures. The replay fix is right: dispatch/replay builds from a bare world/make-world, so a loadout run has to start from make-loadout-world.

On two of the inline notes, from main:

• ?mode=admin doesn't open the console. xsofy.input/dev? only checks ?mode=dev and XSOFY_DEV, so the doc is right as written.
• Bare commands work for every whitelisted command, not only help: run-command accepts a bare symbol as well as a list, so seed behaves like (seed). The console section could mention it in half a sentence.

One nit, not blocking: in balance-harness.md, the section under the new ~13-minute figure still uses the old 20 ms/turn numbers. The heading says "Silent 30-Minute Hang", step 2 estimates "~27 minutes", and "3 runs × 60 turns = 3.6 seconds" would be about 1.8 s at 10 ms/turn. Updating those three would make the section agree with its own figure.

[nnunley]

Timing nit addressed in 0795542. Every figure derived from per-turn cost is recomputed from the measured ~9–10 ms/turn and re-timed on current main:

• Heading: "Silent 30-Minute Hang" → "Silent Multi-Minute Run"
• Scaling example: 3 × 60 ≈ 1.8 s of turns (~2 s with startup), 40 × 2000 ≈ 444× that → ~13 min
• 3 × 60 snippet: ~2 s (measured 2.2 s); 4 × 200 smoke run: ~5 s (measured 4.8 s)
• Sample sweep: ~20 s when recorded, ~37 s on current main (findings kept as the original run)
• balance_explore.lg docstring and banner: ~5 s / up to ~13 min (was ~30 s / ~30 min)

The estimate is now framed as a worst case (n-runs × max-turns × 0.01 s + ~1 s startup), since runs that end early finish sooner. Also fixed while there: the script docstring said max-turns=200 (the code uses 400) and "6 runs per policy". n-runs is the total across combos rounded down to a multiple of the combo count, so the script runs 4 simulations.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-09-22 19:36 UTC