ROM Overlay and Resource Map

Resource and overlay system

Scope: This page is the canonical owner for MKMSZ's global file-table architecture, raw/resource loading mechanisms, stage-overlay identity rules, resource-selector grammar, global-vs-stage-local resource semantics, and resource packaging rules used by MKMSZR.

It does not own literal ROM/RDRAM allocation intervals, cross-stage item-planner/proof chronology, or concrete per-stage pickup/resource records. Those belong respectively to Memory and allocation map, Global item materialization and solvability, and the eight stage catalogs.

Current conclusion

MKMSZ uses a global file table to locate/load file packages, but ordinary stage resources are interpreted through a stage-local resource file and selector table. These namespaces must not be conflated: a global file ID can identify a package across the game, while an ordinary pickup's +0x24 selector is meaningful only against the resource file loaded for that stage.

The ordinary-pickup resource path is sufficiently decoded to explain current production behavior and the constraints consumed by the global materializer. The resource system establishes how selectors resolve, how embedded and externally backed resource records differ, and how stage/overlay identity must be qualified. The global materialization owner decides when and how those mechanisms are used for cross-stage randomization.

Global file table and raw loading

The global file table begins at ROM 0x000A5010 / VA 0x800A4410. Entries are 12 bytes, and file IDs are global identifiers into that table.

Two production-relevant examples are:

• file ID 0x1B: the MKMSZR native payload source used by the proven bootstrap path;
• file ID 0x5E: the normal title-screen image package.

The raw global-file loader at 0x80065D64 is synchronous in the runtime-confirmed native bootstrap path. Exact production ownership of the patched table entries and their backing ROM storage belongs to Memory and allocation map; this page owns the file-table/loader relationship rather than declaring those bytes free or reusable.

Function-level semantics for 0x80065D64 and other helpers remain indexed in Function registry.

Global versus stage-local resource identity

Value / address kind	Scope	Rule
Global file ID	Global file table	Identifies a file/package entry. Do not reinterpret it as a stage-local selector.
Stage resource selector	Current stage resource file	Ordinary pickup +0x24 is a word index into the currently loaded stage resource file. The same numeric selector can mean different things in another stage.
File-relative descriptor/data offset	One loaded resource file	Resolve relative to that file's runtime base. It is not a ROM offset or globally stable VA.
External resource/cache ID	Loader/package context	Numeric identity alone is not proof that the resource is resident or portable to another stage.
Stage-overlay VA	Loaded overlay + source artifact	The VA is not a global function identity; stage/source qualification is required.
Literal ROM/RDRAM interval	Allocation owner/lifecycle	Canonical ownership and availability belong to Memory and allocation map.

Main-stage resource files

Each of the eight main gameplay stages has its own resource file and runtime-loaded base. Concrete file-table entries, stock ROM ranges, verified runtime bases, selector tables, pickup-to-selector usage, and decoded resource records remain canonical in the individual stage catalogs.

This page intentionally does not duplicate the former eight-stage range/slot table. Stage-relative facts should be updated once, in the relevant stage catalog.

The current stage resource-file base used by the ordinary-pickup path is held at 0x802E82B8. Stage-loading code writes the current loader/allocator result there before ordinary resource lookup consumes it. The pointed-to address and extent are dynamic and stage-dependent; their allocation classification belongs to the Memory Map.

Outer selector table grammar

The first words of a stage resource file form a stage-local outer selector table. Occupied entries resolve to file-relative descriptors/structures. Depending on the resource, those structures may lead to:

• embedded-data bundles;
• external-resource/cache-ID backed records;
• zero-terminated lists;
• aliases;
• valid structures whose exact gameplay owner remains unresolved.

A zero outer-table word is only a logical selector-capacity observation. It does not reserve, expose, or prove free physical bytes in the file.

For ordinary pickups, record +0x24 supplies the selector. The exact decoded lookup at pickup manager 0x80038ACC, for each uncollected ordinary record, is:

0x80038BE4  lw   v0, +0x24(s0)      ; selector from pickup record
0x80038BE8  lui  a2, 0x802F
0x80038BEC  lw   a2, 0x82B8(a2)     ; current stage resource-file base
0x80038BF8  sll  v0, v0, 2
0x80038BFC  addu s1, a2, v0         ; entry_ptr = base + selector*4
0x80038C00  jal  0x800281A0
0x80038C04  move a0, s1

0x800281A0 then performs:

lw   a0, 0(s3)       ; relative descriptor offset from selected entry
...
jal  0x80028128
addu a0, a0, s2      ; direct descriptor pointer = base + relative offset

Later in the same pickup-manager iteration, the selected entry is read again and resolved as base + *entry_ptr before actor setup continues.

On this ordinary-pickup path, no stock selector-count/table-width check occurs before the selector is used as a 32-bit word index. Therefore a relocated/expanded resource file can technically place selector words beyond the original stock table and address them with:

pickup +0x24 = appended_selector_entry_offset / 4

This is the resource-system basis for extension selectors. The disposable Proof D/F/H sequence, composed Prison/Fortress stress work, deduplication policy, and production-integration gates are deliberately owned by Global item materialization and solvability. The confirmed ordinary-pickup behavior must not be generalized automatically to other resource consumers.

Resource-record storage forms

The decoded ordinary resource records use two materially different data-location forms:

• embedded form: record +0x04 = 0; record +0x08 is a stage-file-relative compressed-data offset;
• external-resource-ID form: record +0x04 is a cache/resource ID; record +0x08 = 0.

An external resource ID is not a self-contained pointer and is not guaranteed to be portable between stages. Whether the referenced payload is available depends on the active package/cache context. Cross-stage failures and the successful external-to-embedded conversion proofs are recorded under Global item materialization and solvability.

For embedded images, the native path calls 0x8000322C. Compression type 4 dispatches to 0x80003428, whose decoder uses a 1024-byte ring buffer and separate MSB-first control/token streams. Static analysis established the native inclusive back-reference count as low6 + 2. These are resource loading/decoding mechanics; using them to manufacture imported destination bundles is materializer policy and remains outside this page.

Title resource packaging — global file 0x5E

Global file ID 0x5E is the normal title-screen image package. Its clean-ROM file-table entry uses flag 1, and the package decodes to 0x61494 bytes.

The package uses the game's MSB-first LZW-style stream. A matching encoder/decoder pair is Static-confirmed by byte-exact stock decode/re-encode: decoding the stock package and re-encoding it yields the original compressed size 0x2F3E0 and round-trips to the same 0x61494 decoded bytes.

The earlier high-color Candidate-B artwork recompressed to 0x2FD95 bytes, 0x9B5 larger than the stock slot, and required relocation. The 2026-09-29 approved typeset artwork uses the same 16-color CI8 palette shared with configurable edition text. Its default SUB-ZERO compressed package is 0x2D52E bytes, within the 0x2F3E0 stock slot by 0x1EB2 bytes. These are Static/implementation results; this exact new title composition remains runtime Pending. Literal allocation ownership is canonical in Memory and allocation map. The accepted MKMSZR title path is data-only:

1. decode the existing 0x5E package;
2. modify the six CI8 tile pixel regions used by the title art;
3. rasterize the configurable uppercase edition line into that same decoded image;
4. recompress the package losslessly;
5. write the package into the original file-0x5E ROM slot and update its end pointer; the start pointer and compression flag remain stock.

No title executable cave or high-ROM title allocation is required by the new implementation. Its stock-slot bound and build-dependent compressed endpoints are allocation facts owned by Memory and allocation map.

The title palette descriptor is at ROM 0x000B3360; the count word is followed by the 256-entry palette at 0x000B3364. Offline reconstruction uses the verified BGR555 interpretation.

This page owns the file/package mechanics. Branding design, visual acceptance, and title-proof chronology belong to Presentation and branding.

Overlay identity rules

Main stage overlays reuse a common runtime address region. The established main-stage overlay base is 0x802ECE30, but that VA alone does not identify a unique function or byte owner.

Eight main-stage raw overlay source mappings are now Static-confirmed for the supported clean N64 USA Rev. 0 ROM. Each new entry was independently checked against its original 12-byte global file-table row (flag=0), the corresponding native 0x80065D64 loader call with destination 0x802ECE30, and stage catalog pickup/callback addresses:

Stage / overlay	Global file ID	ROM source	Runtime base	Evidence / limit
Temple	0xA0	[0x000CA510,0x000CF160)	0x802ECE30	Static-confirmed (2026-10-08): file-table entry 0xA5790, loader at ROM 0xEE0C / VA 0x8000E20C explicitly loads file 0xA0 to this base; all four ordinary pickups 0xCEF6C..0xCEFFC and scripted Map callback 0x802EEC54 / ROM 0xCC334 fall within the byte-matched source. SHA-256 eab72de2e8a9104bcb050807bff3cb0ae3ce1640b76857c90d30ec66346b89ce. The Map is not a fifth ordinary pickup.
Wind	0xA2	[0x000CF160,0x000D8B90)	0x802ECE30	Static-confirmed (2026-10-08): file-table entry 0xA57A8, loader at ROM 0xFD64 / VA 0x8000F164; six ordinary pickup records 0xD8424..0xD8514, mixed award 0x802F2CB4 / ROM 0xD4FE4, and trigger dispatcher 0x802EE9FC / ROM 0xD0D2C match this raw source. SHA-256 f7339eebe4f44efcafdf6da994f7709e9e21ac3895650f59ad194537c508164b.
Water	0xA1	[0x000B4FC0,0x000BAF60)	0x802ECE30	Static-confirmed (2026-10-08): file-table entry 0xA579C, loader at ROM 0x104C4 / VA 0x8000F8C4; nine ordinary pickup records 0xBAB14..0xBAC94 and award callback 0x802F2448 / ROM 0xBA5D8 match the raw overlay. SHA-256 9e1c1491b8665822ade09697abb6dd53f62c7950a4eadbabf34fa6536e3cfac4.
Fire	0x9D	[0x000E1B80,0x000E6610)	0x802ECE30	Static-confirmed (2026-10-08): file-table entry 0xA576C, normal Fire loader at ROM 0x115F0 / VA 0x800109F0; all 16 ordinary pickups (0xE6098..0xE63F8) and three-icon callback 0x802F0EBC / ROM 0xE5C0C lie inside the source. SHA-256 ee65b26e06694ff36412fdcbb30e20b4ba15ab6fe76e96c1a7c689cac20e36a4. Stage-7/TEST LAB use of file 0x9D was historically diagnostic; it does not redefine normal Fire ownership.
Earth	0x9C	[0x000D8B90,0x000E1B80)	0x802ECE30	File-table entry is raw flag 0; the mapping independently resolves the known Earth key callback 0x802F52B0 to its matching ROM body and Earth boss routine 0x802EDF50 into the same overlay.
Prison	0x9F	[0x000C4C70,0x000CA510)	0x802ECE30	Static-confirmed from file-table entry ROM 0xA5784 and permanent loader call 0x80065D64(0x9F,0x802ECE30) at VA 0x800100CC / ROM 0x10CCC. The ordinary Prison records at 0xCA030/60/90 lie inside this raw file. This mapping rejects file 0xA2 as Prison evidence.
Bridge	0x9B	[0x000BAF60,0x000C0330)	0x802ECE30	Static-confirmed from the clean file-table entry and normal Bridge loader. The range contains award-only callback 0x802EF178, scene-trigger dispatcher 0x802ED888, the Bridge ordinary records at 0xBFFD8..0xC0188, and the direct selector-writer census used by the Bridge destination-ownership closure.
Fortress	0x9E	[0x000C0330,0x000C4C70)	0x802ECE30	Static-confirmed from clean file-table entry 0xA5778. The range contains Fortress assassin/reward manager 0x802EFDB0, crystal-progression dispatcher 0x802EF30C, ordinary reward records 0xC4834..0xC49B4, and the direct selector-writer census used by the final destination-ownership closure.

Any overlay finding must include at least:

• platform/revision;
• loaded stage or overlay identity;
• source artifact/file when known;
• runtime VA;
• evidence scope.

A function observed at a VA in one stage must not be promoted to a globally resident function merely because another stage uses the same address range. Exact continuous ownership of the shared overlay region belongs to Memory and allocation map, while stable function semantics belong to Function registry.

Allocation and materialization boundaries

Resource mechanics do not establish allocation safety.

• A zero selector entry is not free file storage.
• A file-relative offset is not a ROM offset.
• A successful disposable resource relocation does not reserve that ROM range for production.
• Dynamic stage resource allocations do not imply a fixed free RDRAM interval.
• Appending selector/descriptor/data structures requires explicit bounded backing storage and updated file-table metadata.
• Runtime arena/headroom and composition with other production owners must be checked separately.

Literal interval ownership, proof conflicts, production capacity, and free/candidate/unknown classifications belong to Memory and allocation map.

The following cross-stage concerns belong to Global item materialization and solvability, not this page:

• the global logical item pool and exact-visual materialization policy;
• destination-safe key/crystal award handling;
• extension-selector proof chronology;
• foreign-bundle rebasing and external-to-embedded proof history;
• deterministic resource deduplication/capacity planning;
• composed Prison/Fortress stress validation;
• deterministic global retries, solver behavior, required Power Upgrades, and the Temple Map question.

Concrete stage-relative selectors, records, resource IDs, file ranges, runtime bases, and per-stage capacity observations stay in the eight stage catalogs.

Resource-system invariants

1. Global file IDs and stage-local selectors are different namespaces.
2. Stage selectors are meaningful only with the correct loaded stage resource file.
3. External resource IDs are context-dependent, not portable pointers.
4. Zero/unused-looking selector entries do not prove free payload bytes.
5. File-relative, ROM, RDRAM, and overlay-relative coordinates must be labeled explicitly.
6. Overlay VAs require stage/source identity.
7. Proof resource placement never becomes production allocation ownership by implication.

Related canonical pages

• Memory and allocation map — literal ROM/RDRAM ownership, allocation classes, aliases, lifecycle, and conflicts.
• Global item materialization and solvability — cross-stage planner, resource-import proof history, retries, solver, and current integration gates.
• Stage catalogs — all concrete stage-relative ordinary records and resource instances.
• Data structures and encodings — canonical stable record/structure/codec grammar outside the selector/loading rules owned here.
• Function registry — canonical function semantics.
• Pickups and stage-local randomization — current production ordinary-pickup behavior.
• Presentation and branding — current title/legal branding behavior and visual evidence.