oracle-of-secrets/Docs/Items.md

Custom Items System

This document details the functionality of new and modified items in Oracle of Secrets, based on analysis of the Items/ directory.

1. Overview

The item roster has been significantly expanded with new mechanics, and many vanilla items have been reworked to provide new functionality. The system is managed through a combination of hooks into the main player state machine and custom routines for each item.

2. Vanilla Item Modifications

Several items from the original game have been altered.

Hookshot / Goldstar

• Files: goldstar.asm
• Functionality: The Hookshot can be upgraded to the Goldstar, a powerful morning star weapon. The two items share an inventory slot.
• Switching: When the Goldstar is obtained, the player can switch between the Hookshot and Goldstar by pressing the L/R shoulder buttons while it is selected in the menu. The current mode is tracked by the GoldstarOrHookshot WRAM variable.
• Goldstar Mechanics: When active, the item functions as a short-range, powerful melee weapon with its own collision and damage properties, distinct from the Hookshot's grappling mechanic.

Ice Rod

• File: ice_rod.asm
• Functionality: The Ice Rod's projectile now freezes water tiles it hits, creating temporary 16x16 ice platforms. This allows the player to cross water gaps.
• Implementation: The LinkItem_IceRod routine hooks into the ancilla tile collision logic. When the projectile hits a water tile, it dynamically modifies the tilemap properties in RAM and DMAs new ice graphics to VRAM.

Bug-Catching Net -> Roc's Feather

• File: jump_feather.asm
• Functionality: The vanilla Bug-Catching Net has been completely replaced by Roc's Feather. This item allows Link to perform a short hop.
• Implementation: LinkItem_JumpFeather initiates the jump by setting Link's state to a recoil/ledge hop state and applying a burst of vertical velocity.

Bottles

• File: bottle_net.asm
• Functionality: The Bug-Catching Net is no longer required to catch bees, fairies, etc. The Bottle item now has a dual function:
  1. If the bottle is empty, using it initiates the LinkItem_CatchBottle routine, which performs a net-catching swing.
  2. If the bottle is full, using it calls LinkItem_Bottles, which consumes the contents (e.g., drinks a potion, releases a fairy).

Book of Mudora -> Book of Secrets

• File: book_of_secrets.asm
• Functionality: The Book of Mudora is now the Book of Secrets. While its vanilla function of translating Hylian text remains, it has a new secret-revealing capability.
• Implementation: The Dungeon_RevealSecrets routine checks if the L button is held while inside a building. If it is, it disables the BG2 layer, which can be used to hide secret passages or objects behind walls that are part of that background layer.

3. New Active Items

Ocarina

• File: ocarina.asm
• Functionality: A multi-song instrument. When selected, the player can cycle through learned songs using the L/R shoulder buttons. Pressing 'Y' plays the selected song, triggering its unique effect.
• Songs & Effects:
  • Song of Healing: Heals certain NPCs or triggers quest events.
  • Song of Storms: Toggles a rain overlay on the overworld, which can affect the environment (e.g., watering the Magic Bean).
  • Song of Soaring: Warps the player to pre-defined locations (the vanilla flute's bird travel).
  • Song of Time: Toggles the in-game time between day and night.

Shared Slot: Portal Rod & Fishing Rod

• Files: portal_rod.asm, fishing_rod.asm
• Functionality: These two distinct items share a single inventory slot. If the player has the upgrade ($7EF351 >= 2), they can swap between the two by pressing L/R in the menu.
• Portal Rod: Fires a projectile that creates a portal sprite (blue or orange). The Ancilla_HandlePortalCollision logic detects when another projectile (like an arrow) hits a portal and teleports it to the other portal's location.
• Fishing Rod: Initiates a fishing minigame. LinkItem_FishingRod spawns a "floater" sprite, and the player can reel it in to catch fish or other items from a prize table.

4. New Passive Items

Magic Rings

• File: magic_rings.asm
• Functionality: Passive items that grant buffs when equipped in one of the three ring slots in the Quest Status menu. The effects are applied by hooking into various game logic routines.
• Implemented Rings:
  • Power Ring: Increases sword damage.
  • Armor Ring: Reduces damage taken by half.
  • Heart Ring: Slowly regenerates health over time.
  • Light Ring: Allows the sword to shoot beams even when Link is not at full health (down to -2 hearts from max).
  • Blast Ring: Increases the damage of bombs.
  • Steadfast Ring: Prevents or reduces knockback from enemy hits.

5. Consumable Items (Magic Bag)

• File: all_items.asm
• Functionality: The Magic Bag is a sub-menu that holds new consumable items. The Link_ConsumeMagicBagItem routine is a jump table that executes the effect for the selected item.
• Consumables:
  • Banana: Implemented. Restores a small amount of health (#$10).
  • Pineapple, Rock Meat, Seashells, Honeycombs, Deku Sticks: Placeholder entries exist in the jump table, but their effects are not yet implemented (the routines just contain RTS).