GPS

Gopher Popcorn Stew (GPS) is the standard custom block inserter for Super Mario World. It assembles each block's ASM with Asar, puts it in free space, and makes a chosen Map16 tile run that code whenever Mario or a sprite touches it. It also sets the tile's acts-like. This page describes GPS V1.4.5, with main.asm and the tool's src.zip (main.cpp plus Asar's DLL loader). GPS 1.4.5 ships Asar 1.91's DLL.

GPS's files carry no licence text, so this page describes behaviour and formats in its own words and quotes none of GPS's code. The findings come from GPS's documented formats, from its files, and from its observed output on LM-edited ROMs.

A clean-room reimplementation of the block driver and inserter exists in Pipe Dream.

Files

FileWhat it is
list.txtThe insertion list: Map16 tile (or range) → block .asm, with an optional acts-like. The shipped copy is empty apart from a comment
blocks/One .asm file per block
blocks/template.asmThe block API contract: the header and one entry point per contact, each a bare RTL
main.asmThe block driver: the dispatch stubs, block_execute and the tables
defines.asmThe address map that blocks are written against. It is SA-1 aware, and it is the important one
routines/The shared routine library: 27 routines covering Map16 changes, spawning, shattering and score
src.zipThe tool's source (main.cpp, about 30 KB)
README.txt, Changes.txtThe format and command-line docs

What GPS does, step by step

  1. Reads list.txt. Each line maps a Map16 tile, a range (R203-214) or a rectangle to a block file, optionally with an acts-like after a colon (200:0130 above.asm).
  2. Assembles each block with Asar. It runs one Asar patch per block file, so a hack with a couple of hundred block files takes seconds to insert.
  3. Puts each routine from routines/ that a block calls (as %name()) into free space once. Blocks get a macro that JSLs to it.
  4. Writes the per-tile tables (block_bank_byte, block_pointers_1, block_pointers_2) and the contact stubs at $06F690. The driver is main.asm.
  5. Sets each tile's acts-like.
  6. On re-insertion, finds the previous run by its "GPS_VeRsIoN" marker and frees what that run claimed (RATS, Asar's autoclean) before claiming space again. Asar frees autocleaned space in its first pass, so a new insertion can reuse the old space.

Two tiles that list the same block file share one copy of its code at one address.

Block IDs

The block format and API

A block begins with a one-byte header, followed by one three-byte JMP per contact type. Each entry point is a routine that ends in RTL. An entry whose JMP lands on a bare RTL handles nothing.

HeaderMeaning
db $42A normal block: the ten standard contacts
db $37A wall-run block: the ten standard contacts plus WallFeet and WallBody

The entry points, in header order, are:

#ContactOffset (id*3+1)
0Mario below$01
1Mario above$04
2Mario side$07
3Sprite vertical$0A
4Sprite horizontal$0D
5Cape$10
6Fireball$13
7Mario top corner$16
8Mario body inside$19
9Mario head inside$1C
10WallFeet ($37 only)$1F
11WallBody ($37 only)$22

The order comes from GPS's documented header layout. The offsets are derived from it, because db $xx is followed by three-byte JMPs.

A block's first print statement serves as its description.

Inputs a block can rely on

The driver: how a block is reached

GPS blocks run through Lunar Magic's custom-block contact handlers. GPS refuses a ROM that LM has not saved, because it reads LM's acts-like pointer at $06F624. It also repoints that pointer to its own table.

The contact stubs

GPS writes twelve identical 16-byte stubs in $06F690-$06F7E0, one per contact type (Below, Above, Side, SpriteV, SpriteH, WallFeet, WallBody, ...). LM's dispatch calls into this range when Mario or a sprite touches a custom tile. Each stub:

  1. loads id*3+1, the byte offset of that contact type's JMP in the block header;
  2. does JSL block_execute.

The stubs only run on a ROM that carries LM's custom-block dispatch. On a base without it, nothing calls them, and blocks never fire [MEASURED].

block_execute

  1. Checks block_bank_byte for the tile. A value of 0 means no block is inserted there.
  2. Fetches a 16-bit pointer from block_pointers_1. For IDs of $4000 and up it uses block_pointers_2-$8000 instead. The already-shifted index is negative for those IDs, and that negative value is itself the range test.
  3. Adds the contact offset.
  4. Runs LDX $15E9.
  5. Jumps through JML [$0000|!dp] into the block.

Wall-run

Contact offsets of #$001E and above (WallFeet and WallBody) are honoured only when the block's first byte is $37. That byte is the whole opt-in mechanism. Two extra hijacks support wall-run:

AddressHijack
$06F67BWallRun, a JML into the driver
$06F717FixSpriteH, a JML into the driver

The on-ROM format and markers

What Lunar Magic does to a GPS insertion

The following comes from a controlled before/after test in LM 3.40 [MEASURED]. The test covered a level save, the 16x16 editor's F9, -ImportLevel and -ImportAllMap16.

SA-1 handling

defines.asm resolves SA-1 at assembly time, the same way UberASMTool does.

DefineLoROMSA-1
!dp$0000$3000
!addr$0000$6000
!bank$800000$000000
!sprite_slots$0C$16

The define_sprite_table macro emits two aliases for each sprite table, a named one (!sprite_status) and a raw one (!14C8). That is why routines can be written with raw vanilla addresses and still be SA-1 correct. No SA-1 ROM has been checked against GPS's output here.

Command line and build quirks

Sharp edges in the routine library