PIXI (JackTheSpades' SpriteToolSuperDelux, current release 1.43) inserts custom sprites into a Super Mario World ROM. It reads a list of sprites and their configs, assembles each sprite with Asar, inserts a sprite driver and a set of shared routines, writes the tables the driver reads, hooks SMW's sprite code, re-encodes levels whose sprite records change length, and writes the auxiliary files Lunar Magic uses to show the sprites in its editor.
This page describes what PIXI puts in the ROM, its file formats and its behaviour, and gives interface contracts for its shared routines. All addresses are SNES LoROM addresses, written as $BBAAAA. Format facts come from PIXI's README and source tree (master 734b8ed), from PIXI-built ROMs, and from runs in Mesen. [MEASURED] marks a fact measured on an emulator run or by differential testing against PIXI's own code. [LM-DOC] marks a fact from Lunar Magic's help, restated rather than quoted. Untagged facts are read from PIXI's documentation, its output or the SMW disassembly.
PIXI is licensed GPL-3.0 (the root LICENSE covers asm/ and routines/). A clean-room MIT reimplementation of the driver and these routines exists in Pipe Dream; nothing on this page is PIXI code.
README.md is the single best document; it is long and dense.
.cfg and .json sections of the README, src/cfg.cpp, src/json.cpp. JSON is the modern format. PIXI's C# CFG Editor (src/CFG Editor/) edits configs and converts between the two formats.
src/lmdata.cpp, src/iohandler.h.
src/MeiMei/.
src/sprite.cpp, patch_sprites_all_in_one() and patch_sprite().
FetchContent and links it as a library.
list.txt). Entries are NN file for a global sprite and LLL:NN file for a per-level one (B0-BF only). The list is grouped by section headlines (SPRITE:, CLUSTER:, EXTENDED: and the misc kinds). In SPRITE:, slots below C0 read from sprites/, C0-CF from shooters/ and D0 and up from generators/. Only C0-DF run as custom shooters and generators.
.cfg or .json, below).
%Name() macros, its folder's _header.asm, then freecode and the sprite itself. The sprite reports its entry points with Asar prints (print "INIT ",pc, print "MAIN ",pc), and its status entry points (CARRIABLE, KICKED, CARRIED, MOUTH, GOAL) the same way.
JSLs the same copy.
STSD header, the sprite table, per-level tables, the status pointers and Lunar Magic's sprite size table.
.ssc, .mwt, .mw2, .s16) so LM shows the sprites.
Before inserting, PIXI checks that the ROM has Lunar Magic's VRAM patch ($00F6E4 = $5C) and at least one level saved in LM ($06F624). It refuses a ROM that a newer PIXI version has patched. Sprites may carry VERG checks against the version the driver reports.
| kind | numbers | source folder | config |
|---|---|---|---|
| normal sprite | 00-BF | sprites/ | .cfg / .json |
| per-level sprite | B0-BF, per level (LLL:NN) | sprites/ | .cfg / .json |
| shooter | C0-CF | shooters/ | .cfg / .json |
| generator | D0-DF | generators/ | .cfg / .json |
| cluster | list number 00-7F | cluster/ | ASM only |
| extended | list number 00-7F | extended/ | ASM only |
| minor extended, bounce, smoke, spinning coin, score | list number per kind | misc_sprites/<kind>/ | ASM only |
Each folder has its own _header.asm, included before every sprite in it.
A sprite placed in a level is custom when the extra bit $08 of its level-data record is set. A custom sprite shares its number with SMW's sprite of the same number; the extra bit tells them apart.
These are ASM alone, with no config and MAIN-only pointer tables. Each must print MAIN. An extended sprite may also print CAPE; without one, cape interaction does nothing (README).
The sprite, or whatever spawns it, stores the custom number itself: the list number plus an offset, in $1892 (cluster) or $170B (extended). The offsets are SMW's own table sizes, read off its dispatchers:
| kind | number table | offset define | value | SMW dispatch |
|---|---|---|---|---|
| cluster | $1892 | !ClusterOffset | $09 | jump table at $02F825 has entries 00-08; the loop reads the number at $02F815 (LDA $1892,X : BEQ) |
| extended | $170B | !ExtendedOffset | $13 | jump table at $029B2B has entries 00-12; the loop reads the number at $029B16 (LDA $170B,X : BEQ) |
| minor extended | $17F0 | $0C | $028B69; SMW's jump table has 12 entries | |
| bounce | $1699 | $08 | $02904D, the top of the dispatch the bounce/smoke loop JSRs; the timer $16C5 counts down there for SMW's | |
| smoke | $17C0 | $06 | $0296C0; the next instruction drops bit 7 (a flag) | |
| spinning coin | $17D0 | $02 | $0299D7, a loop that JSRs one routine | |
| score | $16E1 | $16 | $02ADBD, a loop that JSRs one routine; it reads its tables by number |
Bit 7 of a cluster number is its extra bit. The minor-kind offsets come from PIXI's asm/sa1def.asm. Its spawn routines (routines/Spawn/*Generic) store the number they are given, so the caller adds the offset. !ExtendedSize is $08 (!ExSprSize+1): spawning keeps off extended slots 8-9, which are Mario's fireballs. Cluster speed tables are named !cluster_misc_1e52 and so on, by address. !Bank8 is $80.
The README names the misc sections and folders and nothing more: not their entry points, registers or how the number is stored.
Apart from each kind's dispatch, SMW reads these number tables only to look for a free slot or to compare with a fixed number, with one exception: the cape's check of extended sprites at $029636, whose clipping ($02A519) is a table indexed by number. That is where an extended sprite's CAPE matters. Extended sprites' timer $176F counts down in SMW's loop before dispatch.
At $02FFE2: the ASCII tag "STSD", a version byte, flags, a dl pointer to the sprite table, the per-level pointers and the status pointers. The version byte reads 140 on a ROM built by PIXI 1.40.
0x100 entries of 0x10 bytes each, one per sprite number:
| offset | size | field |
|---|---|---|
| 0 | 1 | type (0 tweak, 1 custom, 2 shooter/generator) |
| 1 | 1 | acts-like |
| 2 | 6 | the six tweaker bytes, in the order $1656 $1662 $166E $167A $1686 $190F |
| 8 | 3 | INIT pointer (24-bit) |
| 11 | 3 | MAIN pointer (24-bit) |
| 14 | 2 | extra property bytes 1 and 2 |
An empty entry points at $018021, an RTL. Per-level tables (B0-BF) are keyed by the level number in $010B. PIXI writes $010B from $05D8B9.
$0EF30C: dl Size : db $42 points at a 0x400-byte table that gives 3 + count bytes per (extra bits, number), where count is the sprite's extra-byte count. The game's sprite loader steps through a level's sprite list with it. The size table is per number, not per level: if any level has its own B0-BF sprite, B0-BF records are the longer length in every level.
A sprite may print CARRIABLE (status 09), KICKED (0A), CARRIED (0B), MOUTH (07) and GOAL (0C). The printed code then runs in that status in place of SMW's, and a status it does not print runs SMW's code as before. The second extra property byte overrides this: bit 7 runs MAIN instead, bit 6 runs MAIN first (then the sprite's entry, or SMW's).
SMW's load table $1938 holds one byte per record of the level's sprite list, indexed by $161A,x. A set byte means "spawned, do not spawn again". It is 128 bytes, so a 129th record writes into the screen exits at $19B8. Since PIXI 1.2.15 (its changelog) the table is moved to $7FAF00, 256 bytes; !1938 names it, and index FF still means "not from the level". Since PIXI 1.41, !1938 is always the remapped $7FAF00 and disabling the remap (!Disable255SpritesPerLevel) is an error.
Every SMW instruction that addresses $1938 (found by scanning for each absolute opcode with that operand; no long forms exist, and three hits in bank 0D are tile data) [MEASURED]:
$7F.
$0FBC,y.
LDA #$00 : STA $1938,y that free a record: $01AC9C (the off-screen erase), $02AB99 (a shooter's), $02D088, $02FF15, $038712, $03B8BA.
Lunar Magic's bank-1E loader never touches $1938, and jumps back only to $02A846, $02A84B and $02A856.
Lunar Magic is told the limit is 255 by clearing bit 0 of $0FFFE0. LM's help ("Custom Sprite List Sizes") gives this as PC offset 0x801E0; LM's PC offsets count the 0x200-byte copier header (its 0x7750C is the $0EF30C size-table pointer) [LM-DOC]. Every PIXI ROM examined has $FE there; an LM-saved hack without PIXI has $FF.
| address | what is there in SMW | why PIXI hooks it |
|---|---|---|
| $018172 | sprite INIT dispatch | run a custom sprite's INIT |
| $0185C3 | sprite MAIN dispatch | run a custom sprite's MAIN; on a PIXI ROM this is a JSL, which is how a PIXI ROM is recognised |
| $02A963, $02A94B | store byte0 AND #$0D into a position-high byte ($14E0 vertical; $14D4 from LM's horizontal path, whose caller then ANDs A with 1) | without a hook the extra bits would land in the position; the driver keeps bit 0 there and the extra bits in !extra_bits |
| $02A9C9 | the spawn's JSL $07F7D2 (clear the slot, then load SMW's tweakers by $9E) | load the custom tables for a custom sprite |
| $07F785 | the tail of that slot clear | the custom state is cleared with the slot |
| $0187A7 | sprite 9B's INIT stub (reached via $0182B3) | becomes the "give this slot its custom tables" call that spawning code makes; the stub moves |
| $018127 | sprite status handler | the status entry points |
| $02A846 | the sprite loader's record step | step by the size table |
| shooter and generator load and run | custom shooters and generators |
Notes on these hooks [MEASURED]:
JML into LM's bank-1E code: INX : INY : INY, then a BPL that rebases $CE past $80), fixed at 3 bytes. Nothing in the game reads the size table until a driver hooks this. SMW's own loader continues at $02A82E.
JML [$00] from a JSL, and return to bank 01 through the RTS at $0185C2.
JSL $0086DF after it reads its own return address as a jump table.
BNE $02A846 (an absolute operand) as a branch offset of $46. Branch to a label, or use JML.
NN file for a global sprite, LLL:NN file for a per-level one, under section headlines (SPRITE:, CLUSTER:, EXTENDED:, then the misc kinds by name). A misc kind's section name is its folder name under misc_sprites/.
Six lines:
a:b extra-byte counts (extra bit clear : extra bit set), in hex, at most 0C.
The same fields, with these differences:
src/json_const.h has the exact names, typos included (for example "Don't disable cliping when starkilled").
Map16: base64, 8 bytes per 16×16 tile, the TL, BL, TR, BR tile words. A Map16 value that is not base64 reads as no tiles.
DisplayType: XY or ExByte.
Displays: each entry has a description, the extra bit, and either a position nibble X/Y (0-F) or an extension byte Index/Value; then either text or Tiles, each tile a signed pixel offset and a Map16 tile number.
Collection: entries of name, extra bit and up to 12 extra-byte values. This is Lunar Magic's sprite list ("Add Sprites").
These are easy to confuse:
The extra bit lives in bit 2 (value $04) of the sprite's !extra_bits,x byte at runtime ($7FAB10,x on LoROM, $6040,x on SA-1).
Display tiles are numbered in Lunar Magic's sprite Map16, 0x000-0x3FF. A sprite's own Map16 replaces tiles from 0x300. Most real configs use LM's own tiles (0x030 is the green shell; 0x006, 0x007, ...). LM's table sits uncompressed in Lunar Magic.exe: 0x400 tiles × 8 bytes. Tile words use FG Map16's layout, YXPCCCTT TTTTTTTT. 8×8 tiles 0x000-0x1FF are SP1-SP4 and 0x200-0x2FF are GFX33 (Yoshi is 0x080-0x0A3). LM 3.21's copy, as PIXI's CFG Editor++ embeds it in an LM16 export, differs from LM 3.40's in two tiles (16F and 21B) and stops at 0x2FF.
PIXI writes <rom>.ssc (tooltips and display), .mwt (list names), .mw2 (list data) and .s16 (sprite Map16) beside the ROM, from the global slots' JSON configs. The formats are in Lunar Magic's help ("Custom Tooltips for Sprites", "Custom Collections of Sprites", "Custom Map16 for Sprites") [LM-DOC]. These details are as PIXI writes them, where the help is silent [MEASURED]:
.ssc fields are space-separated (the help says tab; LM reads both). Lines end CRLF.
.mwt is tab-separated, CRLF, with the sprite number only on a sprite's first entry.
.ssc TYPE field is the Y nibble, the X nibble, then 20/30 (extra bit clear/set) plus 0 for a description, 2 for tiles or 8 for GFX files. For a display chosen by extension byte it is the byte's number counting the three record bytes (Index + 3), two hex digits of value, then the same. Tile numbers and GFX files are written in hex.
.mw2 starts with a 00 header and ends with FF. Each record is 70|extra<<2|1, 70, number, bytes.... Every record sets the "next group" flag, so each Collection entry is its own list item.
.s16 starts at sprite tile 0x400. PIXI 1.43 writes 0x10 pages (LM itself saves 0x38). PIXI 1.40 writes the same content zero-padded to 0x1C000 bytes. Each sprite's own tiles go in slot order, and its display tiles from 0x300 are renumbered to match.
.cfg sprite.
PIXI does not write the overworld's .sscov/.s16ov.
| 1.2.x | 1.40 | 1.41+ / 1.43 | |
|---|---|---|---|
| shared routines | 27, flat in routines/ | 50: the 27 plus 23 new, in subfolders (Spawn/, Bounce/, Score/, Smoke/, SpinningCoin/, MinorExtended/, Cluster/, Extended/) | |
| routine macro names | the file name | the path with the folders run together: Bounce/SetSpeed.asm is %BounceSetSpeed() | |
| 255 sprites per level | since 1.2.15, can be disabled | can be disabled | always on; disabling is an error |
sa1def.asm | 7 macros; first includes an optional config.asm | adds invoke_sa1; no config.asm include | |
_header.asm | defines %LDE() and spawn macros that call the 1.40 routines | ||
.s16 size | zero-padded to 0x1C000 bytes | 0x10 pages |
?+), which Asar accepts only inside a macro, so each routine has to be included from inside a macro of its own.
Spawn/Sprite.asm is SpawnSprite), and the routines a _header.asm calls must be inserted as well as the ones the sprites call.
.ssc line breaks: a description containing a line break is written raw into the .ssc, ending the line mid-text. LM's escape is \n [MEASURED].
.mw2 stale bytes: extra bytes past a Collection entry's fourth are filled from stale memory (one observed .mw2 held the bytes of "tra", "By", "Ext") [MEASURED].
.cfg sprites: get no aux-file entries at all.
$00. SMW runs it with DB = $02. The one DB-relative read there is Yoshi's run-off speed ($A4B3,y), which therefore comes from bank 0 [MEASURED].
$02-$05; every _header.asm %SpawnCluster() macro passes it in $04-$07.
_header.asm but does not exist: the file is Spawn/Generic.asm, so its macro is %SpawnGeneric().
$40 and up.
$18E2; SMW uses $18DF.
$0E and the high byte to $0F. SMW's version writes the low byte to $0F.
Map16 is not base64 (one observed config holds the text "Cape Shell") reads as no tiles rather than an error.
These are interface contracts for PIXI's shared sprite routines: each is inserted once and called with JSL through %Name(). They are written from the routines' observable behaviour. Each contract says what a caller can see: inputs, outputs, RAM written, flags, stack effects and edge cases. They hold no PIXI code: no instruction sequences, no instruction-by-instruction paraphrase, no PIXI comments and no PIXI data tables. A table is described only when it is SMW's own (its address is cited) or when it can be defined by a formula. SMW addresses were checked against a vanilla ROM.
The contracts were checked by running an independent implementation against PIXI's own routines from thousands of random states each, on the same vanilla ROM in a CPU interpreter, comparing every register, flag and byte of RAM with only what is called a by-product here masked. Where that disagreed with a contract, PIXI was measured black-box (inputs varied one at a time, outputs read) and the contract corrected; corrected points are marked [MEASURED]. The random states were kept to real level modes and screens, Map16 pointers into ROM at $0FBE, a short stripe buffer and a data bank below $10; outside those, SMW's own pointers lead into low RAM.
$E4,x, $14E0,x, etc.; "slot" means a normal-sprite slot 0..$0B. The SA-1 build moves the sprite tables (!addr = $6000 and so on), uses the SA-1 arithmetic unit instead of $4202/$211B, and uses $40/$41 instead of $7E/$7F for Map16. These differences are noted briefly where they apply.
JSL and returns with RTL, unless "Stack" says otherwise.
$0000 is assumed: $00-$FF is RAM $7E:0000-00FF.
$0000-$1FFF mirrors low WRAM ($00-$3F or $80-$BF). Every routine that reads a sprite table with absolute addressing needs this.
XBA exposes. It is listed only where it is deterministic and might be relied on. Otherwise it is a by-product.
!EXLEVEL). It reads the Lunar Magic version string at ROM $0FF0B4; versions above 2.53 set it. Every ROM saved by Lunar Magic 3.x takes the EXLEVEL branch, so that branch is the one that matters for current ROMs. SubOffScreen, GetMap16 and ChangeMap16 behave differently depending on this flag.
RTS.
RTS.
PIXI reaches the RTS-ending routines ($02B554/$02B560, $00C0FB) from another bank with the usual "push a long return address, then push the address of an RTL in the target bank minus 1" trick. The RTL bytes it uses are at $00804D and $02B889. Any equivalent call mechanism is acceptable.
$04 x-low, $0A x-high, $05 y-low, $0B y-high, $06 width, $07 height. Box B is $00, $08, $01, $09, $02, $03 in the same order. $03B72B preserves X and Y, clobbers $0C and $0F, and returns C=1 on contact.
Computes an 8-bit X speed and Y speed of magnitude about speed, pointing from the shooter toward the target.
s, unsigned.
$00-$01 = 16-bit dx = shooter X − target X.
$02-$03 = 16-bit dy = shooter Y − target Y.
$00 = X speed (8-bit). $02 = Y speed (8-bit). $01 = $03 = 0.
d had bit 15 set (target to the right / below), and two's-complement negated when bit 15 was clear. d = 0 gives a negated 0, which is 0.
$00. B = high byte of the 16-bit Vx below.
$04-$05 = S (16-bit, defined below). $06 = 1 if dx was negative, otherwise 0. $07 = 0. $0F = s. The multiplier registers $4202/$4203/$4216/$4217 are left holding the last product.
dx or dy if bit 15 is set. $8000 stays $8000 and is then treated as unsigned.
(|dx| OR |dy|) ≥ $100, shift both right by 1. The shift count is the bit-length of the high byte of the OR. After this, ax, ay ≤ $FF.
d = ax² + ay², a 17-bit unsigned value.
sh as the smallest value in 0..5 with d >> (2·sh) < $100. The six bands are d < $100, < $400, < $1000, < $4000, < $10000, and ≥ $10000. Then k = d >> (2·sh) and m = R[k] >> sh (16-bit logical shift).
S = floor(s · m / 256). This is exact and always fits in 16 bits.
Vy = floor(ay · S / 256) and Vx = floor(ax · S / 256), both 16-bit. The outputs are their low bytes, sign-applied as above.
R is a 256-entry table of 16-bit words: R[0] = $FFFF, and R[k] = min($FFFF, round(65536 / √k)) for k ≥ 1. All 256 entries were checked against this formula. SMW has no such table. m approximates 65536/√d, so S·a/256 ≈ s·a/√d.
$4202/$4203 (SA-1: $2250-$2254/$2306-$2307). Allow 8 cycles before each product read.
dx = dy = 0 gives 0, 0.
d = 1 uses R[1] = $FFFF.
s because of rounding. Only the low byte is kept, so s close to $FF can wrap.
m·s through the SA-1 multiplier with a different path for m ≥ $8000. Its results are the same in intent but not guaranteed to be bit-identical, and this contract does not cover them.
Checks whether sprite X is touching the spinning cape.
$00-$0B (both boxes), plus $0C and $0F (from $03B72B). The early "no" exits write nothing.
$13E8 (cape-spin active) = 0.
$15D0,x | $154C,x | $1FE2,x ≠ 0.
L = $1632,x, with bit 0 flipped when $74 (climbing) ≠ 0. Exit if L ≠ $13F9, comparing the whole byte.
Otherwise:
$13E9/$13EA) − 2, giving $00/$08. Width $14 in $02.
$13EB/$13EC, giving $01/$09. Height $10 in $03.
RTL returns to the caller.
Writes a Map16 tile number at a level position and queues the VRAM update.
B:A is taken as the 16-bit value.
$98-$99 = block Y (16-bit). $9A-$9B = block X (16-bit).
$1933 = layer: 0 = layer 1, 1 = layer 2. Other values index garbage.
$0FBE,y and $1933 absolute.
$99/$9B on vertical layers, and the modulo behaviour noted there.
$7E:addr = tile low byte.
$7F:addr = (tile >> 8) & $7F. Bit 15 of the tile is dropped.
(tile × 2) & $FFFF, its index into the tile-pointer table at $0FBE.
$06/$07 = the VRAM tilemap address (step 3 of GetMap16).
$0C-$0F = the original block X/Y.
$08/$0A = camera values chosen by layer and orientation:
| layer orientation | $08 | $0A | |---|---|---| | horizontal L1 | $1A − $80 | $1C | | horizontal L2 | $1E | $20 − $80 | | vertical L1 | $1A | $1C − $80 | | vertical L2 | $1E − $80 | $20 |
The orientation is bit 0 of the value saved in $0A, which is consumed by shifting $0A right once, so $0A holds half its GetMap16 value before being overwritten. All of these are 16-bit.
$00C0FB decides whether the block is close enough to the camera to upload. If it is, it appends a stripe entry at $7F837D + [$7F837B] and adds $10 to $7F837B. It clobbers $00 and $04-$06.
RTS and is reached through the bank-0 RTL at $00804D.
$9C, not a raw tile number. The VRAM half is SMW's $00C0FB unchanged.
$99 and $9B swapped (see GetMap16).
$8000 is stored with bit 15 cleared, but $00C0FB receives Y = tile×2, also truncated to 16 bits.
Tests two boxes for overlap with 16-bit coordinates.
$00 x, $02 y, $04 w, $06 h.
$08 x, $0A y, $0C w, $0E h. All values are 16-bit.
x1 ≥ x2, X passes when (x1 − x2) < w2. Otherwise it passes when (x2 − x1) < w1.
All comparisons are unsigned 16-bit, and the X axis is evaluated first.
$FFFF does not overlap one near $0000.
Computes radius · cos(angle).
$04-$05 = angle. Only 9 bits count: $05 bit 0 and $04, with $000-$1FF = 0–360°.
$06 = radius.
$07-$08 = 16-bit signed X displacement.
$07, B = $08.
$04-$06 unchanged.
a' = (angle + $80) mod $200. Index i = a' & $FF, sign h = bit 8 of a'. Bits 1-7 of $05 are ignored. The +$80 is a quarter turn, which turns sine into cosine.
T = H[i] (0..$FF).
P = T × r with r = $06 taken as a signed 8-bit value. Result = bits 8..23 of P as a 16-bit value, i.e. floor(T·r / 256) mod $10000.
h = 1, two's-complement negate.
H is a 256-entry half-period sine, H[i] = sin(π·i/256)·256, clamped to $FF. It equals SMW's 16-bit sine table at $07F7DB (256 words), with the single $0100 entry (i = $80) clamped to $FF. All 256 entries were verified.
$211B twice (T, then 0) and $211C (r). These are the Mode 7 matrix A/B registers and the Mode 7 write latch. This is observable if Mode 7 is in use. SA-1 uses its multiplier with r taken as unsigned, so the results differ for r ≥ $80.
$80-$FF produces a negative/garbled magnitude on non-SA-1 (signed multiplier).
Computes radius · sin(angle). The contract is the same as CircleX, with these differences:
i = $04, h = $05 bit 0.
$09-$0A. A low = $09, B = $0A, C = h.
$07-$08 are untouched.
Checks whether extended sprite X is touching the cape, using a box the caller supplies.
$00 = X offset, $01 = width, $02 = Y offset, $03 = height.
$00-$03 are overwritten by the cape box. $04-$0B, $0C and $0F are clobbered.
$171F,x/$1733,x + $00, unsigned. Only the carry reaches the high byte; the offset is not sign-extended.
$01.
$1715,x/$1729,x + $02, unsigned.
$03.
$13E8 itself.
Finds the OAM slot for extended sprite X and the sprite's screen position. Erases or hides the sprite when it is off screen. This is the 1.2.x contract; 1.40 changes the vertical rule (see "Changes to the 1.2.x routines in 1.40").
$0200 page, not $0300.
$00 = $40 if $1747,x (X speed) bit 7 is clear, else $00. This is the OAM X-flip bit.
$01 = low byte of (X − $1A).
$02 = low byte of (Y − $1C), or $F0 when the sprite is hidden or erased.
$170B,x = 0 or $02 = $F0).
X − camX ≠ 0, then erase: $170B,x = 0 and $02 = $F0.
d = (Ylo − camYlo) mod 256 and c = 1 if Ylo ≥ camYlo. Let t = (Yhi + camYhi + c) mod 256. Note the addition: this is not SMW's test.
t ≠ 0: erase if d ≥ $F0, otherwise visible.
t = 0: erase if d < $C0; else hide ($02 = $F0, not erased) if d < $E0; else visible.
t ≠ 0: A = d, C = 0.
t = 0: A = d, C = 1.
$F0, N = 1, Z = 0.
$90,$94,…,$AC).
$00/$01 values, same $170B erase). Differences:
Y − camY ≠ 0 or relY ≥ $F0. PIXI uses the t rule above and has a "hide without erase" band.
Hurts the player if extended sprite X touches them. Uses a fixed 10×10 box.
$171F,x/$1733,x + 3.
$1715,x/$1729,x + 3.
$0A.
$00 [MEASURED]. SMW itself runs it with DB = $02. That routine:
$1490 ≠ 0): turns the extended sprite into a smoke puff. Unless $170B,x = 4, it first moves the sprite 4 px up-left. Then $170B,x = 1 and $176F,x = 7.
$18DF). Its one DB-relative read is Yoshi's run-off speed ($A4B3,y), so with PIXI's DB = $00 the speed is read from bank 0. This is a PIXI bug.
RTS-ending $02A469 is reached through the RTL at $02B889.
$13F9 vs $1779,x).
$0A.
Applies an extended sprite's speed to its position, optionally with gravity.
$15E9 on return, because SMW's X updater reloads it. In extended-sprite code $15E9 holds the current extended index, so in practice X is unchanged.
$00 or $FF: the sign of the last speed applied. In modes 0, 1 and 2 that is the X speed; in mode 3 it is the Y speed. SMW's X updater runs the Y updater on the X fields.
$FD, nothing done). A caller arriving with Z=1 and A ≠ 0 gets mode 0. Callers normally load A immediately before the call, so this does not arise.
$173D,x − $40 has bit 7 set (the CMP/BPL test, not a true signed compare), add 3 to $173D,x. So gravity applies when the Y speed is in $C0-$FF or $00-$3F, and not when it is in $80-$BF (fast upward). There is no cap at exactly $40: $3F becomes $42.
$1751,x += speed·16; position $1715/$1729,x += sign-extended speed>>4 + carry.
$1747/$175B/$171F/$1733 (via X + $0A), then X = $15E9.
RTS and are reached through the RTL at $02B889.
Finalises a sprite's OAM tiles: sets each tile's size bit and hides tiles that are off screen.
$00 = 8×8, $02 = 16×16, any value with bit 7 set = keep each tile's existing size bit.
$0300 + $15EA,x onward, with screen-relative coordinates.
$0300/$0460 are accessed absolute with the caller's DB.
$15E9. N and Z reflect X. C = 1.
$15EA,x + 4·(A+1) mod 256, i.e. one past the last tile.
$F0 if the last tile was hidden, else the low byte of that tile's Y check value. B = 0.
$00-$01 = 16-bit spriteY − camY.
$02-$03 = 16-bit spriteX − camX.
$08 = $FF (the loop count runs out).
$0B = the size argument.
$04-$07, $09 and $0A are untouched.
o; size index j starts at $15EA,x / 4 and counts up by one per tile without wrapping with the OAM index, so past OAM $FC it goes on to $0460 + $40 and up [MEASURED]):
X16 = relX16 + sext8($0300,o − relX_lo).
$0460,j = base + (X16 ≥ $100 ? 1 : 0), an 8-bit add. base is $0B if $0B bit 7 is clear, else $0460,j & $02.
Y16 = relY16 + sext8($0301,o − relY_lo) + $10. If Y16 ≥ $100 (unsigned), set $0301,o = $F0.
A+1 tiles. A = $80..$FF gives A+1 tiles via the decrement-and-test-sign loop, the same as SMW.
base and then ORs bit 0; PIXI adds. They differ only when $0B is non-negative and odd.
$01 internally and uses a different scratch layout ($00-$0A).
Checks whether sprite X is touching either player fireball.
$FF.
$00-$0B, $0C and $0F are clobbered.
$170B is 0. For an occupied slot:
$05).
Sets sprite X's off-screen flags and returns its OAM index and screen position. When the sprite is too far off screen, it abandons the routine that called it.
$186C,x = 0 first.
$00-$01 = 16-bit relX = (X16 − $1A16).
$15A0,x = 1 if the high byte of relX ≠ 0, else 0.
$15C4,x = 1 if relX + $40 ≥ $180 (unsigned 16-bit), i.e. relX is not in [−$40, $140). Else 0.
$15C4,x = 0):
$186C,x = bit 1 | bit 0:
$190F,x bit 5 is set and the high byte of (Y16 + $20 − $1C16) ≠ 0.
(Y16 + $10 − $1C16) ≠ 0.
$01 = low byte of (Y − $1C).
$15EA,x. N and Z reflect Y.
(Y16 + $10 − $1C16). B = $01.
(Y16 + $10 − $1C16) ≥ $10.
$15C4,x = 1):
$186C,x = 0. $01 keeps the high byte of relX (not a Y value).
JSL return.
JSR return of the routine that called it (the sprite's graphics routine).
RTL.
The net effect is to pop 5 bytes and resume just after the JSR that called the graphics routine, in bank DB. This requires that the graphics routine was entered with JSR, that nothing else was pushed in between, and that DB equals that code's bank. PIXI sprites set DB = their own bank at their entry.
$10/$20 and the bits $01/$02 match SMW's table at $01A361. Bank 3's $03B760 uses $0C/$1C and tests $1662 instead. Differences from $01A365:
$14C8,x = 9) from the tall check.
$00/$01 before RTSing to the graphics routine's caller. PIXI sets neither Y nor $01.
$01).
Reads the Map16 tile number at a level position.
$98-$99 = block Y (16-bit). $9A-$9B = block X (16-bit).
$1933 = layer (0 or 1).
$1933, $1925 and $13D7 absolute. DB is pushed and pulled but never changed.
$00hh.
$FFFF (8-bit entry: A = $FF, B = $FF).
$FF/$FFFF matching the entry index width.
$0E-$0F = $98-$99, $0C-$0D = $9A-$9B.
$0A = $5B, or $5B >> 1 when $1933 ≠ 0. Bit 0 of $0A = "this layer is vertical".
$99 and $9B in RAM. They are not swapped back.
$98-$99 ≥ $13D7 (unsigned).
$99 ≥ 2, using the post-swap $99.
$9B after the swap).
$0D/$0F:
$0B = screen number = $9B.
$08-$09 = ($98-$99 & $FFF0) | ($9A >> 4).
$06 = $20 | ($1933 ? $10 : 0) | (($0F & 1) << 3) | (($0D & 1) << 2) | (($98 >> 6) & 3).
$07 = ((($98 >> 4) & 3) << 6) | (($9A >> 3) & $1E).
$06/$07 together form the BG tilemap VRAM word address that ChangeMap16 uses.
p1 = word[$00BEA8 + 2·$1933] + 2·$1925
p2 = word[$00:p1] + 3·$0B
addr = word[$00:p2] + $08-$09
This is SMW's own pointer chain: $00BEA8 = {$BDA8, $BDE8, …} → per-level-mode tables → 3-byte per-screen pointers. Only their low 16 bits are used. 2 × $1933, 2 × $1925 and 3 × the screen are each taken modulo $100, and the tripling keeps the carry out of its doubling (3 × $80 = $81); only out-of-range inputs see this. $1926, $1934 and $0C do not count [MEASURED].
$7F:addr << 8 | $7E:addr.
$98-$9B after a call on a vertical layer see $99/$9B swapped. A second call without restoring them reads the wrong block.
$1933 values other than 0/1 index past the $00BEA8 table.
$40/$41 banks are read instead of $7E/$7F.
If the player is riding Yoshi, Yoshi runs away as if the player had been hit.
$187A = 0, nothing happens. Otherwise, with s = $18E2 − 1 as Yoshi's slot:
$163E,s = $10.
$1DFA = $03, $1DFC = $13.
$C2,s = 2 (running).
$187A = 0, $0DC1 = 0.
$7D = $C0, $7B = 0.
$B6,s = SMW $02A4B3[$157C,s], i.e. $10 when facing right (0), $F0 when facing left (1).
$1594,s = 0, $151C,s = 0, $18AE = 0.
$1497 = $30.
$18DF; PIXI uses $18E2.
$187A itself.
$18E2 = 0 while $187A ≠ 0, then s = $FF and the writes land one below each table [MEASURED]. SMW's version has the same hazard with $18DF.
Returns a random number from 0 to max inclusive.
max.
$148D is read absolute.
$148B-$148E.
r = $148D.
max = $FF, the result is r. Otherwise the result is floor(r·(max+1) / 256), the high byte of the hardware product.
$4202/$4203 (SA-1: $2250-$2254).
Writes the player's interaction box as clipping 1, with 16-bit values.
$187A is read absolute.
$00-$01 = $94 + 2.
$02-$03 = $96 + yoff[i].
$04-$05 = $000C.
$06 = height[i], $07 = 0.
i = ($73 ≠ 0 or $19 = 0 ? 1 : 0) + ($187A ≠ 0 ? 2 : 0).
$96 add.
$02, B = $03.
$06,$14,$10,$18) and $03B660 (heights $1A,$0C,$20,$18).
$00/$08/$02/$01/$09/$03). This is the 16-bit rewrite in clipping-1 layout.
Turns a caller-supplied box into clipping 2 for sprite X by adding the sprite's position.
$08-$09 = X offset, $0A-$0B = Y offset, $0C-$0D = width, $0E-$0F = height (all 16-bit).
$08-$09 += sprite X ($14E0:$E4). $0A-$0B += sprite Y ($14D4:$D8). $0C-$0F unchanged.
$0A, B = new $0B. X and Y untouched.
Decides whether shooter X fires this frame and finds a free sprite slot for the shot.
$FF.
$17AB,x ≠ 0: stop. The timer is not changed.
$17AB,x = A, whether or not the shooter fires afterwards.
($94 − $179B,x + $11) mod 256 < $22. This uses low bytes only, so it means "within about 16 px horizontally".
($1793,x:$178B,x) − ($1D:$1C) ≠ 0.
(shooterX − camX) ≠ 0.
(($179B,x − $1A) + $10) mod 256 < $10, i.e. the shooter is in the rightmost 16 px of the screen.
$FF.
$60). Differences:
$0E/$0F and searches from the top of the $1692-dependent slot range down, keeping 2 slots in reserve.
Spawns an extended sprite at sprite X's position plus an offset, with initial speeds.
$00 = X offset (signed), $01 = Y offset (signed), $02 = X speed, $03 = Y speed.
$15A0,x | $186C,x | $15D0,x ≠ 0). Y is unchanged.
$FF.
$00-$03 unchanged.
$170B,y = 0. Slots 8 and 9 (fireballs) are never used.
$170B,y = number.
$171F,y/$1733,y = parent X16 + sext($00).
$1715,y/$1729,y = parent Y16 + sext($01).
$1747,y = $02, $173D,y = $03.
$1765, $176F, $1779 (layer) are not touched.
Spawns a smoke sprite at sprite X's position plus an offset.
$00 = X offset, $01 = Y offset, $02 = timer.
$FF.
$17C0,y = 0.
$17C0,y = type.
$17CC,y = $02.
$17C4,y = ($D8,x + $01) mod 256.
$17C8,y = ($E4,x + $00) mod 256.
Spawns a normal or custom sprite at sprite X's position plus an offset, with initial speeds.
$00 = X offset (signed), $01 = Y offset (signed), $02 = X speed, $03 = Y speed.
$03.
$FF whenever it started below $80, which is always the case here [MEASURED].
$00-$03 are preserved, even across $0187A7.
$0B down to 0 (SA-1: $15 down to 0), taking the first with $14C8 = 0. All slots are searched: the $1692 sprite-memory limits are ignored.
$9E,n = number.
$9E,n. The carry flag must survive this call; it does in vanilla and in a PIXI-patched ROM.
$7FAB9E,n = number.
$00-$02; PIXI saves and restores $00-$03 around it.
$7FAB10,n = $08 (custom flag set, extra bits clear).
$14C8,n = 1 (init).
$E4,n/$14E0,n = parent X16 + sext($00).
$D8,n/$14D4,n = parent Y16 + sext($01).
$B6,n = $02, $AA,n = $03.
$1632), no off-screen flags.
The same as SpawnSprite, except that the search starts at slot $04 (caller-supplied) and goes down to 0.
$04 must be < the slot count.
$80, Y = $FF. Started at $81 or above, the first decrement makes Y negative and the search ends there, so Y = start − 1. Started at $80 exactly, the search carries on down from $7F.
$04 is not preserved across $0187A7.
Star-kills sprite X and gives the player points, as a star hit does.
$18D2 capped to 8).
$0E-$0F = 16-bit ($94 − sprite X).
$1DF9 = $03, plus a contact-graphic smoke when the sprite is on screen.
$14C8,x = 2 and $AA,x = $D0.
$B6,x = $F0 if the player is to the right ($94/$95 ≥ sprite X), else $10. This is SMW's table at $01A839, indexed by the SubHorzPos result.
$18D2 += 1, then capped at 8.
$18D2: gives points, or a 1-up at 8.
$1DF9 = the sound for $18D2: index 1-7 gives $13-$19, index ≥ 8 gives $03, index 0 gives $00.
$D1/$D2 ($01AD30, the player's X at the start of the frame) and writes only $0F. PIXI uses $94/$95 and writes $0E-$0F.
$1DF9 as $01AB6F set it ($03). PIXI writes $03 itself, so the result is the same.
$18D2 was $FF): SMW reads $01A61D ($60); PIXI uses $00.
$167A bit 1 "immune to star" flag. The caller's code does that.
$F0,$10). Sounds = SMW $01A61E-$01A624 ($13-$19), plus $00 and $03 as above.
JSL to the shared SubHorzPos, so a 1.40 Star needs SubHorzPos inserted too.
Reports which side of sprite X the player is on.
$0E-$0F = 16-bit $94/$95 − $E4/$14E0,x: low byte in $0E, high byte in $0F.
$0F and does not write $0E. Sprites written against SMW's convention that read $0F as the low byte get the high byte here. $01AD30 is the variant that uses $D1/$D2.
Erases sprite X when it has moved too far off screen. A selects the size of the off-screen margin.
$03 = (A & 7) · 2.
$15A0,x | $186C,x = 0: returns at once with A = 0, Z=1, N=0, C=0. Nothing else is changed.
$161A,x (see "Y on return" below).
$14C8,x ≥ 8 and $161A,x = $FF, else 0. On the horizontal-level keep path after the margin test, C = $13 bit 0. On every other path C is a by-product.
$00 and $01 are clobbered. On paths that test margins, $01 ends as A & 7 (horizontal) or the parity index (vertical).
$5B bit 0 = 0):
Y16 − $13D7) is clear;
(Y16 − $1C) − $0BF2) is clear;
(Y16 − $1C) − $0BF0) is set.
$13D7 = level height. $0BF2 and $0BF0 are the Y range limits kept in RAM.
(Yhi + carry(Ylo + $50) − 2) has bit 7 clear.
$167A,x bit 2 is set (process while off screen): return.
i = (A&7)·2 + ($13 & 1).
D = high byte of ($1A16 + sext16(off[i]) − X16), where off = t15[i]:t14[i].
$13 bit 0 is set, D ^= $80.
D bit 7 is set, otherwise return.
The effect: on even frames, test the right margin (erase if the sprite is beyond it); on odd frames, test the left margin.
$167A,x bit 2 is set, or $13 is odd: return.
$14E0,x ≥ 2: erase.
j = ($13 >> 1) & 1. D = high byte of ($1C16 + (t13[j]:t12[j]) − Y16). If j = 1, D ^= $80. Erase if D bit 7 is set.
$14C8,x ≥ 8 and $161A,x ≠ $FF: sprite load table[$161A,x] = 0. The table is at $7FAF00 (or $1938 when PIXI is built with !Disable255SpritesPerLevel; SA-1: $418A00). This lets the sprite reload.
$14C8,x = 0.
i/j, or $161A,x on the reload-clearing erase.
$15E9, so X = $15E9 afterwards. B is restored.
Differences from bank 1:
$9E = $1F) $18C0/$18C1 handling.
$22/$24 are not exempt on vertical odd-half frames.
$7FAF00, not $1938.
Reports whether the player is above or below sprite X.
$0F = low byte of ($96/$97 − $D8/$14D4,x).
$0E untouched.
RTL instead of RTS). The $02D50C variant writes $0E instead, and $01AD42 uses $D3/$D4 and $0E.
"Used by" counts the sprite files that call the routine (%Name() in a sample of 82 PIXI sprite files from several hacks, routines folders excluded. The count of distinct files by content is in brackets.
| routine | used by | SMW equivalent | notes |
|---|---|---|---|
| Aiming | 0 | none | Hardest to get bit-exact: band selection, R[k] formula, three floor-multiplies, sign rules. Fully specified for non-SA-1. |
| CapeContact | 0 | $0293CE-$0293F2 body + $029696 | Easy; layer/climb rule is the only subtlety. |
| ChangeMap16 | 1 [1] | none ($00C0FB reused) | Address math shared with GetMap16; bit 15 dropped on store; leaves $99/$9B swapped. |
| CheckForContactAlternate | 0 | none | Easy; returns M=1 always. |
| CircleX | 0 | table = $07F7DB clamped | Signed PPU multiply (radius ≥ $80 is negative); writes Mode 7 registers. |
| CircleY | 0 | table = $07F7DB clamped | As CircleX. |
| ExtendedCapeClipping | 0 | $02A51C + $029696 | Easy; offsets unsigned. |
| ExtendedGetDrawInfo | 0 | $02A1A4-$02A1D3 (≈) | Odd vertical rule (t uses addition, changed in 1.40); slots 8-9 read past the table. |
| ExtendedHurt | 0 | $02A3F6-tail + $02A469 | Calls $02A469 with DB = $00 (SMW: $02). |
| ExtendedSpeed | 7 [1] | $02B554/$02B560 | X = $15E9 after X update; gravity sign quirk. |
| FinishOAMWrite | 0 | $01B7B3 | Size bit added, not ORed; scratch layout differs from SMW. |
| FireballContact | 0 | box = $02A547 | Any type in slots 8/9 counts. |
| GetDrawInfo | 15 [5] | $01A365 | Stack rewrite on off-screen (5 bytes out, needs DB = caller's bank); no status-9 exclusion. |
| GetMap16 | 0 | none | Pointer chain via $00BEA8; EXLEVEL range check; RAM swap side effect. |
| LoseYoshi | 1 [1] | $02A473-$02A4AD | Uses $18E2 where SMW uses $18DF. |
| Random | 0 | wraps $01ACF9 | Easy. |
| SetPlayerClippingAlternate | 0 | $03B664 (16-bit form) | Easy. |
| SetSpriteClippingAlternate | 0 | none | Trivial. |
| ShooterMain | 0 | $02B466-$02B4A5 | Y unchanged on most "don't fire" paths. |
| SpawnExtended | 0 | none (inline idiom) | Y unchanged on off-screen refusal. |
| SpawnSmoke | 0 | inline idiom ($01AB6F) | Fails instead of reusing slot 0. |
| SpawnSprite | 10 [2] | none | Carry through $07F7D2; $0187A7 with $00-$03 saved; write order. |
| SpawnSpriteSafe | 1 [1] | none | As SpawnSprite, start at $04. |
| Star | 8 [1] | $01A847-$01A87D | Order and $94 vs $D1; $0E-$0F written. |
| SubHorzPos | 13 [3] | $03B817/$02D4FA | Writes $0E=low and $0F=high, unlike SMW. |
| SubOffScreen | 13 [3] | $01AC31… / $03B85D… | EXLEVEL branch, $7FAF00 load table, X ← $15E9, DB switch. |
| SubVertPos | 0 | $03B829 | Exact. |
Contracts for the 23 shared routines that PIXI 1.40 has and 1.2.x does not, under the same rules. The macro name is the path with the folders run together: Bounce/SetSpeed.asm is %BounceSetSpeed(). Intended use was read from the _header.asm files of cluster, extended, shooters, sprites and misc_sprites/*. The 1.40 PIXI folder has no README.
Everything under "Conventions that apply to every routine" above still holds (LoROM, D = 0, JSL/RTL, 8/8 on entry, by-product flags). In addition:
$6000 into each, as define_base2_address does):
| kind | slots | number | X lo/hi | Y lo/hi | X speed | Y speed | X frac | Y frac | other | |---|---|---|---|---|---|---|---|---|---| | bounce | 4 | $1699 | $16A5/$16AD | $16A1/$16A9 | $16B5 | $16B1 | $16B9 | $16BD | $16C9 direction (bits 0-1), $1901 properties | | score | 6 | $16E1 | $16ED/$16F3 | $16E7/$16F9 | — | $16FF | — | — | $1705 layer | | smoke | 4 | $17C0 | $17C8/— | $17C4/— | — | — | — | — | $17CC timer | | spinning coin | 4 | $17D0 | $17E0/$17EC | $17D4/$17E8 | — | $17D8 | — | $17DC | $17E4 layer | | minor extended | 12 | $17F0 | $1808/$18EA | $17FC/$1814 | $182C | $1820 | $1844 | $1838 | $1850 timer | | cluster | 20 | $1892 | $1E16/$1E3E | $1E02/$1E2A | — | — | — | — | | | extended | 8 (+2 fireball) | $170B | $171F/$1733 | $1715/$1729 | $1747 | $173D | $175B | $1751 | |
The bounce fractions: PIXI's names put the X fraction at $16B9 and the Y fraction at $16BD. SMW's own bounce code uses them the other way round (see BounceUpdatePos).
U(s, f, p), used by several routines. s = 8-bit speed (signed, 1/16 px per frame), f = the 8-bit fraction byte, p = the 16-bit position (two bytes):
f ← (f + ((s & $0F) << 4)) mod 256; c = 1 if that sum was ≥ 256.
p ← (p + q + c) mod $10000, where q = floor(sext8(s) / 16) (a value −8..7) as 16 bits.
$00 if s < $80, else $FF. A = the new high byte of p. N, Z, V and C are those of the high-byte add (hi(q) + hi(p) + carry from the low byte); C = carry out of the 16-bit sum.
This is exactly SMW's $02B526 (bounce Y), $02B560 (extended Y) and $02B58E (spinning coin Y).
Spawn/*Generic routine stores the high byte of the accumulator (B) as the new sprite's number; the low byte of A on entry is ignored. The callers' macros in every _header.asm do XBA and then fill $04-$07 with their own position, so the number travels in B. A reimplementation must take it from B.
Finds the OAM slot and screen position of bounce sprite X. Handles the X high bit and layer 2.
$001A+i).
$03 = $02 (16×16 size bit).
camX = $1A/$1B, camY = $1C/$1D, i = 0) when $1901,x bit 7 is clear; layer 2 ($1E/$1F, $20/$21, i = 4) when it is set.
$00 = low byte of X16 − camX. If the high byte of the 16-bit X16 − camX is non-zero, $03 = $03 (size bit plus X high bit). The sprite is not rejected for being off screen horizontally.
$01 = low byte of Y16 − camY. hy = high byte of the 16-bit Y16 − camY.
hy ≠ 0 (not drawable): C=0, A = hy, Z=0, N = bit 7 of hy, Y = i (0 or 4).
hy = 0: C=1, Y = A = SMW's OAM index byte at $0291ED + x ($10,$14,$18,$1C), N=0, Z=0.
$00, $01 and $03 are written on both paths; $02 and $04-$0F are untouched.
$16C9,x bit 7; PIXI from $1901,x bit 7.
$03.
$02-$05; PIXI writes only $00, $01, $03.
Draws bounce sprite X as one 16×16 tile.
$02 = A. Then BounceGetDrawInfo. If that reports C=0, return at once with its exit state ($02 = tile is the only extra write). Otherwise, with o = the OAM index it returned:
$0200+o = $00, $0201+o = $01, $0202+o = $02.
$0203+o = $1901,x ORed with the byte at direct page $64 (SMW's sprite priority), not with the value $64 [MEASURED]. With RAM cleared it is $1901,x exactly.
$0420 + o/4 = $03.
o/4, A = $03 ($02 or $03), N=0, Z=0, C=0. The routine gives no draw status: C is 0 on both paths (for slots 0..3).
$1901,x | $64, size into $0420) with SMW's own tile choice and off-screen rule.
Gives the player the push of a bounce block.
d = $16C9,x & 3.
w. C is from comparing w with $80 (d=2: C=0; otherwise C=1). N and Z are from X, because the slot is restored last [MEASURED].
$80 = "leave alone").
Gives a normal sprite the push of a bounce block.
$0F = the normal sprite's slot. DB must map WRAM.
d = $16C9,x & 3. v = SMW $0290D6[d]; if v ≠ $80, $AA of slot [$0F] = v. w = SMW $0290DA[d]; if w ≠ $80, $B6 of slot [$0F] = w. The same values as BounceSetMarioSpeed.
w, flags as BounceSetMarioSpeed (C from the compare, N and Z from X) [MEASURED]. $0F unchanged.
Accelerates a bounce sprite as SMW's bounce blocks are accelerated.
d = $16C9,x & 3. $16B1,x (Y speed) += SMW $0290CE[d] ($10,$00,$00,$F0); then $16B5,x (X speed) += SMW $0290D2[d] ($00,$F0,$10,$00). 8-bit, wrapping. PIXI's copy of the tables equals SMW's.
$16B5,x. C and V from that last add; N and Z from X [MEASURED].
Sets $98-$9B and $1933 to the block under bounce sprite X, ready for SMW's $00BEB0.
$1933 absolute).
$98 = (Ylo + 8) & $F0, $99 = Yhi + carry of Ylo + 8.
$9A = (Xlo + 8) & $F0, $9B = Xhi + carry of Xlo + 8.
$1933 = bit 7 of $1901,x (0 or 1).
$1933 value, Z = (A = 0), N=0, C = bit 6 of $1901,x. X and Y preserved. $9C is not touched (the _header.asm macros set it before calling).
$16C9,x bit 7, PIXI from $1901,x bit 7. SMW then calls $00BEB0 itself.
Moves bounce sprite X by its speeds.
U($16B1,x, $16BD,x, $16A9:$16A1,x) (Y), then U($16B5,x, $16B9,x, $16AD:$16A5,x) (X).
U for the X update: Y = sign byte of $16B5,x, A = new $16AD,x, N/Z/V/C of its high-byte add. X preserved.
$16B9,x and its X update $16BD,x. PIXI uses $16BD,x for Y and $16B9,x for X.
$1698; PIXI preserves X.
Finds the OAM slot and screen position of score sprite X.
i = (4 · $1705,x) mod 256. $02-$03 = the 16-bit word at $001C+i, $04-$05 = the word at $001A+i (layer 0: $1C/$1A; layer 1: $20/$1E). Written on every path; M=0 only for these two copies.
rx = (X16 − [$04-$05]) mod $10000, ry = (Y16 − [$02-$03]) mod $10000.
rx ≤ $F3 and the high byte of ry is 0. Tested in this order, each failure returning at once: (a) high byte of (X16 + $0C − camX) mod $10000 ≠ 0; (b) high byte of rx ≠ 0; (c) high byte of ry ≠ 0.
$00 = low byte of rx, $01 = low byte of ry, Y = A = SMW $02AD9E + x ($B0,$B8,$C0,$C8,$D0,$D8), C=1, N=1, Z=0.
i. $00/$01 not written.
$0D9B bit 6 is set (boss battles); PIXI has no such case.
Draws score sprite X as two 8×8 tiles side by side, in front of all layers.
$07 = left tile, $08 = right tile, $09 = left properties, $0A = right properties. DB must map WRAM.
o = its OAM index:
$0200+o = $00, $0204+o = ($00 + 8) mod 256; $0201+o = $0205+o = $01.
$0202+o = $07, $0206+o = $08; $0203+o = $09 | $30, $0207+o = $0A | $30.
$0420 + o/4 = 0 and $0421 + o/4 = 0.
o/4. Not drawn: ScoreGetDrawInfo's C=0 exit. X preserved. $07-$0A unchanged.
Lets score sprite X rise one pixel at a time, stopping near the top of the screen.
$04 (SMW's). A is ignored.
$00-$3F/$80-$BF does). DB is restored on exit.
$00 = limit.
t = $16FF,x >> 4. Mask k = SMW's $02AD9A[t] for t 0..3 ($03,$01,$00,$00): speed $00-$0F moves every 4th frame, $10-$1F every 2nd, $20-$3F every frame. PIXI keeps its own 4-byte copy of these values; for t ≥ 4 (speed ≥ $40) it reads whatever PIXI assembled after that copy, which is not defined. Callers keep the speed below $40 (SpawnScoreGeneric uses $30); a differential test must too.
$13 & k ≠ 0, stop.
($16E7,x − $1C) mod 256 < $00, stop (low bytes and layer 1 only, whatever $1705,x says).
$16F9:$16E7,x by 1.
t, A = $13 & k, C = bit 3 of $16FF,x.
$16E7,x, A = ($16E7,x − $1C) mod 256, C=0.
$16E7,x, C=1.
t ≥ 4 reads the next SMW table ($02AD9E).
Finds the OAM slot and screen position of smoke sprite X.
d = ($17C8,x − $1A) mod 256. Low bytes only: no high byte or layer is considered.
d ≥ $F0: C=0, A = d, Y unchanged, Z = (d = $F0), N = bit 7 of d − $F0. Nothing written.
$00 = d, $01 = ($17C4,x − $1C) mod 256, Y = A = SMW $0296B8 + x ($20,$24,$28,$2C), C=1, N=0, Z=0.
d ≥ $F4 and also at a relative Y ≥ $E0.
Draws smoke sprite X as one tile.
$02 = tile, $03 = properties (YXPPCCCT), $04 = the $0420 byte (size and X high bit). DB must map WRAM.
$0200+o = $00, $0201+o = $01, $0202+o = $02, $0203+o = $03, $0420 + o/4 = $04.
o/4, A = $04, N/Z from $04. X preserved. $02-$04 unchanged.
Meant to find the OAM slot and screen position of spinning-coin sprite X, erasing it when off the side of the screen. As shipped it compares the wrong camera bytes (see Behaviour). The contract describes what it does, not what it was meant to do.
i = (4 · $17E4,x) mod 256. $02-$03 = word at $001C+i (camera Y), $04-$05 = word at $001A+i (camera X). For layer 1: $02=$1C, $03=$1D, $04=$1A, $05=$1B.
b = 1 if $17D4,x < $02, else 0. h = ($17E8,x − $04 − b) mod 256: the coin's Y high byte minus the camera's X low byte. c = 1 if $17E8,x ≥ $04 + b (no borrow), else 0. If h ≠ 0: return, not drawn and not erased.
d = ($17E0,x − $03 − (1 − c)) mod 256: the coin's X low byte minus the camera's Y high byte, minus a borrow that is 0 unless $17E8,x = 0, $04 = $FF and b = 1. If d ≥ $F8: $17D0,x = 0 (erase) and return, not drawn.
h, Z=0, N = bit 7 of h, Y = i.
d, Y = i, N/Z from comparing d with $F8.
$00 = d, $01 = ($17D4,x − $02) mod 256, Y = A = SMW $0299E9 + x ($30,$38,$40,$48), C=1, N=0, Z=0.
$02-$05 are written on every path. X preserved. The X high byte $17EC,x is never read.
$02 = Y lo, $03 = X lo, $04 = Y hi and compares against those; PIXI stores two words ($02-$03 = Y, $04-$05 = X) but compares against the same offsets, hence the mix-up. SMW also starts the X subtraction with no borrow, and erases through its own path at $0299E3.
h is almost never 0, so the routine almost always returns "not drawn". Random states are needed to reach steps 3 and 4.
U($17D8,x, $17DC,x, $17E8:$17D4,x).
U. X preserved.
RTL for RTS).
Finds the OAM slot and screen position of minor extended sprite X; erases it when well off screen.
$01 = ry = ($17FC,x − $1C) mod 256. If ry is in $E0..$EF: erase. Only the low bytes are used; the Y high bytes are never read.
$02 = 0. $00 = low byte of X16 − camX (X16 = $18EA:$1808,x, camX = $1B:$1A). If the high byte of that 16-bit difference is non-zero: when ($00 + $38) mod 256 ≥ $70, erase; otherwise $02 = 1 and carry on. Any non-zero high byte counts, not only ±1 screen.
$17F0,x = 0 and return, not drawn.
(ry + $10) mod 256 ($F0..$FF), N and Z from A [MEASURED], Y unchanged. $00 and $02 not written.
($00 + $38) mod 256, N and Z from the test against $70 [MEASURED], Y unchanged. $00, $01 and $02 (= 0) written.
$028B77 + x, N/Z from it. $00, $01, $02 written.
$50,$54,…,$78,$7C; SMW reads it at $028C6E and seven other places, never at $028B77). PIXI reads one byte earlier, so slot n gets SMW's index for slot n−1, and slot 0 gets $60 (the byte before the table), the same index as slot 5. In a vanilla or PIXI-patched ROM the bytes $028B77-$028B82 are $60,$50,$54,$58,$5C,$60,$64,$68,$6C,$70,$74,$78. To match PIXI, read $028B77 + x; to match SMW, $028B78 + x.
The same contract as MinorExtendedGetDrawInfo (including the erase-path flags), on the cluster tables:
$1892,x, Y low $1E02,x, X $1E3E:$1E16,x. X = cluster slot (0..19).
$02FF50 + x (20 bytes: $E0,$E4,…,$FC,$5C,$58,…,$30), the table SMW's cluster code reads at $02FCD9 and elsewhere. Here the address is SMW's own (no offset).
$1892,x = 0.
Moves minor extended sprite X along one axis.
U($182C,x, $1844,x, $18EA:$1808,x).
$18EA:$1808,x += sext8($182C,x) (whole pixels, no fraction).
U($1820,x, $1838,x, $1814:$17FC,x).
$1814:$17FC,x += sext8($1820,x).
$00 if the speed used is < $80, else $FF; A = the new position high byte; N, Z, V, C from the high-byte add (C = carry out of the 16-bit sum). X preserved.
Spawn/ClusterGeneric.asm)Spawns a cluster sprite at an origin plus an offset.
$00 = X offset, $01 = Y offset (both signed). $02-$03 = origin X, $04-$05 = origin Y (16-bit). DB must map WRAM.
$1892,y = 0.
n): $1892,n = B; $1E3E:$1E16,n = [$02-$03] + sext($00); $1E2A:$1E02,n = [$04-$05] + sext($01). Nothing else: no misc tables are cleared.
n, A = the new $1E2A,n, N/Z/V from its add, B = 0.
$FF, A = $1892 (slot 0's number, non-zero), N=1, Z=0, B = entry B. Nothing written.
$00-$07 unchanged.
_header.asm %SpawnCluster() macro puts the caller's position in $04-$07, as for the other *Generic spawns. With this routine's layout, that gives the new cluster sprite X = whatever is in $02-$03 and Y = the caller's X. The routine's own layout is $02/$04; what the header macros should pass is a separate matter.
Spawn/ExtendedGeneric.asm)$00/$01 = X/Y offset (signed), $02 = X speed, $03 = Y speed, $04-$05 = origin X, $06-$07 = origin Y. DB must map WRAM.
$170B,y = 0. The fireball slots 8 and 9 are never used.
$170B,n = B; $1733:$171F,n = origin X + sext($00); $1729:$1715,n = origin Y + sext($01); $1747,n = $02; $173D,n = $03. Fractions, $1765, $176F and $1779 are not touched.
n, A = $03, N/Z from $03, B = 0. No free slot: as SpawnClusterGeneric (A = $170B). X untouched; $00-$07 unchanged.
Spawn/Generic.asm), the minor extended spawner$17F0,y = 0.
$17F0,n = B; $18EA:$1808,n = origin X + sext($00); $1814:$17FC,n = origin Y + sext($01); $182C,n = $02; $1820,n = $03. Fractions and $1850 (timer) are not touched.
$17F0).
%SpawnGeneric(), but every _header.asm calls %SpawnMinorExtendedGeneric(), which no file in routines/ provides. A PIXI-compatible set needs at least the name the headers use.
Spawn/ScoreGeneric.asm)$00/$01 = X/Y offset, $04-$05 = origin X, $06-$07 = origin Y. DB must map WRAM ($18F7 absolute).
$16E1,y = 0. If none is free: decrement $18F7; if the result has bit 7 set, $18F7 = 5; use slot $18F7.
$16E1,n = B; $16F3:$16ED,n = origin X + sext($00); $16F9:$16E7,n = origin Y + sext($01); $16FF,n = $30. $1705 (layer) is not touched.
n, A = $30, N=0, Z=0. C = carry out of the Y high-byte add (by-product: the routine reports no status). B = 0 if a free slot was found; otherwise B = $16E1 (slot 0's number, as the search last read it), or $05 when $18F7 wrapped. X untouched.
$18F7 round-robin). SMW's $02ACEF then places the score at the sprite's position − 8, nudged down when above the screen; PIXI uses origin + offset.
Spawn/SmokeGeneric.asm)$00/$01 = X/Y offset, $02 = timer, $04 = origin X low, $06 = origin Y low ($05 and $07 are ignored). DB must map WRAM.
$17C0,y = 0.
$17C0,n = B; $17C8,n = ($04 + $00) mod 256; $17C4,n = ($06 + $01) mod 256; $17CC,n = $02. 8-bit positions only: the high bytes $1964/$1960 are not written.
n, A = $02, N/Z from $02, B = 0. No free slot: as SpawnClusterGeneric (A = $17C0); slot 0 is not reused, unlike SMW's inline smoke spawns. X untouched.
Spawn/SpinningCoinGeneric.asm)$00/$01 = X/Y offset, $03 = Y speed, $04-$05 = origin X, $06-$07 = origin Y. $02 is ignored. DB must map WRAM.
$17D0,y = 0.
$17D0,n = B; $17EC:$17E0,n = origin X + sext($00); $17E8:$17D4,n = origin Y + sext($01); $17D8,n = $03. $17DC (fraction) and $17E4 (layer) are not touched.
n, A = $03, N/Z from $03, B = 0. No free slot: as SpawnClusterGeneric (A = $17D0).
*Generic spawnssprites/_header.asm version of %SpawnMinorExtended() makes its own ($15A0 | $186C | $15D0 of the parent) before calling; the other macros do not.
$10000.
The 1.2.x files were compared with the 1.40 files of the same macro name (ExtendedX → Extended/X.asm, SpawnX → Spawn/X.asm), both reduced to their instructions (comments, label spelling and 1.40's local-label syntax removed, defines resolved). The two sa1def.asm files give the same values for every define these routines use.
Changed in behaviour: 1 of 27 (ExtendedGetDrawInfo).
t formed by addition) is gone. 1.40 uses the true high byte of the 16-bit Y16 − camY16. With d = (Ylo − camYlo) mod 256 and h = that high byte:
h = 0: erase if d ≥ $F0, otherwise visible.
h = $FF (up to one screen above): erase if d < $C0; hide ($02 = $F0, not erased) if d < $E0; otherwise visible.
h: erase, with C = 0 [MEASURED].
Registers on return keep the same shape: visible with h = 0: A = d, C=0; visible with h = $FF: A = d, C=1; hidden or erased: A = $F0, N=1, Z=0. The X-axis rule, $00, $01 and the erase ($170B,x = 0) are unchanged.
$2C and $2D (defined, but not usable OAM indexes), instead of whatever followed PIXI's copy. Callers still must not use those slots.
JSL to the shared SubHorzPos instead of a private copy reached by JSR. Same writes ($0E-$0F, Y) and results; it uses one more byte of stack, and a 1.40 Star needs SubHorzPos inserted too.
!ExtendedSize − 1, which is 7, as before.
RTL address is written as $B888 instead of $B889 − 1. Same value.
!EXLEVEL / !SA1 conditionals are written as comparisons. Both defines are only ever 0 or 1, so the same branch is assembled.
Aiming, CapeContact, ChangeMap16, CheckForContactAlternate, CircleX, CircleY, ExtendedCapeClipping, ExtendedHurt, ExtendedSpeed, FinishOAMWrite, FireballContact, GetDrawInfo, GetMap16, LoseYoshi, Random, SetPlayerClippingAlternate, SetSpriteClippingAlternate, ShooterMain, SpawnExtended, SpawnSmoke, SpawnSprite, SpawnSpriteSafe, Star, SubHorzPos, SubOffScreen and SubVertPos behave the same (only labels, comments, layout and the spellings noted above differ). The [MEASURED] corrections in the 1.2.x contracts apply to the 1.40 versions unchanged.
Interface contracts for the assembler macros PIXI defines in asm/sa1def.asm, the file every PIXI sprite is assembled with. Same rules as the routines: behaviour only. The 1.2.x-era copy has 7 macros and first includes an optional config.asm; the 1.40 copy has the same 7 plus invoke_sa1, and no config.asm include.
!SA1: 1 when the ROM header byte $00FFD5 is $23 (SA-1 map mode), else 0. Set by sa1def.asm.
!Base2: $6000 on SA-1, $0000 on LoROM. Set by sa1def.asm.
!extra_bits: the extra-bits sprite table, indexed by slot: $7FAB10 (LoROM) / $6040 (SA-1). Set by sa1def.asm through define_sprite_table.
!__debug: optional, from the user or the command line; treated as 0 when undefined.
!__debug is undefined it becomes defined as 0. When !__debug equals 1, the assembler prints a line made of $, the current PC in hex, a space and the text msg. Otherwise nothing is printed.
$6040,x, so DB must reach I-RAM/BW-RAM there ($00-$3F/$80-$BF); on LoROM it is the long $7FAB10,x and DB does not matter.
$04) of the sprite's extra-bits byte !extra_bits,x, the "extra bit" Lunar Magic stores per placed sprite. Branches to label when the bit is set, falls through when clear.
$04 when the branch is taken, $00 when it falls through; B, X, Y unchanged. Z clear when taken, set when not; N clear; C and V unchanged. No RAM written.
label must be near.
$6040,x.
BES with the sense inverted: branches to label when bit 2 of !extra_bits,x is clear (A = $00, Z set), falls through when it is set (A = $04, Z clear).
x is an operand written as it would follow an instruction, normally an immediate such as #$10. The macro also needs "two times x", which the assembler forms by appending *2 to that text (so #$10 gives the immediate $20). label is a near (short-branch) label.
-x <= A < x, branches to label otherwise. In effect: A + x (carry cleared first) is compared, unsigned, with 2*x; the branch is taken when the sum is greater than or equal.
2*x must fit in a byte (x ≤ $7F).
addr: 24-bit address of a routine for the SNES CPU, ending in RTL.
addr little-endian at $0183 (low), $0184 (high), $0185 (bank); writes $D0 to SA-1 register $2209 (raises the SA-1-to-SNES IRQ with the custom IRQ vector selected); waits until $018A reads non-zero (the SA-1 Pack's handler sets it once the SNES routine has returned); then stores 0 to $018A.
$0183-$0185 = addr, $018A = 0.
$018A. Only assemble it inside if !SA1 blocks.
label (ending in RTL; DB is not set for it, so it must set its own). Stores the 24-bit label at $3180 (low), $3181 (high), $3182 (bank), then calls, with a near JSR, the SA-1 Pack's call-SA-1 helper at $1E80, which returns once the SA-1 routine has finished. The calling code must run in a bank where $1E80 is that helper ($00-$3F/$80-$BF). Assumes M=1; A clobbered. SA-1 only.
!name as addr when !SA1 is 0 and as addr_sa1 when !SA1 is 1. name is used as text: it may be passed quoted and may start with a digit (sa1def.asm itself defines both !7FAB10 and !extra_bits this way, each resolving to $7FAB10 / $6040).
!SA1 must be set before it is called. Calling it again for an existing name overwrites it.
!name as addr when !SA1 is 0, and as addr OR !Base2 (addr | $6000) when !SA1 is 1. Meant for $0100-$1FFF WRAM addresses that the SA-1 build relocates to $6100-$7FFF.
In a scan of 107 PIXI sprite and driver files (routines folders excluded):
| macro | files | sprites | where |
|---|---|---|---|
| BEC | 11 | 3 | copies of KoopaShell (including PIXI's own sprites/koopa_shell.asm), UpsideDownKoopaShell and FlyingQuestionBlock |
| debugmsg | 1 | 0 | PIXI's own driver, asm/main.asm |
| BES, Between, invoke_snes, invoke_sa1, define_sprite_table, define_base2_address | 0 | 0 | — |
Other %Name( calls in that scan that are not shared routines and not from sa1def.asm:
SpawnClusterGeneric, BounceSetSpeed, and so on), called from the 1.40 _header.asm files of cluster, extended and misc_sprites/*.
CallSprite, CallStatusPtr, CallPerLevelStatusPtr, CallExtCape: PIXI driver internals (asm/pointer_caller.asm), used only by the driver's own asm/*.asm.