diff --git a/Docs/GEMINI.md b/Docs/GEMINI.md index 2a85b19..ca40d81 100644 --- a/Docs/GEMINI.md +++ b/Docs/GEMINI.md @@ -49,7 +49,7 @@ The 65816 is an 8/16-bit microprocessor used in the Super Nintendo Entertainment ### 2.2. Scoping and Style -- **Guideline:** The established code style uses labels followed by `{}` brackets to define scope for new blocks of logic. This convention must be followed. +- **Guideline:** The established code style uses labels followed by `{}` brackets to define scope for new blocks of logic. This convention must be followed. The `subroutine`/`endsubroutine` keywords are explicitly *not* to be used in this project. - **Rationale:** The `subroutine`/`endsubroutine` keywords are not used in this project. Maintaining a consistent style is crucial for readability. ### 2.3. Data Organization @@ -62,6 +62,19 @@ The 65816 is an 8/16-bit microprocessor used in the Super Nintendo Entertainment - **Guideline:** Avoid hardcoding numerical values. Use `!` or `define()` to create named constants for RAM/SRAM addresses, item IDs, sprite states, tile IDs, etc. - **Rationale:** This makes the code self-documenting and significantly easier to maintain and debug. +### 2.5. Opcode Size Suffixes (.b, .w, .l) + +`asar` can often infer operand sizes, but relying on this can lead to bugs when the processor state (M and X flags) is not what you expect. To write robust, readable, and safe code, you should use explicit size suffixes. + +- **`.b` (byte):** Forces an 8-bit operation. Use this when you are certain you are working with a single byte. + - Example: `LDA.b $7E0010` will correctly load a single byte into the accumulator, regardless of the M flag's state. +- **`.w` (word):** Forces a 16-bit operation. Use this when working with two bytes (a word). + - Example: `LDA.w $7E0022` will load a 16-bit value. This is essential for correctness if the M flag is 1 (8-bit mode). +- **`.l` (long):** Forces a 24-bit operation, typically for addresses in `JML` or `JSL`. + - Example: `JSL.l SomeRoutineInAnotherBank` + +**Golden Rule:** A mismatch between the M/X flags and the intended operation size is a primary cause of crashes. When in doubt, wrap your code in `REP`/`SEP` to explicitly set the processor state, and use size suffixes to make your intent clear to both the assembler and future developers. + ## 3. Project-Specific Conventions ### 3.1. File & Directory Structure @@ -82,7 +95,14 @@ The 65816 is an 8/16-bit microprocessor used in the Super Nintendo Entertainment - When hooking or modifying vanilla code, it is essential to understand the original context. The `usdasm` disassembly is the primary reference for this. - To find the original code for a patch at a given address (e.g., `$07A3DB`), you can search for the SNES address in the `usdasm` files (e.g., `#_07A3DB:`). -## 4. Debugging Tips for BRKs and Crashes +## 4. Build Process and ROM Management + +- **Clean ROM**: The clean, unmodified "The Legend of Zelda: A Link to the Past" ROM should be placed at `Roms/oos169.sfc`. This path is included in `.gitignore`, so the ROM file will not be committed to the repository. +- **Build Script**: A `build.sh` script is provided to automate the build process. For detailed usage, see `Docs/AsarUsage.md`. +- **Workflow**: The build script creates a fresh copy of the clean ROM and applies the `Oracle_main.asm` patch to it using `asar`. +- **Important**: Never apply patches directly to `Roms/oos169.sfc`. Always use the build script to create a new, patched ROM. This ensures the clean ROM remains untouched for future builds. + +## 5. Debugging Tips for BRKs and Crashes When encountering unexpected crashes (often indicated by a `BRK` instruction in emulators), especially after modifying code, consider the following: @@ -92,6 +112,10 @@ When encountering unexpected crashes (often indicated by a `BRK` instruction in - **Check `PHP`/`PLP`:** These save/restore the entire Processor Status Register. Use them when a routine needs a specific P state and you want to restore the caller's state afterwards. - **Stack Corruption:** JSL/JSR push the return address onto the stack. If a called routine pushes too much data onto the stack without popping it, or if the stack pointer (`S`) is corrupted, the return address can be overwritten, leading to a crash when `RTL`/`RTS` is executed. + - **`JSR`/`RTS` vs `JSL`/`RTL` Mismatch:** This is a critical and common error. + - `JSR` (Jump to Subroutine) pushes a 2-byte return address. It **must** be paired with `RTS` (Return from Subroutine), which pulls 2 bytes. + - `JSL` (Jump to Subroutine Long) pushes a 3-byte return address (including the bank). It **must** be paired with `RTL` (Return from Subroutine Long), which pulls 3 bytes. + - Using `RTL` with `JSR` (or `RTS` with `JSL`) will corrupt the stack and almost certainly lead to a crash. Always verify that your subroutine calls and returns are correctly paired. - **Balance Pushes and Pops:** Every `PHA`, `PHX`, `PHY`, `PHP` should ideally have a corresponding `PLA`, `PLX`, `PLY`, `PLP` within the same routine. - **Bank Switching with Stack:** Be extremely careful when performing bank switches (`PHB`/`PLB`, `PHK`/`PLK`) around stack operations, as the stack is in WRAM (bank $7E/$7F). @@ -113,7 +137,12 @@ When encountering unexpected crashes (often indicated by a `BRK` instruction in -## 5. Memory and Symbol Analysis +## 6. Verification Policy + +- **Bugs and Features:** Never mark a bug fix or feature implementation as `DONE` until it has been thoroughly tested and verified in an emulator. This ensures stability and prevents regressions. + + +## 7. Memory and Symbol Analysis This section details the layout and purpose of critical memory regions (WRAM and SRAM) and the symbol definition files that give them context. @@ -160,7 +189,7 @@ This file acts as a central header, defining constants and labels for memory add * **Memory Maps:** It contains the definitive memory maps for WRAM structures, most notably for sprites and ancillae. * **Readability:** Its primary purpose is to replace "magic numbers" (raw addresses) with human-readable labels, which is essential for a project of this scale. -## 6. Disassembly Analysis and Search Guide +## 8. Disassembly Analysis and Search Guide This section provides a high-level analysis of key banks in the Link to the Past disassembly. Use this guide to quickly locate relevant code and understand the overall structure of the game. @@ -694,7 +723,7 @@ This bank is another major collection of advanced sprite and boss logic, complem #### 6.19. Bank $1F: Dungeon Room Data -## 7. ZScream expanded feature ROM map +## 9. ZScream expanded feature ROM map > **Last Updated:** 02/28/2025 > **Note:** All addresses are in PC format unless otherwise stated. diff --git a/Docs/Link.md b/Docs/Link.md new file mode 100644 index 0000000..3989165 --- /dev/null +++ b/Docs/Link.md @@ -0,0 +1,131 @@ +# Bank $07: Core Player (Link) Engine Analysis + +**File**: `ALTTP/bank_07.asm` +**Address Range**: `$078000` - `$07FFFF` + +This bank is dedicated entirely to the player character, Link. It contains his core state machine, which governs everything from movement and physics to item usage and interaction with the world. It is executed every frame that the player has control and is not in a cutscene. + +--- + +### 1. Main Entry Point: `Link_Main` + +* **Routine**: `Link_Main` (`#_078000`) +* **Purpose**: This is the top-level function for all player-related code, called once per frame from the main game loop when the game is in a playable state (e.g., Overworld or Underworld). +* **Functionality**: + 1. It first checks if the player is in a state that prevents control (e.g., a cutscene, indicated by `$02E4` being non-zero). + 2. If the player has control, it calls `Link_ControlHandler`, which is the heart of the player engine. + 3. After the main handler runs, it calls `HandleSomariaAndGraves` to process interactions with those specific objects, which need to be checked every frame. + +--- + +### 2. The Player State Machine: `Link_ControlHandler` + +* **Routine**: `Link_ControlHandler` (`#_07807F`) +* **Purpose**: This function acts as a state machine dispatcher. It reads Link's current state from a single, critical WRAM variable and jumps to the appropriate logic handler for that state. +* **Critical WRAM Variable**: `$7E005D` (`LINKDO`) - This byte holds Link's current state ID. Modifying this value directly forces Link into a different state. + +* **Execution Flow**: + 1. **Damage Check**: Before any other action, the handler checks if Link has taken damage (`$7E0373`, `HURTME`). If so, it processes the damage, checks for the Magic Cape (`$7E0055`), reduces health, and can trigger a state change to `LinkState_Recoil` or the death sequence. + 2. **State Dispatch**: It reads the value of `LINKDO`, multiplies it by two (since each entry is a 2-byte address), and uses it as an index into the `.vectors` jump table (`#_078041`). It then performs a `JMP` to the corresponding state handler routine. + +--- + +### 3. Link State Vector Table + +This table at `#_078041` defines all 31 possible states for Link. Understanding this is key to modifying player behavior. + +| State ID | Label (`#_07....`) | Description | +|:---:|---|---| +| `0x00` | `LinkState_Default` | The normal on-foot state for walking, standing, and most basic interactions. | +| `0x01` | `LinkState_Pits` | Handles the logic for falling into a pit. | +| `0x02` | `LinkState_Recoil` | Handles being knocked back by an enemy or obstacle. | +| `0x03` | `LinkState_SpinAttack` | Manages the spin attack animation and hitbox. | +| `0x04` | `LinkState_Swimming` | The state for swimming in water. | +| `0x05` | `LinkState_OnIce` | Handles movement physics for icy surfaces. | +| `0x06` | `LinkState_Recoil` | A duplicate pointer to the recoil state, likely for a different impact type. | +| `0x07` | `LinkState_Zapped` | A special recoil state for electrical damage. | +| `0x08` | `LinkState_UsingEther` | Handles the animation and logic for using the Ether medallion. | +| `0x09` | `LinkState_UsingBombos` | Handles the animation and logic for using the Bombos medallion. | +| `0x0A` | `LinkState_UsingQuake` | Handles the animation and logic for using the Quake medallion. | +| `0x0B` | `LinkState_HoppingSouthOW` | Manages the multi-frame action of hopping off a ledge to the south. | +| `0x0C` | `LinkState_HoppingHorizontallyOW` | Manages hopping off a ledge to the east or west. | +| `0x0D` | `LinkState_HoppingDiagonallyUpOW` | Manages hopping off a ledge diagonally up-left or up-right. | +| `0x0E` | `LinkState_HoppingDiagonallyDownOW`| Manages hopping off a ledge diagonally down-left or down-right. | +| `0x0F` | `LinkState_0F` | A generic ledge-hopping state. | +| `0x10` | `LinkState_0F` | (Duplicate) A generic ledge-hopping state. | +| `0x11` | `LinkState_Dashing` | The state for running with the Pegasus Boots. | +| `0x12` | `LinkState_ExitingDash` | The brief turn-around animation after a dash collides with a wall. | +| `0x13` | `LinkState_Hookshotting` | Manages Link's state while the hookshot is extended. | +| `0x14`| `LinkState_CrossingWorlds` | Handles the Magic Mirror animation and world transition. | +| `0x15` | `LinkState_ShowingOffItem` | The "item get" pose when Link holds an item above his head. | +| `0x16` | `LinkState_Sleeping` | For the beginning of the game when Link is in bed. | +| `0x17` | `LinkState_Bunny` | The state for when Link is transformed into a bunny in the Dark World. | +| `0x18` | `LinkState_HoldingBigRock` | The state for lifting a heavy, dark-colored rock (requires Titan's Mitt). | +| `0x19` | `LinkState_ReceivingEther` | The cutscene for receiving the Ether medallion from the tablet. | +| `0x1A` | `LinkState_ReceivingBombos` | The cutscene for receiving the Bombos medallion from the tablet. | +| `0x1B` | `LinkState_ReadingDesertTablet` | The cutscene for reading the Desert Palace tablet. | +| `0x1C` | `LinkState_TemporaryBunny` | The brief bunny transformation sequence when entering the Dark World. | +| `0x1D` | `LinkState_TreePull` | The state for pulling on the tree in the haunted grove for the race game. | +| `0x1E` | `LinkState_SpinAttack` | (Duplicate) A second entry for the spin attack state. | + +--- + +### 4. Analysis of Core States + +#### `LinkState_Default` (`#_078109`) + +This is the most complex state and serves as the foundation for player control. It is a large routine that dispatches to numerous sub-handlers. + +* **Initial Checks**: + * `Link_HandleBunnyTransformation`: Checks if Link should transform into a bunny. + * Checks for recoil/damage (`$7E004D`) and branches to a simplified physics handler if necessary. +* **Action Dispatching**: If not recoiling, it checks for player input and calls the appropriate action handler. + * `Link_HandleToss`: Checks if Link is throwing a carried object. + * `Link_HandleAPress`: Handles context-sensitive actions for the A button (talk, read, lift, open, dash). + * `Link_HandleYItem`: Manages using the currently selected item (bow, boomerang, rods, etc.). + * `Link_HandleSwordCooldown`: Manages sword swings and charging a spin attack. +* **Physics and Collision**: If no other action is taken, it processes movement. + * `ResetAllAcceleration`: Clears speed values if Link is standing still. + * `Link_HandleDiagonalCollision` & `Link_HandleCardinalCollision`: Check for collisions with walls and objects. + * `JSL Link_HandleVelocity`: The main physics engine. Applies acceleration, deceleration, and the final movement vector to Link's coordinates. +* **Animation & Camera**: + * `JSL Link_HandleMovingAnimation_FullLongEntry`: Updates Link's sprite graphics based on his direction and action. + * `HandleIndoorCameraAndDoors`: Manages camera scrolling and door transitions indoors. + +#### `LinkState_Recoil` (`#_0786B5`) + +This state demonstrates how control is temporarily taken from the player. + +* **Z-Axis Movement**: It uses `$7E0024` (Link's Z-position) and `$7E0029` (knockback Z-velocity) to handle Link being knocked into the air and falling back down. +* **Timer-Based**: The duration of the recoil is controlled by a countdown timer in `$7E0046` (`INPAIN`). Once the timer reaches zero, Link's state is typically returned to `LinkState_Default`. +* **Collision & Landing**: While in recoil, it still checks for collisions. It also has special checks for landing, such as `Link_SplashUponLanding` if he falls into water, which can change his state to `LinkState_Swimming`. + +#### `LinkState_Bunny` (`#_0783A1`) + +This state shows a persistent change in abilities. + +* **Simplified Controls**: The bunny state has a much simpler control handler. It still allows for movement but disables all item and sword usage. +* **State Check**: It constantly checks for the condition that allows Link to transform back: the presence of the Moon Pearl (`$7EF357`). If the pearl is obtained or Link leaves the Dark World, it triggers the transformation back to the default state. + +--- + +### 5. Key WRAM Variables for Link + +This bank relies on a large number of WRAM addresses to function. Understanding these is critical to debugging or modifying player logic. + +| Address | Label | Description | +|:---:|---|---| +| `$7E005D` | `LINKDO` | **Link's State**: The primary state ID, used as an index for the state machine. | +| `$7E0020/21`| `POSY` | Link's 16-bit Y-coordinate. | +| `$7E0022/23`| `POSX` | Link's 16-bit X-coordinate. | +| `$7E0024` | `POSZ` | Link's 8-bit Z-coordinate (height). | +| `$7E0026` | - | Link's facing direction. | +| `$7E0027/28`| - | Link's Y/X velocity. | +| `$7E002A/2B`| - | Link's Y/X sub-pixel position. | +| `$7E003A` | - | Action flags (bitfield for sword charging, etc.). | +| `$7E0046` | `INPAIN` | Recoil/invincibility timer after taking damage. | +| `$7E004D` | - | A flag indicating Link is in a recoil state. | +| `$7E0303` | - | The ID of the currently selected Y-button item. | +| `$7E0373` | `HURTME` | Damage value to be applied to Link on the next frame. | +| `$7E037B` | - | A flag that temporarily disables taking damage. | +| `$7E0372` | - | A flag indicating Link is currently dashing. | diff --git a/Docs/Ram.md b/Docs/Ram.md new file mode 100644 index 0000000..831d761 --- /dev/null +++ b/Docs/Ram.md @@ -0,0 +1,66 @@ +# RAM Analysis: The Engine's State + +This document provides a high-level analysis of how Work RAM (WRAM) and Save RAM (SRAM) are used to manage the game's state. For a raw list of addresses, see `Core/ram.asm` and `Core/sram.asm`. + +## 1. The Core Game Loop: WRAM in Motion + +The entire game is driven by a master state machine whose state is stored in a single WRAM variable: + +- **`MODE` (`$7E0010`):** This is the game's primary state index. The main loop in `bank_00.asm` reads this value every frame and jumps to the corresponding module in the `Module_MainRouting` table. +- **`SUBMODE` (`$7E0011`):** Many modules have their own internal state machines. This variable holds the sub-state for the current `MODE`. + +This `MODE`/`SUBMODE` pattern is the fundamental driver of the game's flow. For example: +- When Link opens the menu, the game sets `MODE` to `0x0E` (Interface), which gives control to the menu engine. +- When Link talks to a character, `Interface_PrepAndDisplayMessage` is called, which saves the current game state to `MODECACHE` (`$7E010C`) and then sets `MODE` to `0x0E` to display the text box. When the dialogue is finished, the previous state is restored from the cache. +- Transitioning between the overworld and underworld involves setting `MODE` to `0x08` (Overworld Load) or `0x06` (Underworld Load), respectively. + +## 2. Defining the World: Location and Environment + +The player's location and the properties of their environment are controlled by a handful of key WRAM variables. + +- **`INDOORS` (`$7E001B`):** A simple but powerful flag (`0x01` for indoors, `0x00` for outdoors). This variable is checked by numerous systems to alter their behavior. For instance, the `ZSCustomOverworld` system reads this flag to determine whether to apply day/night palettes, and the audio engine uses it to select the appropriate music track. + +- **`OWSCR` (`$7E008A`) and `ROOM` (`$7E00A0`):** These variables store the player's current location. `OWSCR` holds the Overworld screen ID, while `ROOM` holds the Underworld room ID. + +The interaction between these variables is central to world traversal. When Link enters a cave on `OWSCR` 0x35, the following happens: +1. The game looks up the entrance data for that tile in `Overworld/entrances.asm`. +2. This data specifies the destination `ROOM` ID (e.g., 0x0104). +3. The `INDOORS` flag is set to `0x01`. +4. The main game `MODE` is set to `0x06` (Underworld Load). +5. The dungeon engine in `bank_01.asm` takes over. It reads the `ROOM` ID and uses it to look up the room's header in `ALTTP/rooms.asm`. This header contains pointers to all the data needed to draw the room, including its layout, objects, and sprites. + +## 3. Room-Specific Behavior + +Once a room is loaded, its specific behavior is governed by tags and flags. + +- **`TAG1`/`TAG2` (`$7E00AE`/`$AF`):** These are "Room Effect" tags loaded from the room's header. They trigger special behaviors like kill rooms, shutter doors, or custom events defined in `Dungeons/custom_tag.asm`. For example, a kill room tag will cause the `Underworld_HandleRoomTags` routine to check if all sprites in the room (`$7E0E20+`) have been defeated. + +- **`UWDEATH` (`$7FDF80`) and `OWDEATH` (`$7FEF80`):** These are large bitfields in SRAM that track the state of every overworld screen and underworld room. When a kill room is cleared or a key is taken from a chest, a bit is set in this array. This ensures that the state persists permanently in the save file, preventing enemies from respawning or chests from reappearing. + +## 4. The Player and Entities + +- **Link:** The player's state is managed by its own state machine in `bank_07.asm`, with the current state held in `LINKDO` (`$7E005D`). This is covered in detail in `Docs/Link.md`. + +- **Sprites and Ancillae:** The WRAM regions from `$7E0D00` onwards are large arrays that hold the state of all active entities in the game (16 sprites, ~40 ancillae). These are defined as `structs` in `Core/structs.asm`. While there are dozens of variables for each sprite, the most important for general game logic are: + - `SprState` (`$7E0DD0,X`): The sprite's main state (e.g., `0x09` for active, `0x0B` for stunned). + - `SprType` (`$7E0E20,X`): The sprite's ID number. + - `SprX`/`SprY` (`$0D10,X`/`$0D00,X`): The sprite's coordinates. + + The sprite engine in `bank_06.asm` iterates through these arrays each frame, executing the logic for each active sprite. + +## 5. Long-Term Progression: SRAM and Custom Flags + +SRAM (`$7EF000+`) stores the player's save file and is the key to managing long-term quest progression. Oracle of Secrets heavily expands the vanilla save format to support its new data-driven systems. + +- **`OOSPROG` (`$7EF3D6`) and `OOSPROG2` (`$7EF3C6`):** These are the primary bitfields for tracking major and minor quest milestones. They are the heart of the game's custom progression. + - **Example Flow:** + 1. The player talks to the `village_elder` NPC for the first time. + 2. The NPC's code in `Sprites/NPCs/village_elder.asm` sets a specific bit in `OOSPROG` (e.g., `ORA.b #$10 : STA.l OOSPROG`). + 3. Later, the world map code in `Overworld/world_map.asm` checks this bit (`LDA.l OOSPROG : AND.b #$10`). If it's set, a new icon is displayed on the map. + +- **Other Custom SRAM:** The project adds many other custom variables to SRAM to track new systems, such as: + - **New Inventory:** `ZoraMask` (`$7EF347`), `RocsFeather` (`$7EF34D`), etc. + - **Side-Quests:** `MagicBeanProg` (`$7EF39B`) tracks the growth of a magic bean over time. + - **New Collectibles:** A block starting at `$7EF38B` tracks items like `Bananas` and `Seashells`. + +This data-driven approach, centered on modifying and checking flags in SRAM, allows for complex, stateful quest design that persists across play sessions. \ No newline at end of file diff --git a/oracle.org b/oracle.org index 6ae6d45..e9bb119 100644 --- a/oracle.org +++ b/oracle.org @@ -1,479 +1,385 @@ -#+title: Oracle of Secrets -#+author: @scawful +#+title: Oracle of Secrets - Project Tracker +#+author: @scawful & Gemini #+todo: TODO(t) ACTIVE(a) | DONE(d) CANCELED(c) -#+options: H:4 tags:t +#+options: H:5 tags:t #+startup: content -* Oracle of Secrets +* Project Dashboard & Epics - ROM Hack for The Legend of Zelda: A Link to the Past - Based on the Oracle series and using elements from Minish Cap, Link's Awakening, and other Zelda games. +This section provides a high-level overview of the major development efforts (Epics). Each epic groups together numerous smaller tasks from the sections below. - - Plot Doc: https://docs.google.com/document/d/106e_dnY0EAjm3l416l4NDnpRjlUMFH8EKN_o7eiC77c - - Data Sheet: https://docs.google.com/spreadsheets/d/17mfAUalrYgu6Is1LNPlRBbqniAvRg5eNPOg7AQZ-b4U/ +- *Epic: Core Infrastructure Refactor* + - Goal: Improve code quality, readability, and maintainability across all major systems. + - Related Sections: [[Technical Debt & Refactoring]] -* Infrastructure and Organization Improvements +- *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 outlines suggestions for improving the overall structure and maintainability of the "Oracle of Secrets" codebase, primarily by leveraging advanced features of asar. +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. -**Rationale:** As the project grows, a well-organized codebase becomes crucial for efficient development, debugging, and long-term maintenance. These suggestions aim to increase modularity, reduce errors, and improve readability. - -*** TODO Reorganize Patches into a Dedicated File +** General Infrastructure +*** TODO [#B] Reorganize All Patches into a Central File :PROPERTIES: - :ID: infra-patches + :ID: infra-patches-all :END: - - *Current State:* Numerous small `org` patches are located at the end of =Sprites/all_sprites.asm=. - - *Suggestion:* Create a new top-level file, perhaps =Core/patches.asm=, and move all vanilla code patches there. This file can be organized by bank or functionality. - - *Benefits:* - - **Separation of Concerns:** =all_sprites.asm= would only be responsible for including sprite code, not patching the ROM. - - **Maintainability:** Centralizes all direct modifications to original code, making them easier to find, manage, and debug. + - *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 Use ~incbin~ for All Binary Data +*** TODO [#C] Leverage ~struct~ for Complex Data Structures :PROPERTIES: - :ID: infra-incbin + :ID: infra-structs :END: - - *Current State:* GFX data is already well-handled with `incbin`. This is a reminder to continue this practice for all non-code data. - - *Suggestion:* Ensure all graphics, palettes, level data, etc., are included via `incbin`. - - *Benefits:* - - **Cleanliness:** Keeps assembly files focused on logic. - - **Tooling:** Allows for easier use of external tools to edit binary data. + - *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 Leverage ~struct~ for Complex Data +*** TODO [#C] Convert Manual Jump Tables to Use ~table~ :PROPERTIES: - :ID: infra-structs + :ID: infra-tables :END: - - *Current State:* RAM addresses are defined with labels (e.g., in =Core/ram.asm=). This is standard, but for complex related data, it can be improved. - - *Suggestion:* Use asar's `struct` directive for things like sprite state, player data, or complex SRAM layouts. - - *Benefits:* - - **Clarity:** Defines data structures in a high-level, readable format. - - **Maintainability:** Reduces "magic numbers" when accessing data fields. If the structure changes, you only need to update the `struct` definition. + - *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 Use ~table~ for Jump Tables +*** TODO [#C] Document the Dialogue System :PROPERTIES: - :ID: infra-tables + :ID: infra-dialogue-docs :END: - - *Current State:* Jump tables are created manually with `dw` directives, like in =Items/all_items.asm= for =Link_ConsumeMagicBagItem=. - - *Suggestion:* Use the `table` directive to create these tables automatically. - - *Benefits:* - - **Simplicity:** Less boilerplate code. - - **Safety:** Can help prevent errors from misaligned table entries. + - *Goal:* Create comprehensive documentation for the game's dialogue and text rendering system. + - *Blocker For:* [[quest-goron-mines]] (Garo NPC). -*** TODO Combine custom room tags into a table system +** Time System (=Overworld/time_system.asm=) +*** TODO [#B] Refactor Time System [0/3] :PROPERTIES: - :ID: infra-roomtags + :ID: refactor-time-system :END: - - *Current State:* Custom room tags are defined in =Dungeons/crumblefloor_tag.asm= and similar files. - - *Suggestion:* Create a unified table system for all custom room tags, possibly in a new file like =Dungeons/room_tags.asm=. - - *Benefits:* - - **Organization:** Easier to find and manage all custom room tags. - - **Extensibility:** Simplifies adding new tags in the future. + - *Analysis:* The system is functional but monolithic and uses many magic numbers. + - *Tasks:* + - [ ] Group all time-related variables (`Hours`, `Minutes`, `TimeSpeed`, color values) into a single `TimeState` struct. + - [ ] Convert all logic blocks (`RunClock`, `DrawClockToHud`, `ColorSubEffect`) into proper `subroutine`s. + - [ ] Break down the large `RunClock` routine into smaller, single-purpose functions (e.g., `TimeSystem_CheckCanRun`, `TimeSystem_IncrementTime`, `TimeSystem_UpdatePalettes`). -* Levels -** ~S0~ Shrine of Origins -*** Item: Moon Pearl -Located in the Temporal Pyramid where you get transported after your first encounter with Kydrog. +** Minecart System (=Sprites/Objects/minecart.asm=) +*** TODO [#B] Refactor Minecart System [0/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:* + - [ ] 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. -** =D1= Mushroom Grotto -*** Item: Bow -*** Miniboss: Vampire Bat -*** Boss: Mothra -Located in the Mushroom Grotto west of the Maku Tree and Wayward Village +** 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]]. -** =D2= Tail Palace -*** Boss: Big Moldorm (Vanilla) -*** Item: Roc's Feather +** Menu System (=Menu/=) +*** TODO [#B] Refactor Menu System [0/2] + :PROPERTIES: + :ID: refactor-menu + :END: + - *Analysis:* The menu system is robust but has some duplicated code and hardcoded values. + - *Tasks:* + - [ ] Refactor the input handling logic for the Magic Bag, Song Menu, and Ring Box sub-menus into a single, reusable subroutine. + - [ ] Replace all hardcoded menu state values (e.g., `LDA.b #$0C`) with named constants (e.g., `!MENU_STATE_MAGIC_BAG = $0C`). -** =D3= Kalyxo Castle -*** Boss: Armos Knights (Vanilla) -*** Item: Meadow Blade (Lv2 Sword) -*** TODO: Castle Guard Ambush Sequence using overlord sprites and dungeon warp - - [ ] Idea needs fleshing out by @scawful +** 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. -** ~S1~ Shrine of Wisdom -*** Item: Zora Flippers -*** TODO [#C] Shrine of Wisdom Swamp Overworld Improvements :planning: - - [ ] Warp Zones to return the player to the start in case they screw up. - - [ ] Shrubs with Plentiful magic restoring items - - [ ] NPCs to help navigate the player. - - [ ] A possible heart-piece/treasure to reward curious players for venturing off the intended route. +* System Integration & Bugs + :PROPERTIES: + :CATEGORY: Integration + :END: -** =D4= Zora Temple -*** Boss: Advanced Arrghus (Vanilla variant) -*** Item: Hookshot, Zora Mask -*** TODO [#B] Zora Temple Tasks [0/2] :code:bugfix: - - [ ] Zora Follower Sprite Logic - - [ ] Fix Water Gate Collision +This section tracks known conflicts between systems and outstanding bugs. -** =D5= Glacia Estate -*** Boss: Twinrova -*** Item: Fire Rod -*** TODO [#B] Glacia Estate Tasks [0/4] :design:polish: - - [ ] Improve Ice Block sprite collision detection - - [ ] Tune enemies in dungeon, adjust positioning - - [ ] Exterior gfx improvements - - [ ] Add indicator for pushable block in ice puzzle +*** 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. -** ~S2~ Shrine of Power -*** Item: Power Glove -*** TODO [#A] Shrine of Power Tasks [0/3] :design: - - [ ] Fix collision of lava pit corner tiles +*** 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. -** =D6= Goron Mines -*** Boss: King Dodongo (Helmasaur variant) -*** Miniboss: Lanmolas (Large room variant) -*** Item: Hammer -*** Dungeon Ideas - - Goron Follower - - Requires gfx - - Affects `Dungeons/crumblefloor_tag.asm` cracks, can fall down - - Lifting `Sprites/Objects/minecart.asm` to another location - - only works if it is a small corridor so he can't walk back another route - - a puzzle similar to star puzzle in minish grotto? - (if you step on the same star twice, you fail the puzzle). - - walk to the other side of the room without any part of the floor falling down. - enemies or other things can make it difficult for you. - If you fail, the door to the next room wont open. - - only some parts of thefloor are normal and other parts break. - you put an item in front of you but if it ends up on weak parts of the floor - it falls down and you have to start over. - kind of like somaria block try and error on invisible floors - - when you enter the room there are already cracks on the floor. - you need an item to fix the floor so that you can walk over it once. - maybe the song of healing - - make a crack and fall down in the right place - so that you end up in the right place on the floor below +*** TODO [#A] Resolve ZSOW vs. Lost Woods Conflict + :PROPERTIES: + :ID: bug-zsow-lostwoods + :END: + - *Analysis:* The `lost_woods.asm` puzzle directly conflicts with `ZSCustomOverworld.asm`'s transition handler. + - *Task:* Refactor `lost_woods.asm` into a proper `JSL`-callable subroutine (`LostWoods_PuzzleHandler`). + - *Implementation:* Modify the `OverworldHandleTransitions` routine in `ZSCustomOverworld.asm` to check if the current area is the Lost Woods (`#$29`) and call the new handler. The handler should return a status indicating if it has overridden the transition. + +*** ACTIVE [#A] ZSOW vs. Day/Night Sprites + :PROPERTIES: + :ID: bug-zsow-daynight + :END: + - *Status:* Regression. The previous fix attempt introduced a `BRK` crash. + - *Task:* Triage the crash to identify the root cause and develop a new solution for integrating day/night sprite loading with ZSOW. + +*** ACTIVE [#A] ZSOW vs. Song of Storms + :PROPERTIES: + :ID: bug-zsow-storms + :END: + - *Status:* In progress. + - *Blocker:* This task is blocked by the `ZSOW vs. Day/Night Sprites` regression, as they may be related. + +*** 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. -** =D7= Dragon Ship -*** Boss: KydrogBoss -*** Item: Somaria Rod *** TODO [#C] Dragon Ship Tasks [0/1] :design: - - [ ] Extended section??? + :PROPERTIES: + :ID: content-dragon-ship + :END: + - [ ] Flesh out ideas for an extended section. -** ~S3~ Shrine of Courage -*** Boss: Vaati (Vitreous variant) -*** Item: Mirror Shield +*** 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. -** ~S4~ Bonus Shrine (Underwater Eon Abyss) -*** Item: Red Tunic +*** 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. -** =D8= Fortress of Secrets -*** Boss: Dark Link -*** Item: Portal Rod +** Quests & Narrative Sequences +*** ACTIVE [#A] Zora Sanctuary Questline [2/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. + - [ ] Implement waterfall opening event using Song of Storms. This will require coordination between =Items/ocarina.asm= and =Overworld/overlays.asm=. -** =D9= Eon Core (Endgame) -*** Boss Part 1: Kydreeok (Kydrog Gleeok variant) -*** Boss Part 2: Ganon -*** Item: Triforce - -* Quests -** Main Quests -*** Lost Ranch Girl Quest - 1) Get Mushroom from Old Woman house in Mushroom Grotto - 2) Trade Mushroom to Potion Shop - 3) Leave Mountains and return to Potion Shop later for Magic Powder - 4) Use Magic Powder on Cucco in the Ranch House for Ocarina - -*** Mask Salesman Quest - 1) Requires Ocarina from Lost Ranch Girl Quest - 2) Mask Salesman teaches Song of Healing - 3) Play Song of Healing for Deku NPC near the shop for Deku Mask - -*** TODO [#B] Tail Palace Kiki Quest [1/2] :quest:code: -1) [ ] Kiki asks for Bananas instead of Rupees -2) [X] Deku NPCs inhabit Tail Palace OW after dungeon completion - -*** Book of Secrets - 1) Play Song of Healing for sick village child for Running Boots - 2) Use Running Boots to get the Book from the village library. -**** TODO Journal mode :menu: - - [ ] Track quests completed - - [ ] Track items obtained - - [ ] Track dungeon completion - -*** TODO [#A] Kalyxo Castle Questline :quest: -**** Bridge Opening -+ Requires Book of Secrets from Wayward Village library. -**** TODO Prison Sequence [0/2] :sequence:code: - 1) [ ] Occurs after obtaining the Meadow Blade in Kalyxo Castle - 2) [ ] Ambushed by castle guards and locked away in castle prison dungeon room - 3) [ ] Escape the prison cell and sneak past guards to exit the castle using minish form, - requires minish dungeon object tile types and interactions with `probe_ref.asm` (unused) - to do player detection by guards. - -*** ACTIVE [#A] Zora Sanctuary Questline [2/2] :quest: - - [X] Meet lone Sea Zora left at the Sanctuary, learn of Zora Princess - - [X] Conflict over territory lead to Zora Princesses imprisonment - - [ ] Waterfall Song of Storms Event apart of `Items/ocarina.asm` and `Overworld/overlays.asm` - -*** Old Man Mountain Quest - 1) Take the warp portal at the northwest most point on Mount Snowpeak - 2) Enter the Lava Lands cave to find the Old Man. - 3) Escort the Old Man to a rock formation on the mountain and use magic mirror. - 4) Receive the Goldstar before continuing to Glacia Estate +*** 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: - 1) [X] Collectible Goron Rock Meat from Lupo Mountain - - Eon Gorons workers protesting labor, Piratians involved somehow - - Requires Power Glove from Shrine of Power - 2) [X] Kalyxian Goron NPC in the desert asks for five sirloins to open the mines. - 3) [ ] Garo NPC easter egg warps around the map - 4) [ ] Gossip Stones provide some hint related to the Shrines? + :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. -** Side Quests -*** Masks for Sale -**** Bunny Hood - 100 Rupees -**** Stone Mask - 850 Rupees -*** Wolf Mask Quest - 1) Wolfos appears outside of Kalyxo Castle at Night, defeat and play Song of Healing for Wolf Mask. -*** DONE Magic Bean Quest [4/4] :quest: - 1) [X] Buy Magic Bean from Bean Vendor, requires Bottle. - 2) [X] Take Magic Bean to the Ranch and plant it in empty soil north of the houses. - 3) [X] Requires rain (Song of Storms), Pollination (Good Bee) and 3 in game days. - 4) [X] Flower the player can ride to a heart container appears. -*** TODO [#C] Swordsmith Rescue [0/3] :quest: - 1) [ ] Use the Bomb Shop Big Bomb in the Eon Abyss Beach - 2) [ ] Return the Lost Brother to the Smiths house west of Waywrd Village - 3) [ ] Swordsmith brothers improve your Meadow Blade to the Tempered Sword (Lv3) -*** TODO [#C] Korok Cove :quest: - 1) [ ] Find the Korok Cove entrance in graveyard - 2) [ ] Hide and seek minigame with `Sprites/NPCs/korok.asm` -*** TODO [#C] East Kalyxo Zora River Region :quest: - 1) [ ] Use the flippers to swim down the river east of Korok Cove - 2) [ ] Find the hidden grotto with a heart piece - 3) [ ] Come up with more ideas for this area -*** TODO [#C] Fishing Minigame :minigame: -*** TODO [#B] Sky Area Special Overworld Events :quest: - - [ ] Song of Soaring to access Sky Area - - [ ] Sky Area NPCs and Enemies - - Ideas for Cloud area (weather puzzles) - - Some clouds are very thin and Link will fall through them if he is not minish Link. - - Other clouds have strong wind currents so Minish Link will be blown away immediately. - - Some clouds are too far apart to jump over with Roc's feather or hookshot. Then you have to use the flute and switch between sun and rain: New cloud platforms will appear when it rains (water fills them) - - Some clouds are charged with electricity and damage Link if you walk on them. Play the flute to get sunshine so they turn into normal clouds. Or maybe somehow lead the electricity to a mechanism that opens a gate? (for example, playing the melody again so that a normal cloud becomes a thundercloud and conducts the electricity further) -*** TODO [#B] Dream Sequences [0/6] :sequence: - - [ ] 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] 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. -* Items -** Y Items -| Name | Description | -|-----------------+----------------------------------------------| -| Bow | Vanilla | -| Boomerang | Vanilla | -| Hookshot | Goldstar ball and chain upgrade, L/R to swap | -| Bombs | Vanilla | -| Magic Powder | Press A on menu to open Magic Bag | -| Hammer | Vanilla | -| Lamp | Vanilla | -| Fire Rod | Vanilla | -| Ice Rod | Freezes water tiles to walk on | -| Magic Mirror | Allows dual warping with all essences | -| Ocarina | Song of Storms, Soaring, Time, Healing | -| Book of Secrets | Activates special overworld events | -| Cane of Byrna | Vanilla | -| Fishing Rod | Press Y to cast reel in water | -| Portal Rod | Press Y to create blue and orange portals | -| Roc's Feather | Press Y to jump | -| Deku Mask | Shoot magic bubbles, interact with Deku leaf | -| Zora Mask | Press Y to dive underwater | -| Wolf Mask | Press Y to dig for treasure | -| Bunny Hood | Press R to transform and run faster | -| Stone Mask | Reskinned Magic Cape | -| Bottles | No longer requires Bug Catching Net to use | +*** 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 -** Equipment -| Name | Location | -|----------------------+--------------------------| -| Moon Pearl | Shrine of Origins | -| Small Sword (Lv1) | Forest of Dreams | -| Small Shield (Lv1) | Forest of Dreams | -| Meadow Blade (Lv2) | Kalyxo Castle | -| Tempered Blade (Lv3) | Swordsmiths Hut | -| Master Sword (Lv4) | Temporal Pyramid | -| Hero Shield | Shops | -| Mirror Shield | ??? | -| Blue Tunic | Zora Sanctuary Waterfall | -| Red Tunic | Shrine of ?????? | -| Power Glove | Shrine of Power | -| Titans Mitt | Fortress of Secrets? | -| Running Boots | Sick Kid Wayward Village | +*** 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. -** Rings -| Name | Description | -|----------------+----------------------------------| -| Power Ring | Increase attack | -| Armor Ring | Increase defense | -| Heart Ring | Slowly regenerate health | -| Light Ring | Sword beams work at -2 hearts | -| Blast Ring | Higher bomb damage, bombos class | -| Steadfast Ring | No knockback | +*** 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 -** Ocarina Songs -| Name | Effect | -|----------------+---------------------------------------------| -| Song of Storms | Makes it rain and grow plants | -| Song of Soaring| Warp to previously visited locations | -| Song of Time | Change day to night and vice versa | -| Song of Healing| Heals a character and gives Deku Mask | +*** 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 -** NPCs -*** Impa -*** Maku Tree -*** Ranch Girl -*** TODO Garo -*** [#0A] Kaepora Gaebora / Eon Owl - - Return to the Hall of Secrets with Six Essences - - Kaepora Gaebora teaches you the Song of Soaring -*** [#0E] Piratian -*** [#07] Bean Vendor / Village Elder -*** [#22] Tingle - - Player can buy maps for each dungeon from Tingle -*** [#25] Village Dog -*** [#39] Sea Zora Baby -*** [#73] Farore -*** [#A0] Deku Scrub (Mask) and NPCs -*** [#B8] Zora Princess and NPCs -*** [#D7] Vasu -*** [#E8] Happy Mask Salesman -*** [#F0] Mermaid / Maple / Librarian -*** [#F1] Korok -*** [#F2] Goron -** Bosses -*** [#88] Manhandla -*** Advanced Arrghus -*** King Dodongo -*** [#CE] Twinrova -*** [#C1] Dark Link -*** Kydrog -*** [#7A] Kydreeok -** Enemies -*** [#05] Helmet Chuchu -*** [#14] Business Scrub (Kaly/Eon) -*** [#1D] Darknut (Eon) -*** [#2C] Goriya -*** Octorok (Kaly/Eon) -**** TODO Water Octorok -*** [#A4] Pols Voice -*** [#A8] Anti-Kirby -*** [#A9] Wolfos -**** Castle Variant -**** TODO Ice Variant -*** [#AE] Sea Urchin (Kaly/Eon) -*** [#B1] Puffstool -*** [#EF] Poltergeist -*** [#CC] Booki -*** [#CD] Thunder Ghost -** Objects -*** Collectibles -*** Deku Leaf -*** [#D5] Ice Block -*** Minecart -*** Mineswitch -*** Switch track -*** Portal Sprite -* Tasks -** DONE Add Librarian translations -** DONE Goron Mines Opening Animation [2/2] -- [X] Setup Goron Sprite - - [X] Kalyxian Variant - - [X] Eon Abyss Variant -- [X] Animate mines opening animation +** 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. -** DONE Fortress of Secrets Cutscene -Should use the Ganons Tower Crystal Cutscene as the base. +*** 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. -** DONE Fix Minecart mechanics [3/3] -- [X] Follower cart controls -- [X] Tile behavior for follower cart mode -- [X] Center based hitbox detection +*** 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. -** ACTIVE [#B] Collectible Item Quests [2/6] :quest: -- [ ] Bananas -- [X] Pineapples -- [X] Rock Meat -- [ ] Seashells -- [ ] Honeycombs -- [ ] Deku Sticks +*** 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. -** ACTIVE [#A] Add Dungeon Maps [0/11] :assets:map: -Apart of yaze dungeon map editor task. -- [ ] Mushroom Grotto -- [ ] Tail Palace -- [ ] Kalyxo Castle -- [ ] Zora Temple -- [ ] Glacia Estate -- [ ] Goron Mines -- [ ] Dragon Ship -- [ ] Fortress of Secrets -- [ ] Shrine of Wisdom -- [ ] Shrine of Power -- [ ] Shrine of Courage +** 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. -** TODO [#A] Update Kydrog boss [1/3] :boss:code: -- [X] Track offspring sprites spawned, more dynamic spawns -- [ ] Improve Kydrog movement, add additional stage in fight -- [ ] Cinematic opening and ending cutscene with dialogue - -** TODO [#A] Update Kydreeok boss [0/9] :boss:code: -- [ ] Improve fireball attack -- [ ] Improve head/neck rotation -- [ ] pause and neck stretch out attack ala Chain Chomp style -- [ ] neck stretch out and spin around the main body while shooting fire attack -- [ ] A bone throwing attack in the second half -- [ ] heads detach after you kill them and then float around the room like the original gleeok or like blind And then re-attach themselves instead of having them just pop back in like you have it now You could do it in both phases or just in the second bone phase -- [ ] bullet hell section where it just sucks in its heads so you can't hit it and then just shoots fireballs in every direction -- [ ] function that checks if you hit the head and if you do, don't electrocute the player to avoid some potential frustration there -- [ ] pre-fight transformation cutscene with kydrog - -** TODO [#C] End Credits :sequence: - -* Timeline +* Reference +** Timeline | Event | Items | |-------------------+----------------------| | Start Game | Lamp | | Shrine of Origins | Moon Pearl | | Forest of Dreams | Lv1 Sword and Shield | -| | | +| ... | ... | - -- Beginning - - Farore Intro - - GameState 7EF3C5:02 - - StoryState B6:01 - - Kydrog Intro - - OosProg2 7EF3C6:04 - - IntroFlag 7EF300:01 - - Maku Tree Return from Eon Abyss - - OosProg 7EF3D6:02 - -- Kalyxo General - - Impa Hall of Secrets - - OosProg 7EF3D6:04 - - Village Elder - - MAPICON interaction - - Ranch Kid - - MAPICON interaction - -- Toadstool Woods Mushroom -> Magic Powder from Potion Shop -- Magic Powder -> Ocarina from chicken at Toto Ranch -- Ocarina -> Song of Healing from Mask Salesman near village -- Song of Healing -> Deku Mask from Deku Scrub near Mask Shop -- Song of Healing -> Running Boots from Sick Kid in village -- Running Boots -> Book of Secrets from village library - -- Book of Secrets - - Lifts the Kalyxo Castle gates - -* ROM Map +** 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 @@ -490,20 +396,16 @@ ZS reserves everything up to 1.5mb or up to 0x150000 | 0x138000 - 0x13FFFF | Expanded dungeon object data | | 0x140000 - 0x147FFF | Custom overworld data | | 0x148000 - 0x14FFFF | Expanded dungeon object data | -| | | -* Credits +** 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 @@ -512,4 +414,4 @@ Spacewiki - Beta Testing Evolvingfetus - Beta Testing Discodragn - Beta Testing BIGLOU - Beta Testing -HonorThyFamily - Beta Testing +HonorThyFamily - Beta-Testing \ No newline at end of file