Getting Started

Getting Started

Requirements

• Python 3
• Pillow
• Wonderful Toolchain with the WonderSwan target
• SwanSong Desktop, or a local SwanSong build, for the required compiled-route gate
• Git
• Mednafen and/or Mesen for complementary independent emulator proof

The repository expects Wonderful Toolchain at /opt/wonderful by default. You can override tool locations through the environment when your installation is different.

Clone and inspect

git clone https://github.com/RegionallyFamous/swansong-story-forge.git
cd swansong-story-forge
python3 scripts/doctor_story_forge.py

The doctor checks the toolchain, reusable guards, the canonical Codex skill, the reusable novel framework, the Signal Before Dawn vertical slice, and discovered games/<slug> projects.

Start a light novel

python3 scripts/create_light_novel_project.py tea-at-platform-zero \
  --title "Tea at Platform Zero" \
  --genre-profile cozy-comedy \
  --series-id platform-zero
python3 scripts/check_light_novel_project.py \
  novels/tea-at-platform-zero/novel.json \
  --stage concept

Develop the book through the concept, outline, draft, revision, and release gates. Read Light Novel Framework before drafting or commissioning production illustrations. The untouched starter is intentionally incomplete and should fail its first gate until real creative decisions replace the prompts. Revision adds voice/prose/momentum reports and unprimed readers; release requires approved ImageGen art plus inspected EPUB/PDF proofs.

Build an included game

python3 scripts/build_wscvn_game.py soft-click-sunday

The generic builder creates or refreshes the game-local runtime, validates the project and assets, converts the JSON, compiles the ROM, runs emulator smoke, and writes game-local reports.

Ship an included game

python3 scripts/ship_wscvn_game.py soft-click-sunday

This is the normal shareable path. It rebuilds, discovers and plays every reachable route in SwanSong, validates native audio, save-state replay, restart persistence and player settings, packages, verifies the package against the live game tree, and writes a ship report.

To test against a fresh local SwanSong bundle instead of the installed app:

python3 scripts/ship_wscvn_game.py soft-click-sunday \
  --swansong-dylib /path/to/SwanSong.app/Contents/Frameworks/libSwanAresEngine.dylib

Build the flagship vertical slice

python3 scripts/build_signal_before_dawn_slice.py

Signal Before Dawn exercises the deepest graphics, text, visual, audio, story, emulator, and release-evidence gates in the repository.

Ask what can ship

python3 scripts/status_story_forge.py \
  --no-write \
  --check-index CURRENT_RELEASES.md

Use CURRENT_RELEASES.md as the human-facing shelf. It records current ROMs, release archives, checksums, preview evidence, and explicitly pending gates.

Where outputs go

• Shared flagship assets and reports: assets/signal-before-dawn-slice/
• Generic game assets and reports: games/<slug>/assets/ and games/<slug>/reports/
• SwanSong route captures and native audio: games/<slug>/assets/swansong-playthrough/
• Local build runtime: runtime-local/ or games/<slug>/runtime-local/
• Novel source and editorial evidence: novels/<slug>/
• Release packages: releases/ or games/<slug>/releases/

ROMs, release archives, runtime snapshots, and other rebuildable payloads stay out of Git. Approved source art, runtime-ready art, authored projects, and current proof reports belong in Git.

Next

Read Light Novel Framework before creating or substantially rewriting a story, Repository Map before adding a game, and Graphics Pipeline before generating or converting art. Read SwanSong Playtesting and Debugging before changing runtime input, save data, settings, or the ship gate.