oracle-of-secrets/oracle.org

#+title: Oracle of Secrets - Project Tracker
#+author: @scawful & Gemini
#+todo: TODO(t) ACTIVE(a) | DONE(d) CANCELED(c)
#+options: H:5 tags:t
#+startup: content

* Project Dashboard & Epics

This section provides a high-level overview of the major development efforts (Epics). Each epic groups together numerous smaller tasks from the sections below.

- *Epic: Core Infrastructure Refactor*
  - Goal: Improve code quality, readability, and maintainability across all major systems.
  - Related Sections: [[Technical Debt & Refactoring]]

- *Epic: System Integration & Stability*
  - Goal: Resolve all known conflicts between major systems like ZSOW, the Time System, and other custom logic to ensure a stable and bug-free experience.
  - Related Sections: [[System Integration & Bugs]]

- *Epic: Dungeon Polish & Completion*
  - Goal: Finalize the design, puzzles, and presentation of all dungeons.
  - Related Sections: [[New Features & Content]]

- *Epic: Quest & Narrative Implementation*
  - Goal: Implement all remaining main story quests, side-quests, and narrative sequences.
  - Related Sections: [[New Features & Content]]

- *Epic: Boss & Enemy Enhancements*
  - Goal: Refine and improve all custom boss fights and enemy behaviors.
  - Related Sections: [[New Features & Content]]

* Technical Debt & Refactoring
  :PROPERTIES:
  :CATEGORY: Infrastructure
  :STRATEGY: Opportunistic
  :END:

This section tracks tasks focused on improving the existing codebase's structure, readability, and maintainability. Per user feedback, these tasks should be tackled opportunistically alongside feature development and bug-fixing to allow for immediate testing and avoid regressions.

** General Infrastructure
*** TODO [#B] Reorganize All Patches into a Central File
    :PROPERTIES:
    :ID: infra-patches-all
    :END:
    - *Analysis:* Patches are scattered across multiple files (=time_system.asm=, =all_sprites.asm=, etc.).
    - *Task:* Move all `org` patches that modify vanilla code into =Core/patches.asm=. This file should be organized by bank and functionality for clarity.
    - *Benefit:* Centralizes all direct modifications to the original ROM, making them easier to find, manage, and debug.

*** TODO [#C] Leverage ~struct~ for Complex Data Structures
    :PROPERTIES:
    :ID: infra-structs
    :END:
    - *Analysis:* Many systems use parallel arrays or labeled offsets for complex data, which is functional but hard to read.
    - *Task:* Systematically refactor key data structures to use asar's `struct` directive.
    - *Candidates:*
      - [ ] Player Data (Link's state)
      - [ ] Sprite State (Generic sprite properties)
      - [ ] SRAM Layout (Quest flags, item data)

*** TODO [#C] Convert Manual Jump Tables to Use ~table~
    :PROPERTIES:
    :ID: infra-tables
    :END:
    - *Analysis:* Jump tables are often created manually with `dw` directives.
    - *Task:* Convert these tables to use asar's `table` directive for simplicity and safety.
    - *Candidates:*
      - [ ] =Items/all_items.asm= (=Link_ConsumeMagicBagItem=)
      - [ ] =Menu/menu.asm= (=Menu_Entry.vectors=)

*** TODO [#C] Document the Dialogue System
    :PROPERTIES:
    :ID: infra-dialogue-docs
    :END:
    - *Goal:* Create comprehensive documentation for the game's dialogue and text rendering system.
    - *Blocker For:* [[quest-goron-mines]] (Garo NPC).

** Time System (=Overworld/time_system.asm=)
*** DONE [#B] Refactor Time System [3/3]
    :PROPERTIES:
    :ID: refactor-time-system
    :END:
    - *Analysis:* The system is functional but monolithic and uses many magic numbers.
    - *Tasks:*
      - [X] Group all time-related variables (`Hours`, `Minutes`, `TimeSpeed`, color values) into a single `TimeState` struct.
      - [X] Convert all logic blocks (`RunClock`, `DrawClockToHud`, `ColorSubEffect`) into proper `subroutine`s.
      - [X] Break down the large `RunClock` routine into smaller, single-purpose functions (e.g., `TimeSystem_CheckCanRun`, `TimeSystem_IncrementTime`, `TimeSystem_UpdatePalettes`).

*** DONE [#A] Fix Time System Custom BG Color Regression
    :PROPERTIES:
    :ID: bug-time-system-bg-color
    :END:
    - *Symptom:* Custom background color not working correctly after recent changes.
    - *Root Cause:* The Color Math Control Register ($9A) was persisting when transitioning from an overlay area (Rain/Storms) to a normal area, causing additive color math to apply to the background.
    - *Solution:* Explicitly cleared $9A in `Overworld_LoadBGColorAndSubscreenOverlay` and `Overworld_ReloadSubscreenOverlay_Interupt` in `ZSCustomOverworld.asm` when the overlay ID is $FF. Also ensured Time System tint persistence via `Oracle_CgramAuxToMain_Impl` in `mask_routines.asm`.

** Minecart System (=Sprites/Objects/minecart.asm=)
*** ACTIVE [#B] Refactor Minecart System [1/4]
    :PROPERTIES:
    :ID: refactor-minecart
    :END:
    - *Analysis:* An impressive but highly complex system that would benefit greatly from better organization and data-driven design.
    - *Tasks:*
      - [X] Externalize track data into `data/minecart_tracks.asm` (Partial step toward struct/table conversion).
      - [ ] Define a `MinecartTrack` struct and convert the SRAM tracking arrays into a `table` of these structs.
      - [ ] Refactor the four `Minecart_Move...` routines into a single `Minecart_Move` subroutine that uses a lookup table for speed and axis.
      - [ ] Refactor the `Minecart_SetDirection...` routines into a single `Minecart_SetDirection` subroutine that uses lookup tables.
      - [ ] Add high-level block comments to explain the purpose of major routines like `HandleTileDirections` and the track caching system.

** Ice Block System (=Sprites/Objects/ice_block.asm=)
*** TODO [#C] Refactor Ice Block Sprite
    :PROPERTIES:
    :ID: refactor-ice-block
    :END:
    - *Analysis:* The logic is straightforward but can be made more compact and readable.
    - *Task:* Refactor the `Sprite_ApplyPush` routine to use a lookup table for setting speed based on direction, instead of a chain of `CMP`/`BEQ` instructions.
    - *Note:* This is a code quality refactor. A separate bug for the collision mechanics is tracked in [[bug-ice-block-collision]].

** Menu System (=Menu/=)
*** DONE [#B] Refactor Menu System [2/2]
    :PROPERTIES:
    :ID: refactor-menu
    :END:
    - *Analysis:* The menu system is robust but has some duplicated code and hardcoded values.
    - *Tasks:*
      - [X] Refactor the input handling logic for the Magic Bag, Song Menu, and Ring Box sub-menus into a single, reusable subroutine.
      - [X] Replace all hardcoded menu state values (e.g., `LDA.b #$0C`) with named constants (e.g., `!MENU_STATE_MAGIC_BAG = $0C`).

** Music System (=Music/=)
*** TODO [#C] Improve Music System Workflow [0/3]
    :PROPERTIES:
    :ID: improve-music
    :END:
    - *Analysis:* The macro-based system is powerful but could be even more user-friendly for composition.
    - *Tasks:*
      - [ ] Establish a clear naming convention for subroutines (e.g., `.MelodyVerseA`, `.BasslineIntro`) and refactor existing songs to use it.
      - [ ] Create a `Music/common_patterns.asm` library for reusable musical phrases like standard drum beats or arpeggios.
      - [ ] Develop advanced composition macros like `%DefineMeasure(Name, Notes...)` and `%PlayMeasure(Name, Repeats)` to abstract away subroutine creation and calling.

* System Integration & Bugs
  :PROPERTIES:
  :CATEGORY: Integration
  :END:

This section tracks known conflicts between systems and outstanding bugs.

*** ACTIVE [#A] Fix Ice Block Collision and Push Mechanics
    :PROPERTIES:
    :ID: bug-ice-block-collision
    :END:
    - *Problem:* Collision logic was too sensitive, touch was unpredictable and the direction could shift while the player is moving.
    - *Solution:* Implemented an intent-based push system requiring Link to be aligned and hold contact for a short duration, with grid snapping for predictable movement.
    - *Status:* Awaiting emulator verification.

*** ACTIVE [#C] Refactor Ice Block Sprite
    :PROPERTIES:
    :ID: refactor-ice-block
    :END:
    - *Analysis:* The logic is straightforward but can be made more compact and readable.
    - *Task:* Refactored the `Sprite_ApplyPush` routine to use a lookup table for setting speed based on direction. Converted `IceBlock_CheckForGround` and `Sprite_IceBlock_CheckForSwitch` to subroutines. Replaced magic numbers with constants.
    - *Status:* Awaiting emulator verification.

*** DONE [#A] Resolve ZSOW vs. Lost Woods Conflict
    :PROPERTIES:
    :ID: bug-zsow-lostwoods
    :END:
    - *Analysis:* The `lost_woods.asm` puzzle logic was executing prematurely on entry, corrupting coordinates.
    - *Fix:* Added a check to ensure puzzle logic only runs when *inside* Area 0x29. Added `LostWoods_ResetCoordinates` to snap Link's position and clear scroll drifts on exit.
    - *Status:* Main "skipping" bug resolved.
    - *Regression:* Minor camera/coordinate desync when returning West (0x28). Documented in [[file:Docs/Issues/LostWoods_Transition_Desync.md][LostWoods_Transition_Desync.md]]. Low priority.

*** DONE [#A] ZSOW vs. Day/Night Sprites
    :PROPERTIES:
    :ID: bug-zsow-daynight
    :END:
    - *Status:* Fixed.
    - *Task:* Triage the crash to identify the root cause and develop a new solution for integrating day/night sprite loading with ZSOW.

*** DONE [#A] ZSOW vs. Song of Storms
    :PROPERTIES:
    :ID: bug-zsow-storms
    :END:
    - *Status:* Fixed. Rain overlay now persists across all transitions and loads immediately.
    - *Solution:* Multi-part fix across several files:
      1. *ZSCustomOverworld.asm (lines 2307-2310):* Added $7EE00E check before default overlay, forces rain ($9F) when flag is set.
      2. *ZSCustomOverworld.asm (lines 1556-1557):* ActivateSubScreen checks $7EE00E for menu transition visibility.
      3. *ZSCustomOverworld.asm (lines 3625-3629):* LoadAmbientSound forces rain SFX ($01) when flag is set.
      4. *menu_hud.asm (lines 580-583):* Indoor rain SFX ($05) when Song of Storms active.
      5. *ocarina.asm:* OcarinaEffect_SummonStorms now calls JSL Overworld_ReloadSubscreenOverlayAndAdvance_long to properly load/unload rain overlay graphics immediately.
      6. *ocarina.asm:* ResetOcarinaFlag no longer clears $7EE00E on screen transitions.
      7. *ocarina.asm:* Reordered logic - check $7EE00E FIRST so dismissal works from any area. Area checks only block summoning.
    - *Note:* Pool_EnableBeginningRain set to $00 to disable intro rain for Oracle of Secrets.
    - *Known Issues:*
      - Minor graphical artifacts in rain tiles may need editor fix or could be menu layer conflict.
      - Zora areas ($2E, $2F) now error beep on summon attempt. The Zora's Domain waterfall event (dismiss to trigger cutscene) needs position check - should only work when near the event in top-left of large map.
      - Edge cases with synchronization may exist but are deferred.

*** ACTIVE [#B] Menu Empty Items Bug :code:bugfix:
    :PROPERTIES:
    :ID: bug-menu-empty
    :END:
    - *Problem:* Menu system has issues when a section has no items.
    - *Cause:* Likely related to menu refactoring in commit 52a5ed4.
    - *File:* =Menu/menu.asm=

*** ACTIVE [#B] Zora Temple Tasks [0/2] :code:bugfix:
    :PROPERTIES:
    :ID: bug-zora-temple
    :END:
    - [ ] Zora Follower Sprite Logic: Ensure the Zora Baby follower correctly transitions to a standard sprite and interacts with switches.
    - [ ] Fix Water Gate Collision: Debug collision issues with the water gates in the temple.

* New Features & Content

** Dungeons & Levels
*** TODO [#A] Add Dungeon Maps [0/11] :assets:map:
    :PROPERTIES:
    :ID: content-dungeon-maps
    :END:
    - *Task:* Create and integrate map data for all dungeons using the yaze dungeon map editor.
    - [ ] D1: Mushroom Grotto
    - [ ] D2: Tail Palace
    - [ ] D3: Kalyxo Castle
    - [ ] D4: Zora Temple
    - [ ] D5: Glacia Estate
    - [ ] D6: Goron Mines
    - [ ] D7: Dragon Ship
    - [ ] D8: Fortress of Secrets
    - [ ] S1: Shrine of Wisdom
    - [ ] S2: Shrine of Power
    - [ ] S3: Shrine of Courage

*** TODO [#B] Glacia Estate Polish [0/4] :design:polish:
    :PROPERTIES:
    :ID: content-glacia-estate
    :END:
    - [ ] Improve Ice Block sprite collision detection (relates to [[bug-ice-block-collision]]).
    - [ ] Tune enemies in dungeon, adjust positioning for better challenge flow.
    - [ ] Exterior GFX improvements.
    - [ ] Add a visual indicator (e.g., a crack) for the pushable block in the ice puzzle.

*** TODO [#A] Shrine of Power Tasks [0/1] :design:
    :PROPERTIES:
    :ID: content-shrine-power
    :END:
    - [ ] Fix collision of lava pit corner tiles.

*** TODO [#C] Dragon Ship Tasks [0/1] :design:
    :PROPERTIES:
    :ID: content-dragon-ship
    :END:
    - [ ] Flesh out ideas for an extended section.

*** TODO [#C] Shrine of Wisdom Swamp Overworld Improvements :planning:
    :PROPERTIES:
    :ID: content-shrine-wisdom
    :END:
    - *Goal:* Make the swamp area less frustrating and more rewarding to explore.
    - *Ideas:*
      - [ ] Add warp zones that return the player to the start of a section if they fall.
      - [ ] Place shrubs or enemies that drop magic vials to support item usage.
      - [ ] Add a friendly NPC who provides hints about the correct path.
      - [ ] Place a hidden heart piece or other treasure to reward players who explore off the main path.

*** TODO [#B] Goron Mines Dungeon Ideas :design:
    :PROPERTIES:
    :ID: content-goron-mines
    :END:
    - *Goal:* Flesh out puzzle concepts for the Goron Mines.
    - *Ideas:*
      - [ ] *Goron Follower:* A Goron follows you who is heavy enough to trigger crumble floors. You must guide him safely.
      - [ ] *Minecart Lift:* A puzzle where you must lift an empty minecart and place it on a different track to proceed.
      - [ ] *Fragile Floor Maze:* A room with a mix of normal and crumbling floor tiles. You must find the safe path. Maybe use an item (Cane of Somaria?) to test the floor ahead.
      - [ ] *Controlled Collapse:* A puzzle where you must intentionally make a floor tile crumble to fall down to a specific spot on the floor below.

** Quests & Narrative Sequences
*** ACTIVE [#A] Zora Sanctuary Questline [3/3] :quest:
    :PROPERTIES:
    :ID: quest-zora-sanctuary
    :END:
    - [X] Meet lone Sea Zora left at the Sanctuary, learn of Zora Princess.
    - [X] Conflict over territory lead to Zora Princesses imprisonment.
    - [X] Implement waterfall opening event using Song of Storms.
      - Trigger: Song of Storms dismissal at the statue (Map 1E, Top-Left).
      - Logic: Strict 16x16 pixel trigger zone (Y=$06A0-$06B0, X=$0CB0-$0CC0) to prevent camera desync.
      - Fixes: Restored `overlays.asm` camera logic and added palette refresh (`INC $15`) to `ocarina.asm`.

*** TODO [#A] Kalyxo Castle Prison Sequence [0/4] :sequence:code:
    :PROPERTIES:
    :ID: quest-kalyxo-prison
    :END:
    - *Goal:* Create a stealth-based escape sequence after obtaining the Meadow Blade.
    - *Tasks:*
      - [ ] Implement Overlord logic to swarm the player with guards after they get the Lv2 sword, triggering a warp to a dungeon room (prison cell).
      - [ ] Implement guard AI using =probe_ref.asm=. Some guards should have a simple "reset on sight" behavior, while others should give chase.
      - [ ] Design the prison escape path, requiring the use of Minish form to slip through small passages.
      - [ ] Create custom dungeon objects for Minish-only pathways.

*** ACTIVE [#B] Goron Mines Quest [2/4] :quest:
    :PROPERTIES:
    :ID: quest-goron-mines
    :END:
    - [X] Collectible Goron Rock Meat from Lupo Mountain.
    - [X] Kalyxian Goron NPC in the desert asks for five sirloins to open the mines.
    - [ ] Implement Garo NPC. This will be a dialogue-heavy NPC with mysterious warping behavior. (Depends on [[infra-dialogue-docs]]).
    - [ ] Add Gossip Stones that provide hints related to the Shrines or other world lore.

*** TODO [#B] Tail Palace Kiki Quest [1/2] :quest:code:
    :PROPERTIES:
    :ID: quest-tail-palace
    :END:
    - [X] Deku NPCs inhabit Tail Palace OW after dungeon completion.
    - [ ] Modify the Kiki follower logic to require Bananas instead of Rupees to open the palace.

*** TODO [#B] Implement Dream Sequences [0/6] :sequence:
    :PROPERTIES:
    :ID: content-dream-sequences
    :END:
    - [ ] Deku Business Scrub Dream
    - [ ] Twinrova Ranch Girl Dream
    - [ ] Hyrule Castle Dream (Song of Time)
    - [ ] River Zora King Dream
    - [ ] Kydrog Sealing Dream
    - [ ] Mine Collapse Dream

*** TODO [#B] Implement Journal Feature :menu:
    :PROPERTIES:
    :ID: content-journal
    :END:
    - *Goal:* Create a functional journal accessible from the menu.
    - *Tasks:*
      - [ ] Design the UI for the journal in =Menu/menu_journal.asm=.
      - [ ] Create a system to track completed quests and major events using SRAM flags.
      - [ ] Write the text entries for each event.

*** ACTIVE [#B] Implement Consumable Item Effects [2/6] :quest:
    :PROPERTIES:
    :ID: content-consumables
    :END:
    - *Analysis:* The Magic Bag jump table in =all_items.asm= has several unimplemented items.
    - *Tasks:*
      - [X] Banana (restores health)
      - [X] Rock Meat
      - [ ] Pineapple
      - [ ] Seashells
      - [ ] Honeycombs
      - [ ] Deku Sticks

*** TODO [#C] Design and Implement Custom End Credits Sequence
    :PROPERTIES:
    :ID: content-end-credits
    :END:
    - *Goal:* Create a unique end credits sequence for the game.
    - *Note:* Will be implemented using the custom C++ editor, yaze.

** Sprites & Entities
*** TODO [#A] Improve Various Sprites Behavior Quality
    :PROPERTIES:
    :ID: quality-sprites
    :END:
    - *Goal:* A general task to review and polish the AI and behavior of various custom sprites.
    - *Note:* This is a high-level task that should be broken down into specific sprite-by-sprite improvements as development continues.

*** TODO [#A] Update Kydrog Boss Fight [1/3] :boss:code:
    :PROPERTIES:
    :ID: boss-kydrog
    :END:
    - [X] Track offspring sprites spawned for more dynamic spawns.
    - [ ] Improve Kydrog's movement AI and add a second phase to the fight.
    - [ ] Create a cinematic opening and ending cutscene with dialogue.

*** TODO [#A] Update Kydreeok Boss Fight [0/9] :boss:code:
    :PROPERTIES:
    :ID: boss-kydreeok
    :END:
    - *Goal:* Make the fight more dynamic and challenging.
    - *Tasks:*
      - [ ] Improve fireball attack patterns (e.g., targeted shots, spreads).
      - [ ] Add a "neck stretch" lunge attack, similar to a Chain Chomp.
      - [ ] Add a "spin attack" where necks stretch and spin around the body while shooting fire.
      - [ ] Add a bone-throwing attack for the second phase.
      - [ ] Make defeated heads detach and float around the room before re-attaching, instead of just popping back.
      - [ ] Add a "bullet hell" phase where heads are retracted and the body shoots fireballs in all directions.
      - [ ] Modify the damage check to prevent electrocuting the player if they hit a head, reducing frustration.
      - [ ] Create a pre-fight transformation cutscene showing Kydrog turning into Kydreeok.
      - [ ] Improve head/neck rotation visuals.

*** TODO [#B] Enhance Shrine of Courage Boss (Vaati) AI
    :PROPERTIES:
    :ID: boss-vaati
    :END:
    - *Goal:* Move the boss beyond a simple reskin of Vitreous.
    - *Task:* Design and implement new, Vaati-inspired attack patterns.
    - *Inspiration:* Could draw from the "Advanced Arrghus" custom boss logic.

** Creative Ideas & Brainstorming
*** Sky Area Special Overworld Events
    :PROPERTIES:
    :ID: idea-sky-area
    :END:
    - *Goal:* Design puzzles for a cloud-based area accessed with the Song of Soaring.
    - *Ideas:*
      - *Weather Puzzles:* Use the Ocarina to switch between sun and rain. Rain creates new cloud platforms by filling them with water. Sunshine makes electric clouds safe to walk on.
      - *Form-Based Puzzles:* Some clouds are thin and require Minish Form to not fall through. Others have strong winds that blow Minish Link away but not normal Link.
      - *Conduction Puzzles:* Use the Song of Storms to turn a normal cloud into a thundercloud to conduct electricity and power a mechanism.

* Reference
** Timeline

| Event             | Items                |
|-------------------+----------------------|
| Start Game        | Lamp                 |
| Shrine of Origins | Moon Pearl           |
| Forest of Dreams  | Lv1 Sword and Shield |
| ...               | ...                  |

** ROM Map
Expanded space used by ZScream as of 1/16/2024
Addresses are PC unless stated otherwise.
ZS reserves everything up to 1.5mb or up to 0x150000

| Location            | Contents                     |
|---------------------+------------------------------|
| 0x100000 - 0x107FFF | Nothing?                     |
| 0x108000 - 0x10FFFF | Title Screen, Dungeon Map    |
| 0x110000 - 0x117FFF | Default room header location |
| 0x118000 - 0x11FFFF | Unknown                      |
| 0x120000 - 0x127FFF | Expanded overlay data        |
| 0x128000 - 0x12FFFF | Custom collision data        |
| 0x130000 - 0x137FFF | Overworld map data overflow  |
| 0x138000 - 0x13FFFF | Expanded dungeon object data |
| 0x140000 - 0x147FFF | Custom overworld data        |
| 0x148000 - 0x14FFFF | Expanded dungeon object data |

** Credits
Zarby89 - ZScream, Code, Graphics
Jared Brian - Shrine of Power, ZScream, Code
Jeimuzu - Shrine of Wisdom, Tail Palace
Letterbomb - Shrine of Courage, Music, Graphics
NEONswift - Legends of Hyrule Maps
SePH - Overworld, Graphics
Ghillie - Overworld, Graphics
DarkLink45 - Deku Link GFX
W*E*R*D*N*A - Graphics
GameyFireBro - Graphics
Fruttielicious - Beta Testing
LEGO_Vince - Beta Testing
Spacewiki - Beta Testing
Evolvingfetus - Beta Testing
Discodragn - Beta Testing
BIGLOU - Beta Testing
HonorThyFamily - Beta-Testing