Skip to content

Troubleshooting

Jump to bottom
Nick Hamze edited this page Jul 17, 2026 · 2 revisions

Troubleshooting

The doctor cannot find Wonderful Toolchain

Confirm the WonderSwan target is installed and the toolchain binaries are on PATH. Story Forge defaults to /opt/wonderful.

/opt/wonderful/bin/wf-pacman -Q target-wswan

Pillow import fails

Install Pillow for the same Python interpreter used by the scripts:

python3 -m pip install Pillow
python3 -c "import PIL; print(PIL.__version__)"

A report still points at an old checkout path

Reports are evidence, not decorative caches. Re-run the builder or doctor that owns the report so it records the current source paths and hashes. Do not fix a hash-bound report with a text editor and call it fresh.

The ROM compiles but the release is blocked

Compilation proves only one layer. Inspect the first failing report in this order:

  1. game/project validation;
  2. graphics contract;
  3. text contract;
  4. visual contract or game readiness;
  5. build report;
  6. emulator smoke;
  7. game audit;
  8. release verification.

For current generic games, insert SwanSong playthrough between game audit and release packaging. Inspect reports/swansong-playthrough-report.json first.

The game loads in SwanSong but will not progress

Do not treat a rendered frame as accepted input. Run the exhaustive SwanSong playtest and inspect requested masks, observed keys, accepted-action counters, mailbox phase/node, and the stall snapshot. Confirm presses use a three-frame press and three-frame release so the emulated keypad sees an edge.

If the failure occurs only in the app UI, run Scripts/check-player-input.sh from the SwanSong source checkout. Exit 77 means macOS blocked event injection; grant Accessibility permission and rerun.

Saves work until SwanSong restarts

Check the report's persistence_test, not only save-state replay. A save state proves engine serialization; cartridge persistence proves an in-game save can survive a fresh engine. The runtime currently uses save schema 5 and intentionally invalidates schema-4 data.

A route test expects a branch node that never appears

branch and chapter nodes can execute without producing an observable frame. Keep them in graph plans but filter them from the expected runtime node trace.

The installed SwanSong seems older than the local build

Compare the engine dynamic-library hash and check for Contents/Helpers/SwanSongRouteRunner. Do not rely on the visible version number alone. Test with --swansong-dylib to bind the intended bundle.

A sprite family flickers

The frames were probably quantized or segmented independently. Return to one locked neutral master, reuse its palette and binary alpha, and edit only the mouth or eye region. Re-run the audition and approval.

Dialogue passes the character limit but looks crowded

The limit is not the layout. Run the text contract against the exact runtime font and inspect text-preview-sheet.png. Rewrite to three wrapped lines or fewer when the screen needs breathing room.

Music plays too fast

Confirm the Story Forge runtime patch is applied and the runtime advances at the WonderSwan’s roughly 75.472 Hz frame timing rather than 60 Hz.

Emulator smoke passes but the screenshot is weak

Boot proof and visual proof are separate. Capture a clean native framebuffer, review it by eye, and bind the approved screenshot through the ship command.

Physical hardware has not been tested

Record hardware status as pending. Do not promote emulator evidence into a hardware claim.

The wiki or README links are stale

The canonical public locations are:

The local Wiki source checkout is the separate swansong-story-forge.wiki.git repository. Update and validate it alongside source changes that alter build, test, player, or release behavior.

SwanSong Story Forge

Clone this wiki locally