fix(sdk): Add NES Famitone2 (sound/music) support

* nesdoug: full-game example
* nesdoug: mm3-music example

Author: kassane

.github/full-game.gif

@@ -83,6 +83,7 @@ jobs:
             mmc1-hello.nes mmc1-sprites.nes \
             mmc3-hello.nes mmc3-pads.nes \
             gtrom-hello.nes gtrom-color-cycle.nes \
+            nesdoug-mmc3.nes full-game.nes \
             action53-hello.nes fds-hello.fds \
             c64-hello.prg fibonacci.prg plasma.prg \
             vic20-hello.prg \
@@ -151,7 +152,8 @@ jobs:
                    cnrom-hello.nes cnrom-sprites.nes \
                    unrom-hello.nes unrom-512-hello.nes unrom-color-cycle.nes \
                    mmc1-hello.nes mmc1-sprites.nes \
-                   mmc3-hello.nes mmc3-pads.nes; do
+                   mmc3-hello.nes mmc3-pads.nes \
+                   nesdoug-mmc3.nes full-game.nes; do
             smoke "$f"
           done
           # Note: gtrom-hello.nes / gtrom-color-cycle.nes (mapper 111) are NOT tested here —
@@ -255,6 +257,7 @@ jobs:
                    unrom-hello.nes unrom-512-hello.nes unrom-color-cycle.nes \
                    mmc1-hello.nes mmc1-sprites.nes \
                    mmc3-hello.nes mmc3-pads.nes \
+                   nesdoug-mmc3.nes full-game.nes \
                    gtrom-hello.nes gtrom-color-cycle.nes; do
             run_emutest "$f" mesen_libretro.so
           done

.github/nesdoug-mmc3.gif

@@ -48,6 +48,8 @@ zig build nes-gtrom-color-cycle
 zig build nes-unrom-512-hello
 zig build nes-action53-hello
 zig build fds-hello
+zig build nes-nesdoug-mmc3
+zig build nes-full-game
 
 # Commodore 64
 zig build c64-hello
@@ -159,6 +161,8 @@ Output files land in `zig-out/bin/`.
 | `nes-unrom-512-hello` — UNROM-512 mapper (mapper 30) | |
 | `nes-action53-hello` — Action53 multicart (mapper 28) | |
 | `fds-hello` — Famicom Disk System backdrop hello | |
+| `nes-nesdoug-mmc3` — MMC3 demo: banked_call, FamiTone2 music, mid-screen IRQ splits, WRAM | ![](.github/nesdoug-mmc3.gif) |
+| `nes-full-game` — scrolling platformer (MMC3): player, enemies, coins, collectibles, 3 levels | ![](.github/full-game.gif) |
 
 ### SNES
 
@@ -209,6 +213,8 @@ Output files land in `zig-out/bin/`.
 | `nes-unrom-512-hello` | NES UNROM-512 | mos6502 | `.nes` |
 | `nes-action53-hello` | NES Action53 (mapper 28) | mos6502 | `.nes` |
 | `fds-hello` | Famicom Disk System | mos6502 | `.fds` |
+| `nes-nesdoug-mmc3` | NES MMC3 (nesdoug demo) | mos6502 | `.nes` |
+| `nes-full-game` | NES MMC3 scrolling platformer | mos6502 | `.nes` |
 | `c64-hello`, `c64-fibonacci` | Commodore 64 | mos6502 | `.prg` |
 | `c64-plasma` | Commodore 64 | mos6502 | `.prg` |
 | `vic20-hello` | Commodore VIC-20 (24K) | mos6502 | `.prg` |
@@ -390,6 +396,8 @@ The `gen-labels` build step runs this automatically for all NES examples.
 - **NES GTROM colour-cycle** — GTROM PRG bank cycling with LED toggle via `$5000` write.
 - **NES UNROM-512 hello** — uses translated `mapper.h`; calls `set_prg_bank(0)` and `set_chr_bank(0)` to initialise mapper 30 registers. ROM: 512 KB PRG + 32 KB CHR RAM.
 - **NES Action53 hello** — uses translated `mapper.h`; mapper 28 (Action53 multicart). ROM: 64 KB PRG + 8 KB CHR RAM.
+- **NES nesdoug MMC3** — MMC3 demo ported from Doug Fraker's nesdoug-llvm tutorial (chapter 33); exercises `banked_call`, FamiTone2 music playback, mid-screen IRQ colour splits, and WRAM read/write. Includes a Mesen2 testRunner script (`mmc3.lua`) that verifies NMI running, sprite position, and VRAM writes within 120 frames.
+- **NES full-game** — scrolling platformer (chapter 26 port); player movement, enemies, coins, collectibles, score display, and 3 levels. MMC3 mapper with FamiTone2 music; uses nesdoug VRAM buffer for HUD updates.
 - **FDS hello** — Famicom Disk System; uses raw PPU register writes via `nes/hardware.zig` (no neslib — FDS has no CHR ROM, raw PPU only). Writes dark-green backdrop (`$1A`) to palette `$3F00`.
 - **VIC-20 hello** — uses CBM KERNAL `cbm_k_chrout` to print "HELLO VIC20!", then cycles VIC chip background/border colour register (`$900F`). Targets 24K memory expansion, loads at `$1201`.
 - **C64 hello** — uses translated `c64.h` (VIC-II typed struct) via `b.addTranslateC`; cycles VIC-II border colour register.

.github/workflows/ci.yml

@@ -49,8 +49,7 @@ pub fn build(b: *std.Build) void {
         break :blk buf;
     };
 
-    const optimize = b.option(std.builtin.OptimizeMode, "optimize", "Optimize mode for target platform executables (default: ReleaseFast)") orelse .ReleaseFast;
-
+    const optimize = b.standardOptimizeOption(.{});
     // ---- SDK build from source (llvm-mos-sdk git) ----
     const sdk_step = b.step("sdk-build", "Build llvm-mos-sdk platform libraries from source");
 
@@ -476,6 +475,21 @@ pub fn build(b: *std.Build) void {
         addNesLabels(b, elf2mlb, gen_labels, exe, "gg-demo");
     }
 
+    // ---- NES full-game ----
+    {
+        const step = b.step("nes-full-game", "Build NES full game (CH26 port: scrolling platformer, coins, enemies, 3 levels)");
+        const exe = addNesExe(b, sdk_dep, sdk_src, sdk_libs, optimize, "full-game", "nes/nesdoug/full-game/full_game.zig", .{ .chr_src = "nes/nesdoug/full-game/full_game.chr", .with_nesdoug = true, .with_famitone2 = true });
+        exe.root_module.addImport("neslib", neslib_mod);
+        exe.root_module.addImport("nesdoug", nesdoug_mod);
+        exe.root_module.addIncludePath(b.path("nes/nesdoug/mmc3"));
+        exe.root_module.addAssemblyFile(b.path("nes/nesdoug/full-game/music.s"));
+        const install = b.addInstallArtifact(exe, .{ .dest_sub_path = "full-game.nes" });
+        step.dependOn(&install.step);
+        b.getInstallStep().dependOn(&install.step);
+        run_bininfo.addFileArg(exe.getEmittedBin());
+        addNesLabels(b, elf2mlb, gen_labels, exe, "full-game");
+    }
+
     // ---- C64 hello ----
     {
         const step = b.step("c64-hello", "Build C64 hello example");
@@ -842,6 +856,41 @@ pub fn build(b: *std.Build) void {
         run_bininfo.addFileArg(exe.getEmittedBin());
     }
 
+    // ---- NES MMC3 nesdoug demo (banked_call, IRQ splits, FamiTone2, WRAM) ----
+    {
+        const step = b.step("nes-nesdoug-mmc3", "Build NES MMC3 nesdoug demo (banked_call, IRQ splits, FamiTone2 music, WRAM)");
+        const exe = addNesExe(b, sdk_dep, sdk_src, sdk_libs, optimize, "nesdoug-mmc3", "nes/nesdoug/mmc3/mmc3.zig", .{
+            .mapper = .mmc3,
+            .with_nesdoug = true,
+            .with_famitone2 = true,
+            .chr_rom_kb = 16, // Alpha.chr (8KB) + Gears.chr (8KB)
+        });
+        // CHR ROM: both .chr files in a single .chr_rom section.
+        const chr_wf = b.addWriteFiles();
+        const root_fwd_mmc3: []const u8 = blk: {
+            const p = b.build_root.path orelse ".";
+            const buf = b.allocator.dupe(u8, p) catch @panic("OOM");
+            std.mem.replaceScalar(u8, buf, '\\', '/');
+            break :blk buf;
+        };
+        const chr_asm = chr_wf.add("chr-rom-mmc3.s", b.fmt(
+            \\.section .chr_rom,"a",@progbits
+            \\.incbin "{s}/nes/nesdoug/mmc3/Alpha.chr"
+            \\.incbin "{s}/nes/nesdoug/mmc3/Gears.chr"
+        , .{ root_fwd_mmc3, root_fwd_mmc3 }));
+        exe.root_module.addAssemblyFile(chr_asm);
+        // Music and sound-effect data in PRG ROM bank 12.
+        exe.root_module.addIncludePath(b.path("nes/nesdoug/mmc3"));
+        exe.root_module.addAssemblyFile(b.path("nes/nesdoug/mmc3/music.s"));
+        exe.root_module.addImport("neslib", neslib_mod);
+        exe.root_module.addImport("nesdoug", nesdoug_mod);
+        exe.root_module.addImport("mapper", nes_mmc3_mapper_mod);
+        const install = b.addInstallArtifact(exe, .{ .dest_sub_path = "nesdoug-mmc3.nes" });
+        step.dependOn(&install.step);
+        b.getInstallStep().dependOn(&install.step);
+        run_bininfo.addFileArg(exe.getEmittedBin());
+    }
+
     // ---- NES GTROM colour-cycle with LED ----
     {
         const step = b.step("nes-gtrom-color-cycle", "Build NES GTROM mapper colour-cycle with LED example");
@@ -1190,7 +1239,9 @@ fn addNesExe(
         mapper: NesMapper = .nrom,
         chr_src: ?[]const u8 = null,
         chr_srcs: ?[]const []const u8 = null,
+        chr_rom_kb: usize = 0,
         with_nesdoug: bool = false,
+        with_famitone2: bool = false,
     },
 ) *std.Build.Step.Compile {
     const target = b.resolveTargetQuery(.{ .cpu_arch = .mos, .os_tag = .nes });
@@ -1299,17 +1350,21 @@ fn addNesExe(
             \\__chr_ram_size = 8;
             \\INCLUDE "{s}/mos-platform/nes-mmc1/link.ld"
         , .{ reset_dir, sdk_src, sdk_src, sdk_src, sdk_src, sdk_src })),
-        .mmc3 => wf.add(ld_name, b.fmt(
-            \\SEARCH_DIR("{s}");
-            \\SEARCH_DIR("{s}/mos-platform/nes-mmc3");
-            \\SEARCH_DIR("{s}/mos-platform/nes");
-            \\SEARCH_DIR("{s}/mos-platform/nes/rompoke");
-            \\SEARCH_DIR("{s}/mos-platform/common/ldscripts");
-            \\/* MMC3 hello uses CHR RAM; override the 256 KiB CHR ROM weak default. */
-            \\__chr_rom_size = 0;
-            \\__chr_ram_size = 8;
-            \\INCLUDE "{s}/mos-platform/nes-mmc3/link.ld"
-        , .{ reset_dir, sdk_src, sdk_src, sdk_src, sdk_src, sdk_src })),
+        .mmc3 => blk: {
+            const chr_cfg = if (cfg.chr_rom_kb > 0)
+                b.fmt("__chr_rom_size = {d};\n__chr_ram_size = 0;", .{cfg.chr_rom_kb})
+            else
+                "/* MMC3 uses CHR RAM; override the 256 KiB CHR ROM weak default. */\n__chr_rom_size = 0;\n__chr_ram_size = 8;";
+            break :blk wf.add(ld_name, b.fmt(
+                \\SEARCH_DIR("{s}");
+                \\SEARCH_DIR("{s}/mos-platform/nes-mmc3");
+                \\SEARCH_DIR("{s}/mos-platform/nes");
+                \\SEARCH_DIR("{s}/mos-platform/nes/rompoke");
+                \\SEARCH_DIR("{s}/mos-platform/common/ldscripts");
+                \\{s}
+                \\INCLUDE "{s}/mos-platform/nes-mmc3/link.ld"
+            , .{ reset_dir, sdk_src, sdk_src, sdk_src, sdk_src, chr_cfg, sdk_src }));
+        },
         .gtrom => wf.add(ld_name, b.fmt(
             \\SEARCH_DIR("{s}");
             \\SEARCH_DIR("{s}/mos-platform/nes-gtrom");
@@ -1387,6 +1442,7 @@ fn addNesExe(
     exe.root_module.linkLibrary(libs.c);
     if (libs.neslib) |neslib| exe.root_module.linkLibrary(neslib);
     if (cfg.with_nesdoug) if (libs.nesdoug) |nd| exe.root_module.linkLibrary(nd);
+    if (cfg.with_famitone2) if (libs.famitone2) |ft2| exe.root_module.linkLibrary(ft2);
     if (libs.nes_c) |nc| exe.root_module.linkLibrary(nc);
     if (libs.nes_c_startup) |ncs| exe.root_module.linkLibrary(ncs);
     exe.setLinkerScript(wrapper_ld);
@@ -2283,6 +2339,7 @@ fn addEaterExe(
     exe.root_module.linkLibrary(libs.crt0);
     exe.root_module.linkLibrary(libs.c);
     if (libs.crt0_obj) |obj| exe.root_module.addObject(obj);
+    if (libs.mem) |mem_obj| exe.root_module.addObject(mem_obj);
     exe.forceUndefinedSymbol("__zig_call_main_section");
     exe.forceUndefinedSymbol("main");
     exe.setLinkerScript(wrapper_ld);

README.md

@@ -25,6 +25,8 @@ originally written in C for the llvm-mos toolchain.
 | `mappers/`  | 24_Mappers | CNROM 4-bank CHR demo — press Start to cycle banks           |
 | `bat-ball/` | CH05*      | Bat-and-ball from ProgrammingGamesForTheNES CH05             |
 | `megablast/` | CH13*     | Full Megablast game from ProgrammingGamesForTheNES CH13 (enemies, score, lives, levels) |
+| `mmc3/`      | 33_MMC3   | MMC3 mapper demo: banked_call, FamiTone2 music, mid-screen IRQ splits, WRAM            |
+| `full-game/` | 26_Full_Game | Scrolling platformer (MMC3): player, enemies, coins, collectibles, game states      |
 
 * `bat-ball` and `megablast` are ported from
 [tony-cruise/ProgrammingGamesForTheNES](https://github.com/tony-cruise/ProgrammingGamesForTheNES),