romdev-mcp 0.1.1

package/examples/gba/templates/maxmod_demo.c

@@ -0,0 +1,105 @@
+/* ── maxmod_demo.c — Game Boy Advance maxmod music demo (R34) ───────
+ *
+ * Plays a CC0 tracker module compiled into a Maxmod soundbank.
+ * Demonstrates the canonical Maxmod boot dance:
+ *
+ *   1. Hook mmVBlank into the VBlank IRQ slot — Maxmod's per-frame
+ *      mixer state advance depends on this firing every vblank.
+ *   2. Call mmInitDefault(soundbank, channels) once at boot.
+ *   3. Call mmFrame() once per frame (anywhere outside the IRQ).
+ *   4. mmStart(MOD_<NAME>_FROM_HEADER, mode) to begin playback.
+ *
+ * Build via romdev:
+ *   buildSource({
+ *     platform: "gba",
+ *     language: "c",
+ *     source:   <this file>,
+ *     maxmod:   true,
+ *     binaryIncludes: { "soundbank.bin": <bytes from chiptune_soundbank.bin> }
+ *   })
+ *
+ * The maxmod link is opt-in via `maxmod: true`. The soundbank.bin must
+ * be pre-built on the developer's machine with the bundled host tool:
+ *
+ *   build/maxmod/host/mmutil chiptune.xm -osoundbank.bin -hsoundbank.h
+ *
+ * (Source .xm tracker module + Node-based regenerator both live under
+ *  src/platforms/gba/lib/maxmod/music/ — see make_chiptune_xm.js. The
+ *  buildGbaC layer auto-emits a `.incbin "soundbank.bin"` asm stub
+ *  exposing the soundbank under the global symbol `soundbank_bin`.)
+ *
+ * Why we don't include "soundbank.h" directly: the header just defines
+ * MOD_CHIPTUNE = 0 (and similar IDs if more songs are present). We
+ * inline the constant below to keep this template self-contained when
+ * the user runs mmutil with a different .xm.
+ */
+
+#include <tonc.h>
+#include <maxmod.h>
+
+/* soundbank_bin is the symbol auto-defined by buildGbaC's incbin stub
+ * when binaryIncludes contains "soundbank.bin". Treat it as a generic
+ * byte pointer — Maxmod casts it internally. */
+extern const u8 soundbank_bin[];
+
+/* Module IDs come from the auto-generated soundbank.h. For the bundled
+ * chiptune.xm built by mmutil there is exactly one entry: MOD_CHIPTUNE = 0.
+ * Adjust if you regenerate with a differently-named .xm. */
+#define MOD_CHIPTUNE 0
+
+int main(void) {
+    /* ── IRQ setup ── Maxmod requires mmVBlank() in the VBlank slot.
+     * Without this, the mixer DMA buffers never get swapped and audio
+     * hard-locks after the first buffer fill. Single most common
+     * Maxmod gotcha. */
+    irq_init(NULL);
+    irq_add(II_VBLANK, mmVBlank);
+
+    /* TTE setup so we can show a status banner. Standard Tonc setup. */
+    tte_init_chr4c_default(0, BG_CBB(0) | BG_SBB(31));
+    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0;
+
+    tte_write("#{P:24,32}");
+    tte_write("Maxmod demo");
+    tte_write("#{P:24,52}");
+    tte_write("music playing");
+    tte_write("#{P:24,80}");
+    tte_write("Press START to");
+    tte_write("#{P:24,96}");
+    tte_write("toggle playback");
+
+    /* ── Maxmod boot ─────────────────────────────────────────────────
+     * 8 channels is plenty for chip music. The library allocates
+     * channel state from its own static pool; mmInitDefault picks
+     * sensible defaults for GBA (Direct Sound A, 16384 Hz mix rate). */
+    mmInitDefault((mm_addr)soundbank_bin, 8);
+
+    /* Kick off the song in looping mode. */
+    mmStart(MOD_CHIPTUNE, MM_PLAY_LOOP);
+
+    int paused = 0;
+    int prev_keys = 0;
+
+    while (1) {
+        VBlankIntrWait();
+
+        /* Maxmod mixer step — MUST be called once per frame from main
+         * context (not from IRQ). The vblank IRQ handler (mmVBlank)
+         * only flips the double buffers; the actual song advance + new
+         * sample generation happens here. */
+        mmFrame();
+
+        /* Edge-detect START to toggle pause. key_poll-based input would
+         * also work, but raw REG_KEYS keeps this template's runtime
+         * deps to just <maxmod.h> + <tonc.h> with no extra setup. */
+        int keys = ~REG_KEYS & KEY_ANY;
+        int rising = keys & ~prev_keys;
+        if (rising & KEY_START) {
+            paused ^= 1;
+            if (paused) mmPause();
+            else        mmResume();
+        }
+        prev_keys = keys;
+    }
+    return 0;
+}

package/examples/gba/templates/platformer.c

@@ -0,0 +1,215 @@
+/* ── platformer.c — Game Boy Advance Tonc SIDE-SCROLLING platformer ──
+ *
+ * A horizontally scrolling platformer: the world is 512 px wide, BG0
+ * uses a 64x32 map (so the whole world fits with no streaming), the
+ * camera follows the player via REG_BG0HOFS, and the HUD lives on BG1
+ * which we leave un-scrolled. Gravity, jump, land-on-top collision
+ * against a static platform list in WORLD coords.
+ *
+ * Physics is fixed-point: x/y in 1/16-pixel subpixel units. The player
+ * sprite draws at SCREEN x = (worldX>>4) - camX.
+ *
+ * For a world WIDER than the 64x32 map (512 px) you stream the column
+ * entering view each 8-px camera step into the map's screen-blocks —
+ * see the GBA MENTAL_MODEL.md "Horizontal scrolling" section.
+ */
+
+#include <tonc.h>
+#include "gba_sfx.h"
+
+#define TILE_BLANK    0
+#define TILE_PLATFORM 1
+#define TILE_PLAYER   1   /* sprite tile 1 (sprites have their own char base) */
+
+static const u32 tile_platform[8] = {
+    0x11111111, 0x12222221, 0x12222221, 0x12222221,
+    0x12222221, 0x12222221, 0x12222221, 0x11111111,
+};
+static const u32 tile_player[8] = {
+    0x00033000, 0x00333300, 0x03333330, 0x03333330,
+    0x03333330, 0x03333330, 0x00333300, 0x00033000,
+};
+
+typedef struct { s16 x, y, w, h; } Rect;
+
+#define WORLD_W  512
+#define SCREEN_W 240
+
+/* Static platforms in WORLD PIXEL coords, spread across the 512-px world. */
+static const Rect platforms[] = {
+    {   0, 144, 512,  16 }, /* floor spans the world */
+    {  24, 112,  56,   8 },
+    { 140, 100,  64,   8 },
+    { 250,  84,  48,   8 },
+    { 360,  68,  56,   8 },
+    { 440, 120,  56,   8 },
+    { 180,  52,  48,   8 },
+};
+#define N_PLATFORMS (sizeof(platforms) / sizeof(platforms[0]))
+
+static OBJ_ATTR obj_buffer[128];
+
+static int on_platform(s16 px, s16 py) {
+    /* Returns 1 when an 8x8 player at (px, py) is standing on the
+     * top edge of any platform. */
+    for (int i = 0; i < N_PLATFORMS; i++) {
+        const Rect *p = &platforms[i];
+        if (py + 8 == p->y
+            && px + 8 > p->x
+            && px     < p->x + p->w) {
+            return 1;
+        }
+    }
+    return 0;
+}
+
+static int blocked_below(s16 px, s16 py) {
+    for (int i = 0; i < N_PLATFORMS; i++) {
+        const Rect *p = &platforms[i];
+        if (py + 8 <= p->y && py + 9 > p->y
+            && px + 8 > p->x
+            && px     < p->x + p->w) {
+            return 1;
+        }
+    }
+    return 0;
+}
+
+int main(void) {
+    /* ── BG palette (for the platform tile) ──────────────────────────
+     * pal_bg_mem[i] is the BG palette. */
+    pal_bg_mem[0] = CLR_BLACK;
+    pal_bg_mem[1] = CLR_GRAY;       /* platform edge */
+    pal_bg_mem[2] = RGB15(8, 8, 12);/* platform fill */
+
+    /* ── Sprite palette ──────────────────────────────────────────────
+     * Sprite palette 0, colour 3 = red player. */
+    pal_obj_mem[3] = CLR_RED;
+
+    /* ── BG tiles ─ char base 0 ─ */
+    tonccpy(&tile_mem[0][TILE_PLATFORM], tile_platform, sizeof(tile_platform));
+
+    /* ── Sprite tiles ─ char base 4 ─ */
+    tonccpy(&tile_mem[4][TILE_PLAYER], tile_player, sizeof(tile_player));
+
+    /* ── BG0 control ── char-block 0, 64x32 map (= 512x256 px, fits the
+     * whole world). A 64x32 map occupies TWO screen-blocks (28 and 29);
+     * BG1's HUD sits at SBB 30, clear of it. ── */
+    REG_BG0CNT = BG_CBB(0) | BG_SBB(28) | BG_REG_64x32 | BG_4BPP;
+
+    /* Draw platforms into the 64x32 map. A 64-wide map is laid out as two
+     * 32x32 screen-blocks side by side: the left 32 cols in SBB 28, the
+     * right 32 cols in SBB 29. se_index() handles that mapping for us, but
+     * we can address it as a flat 64-wide grid via the helper below. */
+    SCR_ENTRY *sbbL = se_mem[28];
+    SCR_ENTRY *sbbR = se_mem[29];
+    #define MAP_SET(tx, ty, se) do {                                   \
+        if ((tx) < 32) sbbL[(ty) * 32 + (tx)] = (se);                  \
+        else           sbbR[(ty) * 32 + ((tx) - 32)] = (se);           \
+    } while (0)
+    for (int ty = 0; ty < 32; ty++)
+        for (int tx = 0; tx < 64; tx++)
+            MAP_SET(tx, ty, SE_BUILD(TILE_BLANK, 0, 0, 0));
+    for (int i = 0; i < N_PLATFORMS; i++) {
+        const Rect *p = &platforms[i];
+        int tx0 = p->x >> 3, ty0 = p->y >> 3;
+        int tw  = (p->w + 7) >> 3, th = (p->h + 7) >> 3;
+        for (int dy = 0; dy < th; dy++)
+            for (int dx = 0; dx < tw; dx++) {
+                int tx = tx0 + dx, ty = ty0 + dy;
+                if (tx < 64 && ty < 32) MAP_SET(tx, ty, SE_BUILD(TILE_PLATFORM, 0, 0, 0));
+            }
+    }
+
+    oam_init(obj_buffer, 128);
+
+    /* IRQ setup — required for VBlankIntrWait() to function. */
+    irq_init(NULL);
+    irq_add(II_VBLANK, NULL);
+
+    sfx_init();
+
+    /* ── TTE for hint text on a SECOND BG ────────────────────────────
+     * BG1 at screen-block 30, char-block 2 (TTE chr4c packs glyphs
+     * starting around tile 0 of its char-block). */
+    tte_init_chr4c_default(1, BG_CBB(2) | BG_SBB(30));
+    tte_write("#{P:64,8}D-PAD MOVE  A JUMP");
+
+    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0 | DCNT_BG1 | DCNT_OBJ | DCNT_OBJ_1D;
+
+    /* Subpixel state — 1 pixel = 16 subpixels. WORLD coords. */
+    s32 px = 32 << 4, py = 60 << 4;
+    s32 vx = 0,       vy = 0;
+    s32 camX = 0;
+
+    const s32 GRAVITY    = 12;
+    const s32 MOVE_SPEED = 24;
+    const s32 JUMP_VEL   = -200;
+    const s32 MAX_FALL   = 320;
+
+    u16 prev = 0;
+
+    while (1) {
+        VBlankIntrWait();
+        key_poll();
+
+        vx = 0;
+        if (key_held(KEY_LEFT))  vx = -MOVE_SPEED;
+        if (key_held(KEY_RIGHT)) vx =  MOVE_SPEED;
+
+        s16 ipx = px >> 4;
+        s16 ipy = py >> 4;
+        int grounded = on_platform(ipx, ipy);
+
+        u16 now = key_curr_state();
+        if ((now & KEY_A) && !(prev & KEY_A) && grounded) {
+            vy = JUMP_VEL;
+            sfx_tone(1, 1500, 6);   /* boing */
+        }
+        prev = now;
+
+        vy += GRAVITY;
+        if (vy > MAX_FALL) vy = MAX_FALL;
+        if (grounded && vy > 0) vy = 0;
+
+        /* Horizontal — clamp to the world (it scrolls now, no wrap). */
+        px += vx;
+        if (px < 0) px = 0;
+        if (px > ((WORLD_W - 8) << 4)) px = (WORLD_W - 8) << 4;
+
+        /* Vertical with platform-stop. */
+        s32 np = py + vy;
+        s16 npy = np >> 4;
+        if (vy > 0 && blocked_below(ipx, ipy)) {
+            for (int i = 0; i < N_PLATFORMS; i++) {
+                const Rect *p = &platforms[i];
+                if (ipy + 8 <= p->y && npy + 8 >= p->y
+                    && ipx + 8 > p->x && ipx < p->x + p->w) {
+                    py = (p->y - 8) << 4;
+                    vy = 0;
+                    sfx_tone(2, 800, 3);   /* thud */
+                    goto done_y;
+                }
+            }
+        }
+        py = np;
+        if (py > (160 << 4)) { py = 0; vy = 0; }
+done_y:
+
+        /* Camera follows player, centered, clamped to the world. Write the
+         * BG0 horizontal scroll offset. BG1 (HUD) is left un-scrolled. */
+        camX = (px >> 4) - (SCREEN_W / 2 - 4);
+        if (camX < 0) camX = 0;
+        if (camX > WORLD_W - SCREEN_W) camX = WORLD_W - SCREEN_W;
+        REG_BG0HOFS = camX;
+
+        /* Player sprite drawn in SCREEN space = world - camera. */
+        obj_set_attr(&obj_buffer[0],
+            ATTR0_SQUARE,
+            ATTR1_SIZE_8,
+            ATTR2_PALBANK(0) | TILE_PLAYER);
+        obj_set_pos(&obj_buffer[0], (px >> 4) - camX, py >> 4);
+        oam_copy(oam_mem, obj_buffer, 1);
+    }
+    return 0;
+}

package/examples/gba/templates/puzzle.c

@@ -0,0 +1,237 @@
+/* ── puzzle.c — Game Boy Advance Tonc match-3 falling-block scaffold ─
+ *
+ * 6-wide x 12-tall grid. A 1x3 active piece (3 colours, randomly
+ * chosen from the cell palette) drops from the top; LEFT/RIGHT
+ * shifts, A rotates the colour order, DOWN soft-drops, START
+ * triggers a hard-drop. Horizontal triples clear and bump score.
+ *
+ * The grid lives in plain RAM (u8 grid[12][6]) and is drawn into BG0's
+ * 32x32 tile map. We redraw on landings + clears, not every frame.
+ *
+ * Cell size: 8x8 (one BG tile per cell). Grid origin at tile (4, 2)
+ * so the playfield sits at pixel (32, 16) with room for score above
+ * and instructions below.
+ *
+ * Cells:
+ *   0 = empty       1 = red       2 = green       3 = blue
+ *
+ * Yours to extend: vertical-triple clear, T/L shape pieces, gravity
+ * after clears (current code just deletes; no settle), game-over.
+ */
+
+#include <tonc.h>
+#include "gba_sfx.h"
+
+#define COLS 6
+#define ROWS 12
+
+#define TILE_BLANK 0
+#define TILE_RED   1
+#define TILE_GREEN 2
+#define TILE_BLUE  3
+
+/* Grid origin in BG-tile coords. */
+#define GRID_TX 4
+#define GRID_TY 2
+
+static const u32 tile_red[8] = {
+    0x11111111, 0x11111111, 0x11111111, 0x11111111,
+    0x11111111, 0x11111111, 0x11111111, 0x11111111,
+};
+static const u32 tile_green[8] = {
+    0x22222222, 0x22222222, 0x22222222, 0x22222222,
+    0x22222222, 0x22222222, 0x22222222, 0x22222222,
+};
+static const u32 tile_blue[8] = {
+    0x33333333, 0x33333333, 0x33333333, 0x33333333,
+    0x33333333, 0x33333333, 0x33333333, 0x33333333,
+};
+
+static u8 grid[ROWS][COLS];
+
+static u8 piece[3];
+static s16 piece_x;
+static s16 piece_y;
+static u16 fall_timer;
+static u16 score;
+static u32 rng_state = 1;
+
+static u32 xorshift(void) {
+    rng_state ^= rng_state << 13;
+    rng_state ^= rng_state >> 17;
+    rng_state ^= rng_state << 5;
+    return rng_state;
+}
+
+static u8 random_colour(void) { return 1 + (xorshift() % 3); }
+
+static void new_piece(void) {
+    piece[0] = random_colour();
+    piece[1] = random_colour();
+    piece[2] = random_colour();
+    piece_x = COLS / 2 - 1;
+    piece_y = -3;
+}
+
+static int tile_for(u8 cell) {
+    switch (cell) {
+        case 1: return TILE_RED;
+        case 2: return TILE_GREEN;
+        case 3: return TILE_BLUE;
+        default: return TILE_BLANK;
+    }
+}
+
+static void draw_cell(int col, int row) {
+    if (row < 0 || row >= ROWS) return;
+    u8 v = grid[row][col];
+    SCR_ENTRY *map = se_mem[28];
+    map[(GRID_TY + row) * 32 + (GRID_TX + col)] =
+        SE_BUILD(tile_for(v), 0, 0, 0);
+}
+
+static void draw_grid(void) {
+    for (int r = 0; r < ROWS; r++)
+        for (int c = 0; c < COLS; c++)
+            draw_cell(c, r);
+}
+
+static void draw_piece(int col, int row, int clear) {
+    /* Transient overlay: when clearing, restore from grid (so we don't
+     * blow away locked cells behind the piece). */
+    SCR_ENTRY *map = se_mem[28];
+    for (int i = 0; i < 3; i++) {
+        int r = row + i;
+        if (r < 0 || r >= ROWS) continue;
+        u8 v = clear ? grid[r][col] : piece[i];
+        map[(GRID_TY + r) * 32 + (GRID_TX + col)] =
+            SE_BUILD(tile_for(v), 0, 0, 0);
+    }
+}
+
+static int collides(int col, int row) {
+    if (col < 0 || col >= COLS) return 1;
+    for (int i = 0; i < 3; i++) {
+        int r = row + i;
+        if (r >= ROWS) return 1;
+        if (r >= 0 && grid[r][col] != 0) return 1;
+    }
+    return 0;
+}
+
+static void lock_piece(void) {
+    for (int i = 0; i < 3; i++) {
+        int r = piece_y + i;
+        if (r >= 0 && r < ROWS) grid[r][piece_x] = piece[i];
+    }
+    /* Horizontal triples on the affected rows. */
+    for (int i = 0; i < 3; i++) {
+        int r = piece_y + i;
+        if (r < 0 || r >= ROWS) continue;
+        for (int c = 0; c <= COLS - 3; c++) {
+            u8 a = grid[r][c], b = grid[r][c + 1], d = grid[r][c + 2];
+            if (a != 0 && a == b && b == d) {
+                grid[r][c]     = 0;
+                grid[r][c + 1] = 0;
+                grid[r][c + 2] = 0;
+                if (score < 65500) score += 30;
+                sfx_tone(1, 1700, 10);  /* triple-clear chime */
+            }
+        }
+    }
+    draw_grid();
+}
+
+int main(void) {
+    /* TTE first — it may touch pal_bg_mem + REG_BG#CNT, so set up
+     * our BG0 grid resources AFTER its init runs. */
+    tte_init_chr4c_default(1, BG_CBB(2) | BG_SBB(30));
+    tte_write("#{P:88,8}SCORE 00000");
+    tte_write("#{P:8,148}LR MOVE  A ROT  START DROP");
+
+    /* BG palette for grid cells. */
+    pal_bg_mem[0] = CLR_BLACK;
+    pal_bg_mem[1] = CLR_RED;
+    pal_bg_mem[2] = CLR_LIME;
+    pal_bg_mem[3] = CLR_BLUE;
+
+    /* BG tile graphics in char-block 3 (separate from TTE which used 2). */
+    tonccpy(&tile_mem[3][TILE_RED],   tile_red,   sizeof(tile_red));
+    tonccpy(&tile_mem[3][TILE_GREEN], tile_green, sizeof(tile_green));
+    tonccpy(&tile_mem[3][TILE_BLUE],  tile_blue,  sizeof(tile_blue));
+
+    /* Clear screen-block 28 (BG0 map). */
+    SCR_ENTRY *map = se_mem[28];
+    for (int i = 0; i < 32 * 32; i++) map[i] = SE_BUILD(TILE_BLANK, 0, 0, 0);
+
+    REG_BG0CNT = BG_CBB(3) | BG_SBB(28) | BG_REG_32x32 | BG_4BPP | BG_PRIO(0);
+    /* Bump TTE's BG1 to a LOWER priority so the grid (BG0, prio 0) renders
+     * in front. (Higher prio number = drawn behind.) */
+    REG_BG1CNT |= BG_PRIO(1);
+
+    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0 | DCNT_BG1;
+
+    for (int r = 0; r < ROWS; r++)
+        for (int c = 0; c < COLS; c++)
+            grid[r][c] = 0;
+
+    score = 0;
+    fall_timer = 0;
+
+    /* IRQ setup — required for VBlankIntrWait() to function. */
+    irq_init(NULL);
+    irq_add(II_VBLANK, NULL);
+
+    sfx_init();
+    new_piece();
+    draw_grid();
+
+    u16 prev = 0;
+
+    while (1) {
+        VBlankIntrWait();
+        key_poll();
+
+        u16 now = key_curr_state();
+
+        /* Erase the active piece visual. */
+        draw_piece(piece_x, piece_y, 1);
+
+        if ((now & KEY_LEFT) && !(prev & KEY_LEFT)
+            && !collides(piece_x - 1, piece_y)) piece_x--;
+        if ((now & KEY_RIGHT) && !(prev & KEY_RIGHT)
+            && !collides(piece_x + 1, piece_y)) piece_x++;
+        if ((now & KEY_A) && !(prev & KEY_A)) {
+            u8 t = piece[0]; piece[0] = piece[1]; piece[1] = piece[2]; piece[2] = t;
+            sfx_tone(2, 1400, 3);   /* rotate click */
+        }
+        if ((now & KEY_START) && !(prev & KEY_START)) {
+            while (!collides(piece_x, piece_y + 1)) piece_y++;
+            lock_piece();
+            new_piece();
+            prev = now;
+            tte_erase_rect(88 + 6*8, 8, 88 + 11*8, 16);
+            tte_printf("#{P:%d,8}%05d", 88 + 6*8, score);
+            continue;
+        }
+        prev = now;
+
+        u16 fall_rate = (now & KEY_DOWN) ? 4 : 30;
+        if (++fall_timer >= fall_rate) {
+            fall_timer = 0;
+            if (collides(piece_x, piece_y + 1)) {
+                lock_piece();
+                new_piece();
+            } else {
+                piece_y++;
+            }
+        }
+
+        /* Re-draw piece in its new position. */
+        draw_piece(piece_x, piece_y, 0);
+
+        tte_erase_rect(88 + 6*8, 8, 88 + 11*8, 16);
+        tte_printf("#{P:%d,8}%05d", 88 + 6*8, score);
+    }
+    return 0;
+}