# 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.                  | ✓        |
| `$7EF39E` | `StoryState`        | State machine for Link's House intro sequence (0-2).                     | ✓        |

#### **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.                |
| `$7EF39E` | `StoryState`      | State machine for Link's House intro sequence (0=Telepathy, 1=WakeUp, 2=End). |
| `$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    | `Core/patches.asm`, `Util/item_cheat.asm` |