romdev-mcp 0.1.1

package/examples/gba/templates/racing.c

@@ -0,0 +1,175 @@
+/* ── racing.c — Game Boy Advance Tonc top-down racing scaffold ──────
+ *
+ * Endless top-down lane racer. Player car at the bottom of the screen,
+ * three lanes, obstacles spawn from the top and slide down. Left/Right
+ * D-pad switches lanes. Survive as long as possible — score is the
+ * frame count since the last collision.
+ *
+ * Game state:
+ *   - Player car (1 sprite) at fixed Y, X = lane_x[lane]
+ *   - 4 obstacle cars (object pool), spawning from a random lane
+ *   - Speed grows slightly with score
+ *   - On collision: 60-frame freeze then run resets
+ */
+
+#include <tonc.h>
+#include "gba_sfx.h"
+
+#define LANE_LEFT_X    56
+#define LANE_MID_X    116
+#define LANE_RIGHT_X  176
+#define PLAYER_Y      140
+#define MAX_OBSTACLES   4
+
+#define TILE_CAR_P1 1
+#define TILE_CAR_EN 2
+
+static const u32 tile_car_p1[8] = {
+    0x01111110, 0x11111111, 0x12222221, 0x11111111,
+    0x11111111, 0x12222221, 0x11111111, 0x01100110,
+};
+static const u32 tile_car_enemy[8] = {
+    0x03333330, 0x33333333, 0x34444443, 0x33333333,
+    0x33333333, 0x34444443, 0x33333333, 0x03300330,
+};
+
+typedef struct { s16 x, y; u16 alive; } Car;
+
+static OBJ_ATTR obj_buffer[128];
+
+static Car player;
+static Car obstacles[MAX_OBSTACLES];
+static u16 score;
+static u16 spawn_timer;
+static u16 game_over_timer;
+static u16 prev_keys;
+static u8  player_lane;
+
+static const s16 lane_x[3] = { LANE_LEFT_X, LANE_MID_X, LANE_RIGHT_X };
+
+static int aabb(const Car *a, const Car *b) {
+    return a->x < b->x + 8 && a->x + 8 > b->x
+        && a->y < b->y + 8 && a->y + 8 > b->y;
+}
+
+static void reset_run(void) {
+    player_lane = 1;
+    player.x = lane_x[1];
+    player.y = PLAYER_Y;
+    player.alive = 1;
+    for (int i = 0; i < MAX_OBSTACLES; i++) obstacles[i].alive = 0;
+    score = 0;
+    spawn_timer = 0;
+    game_over_timer = 0;
+}
+
+static void spawn_obstacle(void) {
+    for (int i = 0; i < MAX_OBSTACLES; i++) {
+        if (!obstacles[i].alive) {
+            obstacles[i].x = lane_x[(spawn_timer * 13) % 3];
+            obstacles[i].y = -8;
+            obstacles[i].alive = 1;
+            return;
+        }
+    }
+}
+
+int main(void) {
+    /* Sprite palettes. Bank 0 for player (white+grey), bank 1 for enemy
+     * (red+dark grey). Index 0 is always transparent. */
+    pal_obj_bank[0][1] = CLR_WHITE;
+    pal_obj_bank[0][2] = RGB15(20, 20, 20);
+    pal_obj_bank[1][3] = CLR_RED;
+    pal_obj_bank[1][4] = RGB15(12, 12, 12);
+
+    /* Sprite tiles — OBJ char base 4. */
+    tonccpy(&tile_mem[4][TILE_CAR_P1], tile_car_p1,    sizeof(tile_car_p1));
+    tonccpy(&tile_mem[4][TILE_CAR_EN], tile_car_enemy, sizeof(tile_car_enemy));
+
+    oam_init(obj_buffer, 128);
+
+    /* IRQ setup — required for VBlankIntrWait() to function. */
+    irq_init(NULL);
+    irq_add(II_VBLANK, NULL);
+
+    sfx_init();
+
+    /* TTE for score + hint. */
+    tte_init_chr4c_default(0, BG_CBB(0) | BG_SBB(31));
+    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0 | DCNT_OBJ | DCNT_OBJ_1D;
+    tte_write("#{P:160,8}SCORE 00000");
+    tte_write("#{P:64,150}L/R MOVES LANE");
+
+    reset_run();
+    prev_keys = 0;
+
+    while (1) {
+        VBlankIntrWait();
+        key_poll();
+
+        if (game_over_timer > 0) {
+            game_over_timer--;
+            if (game_over_timer == 60) {
+                tte_write("#{P:72,80}CRASH! TRY AGAIN");
+            }
+            if (game_over_timer == 0) {
+                tte_erase_rect(72, 80, 240, 96);
+                reset_run();
+            }
+        } else {
+            u16 now = key_curr_state();
+            if ((now & KEY_LEFT)  && !(prev_keys & KEY_LEFT)  && player_lane > 0) {
+                player_lane--;
+                sfx_tone(2, 1300, 2);   /* lane switch */
+            }
+            if ((now & KEY_RIGHT) && !(prev_keys & KEY_RIGHT) && player_lane < 2) {
+                player_lane++;
+                sfx_tone(2, 1300, 2);
+            }
+            player.x = lane_x[player_lane];
+            prev_keys = now;
+
+            /* Obstacle speed grows slowly with score. */
+            s16 step = 2 + (s16)(score / 500);
+            if (step > 4) step = 4;
+
+            for (int i = 0; i < MAX_OBSTACLES; i++) {
+                if (!obstacles[i].alive) continue;
+                obstacles[i].y += step;
+                if (obstacles[i].y > 160) obstacles[i].alive = 0;
+            }
+
+            if (++spawn_timer >= 32) { spawn_timer = 0; spawn_obstacle(); }
+
+            for (int i = 0; i < MAX_OBSTACLES; i++) {
+                if (obstacles[i].alive && aabb(&player, &obstacles[i])) {
+                    game_over_timer = 60;
+                    sfx_noise(30);          /* crash */
+                    break;
+                }
+            }
+
+            if (score < 65500) score++;
+        }
+
+        /* Sprite slots: 0 = player, 1..4 = obstacles. */
+        obj_set_attr(&obj_buffer[0],
+            ATTR0_SQUARE,
+            ATTR1_SIZE_8,
+            ATTR2_PALBANK(0) | TILE_CAR_P1);
+        obj_set_pos(&obj_buffer[0], player.x, player.y);
+        for (int i = 0; i < MAX_OBSTACLES; i++) {
+            s16 ey = obstacles[i].alive ? obstacles[i].y : 200;
+            obj_set_attr(&obj_buffer[1 + i],
+                ATTR0_SQUARE,
+                ATTR1_SIZE_8,
+                ATTR2_PALBANK(1) | TILE_CAR_EN);
+            obj_set_pos(&obj_buffer[1 + i], obstacles[i].x, ey);
+        }
+        oam_copy(oam_mem, obj_buffer, 1 + MAX_OBSTACLES);
+
+        tte_erase_rect(160 + 6*8, 8, 160 + 11*8, 16);
+        tte_printf("#{P:%d,8}%05d", 160 + 6*8, score);
+    }
+    return 0;
+}

package/examples/gba/templates/shmup.c

@@ -0,0 +1,197 @@
+/* ── shmup.c — Game Boy Advance Tonc vertical-shooter scaffold ──────
+ *
+ * Complete runnable vertical-shmup baseline:
+ *   - Player ship (1 sprite, d-pad moves, A fires)
+ *   - 6 bullet slots, 6 enemy slots (fixed-size object pools)
+ *   - Enemy wave spawner: one enemy from the top every ~28 frames
+ *   - Linear movement, AABB collision (8x8 vs 8x8)
+ *   - 16-bit score, rendered as text via TTE (Tonc Text Engine)
+ *
+ * Sprite slot discipline (GBA has 128 OAM entries, more than enough):
+ *   slot 0          → player
+ *   slot 1..6       → bullets
+ *   slot 7..12      → enemies
+ *   total 13 << 128 → no flicker
+ *
+ * Idiomatic Tonc frame heartbeat: VBlankIntrWait() + key_poll() at the
+ * top of every frame, oam_copy() at the bottom. Update positions in a
+ * shadow OAM buffer (obj_buffer[]); copy to hardware OAM in one DMA.
+ */
+
+#include <tonc.h>
+#include "gba_sfx.h"
+
+#define MAX_BULLETS 6
+#define MAX_ENEMIES 6
+
+#define TILE_BLANK  0
+#define TILE_SHIP   1
+#define TILE_BULLET 2
+#define TILE_ENEMY  3
+
+/* 4bpp tiles (8 rows × 32 bits each = 32 bytes). Each nibble is a
+ * palette index. Index 0 = transparent. */
+static const u32 tile_ship[8] = {
+    0x00011000, 0x00011000, 0x00111100, 0x00111100,
+    0x01111110, 0x01111110, 0x11111111, 0x11000011,
+};
+static const u32 tile_bullet[8] = {
+    0x00022000, 0x00022000, 0x00222200, 0x00222200,
+    0x00222200, 0x00222200, 0x00022000, 0x00022000,
+};
+static const u32 tile_enemy[8] = {
+    0x33000033, 0x03333330, 0x33333333, 0x33033033,
+    0x33333333, 0x03333330, 0x30000003, 0x03000030,
+};
+
+typedef struct { s16 x, y; u16 alive; } Obj;
+
+static OBJ_ATTR obj_buffer[128];
+
+static Obj player;
+static Obj bullets[MAX_BULLETS];
+static Obj enemies[MAX_ENEMIES];
+static u16 score;
+static u16 spawn_timer;
+
+static int aabb_hit(const Obj *a, const Obj *b) {
+    return (a->x < b->x + 8) && (a->x + 8 > b->x)
+        && (a->y < b->y + 8) && (a->y + 8 > b->y);
+}
+
+static void fire_bullet(void) {
+    for (int i = 0; i < MAX_BULLETS; i++) {
+        if (!bullets[i].alive) {
+            bullets[i].x = player.x;
+            bullets[i].y = player.y - 8;
+            bullets[i].alive = 1;
+            return;
+        }
+    }
+}
+
+static void spawn_enemy(void) {
+    for (int i = 0; i < MAX_ENEMIES; i++) {
+        if (!enemies[i].alive) {
+            /* cheap deterministic x scatter */
+            enemies[i].x = ((spawn_timer * 37) & 0xFF) % (240 - 16) + 8;
+            enemies[i].y = -8;
+            enemies[i].alive = 1;
+            return;
+        }
+    }
+}
+
+int main(void) {
+    /* ── Sprite tiles ─ char base 4 is the OBJ tile area in BG mode 0 ─ */
+    tonccpy(&tile_mem[4][TILE_SHIP],   tile_ship,   sizeof(tile_ship));
+    tonccpy(&tile_mem[4][TILE_BULLET], tile_bullet, sizeof(tile_bullet));
+    tonccpy(&tile_mem[4][TILE_ENEMY],  tile_enemy,  sizeof(tile_enemy));
+
+    /* ── Sprite palette ── one palette bank per object class ─────────
+     * pal_obj_bank[N][i] = colour i of bank N. Index 0 = transparent. */
+    pal_obj_bank[0][1] = CLR_WHITE;   /* ship */
+    pal_obj_bank[1][2] = CLR_YELLOW;  /* bullets */
+    pal_obj_bank[2][3] = CLR_RED;     /* enemies */
+
+    oam_init(obj_buffer, 128);
+
+    /* IRQ setup — required for VBlankIntrWait() to function. */
+    irq_init(NULL);
+    irq_add(II_VBLANK, NULL);
+
+    sfx_init();
+
+    player.x = 116; player.y = 130; player.alive = 1;
+    for (int i = 0; i < MAX_BULLETS; i++) bullets[i].alive = 0;
+    for (int i = 0; i < MAX_ENEMIES; i++) enemies[i].alive = 0;
+    score = 0;
+    spawn_timer = 0;
+
+    /* TTE on BG0 at screen-block 31, char-block 0. Renders into VRAM
+     * tile map — no libsysbase / iprintf dependency. */
+    tte_init_chr4c_default(0, BG_CBB(0) | BG_SBB(31));
+    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0 | DCNT_OBJ | DCNT_OBJ_1D;
+    tte_write("#{P:8,8}SCORE 00000");
+    tte_write("#{P:8,144}D-PAD MOVE  A FIRE");
+
+    u16 prev = 0;
+
+    while (1) {
+        VBlankIntrWait();
+        key_poll();
+
+        if (key_held(KEY_LEFT)  && player.x > 8)        player.x -= 2;
+        if (key_held(KEY_RIGHT) && player.x < 240 - 16) player.x += 2;
+        if (key_held(KEY_UP)    && player.y > 24)       player.y -= 2;
+        if (key_held(KEY_DOWN)  && player.y < 160 - 24) player.y += 2;
+
+        u16 now = key_curr_state();
+        if ((now & KEY_A) && !(prev & KEY_A)) {
+            fire_bullet();
+            sfx_tone(2, 1900, 4);   /* pew */
+        }
+        prev = now;
+
+        for (int i = 0; i < MAX_BULLETS; i++) {
+            if (!bullets[i].alive) continue;
+            bullets[i].y -= 4;
+            if (bullets[i].y < -8) bullets[i].alive = 0;
+        }
+        for (int i = 0; i < MAX_ENEMIES; i++) {
+            if (!enemies[i].alive) continue;
+            enemies[i].y += 1;
+            if (enemies[i].y > 160) enemies[i].alive = 0;
+        }
+        if (++spawn_timer >= 28) { spawn_timer = 0; spawn_enemy(); }
+
+        /* Bullet × enemy collisions. */
+        for (int i = 0; i < MAX_BULLETS; i++) {
+            if (!bullets[i].alive) continue;
+            for (int j = 0; j < MAX_ENEMIES; j++) {
+                if (!enemies[j].alive) continue;
+                if (aabb_hit(&bullets[i], &enemies[j])) {
+                    bullets[i].alive = 0;
+                    enemies[j].alive = 0;
+                    if (score < 65500) score += 10;
+                    sfx_noise(6);   /* explosion */
+                    break;
+                }
+            }
+        }
+
+        /* ── Stage shadow OAM ────────────────────────────────────────
+         * Slot 0: player. Slots 1..6: bullets. Slots 7..12: enemies.
+         * Hide inactive slots by parking them offscreen (y = 160). */
+        obj_set_attr(&obj_buffer[0],
+            ATTR0_SQUARE,
+            ATTR1_SIZE_8,
+            ATTR2_PALBANK(0) | TILE_SHIP);
+        obj_set_pos(&obj_buffer[0], player.x, player.y);
+
+        for (int i = 0; i < MAX_BULLETS; i++) {
+            int by = bullets[i].alive ? bullets[i].y : 200;
+            obj_set_attr(&obj_buffer[1 + i],
+                ATTR0_SQUARE,
+                ATTR1_SIZE_8,
+                ATTR2_PALBANK(1) | TILE_BULLET);
+            obj_set_pos(&obj_buffer[1 + i], bullets[i].x, by);
+        }
+        for (int i = 0; i < MAX_ENEMIES; i++) {
+            int ey = enemies[i].alive ? enemies[i].y : 200;
+            obj_set_attr(&obj_buffer[7 + i],
+                ATTR0_SQUARE,
+                ATTR1_SIZE_8,
+                ATTR2_PALBANK(2) | TILE_ENEMY);
+            obj_set_pos(&obj_buffer[7 + i], enemies[i].x, ey);
+        }
+
+        oam_copy(oam_mem, obj_buffer, 128);
+
+        /* Score: 5-digit ASCII via TTE printf. Tte handles VRAM tile
+         * writes — safe to call once per frame. */
+        tte_erase_rect(8 + 6*8, 8, 8 + 11*8, 16);
+        tte_printf("#{P:%d,8}%05d", 8 + 6*8, score);
+    }
+    return 0;
+}

package/examples/gba/templates/sports.c

@@ -0,0 +1,177 @@
+/* ── sports.c — Game Boy Advance Tonc Pong scaffold ─────────────────
+ *
+ * One-player Pong against an AI opponent. The GBA only has one
+ * controller, so the right paddle is always AI — it tracks the ball
+ * vertically.
+ *
+ * Game state:
+ *   - Left + right paddles (24-px tall, 4-px wide), moveable on Y
+ *   - Ball with X + Y velocity
+ *   - Per-side score (0..9), rendered via TTE
+ *   - Ball off either side increments opponent's score + respawns
+ *
+ * Note: real-hardware GBA doesn't have a second controller port. If
+ * you want 2-player you'd need the GBA link cable + a second console
+ * — out of scope for this scaffold.
+ */
+
+#include <tonc.h>
+#include "gba_sfx.h"
+
+#define COURT_TOP   16
+#define COURT_BOT   152
+#define PADDLE_H    24
+#define PADDLE_W    4
+#define BALL_SIZE   8
+#define PADDLE_X1   8
+#define PADDLE_X2   (240 - 8 - PADDLE_W)
+#define COURT_W     240
+
+#define TILE_PADDLE 1
+#define TILE_BALL   2
+
+/* 4bpp 8x8 solid block — colour index 1. */
+static const u32 tile_solid_1[8] = {
+    0x11111111, 0x11111111, 0x11111111, 0x11111111,
+    0x11111111, 0x11111111, 0x11111111, 0x11111111,
+};
+
+static OBJ_ATTR obj_buffer[128];
+
+static s16 p1y, p2y;
+static s16 bx, by;
+static s16 bdx, bdy;
+static u16 score_p1, score_p2;
+static u16 serve_timer;
+
+static void serve_ball(int to_left) {
+    bx = COURT_W / 2 - BALL_SIZE / 2;
+    by = (COURT_TOP + COURT_BOT) / 2;
+    bdx = to_left ? -2 : 2;
+    bdy = ((score_p1 + score_p2) & 1) ? -1 : 1;
+    serve_timer = 30;
+}
+
+static void reset_match(void) {
+    p1y = (COURT_TOP + COURT_BOT) / 2 - PADDLE_H / 2;
+    p2y = p1y;
+    score_p1 = 0;
+    score_p2 = 0;
+    serve_ball(0);
+}
+
+int main(void) {
+    /* Sprite palette — both paddles and ball use index 1 = white. */
+    pal_obj_mem[1] = CLR_WHITE;
+
+    /* Sprite tiles — char base 4 of OBJ tile area. */
+    tonccpy(&tile_mem[4][TILE_PADDLE], tile_solid_1, sizeof(tile_solid_1));
+    tonccpy(&tile_mem[4][TILE_BALL],   tile_solid_1, sizeof(tile_solid_1));
+
+    oam_init(obj_buffer, 128);
+
+    /* IRQ setup — required for VBlankIntrWait() to function. */
+    irq_init(NULL);
+    irq_add(II_VBLANK, NULL);
+
+    sfx_init();
+
+    /* TTE for scores + hint. */
+    tte_init_chr4c_default(0, BG_CBB(0) | BG_SBB(31));
+    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0 | DCNT_OBJ | DCNT_OBJ_1D;
+    tte_write("#{P:16,2}P1");
+    tte_write("#{P:208,2}P2");
+    tte_write("#{P:36,150}UP/DOWN MOVES YOUR PADDLE");
+
+    reset_match();
+
+    while (1) {
+        VBlankIntrWait();
+        key_poll();
+
+        /* Player 1 — UP/DOWN. */
+        if (key_held(KEY_UP)   && p1y > COURT_TOP)            p1y -= 3;
+        if (key_held(KEY_DOWN) && p1y < COURT_BOT - PADDLE_H) p1y += 3;
+
+        /* AI right paddle — tracks ball. */
+        s16 target = by - PADDLE_H / 2;
+        if (p2y < target && p2y < COURT_BOT - PADDLE_H) p2y += 2;
+        else if (p2y > target && p2y > COURT_TOP)       p2y -= 2;
+
+        if (serve_timer > 0) {
+            serve_timer--;
+        } else {
+            bx += bdx;
+            by += bdy;
+
+            if (by < COURT_TOP) { by = COURT_TOP; bdy = -bdy; sfx_tone(2, 1100, 2); }
+            if (by + BALL_SIZE > COURT_BOT) {
+                by = COURT_BOT - BALL_SIZE;
+                bdy = -bdy;
+                sfx_tone(2, 1100, 2);   /* wall blip */
+            }
+
+            if (bdx < 0
+                && bx <= PADDLE_X1 + PADDLE_W
+                && bx + BALL_SIZE >= PADDLE_X1
+                && by + BALL_SIZE > p1y
+                && by < p1y + PADDLE_H) {
+                bdx = -bdx;
+                bx = PADDLE_X1 + PADDLE_W;
+                sfx_tone(1, 1500, 3);   /* paddle hit */
+            }
+            if (bdx > 0
+                && bx + BALL_SIZE >= PADDLE_X2
+                && bx <= PADDLE_X2 + PADDLE_W
+                && by + BALL_SIZE > p2y
+                && by < p2y + PADDLE_H) {
+                bdx = -bdx;
+                bx = PADDLE_X2 - BALL_SIZE;
+                sfx_tone(1, 1500, 3);
+            }
+
+            if (bx + BALL_SIZE < 0) {
+                if (score_p2 < 9) score_p2++;
+                sfx_noise(20);          /* point lost — buzz */
+                serve_ball(0);
+            }
+            if (bx > COURT_W) {
+                if (score_p1 < 9) score_p1++;
+                sfx_tone(1, 1900, 16);  /* point won — chime */
+                serve_ball(1);
+            }
+        }
+
+        /* Sprite slots: 0..2 = P1 paddle (3 vertical tiles)
+         *               3..5 = P2 paddle
+         *               6    = ball */
+        for (int i = 0; i < PADDLE_H / 8; i++) {
+            obj_set_attr(&obj_buffer[i],
+                ATTR0_SQUARE,
+                ATTR1_SIZE_8,
+                ATTR2_PALBANK(0) | TILE_PADDLE);
+            obj_set_pos(&obj_buffer[i], PADDLE_X1, p1y + i * 8);
+        }
+        for (int i = 0; i < PADDLE_H / 8; i++) {
+            obj_set_attr(&obj_buffer[3 + i],
+                ATTR0_SQUARE,
+                ATTR1_SIZE_8,
+                ATTR2_PALBANK(0) | TILE_PADDLE);
+            obj_set_pos(&obj_buffer[3 + i], PADDLE_X2, p2y + i * 8);
+        }
+        obj_set_attr(&obj_buffer[6],
+            ATTR0_SQUARE,
+            ATTR1_SIZE_8,
+            ATTR2_PALBANK(0) | TILE_BALL);
+        obj_set_pos(&obj_buffer[6], bx, by);
+
+        oam_copy(oam_mem, obj_buffer, 7);
+
+        /* Score digits. */
+        tte_erase_rect(28, 2, 36, 14);
+        tte_printf("#{P:28,2}%d", score_p1 % 10);
+        tte_erase_rect(220, 2, 228, 14);
+        tte_printf("#{P:220,2}%d", score_p2 % 10);
+    }
+    return 0;
+}

package/examples/gba/templates/tonc_hello.c

@@ -0,0 +1,72 @@
+/* ── tonc_hello.c — Game Boy Advance libtonc starter (TTE) ──────────
+ *
+ * Idiomatic Tonc-tutorial-style hello world. Uses TTE (Tonc Text
+ * Engine) to draw "Hello, Tonc!" on a Mode-0 tile background — the
+ * canonical "Hello GBA" pattern from gbadev.net/tonc.
+ *
+ * Build via romdev:
+ *   buildSource({platform:"gba", language:"c", source: <this file>})
+ *
+ * (defaults to runtime:"libtonc" — pass {runtime:"libgba"} to use
+ *  devkitPro's libgba instead, or {runtime:"none"} for bare gcc.)
+ *
+ * The bundled libtonc runtime gives you the canonical Tonc-book API:
+ *   - <tonc.h>          umbrella header
+ *   - REG_DISPCNT, DCNT_MODE0, DCNT_BG0, etc. display registers
+ *   - tte_init_chr4c_default()      TTE setup (4bpp char-mode text)
+ *   - tte_set_pos(x, y)             cursor positioning
+ *   - tte_write(str)                draw text (no format)
+ *   - tte_printf(fmt, ...)          formatted output (varargs)
+ *   - tonccpy / toncset             VRAM-safe memcpy/memset (16/32-bit)
+ *   - REG_KEYS, KEY_A/B/SELECT/START etc.
+ *   - VBlankIntrWait()              frame heartbeat
+ *
+ * ⚠️  One omission: libtonc's `tte_iohook` (auto-routing of printf /
+ *    iprintf through TTE via libsysbase) is NOT bundled — same
+ *    reason as libgba's console.c. Use `tte_write` / `tte_printf`
+ *    directly (which is what every Tonc tutorial actually does
+ *    anyway). The Tonc book never says `iprintf` — it says
+ *    `tte_printf`. Following that pattern keeps your code portable.
+ */
+
+#include <tonc.h>
+
+int main(void) {
+    /* Initialise TTE in 4-bits-per-pixel chr-mode with the built-in
+     * sys8 font. Cleanest API in the entire GBA ecosystem — one call
+     * gets you a usable text terminal on BG0.
+     *
+     * NOTE: we deliberately do NOT call tte_init_con() — that lives
+     * in the excluded tte_iohook.c (the libsysbase bridge). Without
+     * it, printf/iprintf don't route through TTE — but `tte_write` /
+     * `tte_printf` work directly without any libsysbase plumbing,
+     * which is what the Tonc tutorial uses everywhere anyway. */
+    tte_init_chr4c_default(0, BG_CBB(0) | BG_SBB(31));
+
+    /* ── IRQ setup ── REQUIRED for VBlankIntrWait() to work ──────
+     * Without this, the BIOS halts the CPU on the first
+     * VBlankIntrWait() forever (it waits for an IRQ that never
+     * fires). Single most common GBA-Tonc gotcha. */
+    irq_init(NULL);
+    irq_add(II_VBLANK, NULL);
+
+    /* Set DISPCNT — turn on BG0 (where TTE drew the font tiles into
+     * char-base 0 + screen-base 31). DCNT_MODE0 is the tile-BG mode. */
+    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0;
+
+    /* Draw text. tte_write moves the internal cursor; \n wraps. */
+    tte_write("#{P:32,32}");         /* position cursor at pixel (32,32) */
+    tte_write("Hello, Tonc!\n");
+    tte_write("Built with romdev\n");
+
+    /* Formatted output without needing iprintf or libsysbase. */
+    int year = 2026;
+    tte_printf("#{P:32,80}Year: %d\n", year);
+
+    /* Game loop. VBlankIntrWait() halts the CPU until next vblank —
+     * saves battery on real hardware. */
+    while (1) {
+        VBlankIntrWait();
+    }
+    return 0;
+}