85 lines
5.5 KiB
Markdown
85 lines
5.5 KiB
Markdown
# 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`).
|