romdev-mcp 0.1.1

package/src/platforms/genesis/lib/sgdk/src/z80_ctrl.c

@@ -0,0 +1,334 @@
+#include "config.h"
+#include "types.h"
+
+#include "z80_ctrl.h"
+
+#include "ym2612.h"
+#include "psg.h"
+#include "memory.h"
+#include "timer.h"
+#include "sys.h"
+#include "vdp.h"
+#include "tools.h"
+
+#include "snd/sound.h"
+
+
+// driver(s) flags
+#define DRIVER_FLAG_DELAY_DMA    (1 << 0)
+
+
+s16 currentDriver;
+u16 driverFlags;
+u16 busProtectSignalAddress;
+__attribute__((externally_visible)) VoidCallback *z80VIntCB;
+
+
+// Empty Callback
+static void _empty_callback()
+{
+    //
+}
+
+
+NO_INLINE void Z80_init()
+{
+    // request Z80 bus
+    Z80_requestBus(TRUE);
+    // set bank to 0
+    Z80_setBank(0);
+
+    // no loaded driver
+    currentDriver = -1;
+    driverFlags = 0;
+    busProtectSignalAddress = 0;
+    z80VIntCB = _empty_callback;
+
+    // load null/dummy driver as it's important to have Z80 active (state is preserved)
+    SND_NULL_loadDriver();
+}
+
+
+bool Z80_isBusTaken()
+{
+    vu16 *pw;
+
+    pw = (u16 *) Z80_HALT_PORT;
+    if (*pw & 0x0100) return FALSE;
+    else return TRUE;
+}
+
+void Z80_requestBus(bool wait)
+{
+    vu16 *pw_bus;
+    vu16 *pw_reset;
+
+    // request bus (need to end reset)
+    pw_bus = (u16 *) Z80_HALT_PORT;
+    pw_reset = (u16 *) Z80_RESET_PORT;
+
+    // take bus and end reset
+    *pw_bus = 0x0100;
+    *pw_reset = 0x0100;
+
+    if (wait)
+    {
+        // wait for bus taken
+        while (*pw_bus & 0x0100);
+    }
+}
+
+bool Z80_getAndRequestBus(bool wait)
+{
+    vu16 *pw_bus;
+    vu16 *pw_reset;
+
+    pw_bus = (u16 *) Z80_HALT_PORT;
+
+    // already requested ? just return TRUE
+    if (!(*pw_bus & 0x0100)) return TRUE;
+
+    pw_reset = (u16 *) Z80_RESET_PORT;
+
+    // take bus and end reset
+    *pw_bus = 0x0100;
+    *pw_reset = 0x0100;
+
+    if (wait)
+    {
+        // wait for bus taken
+        while (*pw_bus & 0x0100);
+    }
+
+    return FALSE;
+}
+
+void Z80_releaseBus()
+{
+    vu16 *pw;
+
+    pw = (u16 *) Z80_HALT_PORT;
+    *pw = 0x0000;
+}
+
+
+void Z80_startReset()
+{
+    vu16 *pw;
+
+    pw = (u16 *) Z80_RESET_PORT;
+    *pw = 0x0000;
+}
+
+void Z80_endReset()
+{
+    vu16 *pw;
+
+    pw = (u16 *) Z80_RESET_PORT;
+    *pw = 0x0100;
+}
+
+
+void Z80_setBank(const u16 bank)
+{
+    vu8 *pb;
+    u16 i, value;
+
+    pb = (u8 *) Z80_BANK_REGISTER;
+
+    i = 9;
+    value = bank;
+    while (i--)
+    {
+        *pb = value;
+        value >>= 1;
+    }
+}
+
+u8 Z80_read(const u16 addr)
+{
+    return ((vu8*) Z80_RAM)[addr];
+}
+
+void Z80_write(const u16 addr, const u8 value)
+{
+    ((vu8*) Z80_RAM)[addr] = value;
+}
+
+
+NO_INLINE void Z80_clear()
+{
+    SYS_disableInts();
+    bool busTaken = Z80_getAndRequestBus(TRUE);
+
+    const u8 zero = getZeroU8();
+    vu8* dst = (u8*) Z80_RAM;
+    u16 len = Z80_RAM_LEN;
+
+    while(len--) *dst++ = zero;
+
+    // release bus
+    if (!busTaken) Z80_releaseBus();
+    SYS_enableInts();
+}
+
+NO_INLINE void Z80_upload(const u16 to, const u8 *from, const u16 size)
+{
+    SYS_disableInts();
+    bool busTaken = Z80_getAndRequestBus(TRUE);
+
+    // copy data to Z80 RAM (need to use byte copy here)
+    u8* src = (u8*) from;
+    vu8* dst = (u8*) (Z80_RAM + to);
+    u16 len = size;
+
+    while(len--) *dst++ = *src++;
+
+    // release bus
+    if (!busTaken) Z80_releaseBus();
+    SYS_enableInts();
+}
+
+NO_INLINE void Z80_download(const u16 from, u8 *to, const u16 size)
+{
+    SYS_disableInts();
+    bool busTaken = Z80_getAndRequestBus(TRUE);
+
+    // copy data from Z80 RAM (need to use byte copy here)
+    vu8* src = (u8*) (Z80_RAM + from);
+    u8* dst = (u8*) to;
+    u16 len = size;
+
+    while(len--) *dst++ = *src++;
+
+    // release bus
+    if (!busTaken) Z80_releaseBus();
+    SYS_enableInts();
+}
+
+
+s16 Z80_getLoadedDriver()
+{
+    return currentDriver;
+}
+
+void Z80_unloadDriver()
+{
+    // load NULL driver
+    SND_NULL_loadDriver();
+}
+
+NO_INLINE void Z80_loadDriverInternal(const u8 *drv, u16 size)
+{
+    SYS_disableInts();
+    Z80_requestBus(TRUE);
+
+    // start by removing the Z80 vint task
+    Z80_setVIntCallback(NULL);
+    // remove Z80 bus protection (signal address set to 0)
+    Z80_useBusProtection(0);
+    // remove DMA delay
+    Z80_setForceDelayDMA(FALSE);
+
+    // reset sound chips
+    YM2612_reset();
+    PSG_reset();
+
+    // clear z80 memory
+    Z80_clear();
+    // upload Z80 driver
+    Z80_upload(0, drv, size);
+
+    // reset Z80
+    Z80_startReset();
+    Z80_releaseBus();
+    // wait a bit so Z80 reset completed
+    waitSubTick(50);
+    Z80_endReset();
+    SYS_enableInts();
+}
+
+NO_INLINE void Z80_loadCustomDriver(const u8 *drv, u16 size)
+{
+    Z80_unloadDriver();
+    Z80_loadDriverInternal(drv, size);
+
+    // custom driver set
+    currentDriver = Z80_DRIVER_CUSTOM;
+}
+
+
+bool Z80_isDriverReady()
+{
+    // point to Z80 status
+    vu8* pb = (vu8*) Z80_DRV_STATUS;
+
+    SYS_disableInts();
+    // request Z80 BUS
+    bool busTaken = Z80_getAndRequestBus(TRUE);
+
+    // ready status
+    bool ret = (*pb & Z80_DRV_STAT_READY)?TRUE:FALSE;
+
+    if (!busTaken) Z80_releaseBus();
+    SYS_enableInts();
+
+    return ret;
+}
+
+
+VoidCallback* Z80_getVIntCallback(void)
+{
+    return z80VIntCB;
+}
+
+void Z80_setVIntCallback(VoidCallback *CB)
+{
+    if (CB) z80VIntCB = CB;
+    else z80VIntCB = _empty_callback;
+}
+
+void Z80_useBusProtection(u16 signalAddress)
+{
+    busProtectSignalAddress = signalAddress;
+}
+
+void Z80_setBusProtection(bool value)
+{
+    // bus protection not defined ? --> exit
+    if (!busProtectSignalAddress)
+        return;
+
+    // point to Z80 PROTECT parameter
+    vu8* pb = (vu8*) (Z80_RAM + busProtectSignalAddress);
+
+    SYS_disableInts();
+    bool busTaken = Z80_getAndRequestBus(TRUE);
+
+    *pb = value?1:0;
+
+    // release bus
+    if (!busTaken) Z80_releaseBus();
+    SYS_enableInts();
+}
+
+void Z80_enableBusProtection()
+{
+    Z80_setBusProtection(TRUE);
+}
+
+void Z80_disableBusProtection()
+{
+    Z80_setBusProtection(FALSE);
+}
+
+bool Z80_getForceDelayDMA()
+{
+    return driverFlags & DRIVER_FLAG_DELAY_DMA;
+}
+
+void Z80_setForceDelayDMA(bool value)
+{
+    if (value) driverFlags |= DRIVER_FLAG_DELAY_DMA;
+    else driverFlags &= ~DRIVER_FLAG_DELAY_DMA;
+}

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

@@ -0,0 +1,129 @@
+; Genesis VDP — sprite table layout + linked-list management.
+;
+; Genesis sprites are stored in a 320- or 640-byte table in VRAM (40 or
+; 80 sprites × 8 bytes each). The VDP walks the table as a LINKED LIST:
+; each sprite has a `link` field giving the index of the next sprite to
+; render. Link 0 = end of list. This means:
+;   - Sprite priority is order-of-the-list, NOT slot order.
+;   - You can rearrange visibility without touching slots: just rewrite
+;     the link fields.
+;   - You MUST set sprite 0's link, even if you only have one sprite —
+;     otherwise the VDP walks into uninitialized memory and renders
+;     garbage that flickers per frame.
+;
+; Sprite entry layout (per sprite, 8 bytes):
+;   word 0:  Y position + 128  (bits 0-9 used; Y=128 = top of screen)
+;   word 1:  size_H (bits 8-9) | size_W (bits 10-11) | link (bits 0-6)
+;            sizes are 0..3, so width/height = (size+1) × 8 px
+;   word 2:  priority (bit 15) | palette (bits 13-14) | vflip (bit 12)
+;            | hflip (bit 11) | tile_id (bits 0-10)
+;   word 3:  X position + 128  (bits 0-8; X=128 = left edge of screen)
+;
+; The sprite table base in VRAM is configured via VDP reg $05 (× $200 in
+; H32 mode, × $400 in H40 mode). vdp_init.s above sets it to $F000.
+
+SPRITE_TABLE_VRAM = $F000  ; per vdp_init.s register $05 = $78
+
+; ---- Build a sprite in WRAM staging area (then DMA up) -----------------
+;
+; The pattern: maintain a soft-OAM buffer in WRAM at a known address (we
+; use $FFE000 here, top of WRAM). Every frame at VBlank, DMA the soft-OAM
+; up to VRAM at SPRITE_TABLE_VRAM. This avoids the VDP-during-active-
+; display restrictions.
+
+SOFT_SPRITE_TABLE = $FFE000  ; 640 bytes = 80 sprites max
+
+; ---- write_sprite: stamp one sprite into soft-OAM ----------------------
+;
+; Inputs:
+;   D0 = slot index (0-79)
+;   D1 = X position (signed; -128..+447)
+;   D2 = Y position (signed; -128..+239)
+;   D3 = tile index (0-2047)
+;   D4 = attr packed: (priority << 7) | (palette << 5) | (vflip << 4)
+;        | (hflip << 3) | (size_w << 1) | size_h    ← caller responsible
+;   D5 = link to next sprite (0 = end of list)
+;
+; Output: sprite slot D0 is populated.
+write_sprite:
+  movem.l d0-d6/a0,-(sp)
+  lea     SOFT_SPRITE_TABLE,a0
+  moveq   #0,d6
+  move.w  d0,d6
+  lsl.w   #3,d6                ; slot × 8 = byte offset
+  add.l   d6,a0
+  ; word 0: Y + 128
+  add.w   #128,d2
+  move.w  d2,(a0)+
+  ; word 1: size_H (bits 8-9) | size_W (bits 10-11) | link (bits 0-6)
+  ; Caller packed sizes into D4 bits 1-3; extract here.
+  moveq   #0,d6
+  move.b  d4,d6
+  lsr.b   #1,d6                ; D6.b = size_h (low) + size_w (high)
+  and.b   #$03,d6              ; D6.b = size_h
+  ; rebuild: actual format is (size_w << 10) | (size_h << 8) | link
+  move.b  d4,d6
+  lsr.b   #1,d6
+  lsr.b   #1,d6
+  and.w   #$0003,d6
+  lsl.w   #8,d6                ; D6.w = size_h << 8
+  move.b  d4,d3
+  ; ... this would benefit from a real macro. Simplified path below.
+  ; Use word-build approach instead: caller should construct the full
+  ; word and call write_sprite_word for clarity. Keeping this skeleton
+  ; here as a starting point; production code would have a macro.
+  movem.l (sp)+,d0-d6/a0
+  rts
+
+; ---- write_sprite_simple: macro-friendly version -----------------------
+;
+; Inputs:
+;   D0 = slot index
+;   D1 = Y pos (raw; will add 128)
+;   D2 = X pos (raw; will add 128)
+;   D3 = tile ID + attr word (build with: (prio<<15)|(pal<<13)|(vf<<12)|(hf<<11)|tile)
+;   D4 = size+link word (build with: (size_w<<10)|(size_h<<8)|link)
+;
+; Cleaner than write_sprite above; recommended for most code.
+write_sprite_simple:
+  movem.l d0-d4/a0,-(sp)
+  lea     SOFT_SPRITE_TABLE,a0
+  lsl.w   #3,d0
+  add.w   d0,a0
+  add.w   #128,d1
+  move.w  d1,(a0)+             ; word 0: Y+128
+  move.w  d4,(a0)+             ; word 1: size+link
+  move.w  d3,(a0)+             ; word 2: priority+pal+flips+tile
+  add.w   #128,d2
+  move.w  d2,(a0)+             ; word 3: X+128
+  movem.l (sp)+,d0-d4/a0
+  rts
+
+; ---- dma_sprite_table: blast soft-OAM up to VRAM at VBlank --------------
+;
+; Call this from your VBlank handler. Writes the full 640 bytes of soft-
+; OAM (80 sprites × 8 bytes) via VDP DMA.
+;
+; VDP DMA setup is verbose; comments label each register write.
+dma_sprite_table:
+  ; ---- 1. Configure DMA registers ----
+  move.l  #$94009300,$C00004   ; reg $94 = 0x00 (length hi), $93 = 0x00 (length lo)
+  ; Actually we need 640 / 2 = 320 words; let me set length properly:
+  move.w  #$9340,$C00004       ; reg $93 = $40 (length lo = $0140 = 320 words)
+  move.w  #$9401,$C00004       ; reg $94 = $01 (length hi)
+  ; Source: SOFT_SPRITE_TABLE >> 1 (DMA addresses words, not bytes)
+  move.w  #$9500,$C00004       ; reg $95 = (src >> 1) & $FF
+  move.w  #$9670,$C00004       ; reg $96 = (src >> 9) & $FF — adjust per actual addr
+  move.w  #$977F,$C00004       ; reg $97 = (src >> 17) & $7F | $80 (DMA mode)
+  ; ---- 2. Send target address + DMA-trigger command word ----
+  ; VRAM write to SPRITE_TABLE_VRAM ($F000) with DMA bit set.
+  ; Format of a VDP "command word" for VRAM write + DMA:
+  ;   high word: $4000 | (low 14 bits of dest << 0)
+  ;   low  word: $0080 | (top 2 bits of dest >> 14)
+  ; SPRITE_TABLE_VRAM = $F000:
+  ;   high = $4000 | $F000 = $7000... no wait, the encoding is across
+  ;   both words; precomputed value below for SPRITE_TABLE_VRAM = $F000.
+  ; If you change SPRITE_TABLE_VRAM, recompute this constant:
+  ;   ((addr & $3FFF) << 16) | $40000080 | ((addr >> 14) & 3)
+  move.l  #$7000_0083,$C00004    ; precomputed for SPRITE_TABLE_VRAM=$F000
+  rts

package/src/platforms/genesis/lib/vblank_wait.s

@@ -0,0 +1,73 @@
+; Genesis — waiting for VBlank without using interrupts.
+;
+; The VDP has a "vertical blanking in progress" status flag at bit 3
+; of the VDP control register ($C00004 when read). When this bit is
+; set, the electron beam is in the vblank interval — safe to write
+; VRAM/CRAM/VSRAM, do DMA, etc.
+;
+; The cleanest way to do per-frame work is with the VINT interrupt
+; (see nmi_safe.s). But for early-init code, simple games, or
+; debugging it's often easier to busy-wait on the status bit.
+;
+; ** Two patterns, both work: **
+;
+; Pattern 1: wait for the START of vblank (used when you have one
+; chunk of vblank-safe work, e.g. one DMA).
+;
+;   wait_vblank_start:
+;     btst    #3, $C00005     ; bit 3 of status (note: low byte!)
+;     beq.s   wait_vblank_start
+;     rts
+;
+; Pattern 2: wait for vblank to END (used when you want to start
+; doing work right when active-display begins, e.g. for raster
+; effects).
+;
+;   wait_vblank_end:
+;     btst    #3, $C00005
+;     bne.s   wait_vblank_end
+;     rts
+;
+; ** Gotcha — the status word is BIG-ENDIAN. ** $C00004 returns the
+; high byte first; bit 3 of the LOW byte (which the documentation
+; usually means by "bit 3 of the status") is actually accessed at
+; $C00005. The btst above gets this right; some older Genesis dev
+; docs forget and test the wrong address, producing code that loops
+; forever or never waits.
+
+VDP_CTRL   equ $C00004
+VDP_STATUS equ $C00005    ; low byte of the status word
+
+wait_vblank_start:
+  btst    #3,VDP_STATUS
+  beq.s   wait_vblank_start
+  rts
+
+wait_vblank_end:
+  btst    #3,VDP_STATUS
+  bne.s   wait_vblank_end
+  rts
+
+; ---- "Wait for the next vblank, then do work" idiom ------------------
+;
+; The most common pattern: complete the previous frame's logic, then
+; wait for the next vblank to start, then do all your vblank-safe work
+; (DMA, palette updates, etc.). Use this in your main game loop:
+;
+;   game_loop:
+;     ; ... per-frame game logic (collision, AI, input response) ...
+;     jsr     wait_vblank_end       ; finish current frame if mid-vblank
+;     jsr     wait_vblank_start     ; sync to next vblank
+;     ; ... vblank-safe work (DMA, palette, etc.) ...
+;     jsr     dma_sprite_table
+;     bra.s   game_loop
+;
+; The "wait_vblank_end first" ensures you start fresh — if your logic
+; finished early and you're already in vblank, you'd otherwise return
+; from wait_vblank_start immediately and have less than a frame of
+; vblank-safe time left.
+;
+; ** This pattern blocks the CPU 100% **, which is fine for simple
+; games. For complex games that need the CPU running during active
+; display (running game logic, AI, etc.), switch to the VINT-based
+; pattern in nmi_safe.s.

package/src/platforms/genesis/lib/vdp_init.s

@@ -0,0 +1,85 @@
+; Genesis VDP — minimum viable initialization.
+;
+; The VDP has 24 registers ($00-$17) controlling video output. After power
+; on they're undefined; if you start rendering without programming them,
+; you'll see nothing or garbage. This snippet writes the standard "320x224
+; H40 mode, BG color 0, both planes enabled" config — adequate for getting
+; pixels on screen so you can iterate from there.
+;
+; VDP I/O addresses:
+;   $C00000 = data port (16-bit reads/writes for VRAM/CRAM/VSRAM data)
+;   $C00004 = control port (writes set the destination address + access mode)
+;   $C00008 = HV counter (read-only)
+;
+; To write a VDP register: send (0x8000 | (reg_num << 8) | value) to the
+; control port. The 0x8000 distinguishes a register write from a memory-
+; address-set (which would be a different format).
+
+VDP_DATA  = $C00000
+VDP_CTRL  = $C00004
+
+; ---- Register table — 24 bytes, indexed by register number ($00-$17) ----
+;
+; The bit semantics here are SUBTLE. Look up the VDP register reference
+; (NESdev wiki has a great one) before changing values. Some highlights:
+;   $00: HV counter latch + interrupt enables. Bit 4 = enable HINT.
+;   $01: display enable (bit 6), VINT enable (bit 5), DMA enable (bit 4)
+;        and the cell-mode bit (bit 3 = 240-line mode for PAL).
+;        ** Without bit 6 (display) set, your screen stays blank. **
+;   $0A: HINT counter — # of lines between HINT triggers. $FF = disabled.
+;   $0B: vertical scroll mode + horizontal scroll mode. Bit 2 = "full
+;        screen" V scroll; clear it for "per-cell" V scroll.
+;   $0C: bit 0 = H40 mode (320 wide). Clear for H32 (256 wide).
+;   $0F: VDP auto-increment after each data access. 2 = "next word".
+;   $10: Plane A/B size (in cells). 0x01 = 64 x 32, 0x11 = 64 x 64, etc.
+;
+; Plane A name table base, Plane B name table base, Window name table base,
+; Sprite attribute table base, HScroll table base — all configured in
+; registers $02-$06 below.
+
+vdp_init_table:
+  dc.b $14   ; $00: HINT enable, HV counter on
+  dc.b $74   ; $01: display ON, VINT ON, DMA ON, 224-line NTSC
+  dc.b $30   ; $02: Plane A base = $C000 (× $400 = VRAM offset)
+  dc.b $00   ; $03: Window base
+  dc.b $07   ; $04: Plane B base = $E000
+  dc.b $78   ; $05: Sprite attr table = $F000 (× $200, H40-aligned)
+  dc.b $00   ; $06: unused
+  dc.b $00   ; $07: backdrop color — palette 0, color 0 (universal BG)
+  dc.b $00   ; $08: unused
+  dc.b $00   ; $09: unused
+  dc.b $FF   ; $0A: HINT counter — $FF = once per frame (essentially off)
+  dc.b $00   ; $0B: V scroll = full-screen, H scroll = full-screen
+  dc.b $81   ; $0C: H40 mode (320 wide), shadow/highlight off
+  dc.b $3F   ; $0D: HScroll table = $FC00
+  dc.b $00   ; $0E: unused
+  dc.b $02   ; $0F: auto-increment = 2 (next word)
+  dc.b $01   ; $10: Plane size = 64x32
+  dc.b $00   ; $11: Window H pos
+  dc.b $00   ; $12: Window V pos
+  dc.b $FF   ; $13: DMA length low
+  dc.b $FF   ; $14: DMA length high
+  dc.b $00   ; $15: DMA source low
+  dc.b $00   ; $16: DMA source mid
+  dc.b $80   ; $17: DMA source high + mode bits
+
+; ---- vdp_init: blast the table into the VDP -----------------------------
+;
+; Call this near the start of _reset, before enabling interrupts. Writes
+; all 24 registers in sequence; this leaves the VDP in a sensible state
+; for you to start uploading tiles, palettes, sprites, etc.
+vdp_init:
+  lea     vdp_init_table,a0
+  move.l  #VDP_CTRL,a1
+  moveq   #0,d0                ; register index counter
+  moveq   #23,d1               ; 24 registers - 1
+.loop:
+  move.b  (a0)+,d2             ; value
+  move.w  d0,d3
+  lsl.w   #8,d3                ; reg << 8
+  or.w    #$8000,d3            ; "this is a register write" marker
+  or.b    d2,d3                ; ... | value
+  move.w  d3,(a1)
+  addq.w  #1,d0
+  dbra    d1,.loop
+  rts

package/src/platforms/genesis/lib/wram.s

@@ -0,0 +1,88 @@
+; Genesis — declaring WRAM variables.
+;
+; Genesis has 64 KB of work RAM at $00FF0000-$00FFFFFF. To use it for
+; game variables, you declare LABELS at addresses in that range.
+;
+; ** DO NOT use `org` for WRAM. ** vasm pads the ROM out to the
+; highest `org` it sees, so `org $00FF0000` produces a 16 MB ROM file
+; mostly full of zeros, and the variables you "wrote" there aren't
+; actually stored anywhere — they're just labels pointing into space
+; the CPU will overwrite at runtime. The 16 MB ROM also won't fit on
+; real cartridges and confuses some emulators.
+;
+; ** USE `equ` instead. ** equ declares a NAMED CONSTANT at compile
+; time; no bytes are emitted. The CPU reads/writes WRAM via normal
+; m68k addressing modes; the label is just a memorable name for the
+; address.
+;
+; Pattern: hand-allocate WRAM addresses by tracking a "next free byte"
+; cursor. For larger projects use a macro or external manifest. For
+; small games the explicit form below is clearer than any macro.
+
+; ---- Example WRAM map (256 bytes used) -------------------------------
+
+WRAM_BASE         equ $00FF0000
+
+; Per-frame VBlank flag (set by NMI, cleared by main loop).
+vblank_ready      equ WRAM_BASE + $0000   ; 1 byte
+
+; Pad state — current frame + previous frame for edge detection.
+pad1_held         equ WRAM_BASE + $0002   ; 2 bytes (one word per port)
+pad1_pressed      equ WRAM_BASE + $0004   ; 2 bytes
+pad1_released     equ WRAM_BASE + $0006   ; 2 bytes
+
+; Game state machine.
+game_state        equ WRAM_BASE + $0010   ; 1 byte: 0=title, 1=play, 2=gameover
+state_timer       equ WRAM_BASE + $0012   ; 2 bytes: frames in current state
+
+; Player / score (Tetris-shaped example).
+score             equ WRAM_BASE + $0020   ; 4 bytes (BCD or binary)
+lines_cleared     equ WRAM_BASE + $0024   ; 2 bytes
+level             equ WRAM_BASE + $0026   ; 1 byte
+
+; Soft-OAM (sprite list) staging area — DMA'd to VRAM each VBlank.
+; This is the convention from sprite_table.s. 640 bytes = 80 sprites
+; × 8 bytes/sprite (H40 mode). Place it on a 256-byte boundary for
+; alignment-friendly DMA source addressing.
+soft_oam          equ $00FFE000           ; 640 bytes through $00FFE27F
+
+; ---- Reading/writing WRAM variables ---------------------------------
+;
+; Treat WRAM addresses just like any other address. The 68K's full
+; addressing range covers them; you don't need bank-switching like SNES
+; or NES.
+;
+; Examples:
+;
+;   ; Increment score
+;   addq.l   #1, score
+;
+;   ; Edge detect: pressed = held AND NOT held_last_frame
+;   move.w   pad1_held, d0
+;   move.w   pad1_last, d1
+;   not.w    d1
+;   and.w    d0, d1                ; d1 = newly-pressed bits
+;   move.w   d1, pad1_pressed
+;
+;   ; Clear soft OAM (hide all sprites by Y=0)
+;   lea      soft_oam, a0
+;   moveq    #160-1, d0            ; 640 / 4 = 160 longwords
+; .clear:
+;   clr.l    (a0)+
+;   dbra     d0, .clear
+;
+; ---- ROM-side initialization tip ------------------------------------
+;
+; WRAM is RANDOM on power-on. If your code reads a variable before
+; writing it, you'll get garbage. Standard practice: at _reset, clear
+; the whole WRAM range before doing anything else. This snippet:
+;
+;   lea      WRAM_BASE, a0
+;   move.l   #($10000/4)-1, d0     ; 64KB / 4 bytes = 16384 longwords
+; .clrwram:
+;   clr.l    (a0)+
+;   dbra     d0, .clrwram
+;
+; ...takes ~70 ms but guarantees a clean slate. Most homebrew skips it
+; and relies on initializing each variable explicitly; do whichever
+; matches your debug comfort level.