[Refactoring] Adopt or retire the 19 orphan scripts under tests/demo/screens/ #374

New issue

Open

opened 2026-07-14 10:48:06 +00:00 by john · 0 comments

john commented

2026-07-14 10:48:06 +00:00

Owner

Spun out of #372, which is otherwise closed.

Context

#372 unrotted the demo_main.py path and added a CI smoke gate for it, so screens/base.py and the 6 wired DemoScreen subclasses (caption, frame, primitives, grid, animation, color) now run headless and are checked by tests/run_tests.py.

The remaining problem

tests/demo/screens/ contains 27 files, but only 8 are part of the demo_main system (__init__.py, base.py, and the 6 wired screens). The other 19 are standalone scripts that never go through demo_main.py:

voxel_core_demo, voxel_* (several), village_demo, terrain_demo, ldtk_demo,
tiled_* (2), navigation* (2), pathfinding_demo, focus_system_demo,
integration_demo, entity3d_demo, model_loading_demo, billboard_building_demo,
skeletal_animation_demo

The screens/ package is really two unrelated things stapled together: a demo-screen framework, and a pile of loose scripts that happen to live in the same directory.

They are not covered by the #372 smoke gate, so they can (and likely already do) rot exactly the way demo_main.py did.

Why they were left out of #372

Most exit only on ESC via on_key, so they never terminate headless. Gating them needs quit-injection (a mcrfpy.Timer driven by mcrfpy.step(), or an explicit sys.exit(0) after N steps — note that as of #350 a headless --exec script must declare its exit status anyway).
The voxel/3D ones need much longer timeouts than a unit test.
They lean on the experimental, un-frozen 3D/Voxel API, which is explicitly outside the 1.0 freeze — gating them would couple CI to a moving target.

Options

Adopt: fix each to run headless with a deterministic exit, add to DEMO_SMOKE_TESTS in tests/run_tests.py (with a longer timeout tier for the 3D ones). Highest value, most work.
Relocate: move them out of screens/ (e.g. tests/demo/standalone/) so the package stops implying they are demo screens, and gate only the 2D subset.
Retire: delete the ones superseded by tests/demo/screens/*_demo.py or by the benchmark/Gauntlet work, keep the rest as explicitly-ungated examples.

Recommend (2) + (1) for the 2D subset, deferring the 3D ones until the Viewport3D API stabilises.

#372 (demo rot + smoke gate) — the parent
#350 (headless --exec must call sys.exit(); --run-forever for long-lived processes)

Spun out of #372, which is otherwise closed. ## Context #372 unrotted the `demo_main.py` path and added a CI smoke gate for it, so `screens/base.py` and the **6 wired `DemoScreen` subclasses** (caption, frame, primitives, grid, animation, color) now run headless and are checked by `tests/run_tests.py`. ## The remaining problem `tests/demo/screens/` contains **27 files**, but only 8 are part of the demo_main system (`__init__.py`, `base.py`, and the 6 wired screens). The other **19 are standalone scripts that never go through `demo_main.py`**: ``` voxel_core_demo, voxel_* (several), village_demo, terrain_demo, ldtk_demo, tiled_* (2), navigation* (2), pathfinding_demo, focus_system_demo, integration_demo, entity3d_demo, model_loading_demo, billboard_building_demo, skeletal_animation_demo ``` The `screens/` package is really two unrelated things stapled together: a demo-screen framework, and a pile of loose scripts that happen to live in the same directory. They are **not** covered by the #372 smoke gate, so they can (and likely already do) rot exactly the way `demo_main.py` did. ## Why they were left out of #372 - Most exit only on ESC via `on_key`, so they never terminate headless. Gating them needs quit-injection (a `mcrfpy.Timer` driven by `mcrfpy.step()`, or an explicit `sys.exit(0)` after N steps — note that as of #350 a headless `--exec` script *must* declare its exit status anyway). - The voxel/3D ones need much longer timeouts than a unit test. - They lean on the **experimental, un-frozen** 3D/Voxel API, which is explicitly outside the 1.0 freeze — gating them would couple CI to a moving target. ## Options 1. **Adopt**: fix each to run headless with a deterministic exit, add to `DEMO_SMOKE_TESTS` in `tests/run_tests.py` (with a longer timeout tier for the 3D ones). Highest value, most work. 2. **Relocate**: move them out of `screens/` (e.g. `tests/demo/standalone/`) so the package stops implying they are demo screens, and gate only the 2D subset. 3. **Retire**: delete the ones superseded by `tests/demo/screens/*_demo.py` or by the benchmark/Gauntlet work, keep the rest as explicitly-ungated examples. Recommend (2) + (1) for the 2D subset, deferring the 3D ones until the Viewport3D API stabilises. ## Related - #372 (demo rot + smoke gate) — the parent - #350 (headless `--exec` must call `sys.exit()`; `--run-forever` for long-lived processes)