scawful/oracle-of-secrets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Simplify GEMINI search heuristics

Browse Source
This commit is contained in:
scawful
2025-10-02 13:16:21 -04:00
parent 6ba634caa4
commit 55ab99d6f9
1 changed files with 106 additions and 422 deletions
Download Patch File Download Diff File Expand all files Collapse all files

526
Docs/GEMINI.md
View File

@@ -98,7 +98,7 @@ The 65816 is an 8/16-bit microprocessor used in the Super Nintendo Entertainment
## 4. Build Process and ROM Management
- **Clean ROM**: The clean, unmodified "The Legend of Zelda: A Link to the Past" ROM should be placed at `Roms/oos169.sfc`. This path is included in `.gitignore`, so the ROM file will not be committed to the repository.
- **Build Script**: A `build.sh` script is provided to automate the build process. For detailed usage, see `Docs/AsarUsage.md`.
- **Build Script**: A `build.sh` script is provided to automate the build process. For detailed usage, see `Docs/General/AsarUsage.md`.
- **Workflow**: The build script creates a fresh copy of the clean ROM and applies the `Oracle_main.asm` patch to it using `asar`.
- **Important**: Never apply patches directly to `Roms/oos169.sfc`. Always use the build script to create a new, patched ROM. This ensures the clean ROM remains untouched for future builds.
@@ -146,7 +146,7 @@ When encountering unexpected crashes (often indicated by a `BRK` instruction in
This section details the layout and purpose of critical memory regions (WRAM and SRAM) and the symbol definition files that give them context.
### 5.1. WRAM (Work RAM) Analysis
### 7.1. WRAM (Work RAM) Analysis
Work RAM (WRAM) holds the active, volatile state of the entire game. The following are some of the most critical variables for understanding real-time game logic.
@@ -164,7 +164,7 @@ Work RAM (WRAM) holds the active, volatile state of the entire game. The followi
* **Sprite and Ancilla Data (`$7E0D00+`):** `Core/symbols.asm` maps the data structures for all sprites and ancillae (projectiles, effects). Key variables include `SprState` (state machine), `SprType` (ID), `SprHealth`, and coordinates. This is fundamental to all NPC and enemy logic.
* **Oracle of Secrets Custom WRAM (`$7E0730+`):** A custom region for new features. Notable variables include `GoldstarOrHookshot` and `FishingOrPortalRod`, used to manage the state of new custom items.
### 5.2. SRAM (Save RAM) Analysis
### 7.2. SRAM (Save RAM) Analysis
SRAM stores the player's save file, including long-term progression and inventory. `Core/sram.asm` reveals significant customization for Oracle of Secrets.
@@ -181,7 +181,7 @@ This highlights the major new features of the hack.
* `Dreams` (`$7EF410`): A new collectible concept.
* **New Collectibles & Side-Quests:** A block from `$7EF38B` holds new items like `Bananas`, `Seashells`, and `Honeycomb`. `MagicBeanProg` (`$7EF39B`) tracks a new multi-day side-quest.
### 5.3. Symbols and Functions (`Core/symbols.asm`)
### 7.3. Symbols and Functions (`Core/symbols.asm`)
This file acts as a central header, defining constants and labels for memory addresses and functions to make the assembly code readable and maintainable.
@@ -193,535 +193,220 @@ This file acts as a central header, defining constants and labels for memory add
This section provides a high-level analysis of key banks in the Link to the Past disassembly. Use this guide to quickly locate relevant code and understand the overall structure of the game.
### 6.1. Bank $00: Game Core & Main Loop
### 8.1. Bank $00: Game Core & Main Loop
**File:** `ALTTP/bank_00.asm`
**Address Range:** `$008000` - `$00FFFF`
This bank is the heart of the game engine. It contains the initial `Reset` vector, the main game loop, interrupt handlers, and the primary game state machine.
**Summary:** The heart of the game engine. Contains the main game loop, interrupt handlers, and the primary game state machine.
#### Key Structures & Routines:
* **`Reset:` (#_008000)**: The entry point of the game on boot. It initializes hardware registers, memory, and SRAM before jumping into the main game logic.
* **`MainGameLoop:` (#_008034)**: The central loop of the game. It waits for the NMI flag (`$12`) to be set, then calls `Module_MainRouting` to execute the logic for the current game state.
* **`Module_MainRouting:` (#_0080B5)**: This is the game's primary state machine. It reads the main game state index from `$10` and uses a jump table (`pool Module_MainRouting`) to jump to the appropriate module's logic. Understanding this table is key to understanding the game's flow.
* **Game State Index:** Stored in WRAM at `$7E0010`.
* **Example States:** `Module07_Underworld`, `Module09_Overworld`, `Module01_FileSelect`, etc.
* **`Interrupt_NMI:` (#_0080C9)**: The Non-Maskable Interrupt handler. This runs every V-Blank (once per frame). It's responsible for:
* Handling music and sound effect updates.
* Reading joypad input (`NMI_ReadJoypads`).
* Calling `NMI_DoUpdates` to perform DMA transfers for graphics (backgrounds and sprites).
* Preparing sprite OAM data (`NMI_PrepareSprites`).
* **`InitializeMemoryAndSRAM:` (#_0087C0)**: Clears WRAM and validates the three SRAM save files by checking for a magic number (`$55AA`).
* **`SaveGameFile:` (#_00894A)**: Handles the logic for saving game progress to the correct SRAM slot.
* **`Reset:` (#_008000)**: Game entry point on boot.
* **`MainGameLoop:` (#_008034)**: Central loop, calls `Module_MainRouting`.
* **`Module_MainRouting:` (#_0080B5)**: Primary state machine dispatcher. Reads `MODE` (`$7E0010`) and uses `pool Module_MainRouting` to jump to the correct game module.
* **`Interrupt_NMI:` (#_0080C9)**: Runs every frame. Handles input (`NMI_ReadJoypads`), graphics DMA (`NMI_DoUpdates`), and sprite preparation (`NMI_PrepareSprites`).
#### Search Heuristics:
* **Game Module Logic (Overworld, Underworld, Menus):** Search `bank_00.asm` for the `pool Module_MainRouting` jump table. The labels (e.g., `Module09_Overworld`) are the entry points for each game state, determined by WRAM `$7E0010` (`MODE`).
* **Per-Frame Logic:** Search `bank_00.asm` for `Interrupt_NMI:`. Key routines called from here are `NMI_ReadJoypads` (input) and `NMI_DoUpdates` (graphics DMA).
* **Initialization Logic:** Start at the `Reset:` label in `bank_00.asm` and trace `JSR`/`JSL` calls to routines like `InitializeMemoryAndSRAM`.
* **To find game state logic:**
1. Identify the game state you're interested in (e.g., "playing in the overworld", "in the file select screen").
2. Search `bank_00.asm` for the `pool Module_MainRouting` table.
3. Find the corresponding module label (e.g., `Module09_Overworld`, `Module01_FileSelect`). This label is the entry point for that game state's main logic.
* **To find per-frame update logic:**
1. Look inside the `Interrupt_NMI` routine in `bank_00.asm`.
2. Follow the calls to `NMI_DoUpdates` for graphics DMA, `NMI_ReadJoypads` for input, and the audio update logic at the start of the NMI.
* **To find core initialization code:**
1. Start at the `Reset:` label in `bank_00.asm`.
2. Follow the `JSR`/`JSL` calls to see how memory, SRAM, and hardware are configured.
### 6.2. Bank $01: Dungeon Engine
### 8.2. Bank $01: Dungeon Engine
**File:** `ALTTP/bank_01.asm`
**Address Range:** `$018000` - `$01FFFF`
This bank contains the engine responsible for loading, drawing, and managing all aspects of interior rooms (dungeons, houses, caves).
**Summary:** Responsible for loading, drawing, and managing all aspects of interior rooms (dungeons, houses, caves).
#### Key Structures & Routines:
* **`Underworld_LoadRoom:` (#_01873A)**: The main entry point for loading a dungeon room. It orchestrates a sequence of operations to build the room from its component parts.
* **Room Object Data:** The core of the dungeon engine is a set of tables that define how to draw room objects. The process is hierarchical:
1. **Room Header:** Contains pointers to lists of objects. `RoomData_ObjectDataPointers` points to this data for each room.
2. **Object Definition:** Each object in the list has a type and position. The type determines which drawing routine to use.
3. **`DrawObjects` Tables:** Located at the top of `bank_01.asm`, these tables are indexed by object ID and contain pointers to the object's raw tile data (`.type1_subtype_1_data_offset`) and the routine used to draw it (`.type1_subtype_1_routine`).
* **`RoomDraw_DrawAllObjects:` (#_0188E4)**: Iterates through a list of objects for the current room and calls `RoomDraw_RoomObject` for each one.
* **`RoomDraw_RoomObject:` (#_01893C)**: The main dispatcher for drawing a single object. It reads the object's ID, looks up the corresponding data and drawing routine in the `DrawObjects` tables, and executes it.
* **`RoomDraw_DrawFloors:` (#_0189DC)**: Handles the drawing of the room's floor tilemap before objects are drawn.
* **Doors:** Doors are a special object type handled by `RoomDraw_DoorObject` (#_018916), which uses the `DoorDrawRoutines` jump table.
* **`Underworld_LoadRoom:` (#_01873A)**: Main entry point for loading a dungeon room.
* **`DrawObjects` Tables:** A set of tables at the top of the bank defining object graphics and drawing routines.
* **`RoomDraw_DrawAllObjects:` (#_0188E4)**: Iterates through a room's object list.
* **`RoomDraw_RoomObject:` (#_01893C)**: Main dispatcher for drawing a single object based on its ID.
#### Search Heuristics:
* **Room Construction Logic:** In `bank_01.asm`, start at `Underworld_LoadRoom` and trace the call sequence: `Underworld_LoadHeader` -> `RoomDraw_DrawFloors` -> `RoomDraw_DrawAllObjects`.
* **Specific Dungeon Object Code:** To find an object's drawing code, search the `.type1_subtype_..._routine` tables at the start of `bank_01.asm` for the object's ID. The corresponding label is the drawing routine. To find its tile data, search the `.type1_subtype_..._data_offset` tables.
* **To understand how a dungeon room is constructed:**
1. Start at `Underworld_LoadRoom` in `bank_01.asm`.
2. Follow the sequence of calls: `Underworld_LoadHeader` -> `RoomDraw_DrawFloors` -> `RoomDraw_DrawAllObjects`.
* **To find the code for a specific dungeon object (e.g., a pushable block, a torch):**
1. Determine the object's ID.
2. Search the `.type1_subtype_..._data_offset` tables at the beginning of `bank_01.asm` for the object ID comment (e.g., `; 094 -`).
3. The label on that line (e.g., `obj0288-RoomDrawObjectData`) points to the object's tile data.
4. Look at the corresponding entry in the `.type1_subtype_..._routine` table to find the drawing routine (e.g., `RoomDraw_DownwardsFloor4x4_1to16`).
* **To modify an object's appearance:** Find its data offset label (e.g., `obj0288`) and locate that data block within `bank_01.asm` to see the raw tilemap data.
### 6.3. Bank $02: Overworld & Transitions
### 8.3. Bank $02: Overworld & Transitions
**File:** `ALTTP/bank_02.asm`
**Address Range:** `$028000` - `$02FFFF`
This bank manages loading the overworld, transitioning between areas (e.g., underworld to overworld), and handling special game sequences like the intro and credits.
**Summary:** Manages loading the overworld, transitioning between areas, and handling special game sequences.
#### Key Structures & Routines:
* **`Module05_LoadFile:` (#_028136)**: Handles the initial loading of a save file. It sets up default graphics, initializes Link's state, and determines whether to start in the light world or dark world, or to trigger a special scene.
* **`Module06_UnderworldLoad:` (#_02821E)**: The primary module for transitioning into and loading a new underworld room. It loads the room entrance data, draws the room via `Underworld_LoadAndDrawRoom`, loads palettes, and initializes sprites.
* **`Module08_OverworldLoad:` (#_0283BF)**: The primary module for loading the overworld. It determines which music and palettes to load based on the overworld area (`$8A`) and player status.
* **`Module07_Underworld:` (#_0287A2)**: The main logic loop for when the player is in the underworld. It calls submodules based on the player's state (`$11`), such as normal player control (`Module07_00_PlayerControl`), screen transitions, or other room events.
* **`Overworld_LoadAllPalettes_long:` (#_02811A)**: A key routine for loading the correct overworld palettes based on the current screen and game events.
* **Transitions:** The bank is filled with logic for handling transitions.
* `LoadOverworldFromUnderworld`: Called by `Module08_OverworldLoad` to set up the overworld when exiting a cave or dungeon.
* `Underworld_TryScreenEdgeTransition`: Checks if Link is at the edge of a screen and initiates a room transition if so.
* **`Module06_UnderworldLoad:` (#_02821E)**: Primary module for transitioning into and loading an underworld room.
* **`Module08_OverworldLoad:` (#_0283BF)**: Primary module for loading the overworld.
* **`Module07_Underworld:` (#_0287A2)**: Main logic loop for when the player is in the underworld. Dispatches to submodules based on WRAM `$11`.
#### Search Heuristics:
* **Overworld Loading:** Start at `Module08_OverworldLoad` in `bank_02.asm`. Logic checks WRAM `$8A` (overworld area number) to determine behavior.
* **Underworld Gameplay:** Start at `Module07_Underworld` in `bank_02.asm`. Examine the `.submodules` jump table to see the different states, determined by WRAM `$11`.
* **Transition Logic:** Search for code that sets the game `MODE` (`$10`) to `$08` (Overworld Load) or `$06` (Underworld Load) to find the start of a transition.
* **To find overworld loading logic:**
1. Start at `Module08_OverworldLoad` in `bank_02.asm`.
2. Examine the logic that checks the overworld area number (`$8A`) to see how different areas are handled.
* **To find underworld gameplay logic:**
1. Start at `Module07_Underworld` in `bank_02.asm`.
2. Examine the `.submodules` jump table to see the different underworld states (player control, transitions, etc.). The value in `$11` determines which state is active.
* **To trace a transition (e.g., cave exit):**
1. Find the code that sets the game module to `$08` (Overworld Load).
2. Look in `Module08_OverworldLoad` and follow the call to `LoadOverworldFromUnderworld`. This will show how screen data, palettes, and sprites are loaded for the overworld.
* **To find palette loading code:** Search for `JSR`/`JSL` calls to `Overworld_LoadAllPalettes`, `Underworld_LoadPalettes`, or `OverworldPalettesLoader`. The code leading up to these calls will determine *which* palettes are loaded.
### 8.4. Bank $03: Tile32 Overworld Layout Data
### 6.3.1. Bank $03: Tile32 Overworld Layout Data
### 8.5. Bank $04: Tile32 Overworld Layout Data, Dungeon Room Headers
### 6.3.2. Bank $04: Tile32 Overworld Layout Data, Dungeon Room Headers
### 6.4. Bank $07: Core Player (Link) Engine
### 8.6. Bank $07: Core Player (Link) Engine
**File:** `ALTTP/bank_07.asm`
**Address Range:** `$078000` - `$07FFFF`
This bank is dedicated entirely to the player character, Link. It contains his core state machine, which governs everything from movement and physics to item usage and interaction with the world.
**Summary:** Contains Link's core state machine, governing movement, physics, item usage, and interactions.
#### Key Structures & Routines:
* **`Link_Main:` (#_078000)**: The top-level entry point for all player logic, called every frame. Its primary job is to call the main state machine handler.
* **`Link_ControlHandler:` (#_07807F)**: The heart of the player engine. This routine functions as a state machine dispatcher.
* **Critical WRAM:** It reads Link's current state from `$7E005D` (`LINKDO`). Changing this value will force Link into a different state.
* **Jump Table:** It uses the value of `LINKDO` to index a jump table (`pool Link_ControlHandler`) and execute the code for the current state.
* **Player States (`LinkState_...`):** The bank is composed of many routines, each handling a specific state. Key states include:
* **`LinkState_Default` (#_078109):** The most common state. It handles walking, stopping, reading joypad input, and dispatching to sub-handlers for actions like `Link_HandleAPress` (talking, lifting), `Link_HandleYItem` (using items), and sword attacks.
* **`LinkState_Recoil` (#_0786B5):** Manages the knockback sequence when Link takes damage. It's a timer-based state that temporarily removes player control.
* **`LinkState_Dashing` (#_078063):** Handles the physics and animation for running with the Pegasus Boots.
* **`LinkState_Swimming` (#_078049):** Manages movement and actions while in the water.
* **`LinkState_Bunny` (#_0783A1):** A simplified state with restricted actions for when Link is a bunny. It also contains the logic to transform back.
* **`LinkState_ShowingOffItem` (#_07806B):** The "item get" pose, which temporarily freezes Link to show the player a new item.
* **`Link_Main:` (#_078000)**: Top-level entry point for all player logic.
* **`Link_ControlHandler:` (#_07807F)**: The heart of the player engine. A state machine dispatcher that reads `LINKDO` (`$7E005D`) and jumps via the `pool Link_ControlHandler` table.
* **`LinkState_Default` (#_078109):** The most common state, handling walking and dispatching to action sub-handlers like `Link_HandleYItem`.
#### Search Heuristics:
* **Player Action Logic (walking, swimming):** In `bank_07.asm`, search for `pool Link_ControlHandler`. The state ID is from WRAM `$7E005D` (`LINKDO`). Find the label for the desired state (e.g., `LinkState_Default`) to locate its main routine.
* **Player Physics/Collision:** Within a player state routine, search for calls to `JSL Link_HandleVelocity` (physics) and `JSR Link_HandleCardinalCollision` (collision).
* **Y-Button Item Logic:** In `LinkState_Default`, search for the call to `JSR Link_HandleYItem`.
* **Player Damage Logic:** Search for writes to WRAM `$7E0373` (`HURTME`).
* **To modify any core player action (walking, swimming, dashing):**
1. Find the corresponding state ID in the `pool Link_ControlHandler` jump table in `bank_07.asm`.
2. Go to the routine for that state (e.g., `LinkState_Default`, `LinkState_Swimming`).
3. Within that routine, look for calls to physics and collision handlers like `JSL Link_HandleVelocity` or `JSR Link_HandleCardinalCollision`.
* **To change how an item is used:**
1. Start in `LinkState_Default` and find the call to `JSR Link_HandleYItem`. This routine is the dispatcher for all Y-button items.
* **To add a new player state:**
1. Find an unused state ID (or create a new one).
2. Write a new `LinkState_...` routine to handle the logic for your new state.
3. Find the code that should trigger your new state and have it write the new state ID to `$7E005D` (`LINKDO`).
* **To find where Link takes damage:** Search for code that writes a non-zero value to `$7E0373` (`HURTME`). The `Link_ControlHandler` will detect this at the start of the next frame and initiate the recoil state.
### 6.5. Bank $05: Specialized Sprite & Object Engine
### 8.7. Bank $05: Specialized Sprite & Object Engine
**File:** `ALTTP/bank_05.asm`
**Address Range:** `$058000` - `$05FFFF`
This bank is a collection of code for unique, complex, and specialized sprites that do not fit the mold of standard, reusable enemy AI. If a sprite has a very specific, scripted, or multi-part behavior, its logic is likely located here.
#### Key Sprite Categories & Examples:
* **Cutscene & Event Sprites:** These handle one-off story moments.
* `Sprite_62_MasterSword` (`#_0588C5`): Manages the entire Master Sword pedestal cutscene, including spawning the circling pendants, the light beams, and giving the item to the player.
* **Minigame Sprites:** Contains the logic for entire minigames.
* `Sprite_65_ArcheryGame` (`#_0581FF`): Controls the archery minigame host, the moving targets, and the prize logic.
* **Complex Environmental Sprites (Traps):**
* `Sprite_66_WallCannon...` (`#_058090`): The logic for wall-mounted cannons that fire projectiles in a set pattern.
* `Sprite_63_DebirandoPit` (`#_058531`): A sentient whirlpool/pit that attempts to drag Link in.
* **Complex Enemy Sprites:**
* `Sprite_64_Debirando` (`#_05874D`): The monster that emerges from the Debirando Pit.
* **Garnish & Effects:**
* `Sprite_SpawnSparkleGarnish` (`#_058008`): A function to spawn decorative sparkles around another sprite, often used for emphasis.
**Summary:** Code for unique, complex, and scripted sprites that do not fit the standard enemy AI model (e.g., cutscene sprites, minigame hosts, complex traps).
#### Search Heuristics:
* **Unique/Non-Enemy Sprites:** When looking for a unique sprite (minigame, cutscene object, complex trap), check `bank_05.asm` first.
* **Finding Sprite Logic:** Search for the sprite's name (e.g., "MasterSword") or its hexadecimal ID (e.g., `Sprite_62`) to find its main routine.
* When looking for the code for a unique, non-enemy sprite (like an NPC in a minigame, a cutscene object, or a complex trap), **check `bank_05.asm` first.**
* Search for the sprite's name (e.g., "MasterSword", "ArcheryGame") or its hexadecimal ID (e.g., `Sprite_62`, `Sprite_65`) to find its main routine.
* The code in this bank often involves state machines (`SprAction, X`) and timers (`SprTimerA, X`) to manage complex sequences of actions.
### 6.6. Bank $06: Main Sprite Engine & Helpers
### 8.8. Bank $06: Main Sprite Engine & Helpers
**File:** `ALTTP/bank_06.asm`
**Address Range:** `$068000` - `$06FFFF`
This bank is arguably the most important for understanding enemy and object behavior, as it contains the **main sprite processing engine**. It also houses a vast library of shared subroutines used by sprites across the entire game.
**Summary:** Contains the main sprite processing engine and a vast library of shared helper subroutines used by sprites game-wide.
#### Key Structures & Routines:
* **`Sprite_Main:` (#_068328)**: This is the master sprite loop, called once per game frame. It iterates through all 16 sprite slots (from 15 down to 0), calling `Sprite_ExecuteSingle` for each one to process its logic.
* **`Sprite_ExecuteSingle:` (#_0684E2)**: The state machine dispatcher for an individual sprite. It reads the sprite's current state from `$7E0DD0,X` (`SprState`) and uses a jump table to execute the appropriate logic (e.g., `SpriteModule_Active`, `SpriteModule_Die`, `SpriteModule_Stunned`).
* **`SpriteModule_Initialize:` (#_06864D)**: This is the master initialization routine. When a sprite is first spawned (state `0x08`), this function is called. It contains a massive jump table that points to a specific `SpritePrep_...` routine for nearly every sprite type. This is where a sprite's unique properties like HP, damage, speed, and prize drops are configured.
* **`SpriteModule_Active:`:** This routine (called from the `Sprite_ExecuteSingle` jump table) is the entry point for a sprite's main AI. It typically contains another jump table indexed by the sprite's ID (`$7E0E20,X`, `SprType`) that leads to the actual AI code (which may be in this bank or another).
* **Helper & Utility Functions:** This bank is filled with common routines that sprites call via `JSR`/`JSL`.
* `Sprite_SpawnSecret` (`#_068264`): A crucial routine that determines the "secret" item that appears when you lift a bush or rock. It contains data tables for different prize packs.
* `Sprite_SpawnThrowableTerrain` (`#_06814B`): Spawns a liftable object (bush, rock) sprite.
* `CheckIfHitBoxesOverlap` (`#_0683E6`): A generic function to check for collision between two entities.
* `Sprite_TimersAndOAM` (`#_0683F2`): Handles decrementing sprite timers and allocating OAM slots for drawing.
* **`Sprite_Main:` (#_068328)**: The master sprite loop that iterates through all 16 sprite slots.
* **`Sprite_ExecuteSingle:` (#_0684E2)**: The state machine dispatcher for an individual sprite, reading `SprState` (`$7E0DD0,X`).
* **`SpriteModule_Initialize:` (#_06864D)**: Master initialization routine. Contains a massive jump table pointing to a specific `SpritePrep_...` routine for nearly every sprite type.
* **`Sprite_SpawnSecret` (`#_068264`):** Determines the "secret" item that appears under a liftable bush or rock.
#### Search Heuristics:
* **Sprite Initialization (HP, damage, etc.):** In `bank_06.asm`, go to `SpriteModule_Initialize`. Find the sprite's ID in the large jump table to get the label for its `SpritePrep_...` routine.
* **Sprite Core AI:** In `bank_06.asm`, go to `SpriteModule_Active`. Find the sprite's ID in its jump table to find the entry point to its main AI logic (which may be in another bank).
* **Bush/Rock Item Drops:** Locate the `Sprite_SpawnSecret` routine and examine the `.ID` table at `#_0681F4` to see the prize mappings.
* **To find any sprite's core AI:**
1. Find the sprite's ID (e.g., `0x6D` for a Rat).
2. Go to the `SpriteModule_Active` routine in this bank. You will likely find a jump table there.
3. Find the entry in the table corresponding to the sprite's ID. This will jump to the sprite's main AI logic, which could be in Bank $06 or another bank entirely.
* **To find how a sprite is initialized (HP, damage, etc.):**
1. Find the sprite's ID.
2. Go to the `SpriteModule_Initialize` routine in this bank.
3. Find the sprite's ID in the large jump table to get the label for its `SpritePrep_...` routine. The code at that label sets the initial properties.
* **To change what items drop from bushes/rocks:**
1. Locate the `Sprite_SpawnSecret` routine.
2. Examine the `.ID` table (`#_0681F4`) which maps a prize index to a sprite ID (e.g., Green Rupee, Heart, Bee). Modifying this table will change the drops.
### 8.9. Bank $08: Ancilla Engine
**File:** `ALTTP/bank_08.asm`
**Address Range:** `$088000` - `$08FFFF`
**Summary:** The engine for "Ancillae" (projectiles, particle effects, etc.). Contains the execution logic for entities like arrows, bombs, and magic spells.
### 6.7. Bank $08: Ancilla Engine
**File:** `ALTTP/bank_08.asm`
**Address Range:** `$088000` - `$08FFFF`
**Description:** This bank is the engine for "Ancillae" (from ancillary). Ancillae are temporary, non-sprite objects, which are typically projectiles, particle effects, or other spawned entities. This includes
everything from Link's sword beam and arrows to bomb explosions and magic spell effects.
#### Key Structures & Routines:
* **`Ancilla_Main:` (#_088242)**: The top-level entry point for the ancilla engine, called once per frame from `Sprite_Main`.
* **`Ancilla_ExecuteAll:` (#_08832B)**: The main loop for the engine. It iterates through all available ancilla slots and calls `Ancilla_ExecuteOne` for each active ancilla.
* **`Ancilla_ExecuteOne:` (#_08833C)**: The core dispatcher for a single ancilla. It reads the ancilla's type ID from WRAM (`$7E0C4A,X`, `AnciType`) and uses it as an index into a large jump
table (`.vectors` at `#_08837F`) to execute the logic for that specific type. This is the state machine for all projectiles and effects.
* **Ancilla Logic Routines (`AncillaXX_...`):** The bulk of the bank consists of the individual routines for each ancilla type, for example:
* `Ancilla02_FireRodShot`
* `Ancilla05_Boomerang`
* `Ancilla07_Bomb`
* `Ancilla09_Arrow`
* `Ancilla18_EtherSpell`
* **Spawning Routines (`AncillaAdd_...`):** This bank contains many of the functions used to create new ancillae. These are called from other banks (e.g., Bank $07 when Link uses an item).
Examples include:
`AncillaAdd_FireRodShot` (`#_0880B3`)
* `AncillaAdd_IceRodSparkle` (`#_0884C8`)
* `AncillaAdd_Bomb` (`#_0884D0`)
* `AncillaAdd_Arrow` (`#_0884D8`)
#### Search Heuristics:
* **Projectile/Effect Logic:** In `bank_08.asm`, find the main jump table in `Ancilla_ExecuteOne` (at `#_08837F`). Look up the ancilla's ID in this table to find the label for its logic routine (e.g., `Ancilla07_Bomb`).
* **Projectile Properties (speed, graphics):** Go to the ancilla's main logic routine (e.g., `Ancilla09_Arrow`) and look for writes to its WRAM properties (e.g., `$0C2C` for X-speed).
* **To find the logic for a specific projectile or effect:**
1. Determine the ancilla's ID (e.g., from the `AncillaObjectAllocation` table at `#_08806F`).
2. Find the main jump table in `Ancilla_ExecuteOne` (at `#_08837F`).
3. Look up the ancilla ID in the table to find the label for its logic routine (e.g., `Ancilla07_Bomb`).
* **To find where a projectile is created:** Search the codebase for `JSL` calls to its corresponding `AncillaAdd_...` function (e.g., search for `AncillaAdd_Bomb` to see where bombs are
spawned).
* **To change the properties of a projectile (speed, graphics, etc.):** Go to its main logic routine (e.g., `Ancilla09_Arrow`) and look for where it sets its WRAM properties (`$0C2C` for
X-speed, `$0C22` for Y-speed, etc.).
### 6.8. Bank $09: Ancilla Spawning & Item Logic
### 8.10. Bank $09: Ancilla Spawning & Item Logic
**File:** `ALTTP/bank_09.asm`
**Address Range:** `$098000` - `$09FFFF`
While Bank $08 contains the ancilla *execution* engine, Bank $09 contains the ancilla *creation* engine. This bank is a library of `AncillaAdd_...` functions that are called from all over the codebase to spawn projectiles and effects. It also handles the critical logic for giving items to the player.
#### Key Structures & Routines:
* **Ancilla Spawning Functions (`AncillaAdd_...`):** This bank is primarily composed of these routines. Each one is responsible for finding an empty ancilla slot and initializing it with the correct properties for that type.
* `AncillaAdd_Bomb` (`#_09811F`)
* `AncillaAdd_Boomerang` (`#_09820F`)
* `AncillaAdd_HitStars` (`#_098024`)
* **`AncillaAdd_ItemReceipt` (`#_0985E8`):** This is one of the most complex and important routines in the bank. It handles the entire process of giving an item to the player.
* It takes an item ID from `$02D8`.
* It looks up the item's properties (SRAM address, value to write, etc.) in a series of large tables.
* It writes the new value to the appropriate SRAM address to save the player's new item.
* It handles special cases for pendants, crystals, mail upgrades, and heart pieces.
* It calls `RefreshIcon_long` to update the HUD.
**Summary:** Contains the ancilla *creation* engine (a library of `AncillaAdd_...` functions) and the critical logic for giving items to the player.
#### Search Heuristics:
* **Projectile/Effect Creation:** To find where a projectile is created, search the codebase for `JSL` calls to its corresponding `AncillaAdd_...` function in this bank (e.g., `JSL AncillaAdd_Bomb`).
* **Item "Get" Properties:** To change the properties of an item the player receives, find the `AncillaAdd_ItemReceipt` routine and examine the large data tables starting at `#_098404`.
* **To find where any projectile or effect is created:** Search the codebase for a `JSL` to its corresponding `AncillaAdd_...` routine in this bank. For example, to see what spawns bombs, search for `JSL AncillaAdd_Bomb`.
* **To change the properties of an item received by the player:**
1. Find the `AncillaAdd_ItemReceipt` routine.
2. Examine the large data tables starting at `#_098404`. These tables define everything about each obtainable item, including its graphics, its corresponding SRAM flag, and the value to write. Modifying these tables is the correct way to change item properties.
### 6.9. Bank $0A: World Map & Flute Menu Engine
### 8.11. Bank $0A: World Map & Flute Menu Engine
**File:** `ALTTP/bank_0A.asm`
**Address Range:** `$0A8000` - `$0AFFFF`
This bank controls all full-screen map interfaces, including the overworld map viewable from the pause menu and the 8-point destination map used when playing the flute.
#### Key Structures & Routines:
* **`Module0E_0A_FluteMenu` (`#_0AB730`):** The state machine for the flute destination selection menu. It handles loading the map graphics, drawing the numbered destination icons, processing player input to select a location, and initiating the duck transport sequence.
* **`Module0E_07_OverworldMap` (`#_0AB98B`):** The state machine for the main overworld map screen. It handles player input for zooming in/out and panning the map.
* **Mode 7 Graphics:** This bank makes heavy use of Mode 7 for rendering the world map. Routines like `WorldMap_LoadLightWorldMap` and `WorldMap_SetUpHDMA` are responsible for loading the map tile data and configuring the HDMA channels to perform the Mode 7 scaling and rotation effects.
* **Map Icon Data:** The bank contains large tables of coordinates (`WorldMapIcon_posx_spr0`, etc.) that define where to draw the blinking squares and boss icons for each dungeon and story location on the map.
**Summary:** Controls all full-screen map interfaces (pause menu map, flute destination map).
#### Search Heuristics:
* **Flute Warp Destinations:** In `bank_0A.asm`, find the `FluteMenu_LoadTransport` routine. The table within it maps the 8 flute spots to screen indexes.
* **Map Icon Locations:** Search for the `WorldMapIcon_posx_...` and `WorldMapIcon_posy_...` tables to adjust icon coordinates.
* **To change the flute warp destinations:**
1. Find the `FluteMenu_LoadSelectedScreen` routine.
2. This routine calls `FluteMenu_LoadTransport`, which contains a table of the screen indexes for each of the 8 flute spots. Modifying this table changes where the duck takes you.
* **To change the location of map icons:** Find the `WorldMapIcon_posx_...` and `WorldMapIcon_posy_...` tables and adjust the coordinates for the desired icon.
* **To modify map rendering:** Look at the `WorldMap_SetUpHDMA` routine and the `WorldMapHDMA_...` tables to understand how the Mode 7 background layers are configured.
### 6.10. Bank $0B: Overworld Environment & State Helpers
### 8.12. Bank $0B: Overworld Environment & State Helpers
**File:** `ALTTP/bank_0B.asm`
**Address Range:** `$0B8000` - `$0BFFFF`
This is a smaller, miscellaneous bank containing important helper functions related to the overworld environment and player state transitions.
#### Key Structures & Routines:
* **`Overworld_SetFixedColAndScroll` (`#_0BFE70`):** This crucial routine is called when loading an overworld screen. It sets the main background color (`$7EC500`) and fixed color (`$9C`) based on the current area. It contains a series of checks to determine the correct palette (e.g., normal, Dark World, Death Mountain, Lost Woods).
* **`WallMaster_SendPlayerToLastEntrance` (`#_0BFFB7`):** This function is called when a Wall Master captures Link. It resets Link's state and moves him back to the entrance of the dungeon.
* **`ResetSomeThingsAfterDeath` (`#_0BFFBF`)::** A helper function called after dying to clear various temporary player state variables.
**Summary:** Miscellaneous helper functions related to the overworld environment and player state.
#### Search Heuristics:
* **Overworld Area Palette:** To change the background color of an overworld area, modify the color values loaded in `Overworld_SetFixedColAndScroll`. The logic checks WRAM `$8A` to decide which color to use.
* **Wall Master Capture:** To change what happens when captured, find the `WallMaster_SendPlayerToLastEntrance` routine.
* **To change the background color of an overworld area:** Modify the color values loaded in `Overworld_SetFixedColAndScroll`. The logic checks the overworld area ID in `$8A` to decide which color to use.
* **To change what happens when captured by a Wall Master:** Find the `WallMaster_SendPlayerToLastEntrance` routine. This is the entry point for that entire sequence.
### 6.11. Bank $0C: Intro & Credits Sequence
### 8.13. Bank $0C: Intro & Credits Sequence
**File:** `ALTTP/bank_0C.asm`
**Address Range:** `$0C8000` - `$0CFFFF`
This bank is dedicated to handling the game's pre-gameplay sequences: the entire introduction from boot-up to the title screen, and the end-game credits.
#### Key Structures & Routines:
* **`Module00_Intro` (`#_0CC120`):** The main entry point for the entire intro sequence, called from the master game state machine in Bank $00. This routine itself acts as a state machine, using the sub-mode variable `$11` to step through the sequence.
* **Intro Sequence:** The intro is a multi-step process orchestrated by the `Module00_Intro` jump table:
1. **Initialization:** `Intro_InitialInitialization` and `Intro_InitializeMemory` set up the screen and clear memory.
2. **Triforce Animation:** `Intro_InitializeTriforcePolyThread` and `Intro_HandleAllTriforceAnimations` manage the pseudo-3D spinning Triforce effect. This uses a special "polyhedral" engine that runs on an IRQ thread.
3. **Logo & Title:** `Intro_FadeLogoIn` displays the Nintendo logo, followed by `Intro_SwordStab` and `Intro_PopSubtitleCard` which handle the iconic "The Legend of Zelda" title and the sword animation.
4. **Transition:** The sequence ends by setting the main game mode (`$10`) to `0x14` (Attract Mode) to start the gameplay demos.
* **Credits:** The bank also contains code for the credits sequence (`Credits_InitializePolyhedral`), which reuses some of the Triforce animation logic from the intro.
**Summary:** Handles the game's intro and end-game credits sequences.
#### Search Heuristics:
* **Intro/Credits Scene Logic:** Start at the `Module00_Intro` or `Module1A_Credits` jump tables. The sub-mode in WRAM `$11` determines which part of the sequence is running. Follow the jump table to the routine for the scene you want to change.
* **To modify any part of the game's opening cutscene:**
1. Start at the `Module00_Intro` jump table in `bank_0C.asm`.
2. The sub-mode in `$11` determines which part of the sequence is currently running. Follow the jump table to the routine for the part you want to change (e.g., `Intro_FadeLogoIn`).
* **To change the timing of the intro sequence:** Look for the code that increments the sub-mode (`INC.b $11`). This is usually at the end of a state's logic (e.g., after a fade is complete). Changing when this happens will alter the pacing.
* **To investigate the 3D Triforce effect:** Look at `TriforceInitializePolyhedralModule` and `Intro_AnimateTriforce`. This is complex code that interacts with IRQs and likely involves custom DMA to achieve the effect.
### 6.12. Bank $0D: Link Animation & OAM Data
### 8.14. Bank $0D: Link Animation & OAM Data
**File:** `ALTTP/bank_0D.asm`
**Address Range:** `$0D8000` - `$0DFFFF`
This bank is not an engine with executable code, but rather a massive **graphical database** that defines every frame of Link's animation. The `LinkOAM_Main` routine (in Bank $00) reads from these tables every frame to construct Link's complete sprite from his body, head, shield, and weapon.
#### Key Structures & Routines:
This bank is almost entirely composed of large data tables.
* **`LinkOAM_AnimationSteps` (`#_0D85FB`):** This is the master animation sequencer. It contains lists of frame indices for every action Link can perform (walking, running, swimming, lifting, swinging the sword, etc.), separated by direction.
* **`LinkOAM_PoseData` (`#_0D8000`):** This table is indexed by the values from `LinkOAM_AnimationSteps`. Each entry defines a single animation frame, specifying which body parts to use and how to orient them (e.g., which head sprite, which body sprite, and flip properties).
* **Equipment Tile Tables (`LinkOAM_WeaponTiles`, `LinkOAM_ShieldTiles`):** These tables map animation frames to the specific graphics tiles used for the sword, shield, and other items Link can hold.
* **Equipment Offset Tables (`LinkOAM_SwordOffsetX/Y`, `LinkOAM_ShieldOffsetX/Y`, etc.):** These tables are crucial for positioning. For every frame of animation, they provide the precise X and Y offsets needed to draw the sword and shield relative to Link's body, creating the illusion that he is holding them correctly.
* **`LinkOAM_ShadowTiles` (`#_0D85CF`):** Defines the graphics for Link's shadow and related effects like water splashes and tall grass movement.
**Summary:** A massive graphical database defining every frame of Link's animation. It is not executable code.
#### Search Heuristics:
* **Link's Animation Sequence:** To modify an animation, find the action in `LinkOAM_AnimationSteps`. The values are indices into the `LinkOAM_PoseData` table, which defines the body parts for each frame.
* **Link's Item Positioning:** To change how Link holds an item, find the animation frame index in `LinkOAM_AnimationSteps` and use it to find the corresponding entries in the `LinkOAM_SwordOffsetX/Y` or `LinkOAM_ShieldOffsetX/Y` tables.
* **To modify Link's appearance or animation:**
1. Identify the action you want to change (e.g., the walking animation).
2. Find the corresponding sequence in `LinkOAM_AnimationSteps`. The values are indices.
3. Use those indices to look up the frames in `LinkOAM_PoseData`. Modifying the values here will change which body parts are used for that frame.
* **To change how Link holds his sword:**
1. Identify the animation frame you want to adjust (e.g., the third frame of the upward sword swing).
2. Find the index for that frame in the `LinkOAM_AnimationSteps` table.
3. Use that index to find the corresponding entries in the `LinkOAM_SwordOffsetX` and `LinkOAM_SwordOffsetY` tables. Changing these values will move where the sword is drawn for that frame.
* **To change the graphics of the Master Sword itself:** Find the `LinkOAM_WeaponTiles` table. This table points to the actual tile numbers for the sword's graphics for each frame.
### 6.13. Bank $0E: Tile Properties & Credits Engine
### 8.15. Bank $0E: Tile Properties & Credits Engine
**File:** `ALTTP/bank_0E.asm`
**Address Range:** `$0E8000` - `$0EFFFF`
This bank has two primary, unrelated functions. It serves as a data repository for fundamental game assets (font, tile properties), and it contains the entire engine for the end-game credits sequence.
#### Key Structures & Routines:
* **Game Font:**
* `TheFont` (`#_0E8000`): This is the raw 2bpp graphical data for the game's main font, included as a binary file.
* **Tile Property Tables:** These tables are critical for world interaction. They define the physical behavior of every map tile in the game.
* `OverworldTileTypes` (`#_0E9459`): A large table where each byte corresponds to a 16x16 map tile and defines its properties (e.g., solid, water, grass, pit, ledge).
* `UnderworldTileTypes` (`#_0E9659`): The equivalent table for all dungeon tilesets.
* `Underworld_LoadCustomTileTypes` (`#_0E942A`): A function that loads alternate sets of tile properties for dungeons that have unique behaviors (e.g., ice physics).
* **Credits Sequence Engine:**
* `Module1A_Credits` (`#_0E986E`): The main entry point for the credits, called from the master game state machine. It functions as a state machine, using the sub-mode in `$11` to step through the entire credits sequence.
* **Sequence Data:** The routine uses a series of large tables to define each scene in the credits:
* `.vectors`: A jump table for the logic of each scene (e.g., `Credits_LoadNextScene_Overworld`, `Credits_ScrollScene_Underworld`).
* `Credits_ScrollScene.target_y/x`: Defines the target camera coordinates for each scene's scrolling motion.
* `Credits_PrepAndLoadSprites.vectors`: A jump table that points to sprite-loading routines for each scene, which in turn use position tables to place each character.
**Summary:** Contains fundamental game assets (font, tile properties) and the credits engine.
#### Search Heuristics:
* **Tile Behavior (e.g., making a wall walkable):** Identify the tile's graphical ID and find its entry in the `OverworldTileTypes` or `UnderworldTileTypes` tables. Change its byte value to match a tile with the desired properties.
* **Custom Tile Physics (e.g., ice):** Search for the `Underworld_LoadCustomTileTypes` function to see how alternate tile property sets are loaded for specific dungeons.
* **To change the behavior of a map tile (e.g., make a wall walkable):**
1. Identify the tile's graphical ID.
2. Find its corresponding entry in the `OverworldTileTypes` or `UnderworldTileTypes` tables.
3. Change the byte value to that of a tile with the desired properties (e.g., change a wall tile's value to a floor tile's value).
* **To change the credits sequence:**
1. Go to the `Module1A_Credits` routine.
2. To change the order of scenes, modify the main `.vectors` jump table.
3. To change the camera movement, modify the `Credits_ScrollScene.target_y/x` tables.
4. To change which characters appear in a scene, find the corresponding `Credits_LoadSprites_...` routine and its associated position data tables.
### 6.14. Bank $0F: Miscellaneous Game Logic & Helpers
### 8.16. Bank $0F: Miscellaneous Game Logic & Helpers
**File:** `ALTTP/bank_0F.asm`
**Address Range:** `$0F8000` - `$0FFFFF`
This bank is a collection of important, miscellaneous subroutines that support the main game engines. It handles specific states like player death and provides common utility functions that are called from many different parts of the codebase.
#### Key Structures & Routines:
* **Player Death Sequence:**
* `PrepareToDie` (`#_0FFA6F`): This is called when Link's health reaches zero. It is responsible for resetting a large number of WRAM variables to their default state, effectively cleaning up Link's status before the death animation begins.
* `Link_SpinAndDie` (`#_0FF5C3`): This routine manages the entire visual and timed sequence of Link's death, including the spinning animation, the flashing, and the eventual transition to the "Game Over" screen.
* **Engine Helpers:**
* `Ancilla_CheckForAvailableSlot` (`#_0FF577`): A critical support function for the Ancilla Engine. Before any projectile or effect can be spawned, this routine is called to find an empty slot in the ancilla memory table. It contains logic to limit the number of certain ancilla types on screen at once.
* `Sprite_CancelHookshot` (`#_0FF540`): A utility function to immediately terminate the hookshot, returning it to Link. This is used when Link is hit or other interrupting events occur.
* **Interface Management:**
* `Interface_PrepAndDisplayMessage` (`#_0FFDAA`): A standard helper function used throughout the game to initiate a dialogue box. It saves the current game state and switches the main game `MODE` (`$10`) to `0x0E` (Interface), which passes control to the menu and text engine.
**Summary:** A collection of important miscellaneous subroutines, including player death and dialogue box initiation.
#### Search Heuristics:
* **Player Death Sequence:** The entry points are `PrepareToDie` and `Link_SpinAndDie`.
* **Dialogue Box Trigger:** Search for `JSL Interface_PrepAndDisplayMessage`. The code immediately preceding it sets up the message ID to be displayed.
* **To modify the player death sequence:** The entry points are `PrepareToDie` and `Link_SpinAndDie`. Changes to the animation timing or visual effects would be made here.
* **To change the number of a certain projectile allowed on screen:** Find where `Ancilla_CheckForAvailableSlot` is called before the `AncillaAdd_...` routine for that projectile. The value passed to it determines the limit.
* **To find code that triggers a message box:** Search for `JSL Interface_PrepAndDisplayMessage`. The code immediately preceding it will be setting up the message ID to be displayed.
### 8.17. Bank $10-$18: Graphics Sheets for Link, Dungeon, Overworld, Sprites
### 6.14.1. Bank $10-$18: Graphics Sheets for Link, Dungeon, Overworld, Sprites
### 8.18. Bank $19: Sound Data
### 6.14.2. Bank $19: Sound Data
### 6.15. Bank $1A: Miscellaneous Sprites & Cutscenes
### 8.19. Bank $1A: Miscellaneous Sprites & Cutscenes
**File:** `ALTTP/bank_1A.asm`
**Address Range:** `$1A8000` - `$1AFFFF`
This bank is a collection of miscellaneous sprite logic. It doesn't contain a single, unified engine but rather houses the code for a variety of unique sprites, NPCs, cutscene events, and environmental interactions that are too specific for the main sprite engine in Bank $06.
#### Key Structures & Routines:
* **`Sprite_37_Waterfall` / `BatCrash`:** The cutscene logic for the bat that crashes into the Pyramid of Power, opening the entrance. It's initiated by a special waterfall sprite (`Sprite_37`) that dispatches to the `BatCrash` routine.
* **`Sprite_Cukeman`:** The logic for the friendly green Zora who gives you the Zora Flippers, including its dialogue trigger logic.
* **`Overworld_SubstituteAlternateSecret`:** A system that can dynamically replace the item found under a liftable rock/bush with an enemy or a different item based on various conditions like game state and number of sprites on screen.
* **`SpriteDraw_Mothula`:** The complex drawing routine for the Mothula boss, which handles its multi-part body and wings.
* **`Lanmola_SpawnShrapnel`:** A helper function for the Lanmola boss fight to spawn rock shrapnel when a segment is destroyed.
* **`SpawnHammerWaterSplash`:** A utility to create a water splash effect when the hammer hits a water tile, used to reveal the entrance to the Waterfall of Wishing.
* **Various NPC/Object Routines:** Includes logic for the Drunkard (`SpriteDraw_Drunkard`), the Race Game Lady (`SpriteDraw_RaceGameLady`), the Chicken Lady (`ChickenLady`), the Digging Game Guy (`SpritePrep_DiggingGameGuy`), and the pushable mantlepiece in Hyrule Castle (`Sprite_EE_CastleMantle`).
**Summary:** Logic for a variety of unique sprites, NPCs, and cutscene events that are too specific for the main sprite engine.
#### Search Heuristics:
* **Pyramid of Power Opening:** Search for `BatCrash` or `CreatePyramidHole`.
* **Waterfall of Wishing Splash:** Search for `SpawnHammerWaterSplash`.
* **Secret Item Substitution:** To understand how items under rocks are sometimes replaced by enemies, analyze `Overworld_SubstituteAlternateSecret`.
* To find the Pyramid of Power opening cutscene, search for `BatCrash` or `CreatePyramidHole`.
* To find logic for unique NPCs not found in other banks (like the Cukeman or the Drunkard), check this bank.
* To understand how secrets under rocks are sometimes replaced by enemies, analyze `Overworld_SubstituteAlternateSecret`.
* For specific boss-related drawing or helper functions (like Mothula's drawing or Lanmola's shrapnel), this bank might contain the code if it's not in the main sprite banks.
* To find the code that creates the splash when hammering the waterfall to reveal the cave, look for `SpawnHammerWaterSplash`.
### 6.16. Bank $1B: Overworld Interaction & Palettes
### 8.20. Bank $1B: Overworld Interaction & Palettes
**File:** `ALTTP/bank_1B.asm`
**Address Range:** `$1B8000` - `$1BFFFF`
This bank is the heart of the overworld interaction system. It contains extensive data tables and logic that govern how the player transitions from the overworld to the underworld, as well as how items affect the environment. It manages all pits, doors, and item-based tile interactions like digging, hammering, and bombing. A significant portion of the bank is also dedicated to storing palette data for the entire game.
#### Key Structures & Routines:
* **Entrance Data Tables:** A massive collection of tables at the start of the bank (`Overworld_EntranceScreens`, `Overworld_EntranceTileIndex`, `Overworld_Entrance_ID`) that define every entrance in the game, mapping overworld tile coordinates to specific underworld room IDs.
* **`Overworld_UseEntrance`:** The primary routine called when Link interacts with a door tile. It uses the entrance tables to look up the destination and initiate the transition to the underworld.
* **`Overworld_GetPitDestination`:** Determines where Link ends up when he falls into a hole in the overworld, using its own set of tables to map pit locations to specific entrances.
* **`HandleItemTileAction_Overworld`:** The main dispatcher for when an item is used on an overworld tile. It checks the item used (shovel, powder, hammer) and the tile type to call the appropriate sub-handler.
* **`OverworldData_HiddenItems`:** A huge database, organized by screen, that lists the location and type of every secret hidden under a liftable object or behind a bombable wall.
* **`Overworld_RevealSecret`:** The function that consults the `OverworldData_HiddenItems` tables to determine what to spawn when a secret is uncovered.
* **`PaletteData`:** A very large section containing hundreds of pre-defined 15-color palettes for sprites, Link's armor, UI elements, and backgrounds.
* **`Palettes_Load_*` Routines:** A suite of functions that read from the `PaletteData` section and write the colors to CGRAM, such as `Palettes_Load_LinkArmorAndGloves`, `Palettes_Load_SpriteMain`, and `Palettes_Load_OWBGMain`.
**Summary:** The heart of the overworld interaction system. Manages all entrances, pits, and item-based tile interactions (digging, bombing). Also contains a very large store of palette data.
#### Search Heuristics:
* **Overworld Entrances:** To change where a door leads, find its entry in the `Overworld_Entrance...` tables at the top of the bank.
* **Hidden Item Locations:** To change the item under a specific bush, find the correct `OverworldData_HiddenItems_Screen_XX` table and modify the entry for that bush's coordinates.
* **Sprite/Armor Colors:** To change a color, find the correct palette in the `PaletteData` section and modify the desired color values.
* **To change where an overworld door leads:** Find its entry in the `Overworld_Entrance...` tables at the top of the bank.
* **To modify what happens when an item is used on the ground:** Start at `HandleItemTileAction_Overworld`.
* **To change the item under a specific bush:** Find the correct `OverworldData_HiddenItems_Screen_XX` table and modify the entry corresponding to that bush's coordinates.
* **To change a sprite or armor color:** Find the correct palette in the `PaletteData` section and modify the desired color values.
### 8.21. Bank $1C: Text Data
### 6.16.1. Bank $1C: Text Data
### 8.22. Bank $1D & $1E: Advanced Sprite & Boss AI
### 6.17. Bank $1D: Advanced Sprite & Boss AI
**File:** `ALTTP/bank_1D.asm`
**Address Range:** `$1D8000` - `$1DFFFF`
This bank contains the specific, complex logic for many of the game's most iconic bosses and late-game enemies. While other banks manage the general sprite framework, this bank gives these characters their unique attack patterns and behaviors.
#### Key Structures & Routines:
* **Ganon Fight:** A significant portion of the bank is dedicated to the final battle with Ganon. This includes logic for his different phases, spawning his phantom (`SpawnPhantomGanon`), his trident attack (`Sprite_GanonTrident`), and his fire bat attack (`Sprite_GanonBat`).
* **Major Boss AI:** It contains the complete AI for several key dungeon bosses:
* **Moldorm** (`Sprite_09_Moldorm`): The boss of the Tower of Hera.
* **Vitreous** (`Sprite_BD_Vitreous`): The boss of Misery Mire, including its smaller eyeballs.
* **Trinexx** (`Sprite_CB_TrinexxRockHead`): The main logic for Trinexx, the boss of Turtle Rock, including its rock, fire, and ice heads.
* **Blind the Thief** (`Sprite_CE_Blind`): The boss of the Thieves' Town.
* **Complex Enemies:** It also handles a variety of other challenging enemies:
* **Lynel** (`Sprite_D0_Lynel`): The powerful centaurs on Death Mountain.
* **Chain Chomp** (`Sprite_CA_ChainChomp`): The familiar enemy from the Mario series.
* **Pokey** (`Sprite_C7_Pokey`): The cactus enemy from the Desert Palace.
* **Swamola** (`Sprite_CF_Swamola`): The large, flying serpents in the Swamp of Evil.
* **Shared Physics and Utilities:** The bank also includes many common helper routines for sprite physics, such as `Sprite_Move_XY_Bank1D`, `Sprite_BounceFromTileCollision`, and `Sprite_ApplyConveyor`.
**Files:** `ALTTP/bank_1D.asm`, `ALTTP/bank_1E.asm`
**Summary:** These banks contain the specific, complex AI for most of the game's major bosses and late-game enemies (Ganon, Moldorm, Trinexx, Helmasaur King, Kholdstare, Agahnim, etc.).
#### Search Heuristics:
* **Boss/Enemy AI:** To modify a specific boss or advanced enemy, search for its `Sprite_...` routine in these two banks (e.g., `Sprite_92_HelmasaurKing` in bank $1E).
* **Sprite Dispatch Table:** The jump table at `SpriteModule_Active_Bank1E` in `bank_1E.asm` provides a comprehensive list of all sprites managed by that bank and is a good starting point for investigation.
* To modify the final battle, search for `Ganon` routines in this bank.
* To alter the behavior of bosses like Moldorm, Vitreous, Trinexx, or Blind, their main AI routines are located here.
* To change how late-game enemies like Lynels or Chain Chomps behave, find their corresponding `Sprite_...` routine in this bank.
### 6.18. Bank $1E: Advanced Sprite & Boss AI (Continued)
**File:** `ALTTP/bank_1E.asm`
**Address Range:** `$1E8000` - `$1EFFFF`
This bank is another major collection of advanced sprite and boss logic, complementing Bank $1D$. It contains the AI for some of the most mechanically complex bosses and enemies, as well as a master jump table (`SpriteModule_Active_Bank1E`) that dispatches to all the sprite routines housed within it.
#### Key Structures & Routines:
* **Major Boss AI:** This bank is home to several major boss encounters:
* **Helmasaur King** (`Sprite_92_HelmasaurKing`): The complete AI for the Palace of Darkness boss, including its tail-wagging, fireballs, and mask-breaking mechanics.
* **Kholdstare** (`Sprite_A2_Kholdstare`): The Ice Palace boss, including the logic for its shell (`Sprite_A3_KholdstareShell`) and the falling ice (`Sprite_A4_FallingIce`) it summons.
* **Arrghus** (`Sprite_8C_Arrghus`): The boss of the Swamp Palace, which manages the main body and the smaller "Arrghi" that circle it (`Sprite_8D_Arrghi`).
* **Agahnim** (`Sprite_7A_Agahnim`): The logic for the wizard boss fight, including his ball lightning attack (`Sprite_7B_AgahnimBalls`).
* **Complex Enemies:** It also defines the behavior for many memorable enemies:
* **Freezor** (`Sprite_A1_Freezor`): The invincible ice enemies from the Ice Palace.
* **Wizzrobe** (`Sprite_9B_Wizzrobe`): The teleporting magic-users.
* **Stalfos Knight** (`Sprite_91_StalfosKnight`): The large, bone-throwing skeletons.
* **Key NPCs and Objects:**
* **Kiki the Monkey** (`Sprite_B6_Kiki`): The monkey who opens the Palace of Darkness.
* **Blind's Maiden** (`Sprite_B7_BlindMaiden`): The maiden who follows Link before revealing herself as the boss Blind.
* **Purple Chest** (`Sprite_B4_PurpleChest`): The special chest that follows Link until it can be opened by the smithy.
#### Search Heuristics:
* To find the AI for bosses like Helmasaur King, Kholdstare, Arrghus, or Agahnim, search for their respective `Sprite_...` routines in this bank.
* The master jump table at `SpriteModule_Active_Bank1E` provides a comprehensive list of all sprites managed by this bank and is a good starting point for investigation.
* To modify the behavior of unique NPCs like Kiki or the maiden who becomes Blind, their logic is located here.
#### 6.19. Bank $1F: Dungeon Room Data
### 8.23. Bank $1F: Dungeon Room Data
## 9. ZScream expanded feature ROM map
@@ -751,4 +436,3 @@ ZScream reserves:
| `0x1E0000 - 0x1E7FFF` | 1 Bank | Custom ASM patches |
| `0x1E8000 - 0x1EFFFF` | 1 Bank | Expanded Tile16 space |
| `0x1F0000 - 0x1FFFFF` | 2 Banks | Expanded Tile32 space |