From f1984c16eaaf807761bbff0ca467ca52f1ef380c Mon Sep 17 00:00:00 2001 From: type-two Date: Sat, 25 Jul 2026 19:13:31 +1000 Subject: [PATCH] Document the display dependency: no display = silent hang at mod load, process-alive is not proof Co-Authored-By: Claude Opus 5 --- MEGAPLAN.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/MEGAPLAN.md b/MEGAPLAN.md index 7058829..6c43a47 100644 --- a/MEGAPLAN.md +++ b/MEGAPLAN.md @@ -195,6 +195,16 @@ faction, or it reads as clip-art soup. Fix the Blender camera rig once, reuse. ## 6. Known traps +**The game needs a live display.** OpenRA is SDL2/OpenGL only — there is no null +renderer. If the Mac's screen is locked or asleep, `launch-game.sh` hangs +silently at `Loading mod: vinylgod`: the process stays alive, no exception log is +written, and no game ever starts. **A running process is NOT proof the game +works.** Check for a live display first (`screencapture -x /tmp/x.png` fails with +"could not create image from display" when it is unavailable). When there is no +display, the strongest available verification is: +`luac -p` on every .lua, `./utility.sh --check-yaml` (0 errors), +`./utility.sh --map refresh` (validates every map), and `make`. + Learned the hard way on 2026-07-20 (phases A–F): - **Smoke-test any change by launching straight into a game**: `./launch-game.sh Game.Mod=vinylgod Launch.Map=vinylgod` — `Launch.Map` accepts the map's *folder name*, no UID needed. Run ~45s, then check `~/Library/Application Support/OpenRA/Logs/` for `exception-*.log` (renamed with a timestamp on crash — absence of `exception.log` alone proves nothing).