oracle-of-secrets/Docs/Features/Masks/Masks.md

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.