146 lines
8.4 KiB
Markdown
146 lines
8.4 KiB
Markdown
# Mask System
|
|
|
|
This document provides a detailed analysis of the Mask System in Oracle of Secrets, based on the code in the `Masks/` directory. The system allows Link to transform into various forms, each with unique graphics, palettes, and abilities.
|
|
|
|
## 1. System Architecture
|
|
|
|
The Mask System is built around a central WRAM variable and a set of core routines that handle transformations, graphics, and palettes.
|
|
|
|
- **`!CurrentMask` (`$02B2`):** A WRAM variable that stores the ID of the currently active mask. A value of `0x00` represents Link's normal human form.
|
|
- **`!LinkGraphics` (`$BC`):** A WRAM variable that holds the bank number for Link's current graphics sheet. The Mask System changes this value to load the appropriate sprite graphics for each form.
|
|
|
|
### Mask IDs
|
|
|
|
| ID | Mask / Form |
|
|
|------|---------------|
|
|
| `00` | Human (Default) |
|
|
| `01` | Deku Mask |
|
|
| `02` | Zora Mask |
|
|
| `03` | Wolf Mask |
|
|
| `04` | Bunny Hood |
|
|
| `05` | Minish Form |
|
|
| `06` | GBC Form |
|
|
| `07` | Moosh Form |
|
|
|
|
## 2. Core Routines & Hooks (`Masks/mask_routines.asm`)
|
|
|
|
A set of shared routines and hooks form the backbone of the system.
|
|
|
|
- **`Link_TransformMask`:** This is the primary function for changing forms. It is typically called when the player uses a mask item.
|
|
- **Trigger:** It requires a new R-button press (`CheckNewRButtonPress`) to prevent rapid toggling.
|
|
- **Logic:** It takes a mask ID in the A register. If the requested mask is already active, it reverts Link to his human form. Otherwise, it sets `!CurrentMask`, updates the graphics bank in `$BC` from a lookup table, and calls `Palette_ArmorAndGloves` to apply the new look.
|
|
- **Effect:** It spawns a "poof" of smoke (`AddTransformationCloud`) and plays a sound effect.
|
|
|
|
- **`Palette_ArmorAndGloves` (Hook):** This routine hooks the vanilla palette loading function (`$1BEDF9`). It checks `!CurrentMask` and jumps to the appropriate `Update...Palette` routine for the active form, ensuring the correct colors are loaded. If no mask is active, it proceeds with the vanilla logic for loading Link's tunic color.
|
|
|
|
- **`LinkItem_CheckForSwordSwing_Masks` (Hook):** This routine hooks the vanilla sword swing check (`$079CD9`). It prevents certain forms (Deku, Wolf, Minish, Moosh) from using the sword, while allowing others (Zora, GBC Link) to use it freely.
|
|
|
|
- **Reset Routines:**
|
|
- `ResetToLinkGraphics`: Reverts Link to his default graphics and `!CurrentMask = 0`.
|
|
- `ForceResetMask_GameOver` / `ForceResetMask_SaveAndQuit`: Hooks into the game over and save/quit routines to ensure Link's form is reset before the game saves or restarts.
|
|
|
|
## 3. Transformation Masks
|
|
|
|
These masks grant Link new forms with significant new abilities.
|
|
|
|
### Deku Mask
|
|
|
|
- **File:** `Masks/deku_mask.asm`
|
|
- **Transformation:** Replaces the Quake Medallion. Pressing 'Y' with the item selected transforms Link.
|
|
- **Abilities:**
|
|
- **Spin Attack:** Pressing 'Y' performs a spinning attack.
|
|
- **Deku Bubble:** If not on a Deku Flower, the spin attack also shoots a bubble projectile (`Ancilla0E_MagicBubble`).
|
|
- **Hover:** If standing on a Deku Flower (tile property check sets WRAM `$71`), the spin attack launches Link into the air, allowing him to hover for a short time.
|
|
- **Bomb Drop:** While hovering, pressing 'Y' drops a bomb.
|
|
- **Cancel Hover:** Pressing 'B' or letting the timer expire cancels the hover.
|
|
- **Key Flags & Variables:**
|
|
- `!CurrentMask`: `0x01`
|
|
- `DekuFloating` (`$70`): Flag set when Link is hovering.
|
|
- `DekuHover` (`$71`): Flag set when Link is standing on a Deku Flower, enabling the hover ability.
|
|
- **Code Interactions:**
|
|
- Hooks `LinkItem_Quake` (`$07A64B`).
|
|
- Repurposes Link's "Using Quake Medallion" state (`$5D = 0x0A`) for the hover ability.
|
|
- Hooks `LinkOAM_DrawShield` (`$0DA780`) to prevent the shield from being drawn.
|
|
|
|
### Zora Mask
|
|
|
|
- **File:** `Masks/zora_mask.asm`
|
|
- **Transformation:** Replaces the Bombos Medallion. Pressing 'Y' with the item selected transforms Link.
|
|
- **Abilities:**
|
|
- **Diving:** Allows Link to dive in deep water by pressing 'Y'. Pressing 'Y' again resurfaces.
|
|
- **Overworld Diving:** When diving in the overworld, Link becomes invincible, moves faster, and is hidden beneath a ripple effect.
|
|
- **Dungeon Diving:** When diving in a dungeon, Link moves to the lower layer (`$EE=0`), allowing him to swim under floors and obstacles.
|
|
- **Sword:** The Zora form can use the sword.
|
|
- **Key Flags & Variables:**
|
|
- `!CurrentMask`: `0x02`
|
|
- `!ZoraDiving` (`$0AAB`): Flag set when Link is currently underwater.
|
|
- **Code Interactions:**
|
|
- Hooks `LinkItem_Bombos` (`$07A569`).
|
|
- Hooks the end of `LinkState_Swimming` (`$079781`) to handle the dive input.
|
|
- Hooks the end of `LinkState_Default` (`$0782D2`) to handle resurfacing in dungeons.
|
|
- Hooks `Link_HopInOrOutOfWater_Vertical` (`$07C307`) to reset the dive state when using water stairs.
|
|
|
|
### Wolf Mask
|
|
|
|
- **File:** `Masks/wolf_mask.asm`
|
|
- **Transformation:** Shares an item slot with the Flute. When selected, it replaces the Shovel. Pressing 'Y' transforms Link.
|
|
- **Abilities:**
|
|
- **Dig:** When transformed, pressing 'Y' executes the vanilla `LinkItem_Shovel` routine, allowing Wolf Link to dig for items without needing the shovel.
|
|
- **Key Flags & Variables:**
|
|
- `!CurrentMask`: `0x03`
|
|
- **Code Interactions:**
|
|
- Hooks the `LinkItem_Shovel` vector (`$07A313`) to a new `LinkItem_ShovelAndFlute` routine that dispatches between the Flute and Wolf Mask logic based on the selected item (`$0202`).
|
|
|
|
### Minish Form
|
|
|
|
- **File:** `Masks/minish_form.asm`
|
|
- **Transformation:** Context-sensitive. When standing on a special portal tile (`ID 64`), pressing 'R' transforms Link into Minish form. Pressing 'R' on the portal again reverts him.
|
|
- **Abilities:**
|
|
- **Access Minish Areas:** Allows Link to pass through special small openings (`Tile ID 65`).
|
|
- **Restricted Actions:** Cannot lift objects.
|
|
- **Key Flags & Variables:**
|
|
- `!CurrentMask`: `0x05`
|
|
- **Code Interactions:**
|
|
- Hooks the overworld (`$07DAF2`) and underworld (`$07D8A0`) tile collision tables to add handlers for the portal and passage tiles.
|
|
- Hooks the lift check (`$079C32`) to disable lifting while in Minish form.
|
|
|
|
### Moosh Form
|
|
|
|
- **File:** `Masks/moosh.asm`
|
|
- **Transformation:** The trigger for transforming into Moosh is not defined within the mask's own file, but is handled by `Link_TransformMoosh`.
|
|
- **Abilities:**
|
|
- **Hover Dash:** Attempting to use the Pegasus Boots (dash) while in Moosh form will instead trigger a short hover, similar to the Deku Mask's ability.
|
|
- **Key Flags & Variables:**
|
|
- `!CurrentMask`: `0x07`
|
|
- **Code Interactions:**
|
|
- Hooks the dash initiation logic (`$079093`) to intercept the dash and call `PrepareQuakeSpell`, which sets Link's state to `0x0A` (hover).
|
|
- Shares the hover/recoil animation logic with the Deku Mask.
|
|
|
|
## 4. Passive & Cosmetic Forms
|
|
|
|
### Bunny Hood
|
|
|
|
- **File:** `Masks/bunny_hood.asm`
|
|
- **Transformation:** Replaces the Ether Medallion. Pressing 'Y' activates the Bunny Hood state. This is a state change, not a visual transformation.
|
|
- **Abilities:**
|
|
- **Increased Speed:** While the Bunny Hood is the active mask (`!CurrentMask = 0x04`), Link's movement speed is increased across various actions (walking, carrying, etc.). The specific speed values are defined in `BunnySpeedTable`.
|
|
- **Key Flags & Variables:**
|
|
- `!CurrentMask`: `0x04`
|
|
- **Code Interactions:**
|
|
- Hooks `LinkItem_Ether` (`$07A494`) to trigger the state change.
|
|
- Hooks the velocity calculation in the player engine (`$07E330`) to load custom speed values from a table.
|
|
|
|
### GBC Form
|
|
|
|
- **File:** `Masks/gbc_form.asm`
|
|
- **Transformation:** An automatic, cosmetic transformation that occurs whenever Link is in the Dark World.
|
|
- **Abilities:**
|
|
- Changes Link's graphics to a Game Boy Color-inspired sprite.
|
|
- Applies a unique, limited-color palette. The palette correctly reflects Link's current tunic (Green, Blue, or Red).
|
|
- This form can still use the sword.
|
|
- **Key Flags & Variables:**
|
|
- `!CurrentMask`: `0x06`
|
|
- `$0FFF`: The vanilla Dark World flag.
|
|
- **Code Interactions:**
|
|
- Hooks numerous overworld, underworld, and transition routines to consistently apply the effect when in the Dark World and remove it when in the Light World.
|