Home

SwanSong Story Forge Wiki

Welcome to the workshop manual for SwanSong Story Forge, a graphics-first production workflow for original WonderSwan Color visual novels.

The main repository is the showroom. This wiki explains the machinery: project shape, hardware limits, art conversion, audio timing, build evidence, release verification, and the companion SwanSong Desktop lane.

Start here

If you want to…	Read…
Install the toolchain and build a game	Getting Started
Understand the folders and tracked artifacts	Repository Map
Develop, draft, revise, and approve a strong novel	Light Novel Framework
Write nodes, choices, flags, and endings	Story and Project Format
Make sprites and backgrounds that survive 224×144	Graphics Pipeline
Compose tracker cues without timing surprises	Audio and Timing
Build, test, package, and verify a ROM	Build, Test, and Release
Debug exhaustive routes, saves, audio, or input	SwanSong Playtesting and Debugging
Bind a ROM release to SwanSong Desktop evidence	SwanSong Desktop Release Lane
Diagnose common failures	Troubleshooting

The core rule

Story quality and graphics quality are product goals. A technically valid ROM does not rescue a repetitive manuscript, and a strong manuscript does not excuse weak production art. The novel framework locks causality, voice, genre pleasure, chemistry, signature moments, emotional rhythm, reader evidence, ImageGen illustration provenance, publication polish, and human approval before adaptation; the graphics pipeline then protects the result at handheld scale.

The Forge therefore keeps creative and technical evidence together:

• editable .wscvn.json projects;
• prose-first novel.json manifests and manuscripts;
• causal scene plans, delight/rhythm maps, revision ledgers, reports, scorecards, reader tests, and EPUB/PDF proofs;
• approved source art and runtime-ready assets;
• native-size review sheets;
• build, emulator, playthrough, and release reports;
• hash-bound packages that prove which files produced the shipped ROM.

Two products, one release story

Story Forge builds and proves the game. SwanSong Desktop provides a native macOS player and an additional deterministic compatibility lane. A coordinated release can bind the exact ROM hash to the exact app build without confusing “booted,” “reached video,” and “fully compatible.”

The normal game ship command now drives every reachable compiled route through SwanSong, validates its native audio stream, replays a save state, and proves save/settings persistence across a fresh engine instance before packaging.

Safety boundary

This project is for original and homebrew work. Commercial ROMs, firmware, System Startup Files, save states, and private owned-game diagnostics do not belong in the public repository or release archives.