Randomizer internals

At a glance

Crate

crates/patcher (legaia_patcher); disc bridge disc::DiscPatcher, orchestration apply, patch output ppf

Three capabilities

LZS encoder (legaia_lzs::compress), Mode 2/2352 sector write-back with EDC/ECC (legaia_iso::write), PROT-entry → LBA addressing (DiscPatcher)

Editing rule

Same-size in place; only doors and place names resize a record, through MAN relocation

Code hosts

SCUS rodata gap 0x8007AB38 (1028 B), the SCUS arena (652 B in four regions), reference-free dead runs inside overlays 0898 / 0899 / 0958, the DMY.DAT annex

Detour shape

Two words at the hook site become j routine + nop; the routine replays the two displaced instructions and jumps back

Guards

Every hook word must match the US build; every landing zone must be all-zero, outside every known table, and read-watch-verified unreferenced

Confidence

Confirmed: disc oracles pin every byte; the MIPS hooks are additionally verified by emulator playtest (the from-scratch engine cannot execute them)

How a patch reaches the disc

A PlayStation disc is not a folder of files. Almost every value the randomizer changes sits inside a compressed block, on a sector whose checksums must be recomputed, at an address nothing else may move. Three capabilities the preservation track never needed make that editable.

The editing rule

• Same size, in place. No sector address, PROT entry or ISO directory record ever moves, so a patch is a pure byte overwrite plus checksum recompute. The disc image's size never changes.
• Fixed slots pad; tight streams re-pack. A monster record is re-emitted zero-padded back to its 0x14000-byte slot in the battle_data archive (PROT 867). A scene MAN has no compressed slack, so the encoder's lazy matching has to fit the exact original span; the rare stream that overflows is skipped and reported.
• Budget from the boundary. A MAN's re-pack budget is its span up to the next descriptor, not its current compressed length - otherwise a second pass over the same scene (encounters, then chests, then shops) would shrink the budget each time.
• Doors and place names are the exception. A destination carries its scene name inline and a banner name is stored unpadded, so re-pointing or renaming changes a record's length. The MAN relocation engine fixes every offset the resize disturbs and rewrites the descriptor's size word.

The error-correction math is the generic CD-ROM scheme (ECMA-130): EDC is a CRC over reversed polynomial 0xD8018001, ECC is Reed-Solomon P/Q over GF(2⁸) with generator 0x11D, and the header is treated as zero so parity is independent of the sector's address. It embeds no game bytes; the disc-gated ecc_real test reproduces real PROT.DAT sectors bit-for-bit.

The technique ladder

Every feature uses one of six techniques, from "overwrite a byte in a table" up to "host new machine code in unused overlay space". The disc-patching write-ups walk each tier with a worked example.

Code hooks: where injected code lives

A detour overwrites two instructions at a hook site with j routine + nop. The routine does its work, replays the two displaced instructions, and jumps back to the word after the site. On the PSX all resident RAM is executable, so a routine written into a dead data region runs when jumped to. Every feature below guards on the hook words matching the US build and refuses a differently-laid-out image rather than corrupting it.

The dead-space map

"Dead" is a runtime property, not a file-byte one: a region qualifies only when it is all-zero in the clean image, constant across states, outside every known table, and read-watch-verified unreferenced on a live PCSX-Redux session. These are the regions that pass.

The injected-code arena budget

Every hand-assembled SCUS-resident feature that needs more than the rodata gap offers lands in the same four verified-dead regions, and they add up to 652 bytes. The limit is arithmetic, not policy: a sweep of every zero run in the executable outside the known live tables finds only 53 further candidate bytes.

Shiny Seru leaves 34 bytes in fragments of 4, 5, 8 and 12; nothing else fits beside it. So the arena claimants are mutually exclusive, enforced by the CLI and the browser patcher:

The Super Arts list payload cannot move into the battle overlay: the arts list is a shared window widget whose renderer has one reference on the disc, from a dispatcher the field and menu overlays call 64 times between them, so it runs when PROT 0898 is not resident. A Super Art damage row claims no arena and composes with everything. Growing PROT 0898 to cover the Pack's block was rejected because it would zero 0x801F7018..0x801FD000 - persistent effect and world state the field overlay leaves there - on every battle load.

Three traps in the MIPS injection features

Each has bitten a shipped hook at least once; each is guarded now.

The signed accrual tail

The Spirit and enemy-damage AP sliders accept negative values, which invert the knob: Spirit then spends AP, or being hit drains it. The gauge is a u16 and every retail site that grows it clamps only against the 100 ceiling, so a negative constant alone would read back as +200-odd and pin the gauge at 100. The consumer has to honour the sign as well.

• Damage site: the ceiling words are dead once the site only subtracts, so a bgez floor fits in them.
• Spirit site: its add/clamp tail is shared with the +8 every non-Spirit action grants, so the ceiling must survive beside the new floor. They fit because a negative setting makes the AP-Boost-1 accessory arm dead, and the head of that arm hosts the relocated over-100 clamp. Consequence: while a slider is negative, the "spirit gain up" accessory is inert.
• No arena involved: every word is a same-size rewrite inside PROT 0898; the two sliders compose with each other and with everything else, and the retail value restores the stock bytes exactly.

801e5e78  bgez v1,0x801e5e84
801e5e7c  _slti v0,v1,0x65         ; delay slot: ceiling test
801e5e80  move v1,zero             ; floor at 0
801e5e84  beq  v0,zero,0x801e5e40  ; over 100 -> the relocated clamp
801e5e88  _sh  v1,0x170(s3)        ; delay slot: the store

Crate modules

One machinery, three families on top: the randomizer, the translation packs and the manual edits. Each module is one row.

Tests

Three layers. Disc-gated tests read LEGAIA_DISC_BIN; with it unset they skip and pass.

No-Sony-bytes hygiene

• The crate never embeds, commits or redistributes game bytes. Injected routines are the project's own code; item and equipment ids come from the user's disc at patch time.
• A patched .bin contains Sony data and is never committed. The distribution form is a patcher plus seed, or the PPF the CLI emits - a PPF carries only the deltas between the user's original disc and the patched one and is meaningless without the original.
• Disc-gated tests skip without LEGAIA_DISC_BIN; CI runs without disc data.

How we know

See also