oracle-of-secrets/Docs/Menu.md

Custom Menu & HUD System

This document provides a detailed analysis of the custom menu and Heads-Up Display (HUD) systems in Oracle of Secrets, based on the code in the Menu/ directory.

1. Overview

The project features a completely custom menu and HUD, replacing the vanilla systems. The menu is a robust, multi-screen system, while the HUD provides a clean, modern interface for in-game stats.

• Menu System: A two-page design that separates selectable items from quest status and equipment. It is accessible by pressing the Start button.
• HUD System: A persistent on-screen display for health, magic, rupees, and the currently equipped item.

2. Menu System Architecture

The entire menu operates as a large state machine, with the main entry point being Menu_Entry in Menu/menu.asm. The flow is controlled by the value in WRAM $0200.

2.1. Main State Machine

The Menu_Entry routine uses a jump table (.vectors) to execute different subroutines based on the state in $0200. This modular approach allows for a clean separation of tasks like initialization, drawing, input handling, and screen transitions.

Key States in $0200:

State ID	Label	Purpose
0x00	Menu_InitGraphics	Initializes the menu, clears player state, and prepares for drawing.
0x01	Menu_UploadRight	Draws the entire right-hand screen (Quest Status).
0x02	Menu_UploadLeft	Draws the entire left-hand screen (Item Selection).
0x04	Menu_ItemScreen	The main interactive state for the Item screen. Handles cursor movement.
0x05	Menu_ScrollTo	Handles the smooth scrolling animation when moving from Items to Quest.
0x06	Menu_StatsScreen	The main interactive state for the Quest Status screen.
0x0A	Menu_Exit	Exits the menu, restores the game state, and updates the equipped item.
0x0C	Menu_MagicBag	A sub-menu for viewing collectible items.
0x0D	Menu_SongMenu	A sub-menu for selecting Ocarina songs.
0x0E	Menu_Journal	A sub-menu for reading the player's journal.
0x09	Menu_RingBox	A sub-menu for managing magic rings.

2.2. Item Selection Screen (Left Page)

This is the primary interactive screen where the player selects their Y-button item.

• Drawing (DrawYItems): This routine is responsible for rendering all 24 item slots. It reads the SRAM address for each slot from Menu_AddressIndex (menu_select_item.asm), checks if the player owns the item, and then calls DrawMenuItem.
• DrawMenuItem: This generic function is the core of the drawing system. It takes an item's SRAM value (e.g., Sword level 0-4) and uses it to look up the correct 16x16 tile data from a large graphics table in Menu/menu_gfx_table.asm. This makes the menu highly data-driven.
• Selection (menu_select_item.asm): Cursor movement is handled by Menu_FindNextItem, Menu_FindPrevItem, etc. These routines intelligently skip over empty slots, ensuring the cursor always lands on a valid item. The currently selected slot index is stored in $0202.

2.3. Quest Status Screen (Right Page)

This screen is a static display of the player's overall progress.

• Drawing: It is rendered by a series of functions in menu_draw.asm, including:
  • Menu_DrawQuestItems: Draws equipped sword, shield, tunic, etc.
  • Menu_DrawPendantIcons & Menu_DrawTriforceIcons: Reads SRAM flags to draw collected pendants and crystals.
  • Menu_DrawCharacterName: Reads the player's name from SRAM and renders it.
  • DrawLocationName: Reads the current overworld area ($008A) or underworld room ($00A0) and looks up the corresponding name from the tables in menu_map_names.asm.

3. HUD System Architecture

The HUD is a separate system that hooks the vanilla game's NMI rendering routines. Its main entry point is HUD_Update in Menu/menu_hud.asm.

• Functionality: The HUD_Update routine runs every frame during gameplay. It reads player stats directly from SRAM and WRAM and draws them to the VRAM buffer for the top of the screen.
• Key Drawing Logic:
  • Hearts: HUD_UpdateHearts is a loop that draws empty hearts based on MAXHP ($7EF36C) and then overlays full/partial hearts based on CURHP ($7EF36D).
  • Magic Meter: It reads MagicPower ($7EF36E) and uses the MagicTilemap lookup table to find the correct tiles to display the green bar.
  • Counters: It uses a HexToDecimal routine to convert the values for Rupees, Bombs, and Arrows into drawable digits.
  • Equipped Item: HUD_UpdateItemBox reads the currently equipped item index ($0202), finds its graphics data in the HudItems table, and draws the icon in the top-left box.

4. Data-Driven Design & Areas for Improvement

The entire menu and HUD are heavily data-driven, which is a major strength.

• Graphics: All item icons for both the menu and HUD are defined in data tables in menu_gfx_table.asm and menu_hud.asm, not hardcoded.
• Item Layout: The position and SRAM address of every item in the menu are defined in the Menu_ItemCursorPositions and Menu_AddressIndex tables, allowing the layout to be easily changed.
• Text: Item names, location names, and other text are all stored in data tables in menu_text.asm and menu_map_names.asm.

This analysis confirms the suggestions in the placeholder Menu.md file:

1. Refactor Redundant Code: The input handling logic for the Magic Bag, Song Menu, and Ring Box is nearly identical and is a prime candidate for being refactored into a single, reusable subroutine.
2. Use table for Jump Tables: The main Menu_Entry jump table is created with manual dw directives and would be cleaner and safer if generated with asar's table directive.
3. Replace Hardcoded Values: Hardcoded state values (e.g., LDA.b #$0C : STA.w $0200) should be replaced with named constants (!MENU_STATE_MAGIC_BAG = $0C) for readability and maintainability.