feat: Super Game Boy day/night borders, chosen by the seed

Each sea gets a day or night SGB border selected by bit 0 of wSeed16,
beamed over with CHR_TRN/PCT_TRN VRAM transfers while the screen is
frozen via MASK_EN. Sent once per voyage from EnterSail (and at boot
when a save exists, so the title screen gets the saved sea's sky).

- tools/png2sgb.py converts 256x224 PNGs to SNES 4bpp tiles + 32x28(+1)
  map + three 15-color palettes (color quantize + least-damaging tile
  merges to fit the 256-tile CHR RAM); output committed as src/sgb_*.inc
- sgb.asm: JOYP packet sender, SGB VRAM transfer, screen freeze/restore
- detection via boot-ROM C register ($14 = SGB/SGB2); header $0146=$03
  and $014B=$33 unlock SGB functions; ROM grows to 64 KiB (banks 1-2)
- test_sgb.py: header bytes, DMG-inert, forced full-path transfer run
- verified visually in Mesen2 (SGB2 firmware): day + night borders at
  the title screen and while sailing

Author: splch

.gitignore

@@ -8,3 +8,6 @@ tools/rgbds/
 build/
 *.gb
 *.gb.ram
+
+# Python test artifacts
+__pycache__/

Makefile

@@ -5,7 +5,7 @@ RGBASM := $(RGBDS)rgbasm
 RGBLINK := $(RGBDS)rgblink
 RGBFIX := $(RGBDS)rgbfix
 
-SRC := src/main.asm src/joypad.asm src/rng.asm src/tiles.asm src/sail.asm src/world.asm src/port.asm src/combat.asm src/isles.asm src/sound.asm
+SRC := src/main.asm src/joypad.asm src/rng.asm src/tiles.asm src/sail.asm src/world.asm src/port.asm src/combat.asm src/isles.asm src/sound.asm src/sgb.asm
 OBJ := $(SRC:src/%.asm=build/%.o)
 
 pirates_folly.gb: $(OBJ)
@@ -15,6 +15,14 @@ pirates_folly.gb: $(OBJ)
 build/%.o: src/%.asm src/defs.inc src/testmap.inc include/hardware.inc | build
 	$(RGBASM) -o $@ -I include/ -I src/ -Wall $<
 
+build/sgb.o: src/sgb_day.inc src/sgb_night.inc
+
+# Regenerate the SGB border data after editing the art (needs numpy):
+src/sgb_day.inc: res/sgb_day.png tools/png2sgb.py
+	python3 tools/png2sgb.py $< $@ sgb_day 1
+src/sgb_night.inc: res/sgb_night.png tools/png2sgb.py
+	python3 tools/png2sgb.py $< $@ sgb_night 2
+
 build:
 	mkdir -p build
 

README.md

@@ -12,7 +12,8 @@ Assemble all nine, survive the final fleet, and the Treasure of the Nine
 Isles is yours.
 
 Runs on DMG, CGB, AGB, SGB, emulators, and Analogue Pocket. DMG-first
-(4 shades), with color palettes auto-detected on CGB.
+(4 shades), with color palettes auto-detected on CGB. On a Super Game Boy
+each sea gets a day or night border, chosen by the seed itself.
 
 ## Playing
 
@@ -89,6 +90,7 @@ python tests/lint_worlds.py    # seed sweep: spawns, isle land, port census
 - `test_title.py` / `test_cgb.py` — title screen, CGB palette init, DMG/CGB parity
 - `test_m2.py` … `test_m5.py` — worldgen/streaming, ports & economy, combat, the Nine Isles
 - `test_sound.py` — APU driver and song/SFX triggers
+- `test_sgb.py` — SGB header/detection, forced-run of the border transfer
 - `test_ports_m6.py` — port content pass
 - `tests/lint_worlds.py` — reimplements the worldgen math in Python and sweeps
   16 seeds against the running ROM, validating spawns land on water, every
@@ -110,13 +112,17 @@ src/            RGBDS assembly (the whole game is hand-written SM83)
   isles.asm     the Nine Isles, digs, final battle, victory
   port.asm      docking, market, tavern, repair/recruit, battery save/load
   sound.asm     3-channel shanty driver + SFX (no hUGEDriver)
+  sgb.asm       SGB border transfer (CHR_TRN/PCT_TRN), seed-picked day/night
+  sgb_day.inc, sgb_night.inc   generated border data (tools/png2sgb.py)
   tiles.asm     hand-drawn 2bpp tiles & 3x5 font (gfx literals), CGB palettes
   rng.asm       Mul8, Mix16 coordinate hash, xorshift16 PRNG
   joypad.asm    input with new-press detection and auto-repeat
   defs.inc      shared constants (states, tiles, tuning knobs)
   gen.asm, testmap.asm   legacy M0/M1 generator-lab artifacts (not built)
 tests/          PyBoy headless test suite + world lint + balance tuner
-tools/          gen_testmap.py (legacy), vendored RGBDS (gitignored)
+res/            SGB border art (256x224 PNGs)
+tools/          png2sgb.py (SGB border converter), gen_testmap.py (legacy),
+                vendored RGBDS (gitignored)
 docs/           PIRATE_GAME_PLAN.md, PIRATE_LORE.md, dev references
 MANUAL.md       the player's manual
 ```
@@ -138,6 +144,11 @@ MANUAL.md       the player's manual
   districts), port names (16×16 prefix/suffix), market price drift, tavern
   rumors, encounter rolls, and the Nine Isles' positions are all pure hash
   functions of coordinates + seed — deterministic and storage-free.
+- **SGB borders.** On SGB/SGB2 (detected via the boot ROM's C register),
+  the border is beamed over with CHR_TRN/PCT_TRN VRAM transfers while the
+  screen is frozen with MASK_EN: 256 SNES 4bpp tiles, a 32x28+1 map, and
+  three 15-color palettes per border, all generated offline from PNG art.
+  Day or night is bit 0 of `wSeed16` — the sky is part of the world.
 - **Battery save.** MBC5 SRAM at `$A000` with magic bytes, a version field,
   and a checksum; validated on boot. Isle positions are recomputed from the
   seed on load, never saved.

res/sgb_day.png

@@ -15,6 +15,10 @@ SECTION "VBlank vector", ROM0[$0040]
 SECTION "Header", ROM0[$0100]
     nop
     jp EntryPoint
+    ds $0146 - @, 0             ; rgbfix -v fills the logo and checksums
+    db $03                      ; $0146: SGB flag — unlock SGB functions
+    ds $014B - @, 0
+    db $33                      ; $014B: old licensee $33 — required for SGB
     ds $0150 - @, 0
 
 SECTION "Shared WRAM", WRAM0
@@ -31,11 +35,14 @@ wSeedNib::      ds 8
 wSeed16::      dw             ; seed folded to 16 bits for the generator
 wRngState::    dw
 wIsCGB::       db             ; $11 = CGB/AGB (boot ROM leaves it in a)
+wIsSGB::       db             ; $14 = SGB/SGB2 (boot ROM leaves it in c)
 
 SECTION "Main", ROM0[$0150]
 EntryPoint:
     di
     ld [wIsCGB], a               ; boot ROM: $11 on CGB/AGB, $01 on DMG
+    ld a, c
+    ld [wIsSGB], a               ; boot ROM: $14 on SGB/SGB2, $13 on DMG/MGB
     ld sp, $E000
 
 .waitVb                          ; LCD is on after boot ROM; find VBlank
@@ -135,6 +142,19 @@ EntryPoint:
 
     ld a, LCDC_ON | LCDC_BG_ON | LCDC_BLOCK01
     ldh [rLCDC], a
+    ; SGB: give the title screen the saved voyage's border, if there is one
+    ; (no save: the seed isn't final until the editor, so EnterSail does it)
+    ld a, [wHasSave]
+    and a
+    jr z, .noBorder
+    call SGBTransferBorder
+    and a
+    jr z, .noBorder
+    call DrawTitleScreen         ; redraw what the transfer trashed (LCD off)
+    ld a, LCDC_ON | LCDC_BG_ON | LCDC_BLOCK01
+    ldh [rLCDC], a
+    call SGBUnfreeze
+.noBorder
     xor a
     ldh [rIF], a
     ld a, IE_VBLANK

res/sgb_night.png

@@ -72,6 +72,12 @@ EnterSail::
     call ComputeShipPx
     call SailCamera
     call SailRedrawBody
+    call SGBTransferBorder       ; the seed is final now: send its border
+    and a
+    jr z, .noSGB                 ; not SGB: nothing was touched
+    call SailRedrawBody          ; rebuild what the transfer trashed
+    call SGBUnfreeze
+.noSGB
     ld a, SONG_SAIL
     call SetSong
     ret

src/main.asm

@@ -0,0 +1,235 @@
+; Super Game Boy border: each sea gets a day or night border, chosen by
+; bit 0 of the folded seed (a pure function of the seed, like the world).
+; Border art lives in ROMX banks 1-2 (generated by tools/png2sgb.py from
+; res/sgb_day.png / res/sgb_night.png) and is beamed to the SNES with the
+; SGB VRAM-transfer commands (pandocs: SGB VRAM Transfer, Command Border).
+;
+; Unlock requirements (cartridge header, set in main.asm): $0146 = $03 and
+; $014B = $33. Detection: the boot ROM leaves C = $14 only on SGB/SGB2.
+
+INCLUDE "hardware.inc"
+INCLUDE "defs.inc"
+
+SECTION "SGB WRAM", WRAM0
+wSGBBank: db            ; ROM bank of the selected border
+wSGBSrc:  dw            ; its tile data address (map/pal follow at fixed offsets)
+
+SECTION "SGB", ROM0
+
+; in: hl = 16-byte packet. Bit-banged over JOYP bits 4/5: start pulse,
+; 128 data bits (LSB first; P14 low = 0, P15 low = 1), stop 0 bit.
+; Pulses >= 5 M-cycles, spaces >= 15 M-cycles, per pandocs.
+SGBSendPacket:
+    xor a
+    ldh [rJOYP], a             ; start pulse: P14+P15 low
+    nop
+    nop
+    nop
+    ld a, $30
+    ldh [rJOYP], a             ; idle
+    ld b, 16
+.byte
+    ld e, [hl]
+    inc hl
+    ld c, 8
+.bit
+    ld a, $20                  ; P14 low = 0 bit
+    rr e
+    jr nc, .send
+    ld a, $10                  ; P15 low = 1 bit
+.send
+    ldh [rJOYP], a
+    nop
+    nop
+    nop
+    ld a, $30
+    ldh [rJOYP], a             ; idle high
+    nop
+    nop
+    nop
+    nop
+    nop
+    dec c
+    jr nz, .bit
+    dec b
+    jr nz, .byte
+    ld a, $20                  ; stop bit: 0
+    ldh [rJOYP], a
+    nop
+    nop
+    nop
+    ld a, $30
+    ldh [rJOYP], a
+    ret
+
+; in: b = frames to wait. LCD must be ON (polls LY).
+SGBWaitVBlanks:
+.out
+    ldh a, [rLY]
+    cp 144
+    jr nc, .out
+.in
+    ldh a, [rLY]
+    cp 144
+    jr c, .in
+    dec b
+    jr nz, .out
+    ret
+
+; The SGB reads VRAM-transfer data out of the video signal: the BG map must
+; display tiles $00-$FF in order ($00-$13 on the first row, $14-$27 next).
+; LCD off. clobbers a, b, c, d, e, h, l
+SGBFillSeqMap:
+    ld hl, $9800
+    xor a                      ; tile number (wraps mod 256)
+    ld c, 14                   ; 14 rows x 20 = 280 >= 256
+.row
+    ld b, 20
+.col
+    ld [hli], a
+    inc a
+    dec b
+    jr nz, .col
+    ld de, 32 - 20
+    add hl, de
+    dec c
+    jr nz, .row
+    ret
+
+; in: a = ROM bank, hl = source (ROMX), de = dest (VRAM), bc = count. LCD off.
+SGBCopyROMtoVRAM:
+    ld [$2000], a              ; MBC5 ROM bank select
+.loop
+    ld a, [hli]
+    ld [de], a
+    inc de
+    dec bc
+    ld a, b
+    or c
+    jr nz, .loop
+    ret
+
+; out: hl = wSGBSrc, a = wSGBBank
+SGBGetSrc:
+    ld a, [wSGBSrc]
+    ld l, a
+    ld a, [wSGBSrc+1]
+    ld h, a
+    ld a, [wSGBBank]
+    ret
+
+; Beam the seed's border to the SGB. Entry: LCD on (a nice frame showing,
+; it gets frozen). out: a = 1 and LCD OFF (VRAM trashed, game tiles
+; reloaded) iff running on SGB and the border was sent; a = 0 and LCD
+; untouched otherwise. Caller redraws its screen, then calls SGBUnfreeze.
+SGBTransferBorder::
+    ld a, [wIsSGB]
+    cp $14                       ; $14 = SGB/SGB2 (boot ROM C value)
+    jr z, .sgb
+    xor a
+    ret
+.sgb
+    ; day or night: bit 0 of the folded seed
+    ld a, [wSeed16+1]
+    and 1
+    jr nz, .night
+    ld a, BANK(sgb_day_tiles)
+    ld hl, sgb_day_tiles
+    jr .sel
+.night
+    ld a, BANK(sgb_night_tiles)
+    ld hl, sgb_night_tiles
+.sel
+    ld [wSGBBank], a
+    ld a, l
+    ld [wSGBSrc], a
+    ld a, h
+    ld [wSGBSrc+1], a
+    ; freeze the SGB display so the VRAM trashing stays invisible
+    ld hl, SGB_PKT_MASK_FRZ
+    call SGBSendPacket
+    ld b, 4                      ; >= 60 ms between packets (pandocs)
+    call SGBWaitVBlanks
+    ; transfer setup: canonical BGP, no scroll, map shows tiles $00-$FF
+    call WaitVBlankPoll
+    xor a
+    ldh [rLCDC], a
+    ldh [rSCX], a
+    ldh [rSCY], a
+    ld a, $E4
+    ldh [rBGP], a
+    call SGBFillSeqMap
+    ; --- CHR_TRN: border tiles $00-$7F ---
+    call SGBGetSrc
+    ld de, $8000
+    ld bc, 4096
+    call SGBCopyROMtoVRAM
+    ld a, LCDC_ON | LCDC_BG_ON | LCDC_BLOCK01
+    ldh [rLCDC], a
+    ld hl, SGB_PKT_CHR0
+    call SGBSendPacket
+    ld b, 6                      ; transfer runs through the 5th frame
+    call SGBWaitVBlanks
+    ; --- CHR_TRN: border tiles $80-$FF ---
+    call WaitVBlankPoll
+    xor a
+    ldh [rLCDC], a
+    call SGBGetSrc
+    ld bc, 4096
+    add hl, bc
+    ld de, $8000
+    ld bc, 4096
+    call SGBCopyROMtoVRAM
+    ld a, LCDC_ON | LCDC_BG_ON | LCDC_BLOCK01
+    ldh [rLCDC], a
+    ld hl, SGB_PKT_CHR1
+    call SGBSendPacket
+    ld b, 6
+    call SGBWaitVBlanks
+    ; --- PCT_TRN: 32x28+1 map at $8000, palettes 4-6 at $8800 ---
+    call WaitVBlankPoll
+    xor a
+    ldh [rLCDC], a
+    call SGBGetSrc
+    ld bc, 8192
+    add hl, bc
+    ld de, $8000
+    ld bc, 1856
+    call SGBCopyROMtoVRAM
+    call SGBGetSrc
+    ld bc, 8192 + 1856
+    add hl, bc
+    ld de, $8800
+    ld bc, 96
+    call SGBCopyROMtoVRAM
+    ld a, LCDC_ON | LCDC_BG_ON | LCDC_BLOCK01
+    ldh [rLCDC], a
+    ld hl, SGB_PKT_PCT
+    call SGBSendPacket
+    ld b, 6
+    call SGBWaitVBlanks
+    ; done: LCD off, game tiles restored. Caller redraws + unfreezes.
+    call WaitVBlankPoll
+    xor a
+    ldh [rLCDC], a
+    call LoadTiles
+    ld a, 1
+    ret
+
+; Unfreeze the SGB display after the post-transfer redraw. No-op off SGB.
+SGBUnfreeze::
+    ld a, [wIsSGB]
+    cp $14
+    ret nz
+    ld hl, SGB_PKT_MASK_OFF
+    jp SGBSendPacket
+
+SECTION "SGB packets", ROM0
+SGB_PKT_MASK_FRZ: db $B9, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ; MASK_EN freeze
+SGB_PKT_MASK_OFF: db $B9, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ; MASK_EN off
+SGB_PKT_CHR0:     db $99, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ; CHR_TRN tiles $00-$7F
+SGB_PKT_CHR1:     db $99, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ; CHR_TRN tiles $80-$FF
+SGB_PKT_PCT:      db $A1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ; PCT_TRN
+
+INCLUDE "sgb_day.inc"
+INCLUDE "sgb_night.inc"