ビルド手順

NES ROM（UNROM / mapper 2, PRG 128KB, CHR-RAM 8KB）のビルド環境と手順。

前提ツールの導入

cc65 ツールチェーン（ca65 / ld65）を使用する。

brew install cc65
ca65 --version   # V2.18 以降を確認

ビルド

make            # build/engine.nes（ゲーム本体）を生成
make debug      # build/engine-debug.nes（デバッグメニュー付き、-D DEBUG_MENU=1）
make nromtest   # build/nrom_test.nes（NROM / mapper 0 テスト ROM、ドナー基板検証用）
make flashbin   # build/flash/{prg,chr}_512k.bin（SST39SF040 書き込み像。nromtest に依存）
make hello      # build/hello.nes（旧 Hello World）
make hex        # 先頭32バイト（iNESヘッダ含む）を xxd でダンプ
make clean      # build/ を削除

生成物:

• build/engine.nes — 131,088 バイト（iNES ヘッダ 16 + PRG 8×16KB = 131,072）
• build/engine.map / build/engine.dbg — リンカマップ・デバッグ情報（Lua テストの RAM アドレスはここから引く）
• build/nrom_test.nes — 40,976 バイト（16 + PRG 32KB + CHR 8KB）

src/bgm_data.inc / bgm_samples.inc / charts_data.inc は assets/bgm/*.json / assets/charts/charts.json から Makefile が自動生成する（手編集禁止）。プロローグ / エンディングフォントの再生成は make prologue-font / make ending-font（MISAKI_BDF に美咲フォントの BDF パスを指定）。

ビルド成否は必ず exit code で確認する（make が通っても make debug が固定バンク溢れで落ちることがある）。

テスト

python3 -m unittest discover -s tools -p 'test_*.py'   # アセット・フォント・進行モデル・flashnes（61 件）

Mesen2 用の Lua スクリプト（tests/*.lua）は BGM 再生・拍同期・ランク境界・ゲームオーバー演出を検証する（Mesen2 の Script ウィンドウから実行、emu.stop(0) が pass）。dev-workflow の E2E エビデンスは Web エミュレータ（cluade-famicom-emu）で決定的フレーム駆動して取得する。

iNES ヘッダの期待値

4e 45 53 1a 08 00 21 00 ...

• byte 0-3: NES<EOF> マジック
• byte 4: 08 = PRG-ROM 8×16KB（128KB）
• byte 5: 00 = CHR-ROM なし（CHR-RAM 8KB を使用）
• byte 6: 21 = mapper 2（上位ニブル）+ 垂直ミラーリング（bit0）

実行（Mesen2）

環境変数 MESEN に Mesen2 の実行パスを設定して make run する。

export MESEN="/Applications/Mesen.app/Contents/MacOS/Mesen"
make run

MESEN 未設定の場合は「Mesen2未設定」メッセージを表示して終了する（エラーにはならない）。

構成

src/engine.s          # ゲーム本体（ca65）
src/sound.s           # BGM ドライバ
src/*.inc             # 生成データ（スプライト・BG・フォント・BGM・譜面）
src/nrom_test.s       # NROM テスト ROM
src/hello.s           # 旧 Hello World
cfg/nes.cfg           # ld65 リンカ設定（UNROM 128KB, 全8バンク出力・$FFパディング）
cfg/nrom.cfg          # NROM 用リンカ設定
build/                # 生成物（git 管理外）

備考（UNROM バス競合）

UNROM はバンク切替時のバス競合回避回路を持たないため、$8000-$FFFF への 書き込み値は ROM 上の同アドレスの値と一致させる必要がある（ROM 内バンク テーブルに対する lda banktable,x / sta banktable,x 方式）。エンジンは BGM / 譜面 / 観客 / CHR / CLEAR 演出をバンク 0〜6 に置いており、この方式で切り替えている （エンジン設計）。