Template example programs (templates/*/) are shipped but gated by nothing #380

New issue

Open

opened 2026-07-15 04:27:25 +00:00 by john · 0 comments

john commented

2026-07-15 04:27:25 +00:00

Owner

Problem

The site's templates/{minimal,complete,roguelike}/ directories ship multi-file, "fully playable" starting-point programs (game.py, entities.py, ai.py, combat.py, dungeon.py, turns.py, ui.py, constants.py, ...). Users are told to copy these as the basis for their own game.

The 2026-07-14 docs sweep (commit ba92e42 in mcrogueface.github.io) fixed and verified all 88 hand-written pages including the template README.md files, and promoted every complete inline example into the engine's gated snippet suite (tests/snippets/131-282, commit 07442dd). But the sweep only touched the READMEs and the runnable snippets — the shipped .py template programs themselves are validated by nothing. No test in run_tests.py imports or runs them, so they can drift out of sync with the engine silently, exactly like the pages did before this sweep.

Concretely: the review pass flagged that templates/complete/README.md is now correct against the shipping API but contradicts its own accompanying example files (e.g. at() now returns GridPoint-or-None, UIGridPointState was removed in #294). A stale reference also survives: templates/complete/constants.py:154 still mentions keypressScene in a comment.

Why it matters

These are the highest-leverage "first contact" code a new user copies. If they're broken, the copy-paste-and-run promise fails on line one — and unlike the snippets, nothing catches it.

Proposed work

Audit each template program against the 0.2.8-dev API (same known-broken list the sweep used: mcrfpy.Animation, add_layer("..."), sceneUI/setScene/createScene/keypressScene, compute_astar_path, GridPoint.color, entity.gridstate).
Reconcile templates/complete/ with its README so the two agree.
Add a gate: either a smoke test per template (import + headless boot for N steps) discovered by run_tests.py, or fold the template entry points into the snippet-style harness. Without a gate this rots again.

Discovered during the hand-written-docs sweep; see docs-release-pipeline notes and site commit ba92e42.

## Problem The site's `templates/{minimal,complete,roguelike}/` directories ship multi-file, "fully playable" starting-point programs (`game.py`, `entities.py`, `ai.py`, `combat.py`, `dungeon.py`, `turns.py`, `ui.py`, `constants.py`, ...). Users are told to copy these as the basis for their own game. The 2026-07-14 docs sweep (commit `ba92e42` in mcrogueface.github.io) fixed and verified all 88 hand-written pages **including the template `README.md` files**, and promoted every *complete inline example* into the engine's gated snippet suite (`tests/snippets/131-282`, commit `07442dd`). But the sweep only touched the READMEs and the runnable snippets — **the shipped `.py` template programs themselves are validated by nothing.** No test in `run_tests.py` imports or runs them, so they can drift out of sync with the engine silently, exactly like the pages did before this sweep. Concretely: the review pass flagged that `templates/complete/README.md` is now correct against the shipping API but **contradicts its own accompanying example files** (e.g. `at()` now returns `GridPoint`-or-`None`, `UIGridPointState` was removed in #294). A stale reference also survives: `templates/complete/constants.py:154` still mentions `keypressScene` in a comment. ## Why it matters These are the highest-leverage "first contact" code a new user copies. If they're broken, the copy-paste-and-run promise fails on line one — and unlike the snippets, nothing catches it. ## Proposed work 1. Audit each template program against the 0.2.8-dev API (same known-broken list the sweep used: `mcrfpy.Animation`, `add_layer("...")`, `sceneUI`/`setScene`/`createScene`/`keypressScene`, `compute_astar_path`, `GridPoint.color`, `entity.gridstate`). 2. Reconcile `templates/complete/` with its README so the two agree. 3. Add a gate: either a smoke test per template (import + headless boot for N steps) discovered by `run_tests.py`, or fold the template entry points into the snippet-style harness. Without a gate this rots again. Discovered during the hand-written-docs sweep; see docs-release-pipeline notes and site commit `ba92e42`.