Files

scawful 26d35364af Add advanced technical documentation for ZScream custom overworld

- Introduced comprehensive documentation covering internal hook architecture, memory management, graphics loading pipeline, sprite loading system, cross-namespace integration, performance considerations, and debugging strategies.
- Detailed sections on adding custom features and modifying existing behaviors, including examples and code snippets.
- Included a complete hook list and memory map quick reference for developers.

2025-10-03 15:50:34 -04:00

14 KiB

Raw Blame History

Memory Map

This document provides a detailed map of the WRAM and SRAM memory regions, serv| $7EF358 | WolfMask | Flag indicating if the player has obtained the Wolf Mask. |

Repurposed Vanilla SRAM Blocks

The following blocks were marked "unused" in vanilla ALTTP but are now utilized for OOS custom data:

Block $7EF38A-$7EF3C4 - Collectibles & Custom Progression

This is a large block of vanilla unused SRAM now used for various collectibles, side-quests, and tracking systems.

Address	Label	Description	Verified
`$7EF38A`	`FishingRod`	Flag indicating if the player has the Fishing Rod.	✓
`$7EF38B`	`Bananas`	Number of bananas collected for side-quest.	✓
`$7EF38D`	`Pineapples`	Number of pineapples collected.	✓
`$7EF38F`	`RockMeat`	Number of rock meat items collected.	✓
`$7EF391`	`Seashells`	Number of secret seashells collected.	✓
`$7EF393`	`Honeycomb`	Number of honeycombs collected.	✓
`$7EF395`	`DekuSticks`	Number of Deku sticks collected.	✓
`$7EF396`	`TingleMaps`	Tingle map collection tracking.	✓
`$7EF397`	`TingleId`	Tingle identification value.	✓
`$7EF398`	`Scrolls`	Bitfield tracking lore scroll collection (7 dungeons: `.dgi zktm`).	✓
`$7EF39A`	`PrevScroll`	Tracks the previous scroll for re-reading old hints.	✓
`$7EF39B`	`MagicBeanProg`	Multi-day growth cycle tracking for magic bean side-quest (`.dts fwpb`).	✓
`$7EF39C`	`JournalState`	Current state of the player's journal.	✓
`$7EF39D`	`SRAM_StormsActive`	Flag indicating if the Song of Storms effect is active.	✓

Block $7EF403-$7EF4FD - Partially Repurposed

Most of this block remains unused, but OOS utilizes a portion for the Dreams collectible system.

Address	Label	Description	Verified
`$7EF410`	`Dreams`	Bitfield tracking collection of three Dreams (`.cpw`: Courage, Power, Wisdom).	✓

💡 Usage Notes:

Scrolls ($7EF398): One scroll per dungeon (7 total). Bitfield format: .dgi zktm where each letter represents a dungeon (m=Mushroom Grotto, t=Tail Palace, k=Kalyxo Castle, z=Zora Temple, i=Glacia Estate, g=Goron Mines, d=Dragon Ship).

MagicBeanProg ($7EF39B): Tracks multi-day growth cycle with bitfield .dts fwpb (b=bean planted, w=watered, p=pollinated, f=first day, s=second day, t=third day, d=done).

Dreams ($7EF410): Similar to vanilla Pendants, tracks three key collectibles. Bitfield: .cpw (c=Courage, p=Power, w=Wisdom).

SRAM Address Contradictions (Source File Notes)

The following addresses appear with both active label definitions and UNUSED_ markers in Core/sram.asm. The label definitions take precedence - these addresses are actively used:

$7EF3D4 - Both MakuTreeQuest and UNUSED_7EF3D4 (✓ In Use)
$7EF3D6 - Both OOSPROG and UNUSED_7EF3D6 (✓ In Use)
$7EF38A - Both FishingRod and UNUSED_7EF38A (✓ In Use)

These contradictions appear to be legacy comments from the vanilla ALTTP disassembly that were not removed when OOS repurposed these addresses.

as a central reference for understanding the game's state.

1. WRAM (Work RAM) - `$7E0000`

This section details the layout of the game's volatile memory.

Key Vanilla WRAM Variables

This section contains a table listing critical vanilla WRAM addresses, their labels (from Core/ram.asm and Core/symbols.asm), and their purpose.

Address	Label	Description
`$7E0010`	`MODE`	The main game state/module index.
`$7E0011`	`SUBMODE`	The sub-state for the current game mode.
`$7E001A`	`FRAME`	A counter that increments each non-lagging frame.
`$7E001B`	`INDOORS`	A flag indicating if Link is indoors (0x01) or outdoors (0x00).
`$7E002F`	`DIR`	The direction Link is facing (0=U, 2=D, 4=L, 6=R).
`$7E005D`	`LINKDO`	Link's personal state machine ID (walking, swimming, etc.).
`$7E008A`	`OWSCR`	The current Overworld screen ID.
`$7E00A0`	`ROOM`	The current Underworld room ID.
`$7E02E0`	`BUNNY`	A flag indicating if Link is in his bunny form (0x01).
`$7E031F`	`IFRAMES`	Link's invincibility frame timer after taking damage.
`$7E0DD0`	`SprState`	An array storing the state for each of the 16 sprites.
`$7E0E20`	`SprType`	An array storing the ID for each of the 16 sprites.
`$7E0E50`	`SprHealth`	An array storing the health for each of the 16 sprites.

Custom WRAM Region - `$7E0730+`

This section details the custom WRAM area defined in Core/ram.asm and Core/symbols.asm. It explains the purpose of each custom variable.

Address	Label	Description
`$7E0730`	`MenuScrollLevelV`	Vertical scroll position for the menu.
`$7E0731`	`MenuScrollLevelH`	Horizontal scroll position for the menu.
`$7E0732`	`MenuScrollHDirection`	The direction of horizontal scrolling in the menu.
`$7E0734`	`MenuItemValueSpoof`	Used to temporarily override the displayed value of a menu item.
`$7E0736`	`ShortSpoof`	A shorter version of the spoof value.
`$7E0737`	`MusicNoteValue`	The value of the current music note being played.
`$7E0739`	`GoldstarOrHookshot`	Differentiates between the vanilla Hookshot and the custom Goldstar item.
`$7E073A`	`Neck_Index`	Used for multi-part sprites, like a centipede body.
`$7E0745`	`FishingOrPortalRod`	Differentiates between the Fishing Rod and the Portal Rod.

2. SRAM (Save RAM) - `$7EF000`

This section details the layout of the save file memory.

🔍 SRAM Verification Note: All custom SRAM variables documented below have been cross-referenced with Core/sram.asm. Some addresses in the source file have contradictory UNUSED_ markers alongside actual label definitions (e.g., OOSPROG = $7EF3D6 vs UNUSED_7EF3D6 = $7EF3D6). The actual usage takes precedence - if a label is defined for an address, it is considered in-use regardless of UNUSED_ markers. This appears to be a legacy comment artifact from the vanilla ALTTP disassembly.

Key Vanilla SRAM Variables

This section lists key vanilla save data locations, such as inventory, health, and progression flags, as defined in Core/sram.asm.

Address	Label	Description
`$7EF340`	`Bow`	The player's current bow type (0x00-0x04).
`$7EF343`	`Bombs`	The number of bombs the player has.
`$7EF359`	`Sword`	The player's current sword type (0x00-0x04).
`$7EF35A`	`Shield`	The player's current shield type (0x00-0x03).
`$7EF360`	`Rupees`	The player's current rupee count.
`$7EF36C`	`MAXHP`	The player's maximum health (1 heart = 8 HP).
`$7EF36D`	`CURHP`	The player's current health.
`$7EF374`	`Pendants`	A bitfield for the collected pendants (Courage, Power, Wisdom).
`$7EF37A`	`Crystals`	A bitfield for the collected crystals from Dark World dungeons.
`$7EF3C5`	`GameState`	The main progression state of the game.

Custom SRAM Region

This is a critical section. It provides a comprehensive breakdown of all custom variables added to the SRAM, explaining what each flag or value represents. This information is primarily found in Core/sram.asm.

Address	Label	Description
`$7EF3D6`	`OOSPROG`	A primary bitfield for major quest milestones unique to Oracle of Secrets.
`$7EF3C6`	`OOSPROG2`	A secondary bitfield for less critical progression flags.
`$7EF3D4`	`MakuTreeQuest`	A flag indicating if the Maku Tree has met Link.
`$7EF3C7`	`MapIcon`	Controls the position of the guiding 'X' on the world map.
`$7EF351`	`CustomRods`	A flag to differentiate between the Fishing Rod (1) and Portal Rod (2).
`$7EF38A`	`FishingRod`	Flag indicating if the player has the Fishing Rod.
`$7EF38B`	`Bananas`	The number of bananas collected for a side-quest.
`$7EF391`	`Seashells`	The number of secret seashells collected.
`$7EF398`	`Scrolls`	A bitfield tracking which of the lore scrolls have been found.
`$7EF39B`	`MagicBeanProg`	Tracks the multi-day growth cycle of the magic bean side-quest.
`$7EF39C`	`JournalState`	The current state of the player's journal.
`$7EF39D`	`SRAM_StormsActive`	A flag indicating if the Song of Storms effect is active.
`$7EF410`	`Dreams`	A bitfield tracking the collection of the three "Dreams" (Courage, Power, Wisdom).
`$7EF347`	`ZoraMask`	Flag indicating if the player has obtained the Zora Mask.
`$7EF348`	`BunnyHood`	Flag indicating if the player has obtained the Bunny Hood.
`$7EF349`	`DekuMask`	Flag indicating if the player has obtained the Deku Mask.
`$7EF34D`	`RocsFeather`	Flag indicating if the player has obtained Roc's Feather.
`$7EF352`	`StoneMask`	Flag indicating if the player has obtained the Stone Mask.
`$7EF358`	`WolfMask`	Flag indicating if the player has obtained the Wolf Mask.

3. Custom Code and Data Layout (ROM Banks)

This section details the allocation of custom code and data within the ROM banks, as defined by org directives in the project's assembly files. The order of incsrc directives in Oracle_main.asm is crucial for the final ROM layout.

Bank (Hex)	Address Range (PC)	Purpose / Contents
$20	`$208000` - `$20FFFF`	Expanded Music
$21-$27		ZScream Reserved
$28	`$288000` - `$28FFFF`	ZSCustomOverworld data and code
$29-$2A		ZScream Reserved
$2B	`$2B8000` - `$2BFFFF`	Items
$2C	`$2C8000` - `$2CFFFF`	Underworld/Dungeons
$2D	`$2D8000` - `$2DFFFF`	Menu
$2E	`$2E8000` - `$2EFFFF`	HUD
$2F	`$2F8000` - `$2FFFFF`	Expanded Message Bank
$30	`$308000` - `$30FFFF`	Sprites
$31	`$318000` - `$31FFFF`	Sprites
$32	`$328000` - `$32FFFF`	Sprites
$33	`$338000` - `$33FFFF`	Moosh Form Gfx and Palette
$34	`$348000` - `$34FFFF`	Time System, Custom Overworld Overlays, Gfx
$35	`$358000` - `$35FFFF`	Deku Link Gfx and Palette
$36	`$368000` - `$36FFFF`	Zora Link Gfx and Palette
$37	`$378000` - `$37FFFF`	Bunny Link Gfx and Palette
$38	`$388000` - `$38FFFF`	Wolf Link Gfx and Palette
$39	`$398000` - `$39FFFF`	Minish Link Gfx
$3A	`$3A8000` - `$3AFFFF`	Mask Routines, Custom Ancillae (Deku Bubble)
$3B	`$3B8000` - `$3BFFFF`	GBC Link Gfx
$3C		Unused
$3D		ZS Tile16
$3E		LW ZS Tile32
$3F		DW ZS Tile32
$40	`$408000` - `$40FFFF`	LW World Map
$41	`$418000` - `$41FFFF`	DW World Map
Patches	Various	Targeted modifications within vanilla ROM addresses

14 KiB Raw Blame History