romdevtools 0.13.0

package/src/platforms/sms/lib/c/sms_music.c

@@ -0,0 +1,178 @@
+/* sms_music.c — 3-voice PSG tracker for SMS.
+ *
+ * Hand-authored song: a relaxed C-major arpeggio loop. Voice 0 carries
+ * the melody (octave-5/4 line), voice 1 plays a slower harmony, voice 2
+ * drives a walking bass. Each voice has its own independent step cursor
+ * + per-step countdown, so the three tracks can be different lengths
+ * and they'll polyrhythm naturally — voice 2 (bass) loops every 16
+ * steps, voice 1 (harmony) every 8, voice 0 (melody) every 16. The
+ * common period is 16 steps so the song lines up cleanly on the loop.
+ *
+ * Playback is purely time-driven: when a voice's frame counter hits 0
+ * we (a) advance the step cursor (wrapping at the track length), (b)
+ * write the new divider to the PSG via the SN76489 latch+data protocol,
+ * and (c) reload the frame counter from the new step's duration. We
+ * keep the volume latched at "loud" (attenuation 0) for tone channels
+ * while a note is held, and write attenuation 0xF (silent) on rests.
+ *
+ * Why not reuse sms_sfx.c's psg_write?
+ *   sms_sfx.c keeps psg_write static — its API is the high-level sfx_*.
+ *   We write the same byte directly to PORT_H_COUNTER ourselves so the
+ *   music driver is self-contained and doesn't entangle the two layers
+ *   (sfx auto-silences after N frames; music doesn't want that).
+ *
+ * Z80 / SDCC notes:
+ *   - C89 only: all locals declared at top of block (see SDCC_GOTCHAS).
+ *   - uint16_t divider table is in const ROM (declared `const`) — fine.
+ *   - All state in static RAM, no malloc.
+ */
+
+#include "sms_music.h"
+#include "sms_hw.h"
+
+/* ─── Note dividers (NTSC, 3.58MHz / 32) ───────────────────────────── */
+#define D_REST  0
+#define D_C3    855
+#define D_G3    570
+#define D_A3    509
+#define D_C4    427
+#define D_D4    381
+#define D_E4    339
+#define D_F4    320
+#define D_G4    285
+#define D_A4    254
+#define D_B4    226
+#define D_C5    214
+#define D_D5    191
+#define D_E5    170
+
+/* ─── Song data — parallel per-voice tracks ────────────────────────── */
+/* 60 fps; quarter ≈ 18 frames, half ≈ 36, eighth ≈ 9. */
+#define Q  18
+#define H  36
+#define E  9
+
+/* Voice 0 — melody (16 steps, ~3.2 sec/loop). Mary-had-a-little-lamb
+ * style line transposed to feel like a chiptune arpeggio. */
+static const uint16_t mel0_freq[16] = {
+  D_E5, D_D5, D_C5, D_D5, D_E5, D_E5, D_E5, D_REST,
+  D_D5, D_D5, D_D5, D_REST, D_E5, D_G4, D_G4, D_REST,
+};
+static const uint8_t  mel0_len[16] = {
+  Q, Q, Q, Q,  Q, Q, H, E,
+  Q, Q, H, E,  Q, Q, H, E,
+};
+
+/* Voice 1 — harmony / countermelody (8 steps, ~2.4 sec/loop). Holds
+ * thirds + fifths under the melody. */
+static const uint16_t mel1_freq[8] = {
+  D_G4, D_E4, D_F4, D_E4,
+  D_G4, D_C4, D_D4, D_E4,
+};
+static const uint8_t  mel1_len[8] = {
+  H, H, H, H,
+  H, H, H, H,
+};
+
+/* Voice 2 — bass (8 steps, ~3.2 sec/loop). Walking C/G/A/F pattern. */
+static const uint16_t mel2_freq[8] = {
+  D_C3, D_C3, D_G3, D_G3,
+  D_A3, D_A3, D_F4, D_G3,
+};
+static const uint8_t  mel2_len[8] = {
+  H, H, H, H,
+  H, H, H, H,
+};
+
+/* ─── Playback state ────────────────────────────────────────────────── */
+static uint8_t  cursor[3];      /* current step index per voice */
+static uint8_t  remaining[3];   /* frames left on current step */
+static uint8_t  playing;        /* nonzero = music_update() drives PSG */
+
+/* Track length per voice — kept as a tiny lookup so the step-advance
+ * code can stay branch-free across voices. */
+static const uint8_t track_len[3] = { 16, 8, 8 };
+
+/* ─── PSG write primitive (same byte to port $7F as sms_sfx.c) ────── */
+static void psg_write(uint8_t b) {
+  PORT_H_COUNTER = b;
+}
+
+static void psg_silence(uint8_t channel) {
+  psg_write(0x90 | (channel << 5) | 0x0F);
+}
+
+static void psg_tone(uint8_t channel, uint16_t divider) {
+  psg_write(0x80 | (channel << 5) | (divider & 0x0F));
+  psg_write((divider >> 4) & 0x3F);
+  psg_write(0x90 | (channel << 5) | 0x00);   /* volume max */
+}
+
+/* Fetch the (freq, len) at step `s` of voice `v`. We keep the song
+ * tables typed individually for clarity rather than a 3-row 2D array;
+ * the compiler folds this switch into a jump table just fine. */
+static void fetch_step(uint8_t v, uint8_t s, uint16_t *freq_out, uint8_t *len_out) {
+  if (v == 0) {
+    *freq_out = mel0_freq[s];
+    *len_out  = mel0_len[s];
+  } else if (v == 1) {
+    *freq_out = mel1_freq[s];
+    *len_out  = mel1_len[s];
+  } else {
+    *freq_out = mel2_freq[s];
+    *len_out  = mel2_len[s];
+  }
+}
+
+static void start_step(uint8_t v) {
+  uint16_t f;
+  uint8_t  len;
+  fetch_step(v, cursor[v], &f, &len);
+  if (f == D_REST) {
+    psg_silence(v);
+  } else {
+    psg_tone(v, f);
+  }
+  remaining[v] = len;
+}
+
+void music_init(void) {
+  uint8_t i;
+  for (i = 0; i < 3; i++) {
+    cursor[i] = 0;
+    remaining[i] = 0;
+    psg_silence(i);
+  }
+  playing = 0;
+}
+
+void music_play(uint8_t song_idx) {
+  uint8_t i;
+  (void)song_idx;          /* one bundled song for now — future banks */
+  for (i = 0; i < 3; i++) {
+    cursor[i] = 0;
+    start_step(i);
+  }
+  playing = 1;
+}
+
+void music_update(void) {
+  uint8_t v;
+  if (!playing) return;
+  for (v = 0; v < 3; v++) {
+    if (remaining[v] > 0) {
+      remaining[v]--;
+    }
+    if (remaining[v] == 0) {
+      cursor[v]++;
+      if (cursor[v] >= track_len[v]) cursor[v] = 0;
+      start_step(v);
+    }
+  }
+}
+
+void music_stop(void) {
+  uint8_t i;
+  playing = 0;
+  for (i = 0; i < 3; i++) psg_silence(i);
+}

package/src/platforms/sms/lib/c/sms_music.h

@@ -0,0 +1,50 @@
+/* sms_music.h — tiny 3-voice tracker for the SMS SN76489 PSG.
+ *
+ * Sits on top of sms_sfx.{h,c}'s raw PSG write path. The "song" is a
+ * pair of parallel arrays: a list of (divider, duration_frames) events
+ * per voice, played back step-by-step. When the per-voice cursor hits
+ * the end of its track it loops back to step 0 — instant continuous
+ * music with no need for an asset pipeline.
+ *
+ * Three tone voices (ch 0/1/2). The noise channel (ch 3) is left alone
+ * so a game's sfx layer can keep using sfx_noise for hit/explosion FX.
+ *
+ * SN76489 frequency divider math (NTSC SMS):
+ *   Hz = 3579545 / 32 / divider     →    divider = 111861 / Hz
+ *
+ *   note    Hz       divider
+ *   C3      130.81   855
+ *   G3      196.00   570
+ *   C4      261.63   427
+ *   D4      293.66   381
+ *   E4      329.63   339
+ *   F4      349.23   320
+ *   G4      392.00   285
+ *   A4      440.00   254
+ *   B4      493.88   226
+ *   C5      523.25   214
+ *
+ * Use divider 0 to mean "rest" — the driver skips the PSG write and
+ * just counts the duration down before advancing to the next step.
+ *
+ * API mirrors sfx_*:
+ *
+ *   music_init()              — clear state, silence tone channels
+ *   music_play(song_idx)      — start playback at song step 0
+ *                               (song_idx reserved for future multi-song
+ *                                 banks; current build has one song)
+ *   music_update()            — call ONCE per frame from the vblank loop
+ *   music_stop()              — silence the 3 tone channels, halt playback
+ */
+
+#ifndef SMS_MUSIC_H
+#define SMS_MUSIC_H
+
+#include <stdint.h>
+
+void music_init(void);
+void music_play(uint8_t song_idx);
+void music_update(void);
+void music_stop(void);
+
+#endif

package/src/platforms/sms/lib/c/sms_sfx.c

@@ -0,0 +1,82 @@
+/* sms_sfx.c — SN76489 PSG driver for SMS / Game Gear.
+ *
+ * SN76489 latch protocol (write-only via port $7F):
+ *   Latch byte (bit 7 = 1):
+ *     bit 7    = 1 (latch)
+ *     bits 6-5 = channel (00=ch0, 01=ch1, 10=ch2, 11=ch3-noise)
+ *     bit 4    = 0 (frequency) | 1 (volume/attenuation)
+ *     bits 3-0 = low 4 bits of frequency, OR 4-bit attenuation (0=loud, 15=silent)
+ *   Data byte (bit 7 = 0):
+ *     bits 5-0 = high 6 bits of frequency
+ *
+ * To play a tone:
+ *   1. Latch: $80|chan<<5|0|(freq & 0x0F)
+ *   2. Data:  (freq >> 4) & 0x3F
+ *   3. Latch volume: $90|chan<<5|attenuation
+ *
+ * Noise uses a different latch (low 3 bits select shift rate / source):
+ *   $E0 | (mode_bit << 2) | rate
+ *   rate 0=clock/512, 1=clock/1024, 2=clock/2048, 3=use ch2 freq
+ *
+ * Attenuation is in 2 dB steps: 0=loudest, 15=off.
+ *
+ * Per-channel "frames-left" countdown drives auto-silence. sfx_update
+ * runs once per frame and silences a channel whose counter hits 0.
+ */
+
+#include "sms_sfx.h"
+#include "sms_hw.h"
+
+static uint8_t sfx_remaining[4];
+
+static void psg_write(uint8_t b) {
+  PORT_H_COUNTER = b;            /* port $7F is the PSG write port */
+}
+
+void sfx_init(void) {
+  uint8_t i;
+  for (i = 0; i < 4; i++) {
+    sfx_remaining[i] = 0;
+    /* Silence channel i (latch volume = 0xF = off). */
+    psg_write(0x90 | (i << 5) | 0x0F);
+  }
+}
+
+void sfx_tone(uint8_t channel, uint16_t freq, uint8_t length_frames) {
+  if (channel > 2) return;
+  /* Latch + data byte for frequency. */
+  psg_write(0x80 | (channel << 5) | (freq & 0x0F));
+  psg_write((freq >> 4) & 0x3F);
+  /* Volume at max (attenuation 0). */
+  psg_write(0x90 | (channel << 5) | 0x00);
+  sfx_remaining[channel] = length_frames;
+}
+
+void sfx_noise(uint8_t length_frames) {
+  /* White noise, rate = clock/1024 (mid frequency). */
+  psg_write(0xE0 | 0x04 | 0x01);
+  /* Volume at max (channel 3 attenuation = 0). */
+  psg_write(0xF0);
+  sfx_remaining[3] = length_frames;
+}
+
+void sfx_update(void) {
+  uint8_t i;
+  for (i = 0; i < 4; i++) {
+    if (sfx_remaining[i] > 0) {
+      sfx_remaining[i]--;
+      if (sfx_remaining[i] == 0) {
+        /* Silence channel i. */
+        psg_write(0x90 | (i << 5) | 0x0F);
+      }
+    }
+  }
+}
+
+void sfx_off(void) {
+  uint8_t i;
+  for (i = 0; i < 4; i++) {
+    psg_write(0x90 | (i << 5) | 0x0F);
+    sfx_remaining[i] = 0;
+  }
+}

package/src/platforms/sms/lib/c/sms_sfx.h

@@ -0,0 +1,40 @@
+/* sms_sfx.h — minimal SMS PSG sound-effects wrapper.
+ *
+ * SMS audio = SN76489 PSG (same chip as Genesis PSG, 4 channels):
+ *   ch 0, 1, 2 = square-wave tones
+ *   ch 3       = noise
+ *
+ * Accessed via I/O port $7F (write-only — reads return the H-counter).
+ *
+ * Same shape as nes_runtime / gb_runtime / gba_sfx / genesis_sfx:
+ *
+ *   sfx_init()
+ *   sfx_tone(channel, freq, length_frames)
+ *   sfx_noise(length_frames)
+ *   sfx_update()    // call once per frame to tick auto-silence
+ *   sfx_off()
+ *
+ * Game Gear shares the SAME chip + the same port $7F write path,
+ * so this wrapper works unchanged on GG. (GG adds a stereo register
+ * at port $06 that's optional — we don't touch it.)
+ *
+ * The PSG has NO automatic envelope. We hand-decrement a per-channel
+ * counter and silence on zero — that's what sfx_update does. Forget
+ * to call it once per frame and notes ring forever.
+ *
+ * Frequency on SMS is 10-bit (0..1023). Hz = 3579545 / 32 / freq.
+ * Useful values: 200 = high pew, 400 = mid blip, 800 = low thump.
+ */
+
+#ifndef SMS_SFX_H
+#define SMS_SFX_H
+
+#include <stdint.h>
+
+void sfx_init(void);
+void sfx_tone(uint8_t channel, uint16_t freq, uint8_t length_frames);
+void sfx_noise(uint8_t length_frames);
+void sfx_update(void);
+void sfx_off(void);
+
+#endif

package/src/platforms/sms/lib/c/sprite_table.c

@@ -0,0 +1,60 @@
+/* SMS sprite attribute table — shadow OAM in WRAM, DMA'd to SAT once
+ * per frame.
+ *
+ * SAT VRAM layout ($3F00):
+ *   $00-$3F:  64 Y bytes ($D0 in any slot = HARD TERMINATOR — see below)
+ *   $80-$FF:  64 (X, tile) pairs
+ *
+ * The $D0 terminator footgun:
+ *   The VDP stops scanning further sprite slots the moment it sees Y=$D0
+ *   in ANY OAM byte. If you populate slots 0..5 and slot 6 still has
+ *   $D0, slot 5 is the last sprite you'll ever see. Earlier rounds of
+ *   this runtime initialised every slot to $D0 — "hidden at boot" — but
+ *   that meant the FIRST gap in your sprite allocation killed the
+ *   renderer for everything past it. We now initialise unused slots to
+ *   $E0 instead: still off-screen (below the 192-line visible area on
+ *   SMS) but NOT the terminator. Slots you don't touch stay invisible;
+ *   slots you do touch render. Set a slot's Y to $D0 yourself if you
+ *   ACTUALLY want the renderer to stop there.
+ *
+ * Workflow:
+ *   sms_sprite_init();             // once
+ *   sms_sprite_set(0, x, y, 4);    // game logic
+ *   ...
+ *   sms_sat_upload();              // once per vblank
+ */
+#include "sms_hw.h"
+
+extern void sms_vdp_set_addr(uint16_t addr, uint8_t prefix);
+
+/* Shadow OAM: matches the VDP's expected SAT layout. */
+uint8_t shadow_oam[256];
+
+/* Y value for "hidden but not terminator." 192-line mode is visible
+ * Y=0..191; $E0 (224) is below the visible area and won't render. */
+#define OAM_Y_HIDDEN  0xE0
+
+void sms_sprite_init(void) {
+  uint8_t i;
+  /* Park every slot off-screen with a non-terminator Y. The renderer
+   * keeps scanning past these (so any slot you later populate will
+   * actually draw); they just don't render themselves. */
+  for (i = 0; i < 64; i++) shadow_oam[i] = OAM_Y_HIDDEN;
+  for (i = 0; i < 128; i++) shadow_oam[0x80 + i] = 0;
+}
+
+void sms_sprite_set(uint8_t slot, uint8_t x, uint8_t y, uint8_t tile) {
+  shadow_oam[slot] = y;
+  shadow_oam[0x80 + (uint16_t)slot * 2] = x;
+  shadow_oam[0x80 + (uint16_t)slot * 2 + 1] = tile;
+}
+
+void sms_sat_upload(void) {
+  uint8_t i;
+  /* Y bytes → VRAM $3F00. */
+  sms_vdp_set_addr(0x3F00, VDP_VRAM_WRITE);
+  for (i = 0; i < 64; i++) PORT_VDP_DATA = shadow_oam[i];
+  /* (X, tile) pairs → VRAM $3F80. */
+  sms_vdp_set_addr(0x3F80, VDP_VRAM_WRITE);
+  for (i = 0; i < 128; i++) PORT_VDP_DATA = shadow_oam[0x80 + i];
+}

package/src/platforms/sms/lib/c/vblank_wait.c

@@ -0,0 +1,10 @@
+/* SMS vblank wait — polls VDP_CTRL bit 7.
+ *
+ * Reading $BF returns the status byte and CLEARS bit 7. Spin until set;
+ * the act of reading clears the flag for the next iteration.
+ */
+#include "sms_hw.h"
+
+void sms_vblank_wait(void) {
+  while ((PORT_VDP_CTRL & 0x80) == 0) { }
+}

package/src/platforms/sms/lib/c/vdp_init.c

@@ -0,0 +1,58 @@
+/* SMS VDP — minimum viable initialization (C).
+ *
+ * Writes the 11 mode-4 registers to a sane baseline:
+ *   display OFF, vblank IRQ off, 192-line mode 4, name table at $3800,
+ *   BG tile data at $0000, sprite attr table at $3F00, sprite tile data
+ *   at $0000 (R6=0xFB → SA13 clear → tiles read from $0000-$1FFF). Call
+ *   once after reset before uploading palette/tiles/map.
+ *
+ * Footgun: many SMS references say "R6=0xFB → sprite tiles at $2000"
+ * which is BACKWARDS. R6 bit 2 (the SA13 select) is CLEAR in 0xFB, so
+ * sprite tiles read from $0000 (sharing the bank with BG tiles). To
+ * separate sprite tiles to $2000, set R6 = 0xFF instead. The
+ * sprites({op:'inspect'}) tool's spriteTileDataBase field will show you the
+ * real address the VDP is reading from.
+ *
+ * After loading assets, enable display by re-writing R1 with bit 6 set:
+ *   sms_vdp_display_on();
+ */
+#include "sms_hw.h"
+
+/* Write a value to a VDP register. SMS convention: data first, then
+ * (0x80 | reg). */
+void sms_vdp_write_reg(uint8_t reg, uint8_t value) {
+  PORT_VDP_CTRL = value;
+  PORT_VDP_CTRL = VDP_REG_WRITE | reg;
+}
+
+void sms_vdp_init(void) {
+  static const uint8_t regs[11] = {
+    0x36,  /* R0:  Mode 4 */
+    0x80,  /* R1:  display OFF, vblank IRQ off */
+    0xFF,  /* R2:  name table at $3800 */
+    0xFF,  /* R3:  color table (ignored in M4) */
+    0xFF,  /* R4:  BG tile data at $0000 */
+    0xFF,  /* R5:  sprite attr table at $3F00 */
+    0xFB,  /* R6:  sprite tile data at $0000 (set 0xFF for $2000) */
+    0x00,  /* R7:  border = sprite palette entry 0 */
+    0x00,  /* R8:  BG X scroll */
+    0x00,  /* R9:  BG Y scroll */
+    0xFF,  /* R10: line IRQ counter disabled */
+  };
+  uint8_t i;
+  for (i = 0; i < 11; i++) sms_vdp_write_reg(i, regs[i]);
+}
+
+void sms_vdp_display_on(void) {
+  sms_vdp_write_reg(1, 0xE0);  /* display on, vblank IRQ on, 192-line */
+}
+
+void sms_vdp_display_off(void) {
+  sms_vdp_write_reg(1, 0x80);
+}
+
+/* Set the VDP destination address (for the next data-port writes). */
+void sms_vdp_set_addr(uint16_t addr, uint8_t prefix) {
+  PORT_VDP_CTRL = (uint8_t)(addr & 0xFF);
+  PORT_VDP_CTRL = (uint8_t)((addr >> 8) & 0x3F) | prefix;
+}

package/src/platforms/sms/lib/header.s

@@ -0,0 +1,33 @@
+; SMS / Game Gear ROM header (TMR SEGA).
+;
+; Lives at $7FF0-$7FFF (last 16 bytes of bank 0). The BIOS verifies this
+; on power-on; without it, real hardware refuses to boot. Most emulators
+; (gpgx included) tolerate its absence, but ship the header anyway so
+; your ROM runs on real cartridges.
+;
+; Layout:
+;   $7FF0..$7FF7  "TMR SEGA"           — magic string
+;   $7FF8..$7FF9  reserved             — 0x00 0x00
+;   $7FFA..$7FFB  checksum (LE word)   — sum of bytes $0000-$7FEF
+;   $7FFC..$7FFE  product code         — 5 nibbles BCD (low at $7FFC,
+;                                         high nibble of $7FFE = high digit)
+;   $7FFE high   version               — 4-bit revision number
+;   $7FFF        region | rom_size     — bits 7-4 = region, bits 3-0 = size
+;
+; Region codes:
+;   3 = SMS Japan, 4 = SMS Export, 5 = GG Japan, 6 = GG Export, 7 = GG Int'l
+; ROM size codes (relevant for ≥32KB carts):
+;   $a = 8KB, $b = 16KB, $c = 32KB, $d = 48KB (rare),
+;   $e = 64KB, $f = 128KB, $0 = 256KB, $1 = 512KB
+
+        .org $7FF0
+        .ascii "TMR SEGA"
+        .db $00, $00
+        ; Checksum slot — most assemblers won't compute this for you;
+        ; either patch it post-build (sums of bytes $0000-$7FEF) or use
+        ; the BIOS-skip approach (most emulators don't enforce).
+        .db $00, $00
+        ; Product code (placeholder: 00001)
+        .db $01, $00, $00
+        ; Region (4 = SMS Export) and rom size ($c = 32 KB).
+        .db $4C

package/src/platforms/sms/lib/joypad_read.s

@@ -0,0 +1,40 @@
+; SMS joypad read.
+;
+; Port $DC = controller port A (P1 directions + buttons 1+2, P2 D-pad).
+; Port $DD = controller port B (P2 buttons + reset/cart inserted bits).
+;
+; Bit layout for port $DC (active LOW — pressed = 0):
+;   bit 0  P1 up
+;   bit 1  P1 down
+;   bit 2  P1 left
+;   bit 3  P1 right
+;   bit 4  P1 button 1 (TL)
+;   bit 5  P1 button 2 (TR)
+;   bit 6  P2 up
+;   bit 7  P2 down
+;
+; This routine reads $DC, inverts (so pressed = 1), and stores into
+; (_p1_state). The agent can then test individual bits.
+
+JOY_PORT_A equ $DC
+JOY_PORT_B equ $DD
+
+joypad_read:
+        in a,(JOY_PORT_A)
+        cpl                      ; invert: pressed=1
+        ld (_p1_state),a
+        in a,(JOY_PORT_B)
+        cpl
+        ld (_p2_state),a
+        ret
+
+; Convenience masks — combine into your own test code as needed:
+JOY_UP    equ $01
+JOY_DOWN  equ $02
+JOY_LEFT  equ $04
+JOY_RIGHT equ $08
+JOY_B1    equ $10
+JOY_B2    equ $20
+
+_p1_state .equ $C010
+_p2_state .equ $C011

package/src/platforms/sms/lib/load_palette.s

@@ -0,0 +1,30 @@
+; SMS palette loader.
+;
+; CRAM has 32 entries (16 BG + 16 sprite), one byte each. Entry layout:
+;   bits 0-1 = R (2 bits)
+;   bits 2-3 = G
+;   bits 4-5 = B
+;
+; To write CRAM:
+;   1. Set the VDP address to CRAM via control port:
+;        send word (cram_offset | $C000) — the $C000 prefix tells the VDP
+;        "the next data-port write goes to CRAM at this address".
+;        Use $4000 prefix for VRAM writes instead.
+;   2. Write each color byte to VDP_DATA ($BE). Auto-increments the
+;      address pointer.
+;
+; CALLING: HL → 32-byte palette table; entry 0 written first.
+
+VDP_DATA equ $BE
+VDP_CTRL equ $BF
+
+load_palette:
+        ld a,$00                 ; LOW byte of CRAM dest addr ($0000)
+        out (VDP_CTRL),a
+        ld a,$C0                 ; HIGH byte: $C0 = CRAM write
+        out (VDP_CTRL),a
+
+        ld b,32                  ; 32 entries (16 BG + 16 sprite)
+        ld c,VDP_DATA
+        otir                     ; (HL)+ → out (C); B--; loop until B=0
+        ret

package/src/platforms/sms/lib/load_tiles.s

@@ -0,0 +1,50 @@
+; SMS tile loader — VRAM upload.
+;
+; SMS tiles are 32 bytes each (4bpp interleaved). VRAM is 16 KB at
+; $0000-$3FFF. Tile N lives at VRAM offset (N * 32).
+;
+; To write VRAM:
+;   1. Set VDP address: low byte first, then (high | $40) — the $40
+;      prefix in the high byte signals VRAM write.
+;   2. Write bytes to VDP_DATA — auto-increments.
+;
+; CALLING:
+;   HL  → source bytes
+;   BC  → byte count (= tileCount * 32)
+;   DE  → VRAM destination (e.g. $2000 = tile 256)
+; CLOBBERS: A, BC, HL, DE.
+
+VDP_DATA equ $BE
+VDP_CTRL equ $BF
+
+load_tiles:
+        ; Set VDP address: low(e), high(d) | $40
+        ld a,e
+        out (VDP_CTRL),a
+        ld a,d
+        or $40
+        out (VDP_CTRL),a
+
+        ; Bulk copy. OTIR transfers 1 byte at a time and loops on B until
+        ; B reaches 0, so we have to outer-loop over C.
+        ld d,c                   ; D = high-byte page count
+        inc d                    ; INC because OTIR-then-test-B-zero needs round-up
+        ld a,b
+        or a
+        jr nz,_lt_page
+
+_lt_check_partial:
+        ld a,c
+        or a
+        ret z                    ; nothing left
+        ld b,c
+        ld c,VDP_DATA
+        otir
+        ret
+
+_lt_page:
+        ld c,VDP_DATA
+        otir                     ; one full 256-byte page
+        ld c,VDP_DATA            ; restore C
+        djnz _lt_page            ; B was decremented
+        jr _lt_check_partial

package/src/platforms/sms/lib/sprite_table.s

@@ -0,0 +1,44 @@
+; SMS sprite attribute table (SAT) — populate from shadow OAM.
+;
+; SAT lives at VRAM $3F00 by default (set via VDP R5). Layout:
+;   $00-$3F:  64 Y bytes. $D0 in any slot = terminator (VDP stops rendering).
+;   $80-$FF:  64 (X, tile) pairs.
+;
+; Strategy: keep shadow OAM in WRAM (256 bytes), update it during your
+; game logic, then DMA-copy to VRAM once per vblank.
+;
+; CALLING: HL → shadow OAM bytes (256 bytes); writes Y entries 0-63 to
+; VRAM $3F00 then X/tile pairs to VRAM $3F80.
+
+VDP_DATA equ $BE
+VDP_CTRL equ $BF
+
+sat_upload:
+        ; Write Y bytes (slots 0-63 = first 64 bytes of shadow).
+        ld a,$00                 ; VRAM offset $3F00 low
+        out (VDP_CTRL),a
+        ld a,$3F | $40           ; $3F | $40 = VRAM write
+        out (VDP_CTRL),a
+        ld b,64
+        ld c,VDP_DATA
+        otir
+
+        ; Write (X, tile) pairs to $3F80.
+        ld a,$80
+        out (VDP_CTRL),a
+        ld a,$3F | $40
+        out (VDP_CTRL),a
+        ld b,128                 ; 64 sprites × 2 bytes
+        ld c,VDP_DATA
+        otir
+        ret
+
+; To set sprite N's position to (x, y) and tile T from your game code:
+;   ld a,y      ; shadow_oam + N
+;   ld (shadow_oam + N),a
+;   ld a,x      ; shadow_oam + 0x80 + N*2
+;   ld (shadow_oam + 0x80 + N*2),a
+;   ld a,t
+;   ld (shadow_oam + 0x80 + N*2 + 1),a
+;
+; To hide all sprites (init): fill shadow_oam[0..63] with $D0.