oracle-of-secrets/Docs/World/Overworld/TimeSystem.md

Time System (Overworld/time_system.asm)

Overview

This system manages the in-game clock, day/night cycle, and associated palette effects. It runs continuously, updating the time and adjusting visual elements like the sky color and sprite palettes based on the current hour.

Key Functionality

• Clock: A 24-hour clock is maintained in SRAM (Hours at $7EE000, Minutes at $7EE001).
• Palette Modulation: The core of the system is ColorSubEffect, which subtracts values from the red, green, and blue components of palettes based on the time of day, using lookup tables.
• Time-Based Events: The system checks for daily events (like the Magic Bean quest) and handles time manipulation effects (like the Song of Time).
• HUD Display: It includes logic to draw the current time to the HUD.

Analysis & Areas for Improvement

The time system is functional but could be significantly improved in terms of structure, readability, and maintainability.

1. Move Patches to Core/patches.asm

• Observation: The file contains numerous org patches that modify vanilla game logic to hook in the time system.
• Suggestion: Relocate all org blocks to the centralized Core/patches.asm file. This is the most important cleanup step.
• Benefit: This will separate the new system's implementation from the act of patching it into the original code, making both parts easier to understand and manage.

2. Use a struct for Time-Related Variables

• Observation: Time-related variables are defined as individual labels pointing to SRAM addresses (e.g., Hours, Minutes, TimeSpeed, !BlueVal).

• Suggestion: Group these related variables into a single struct.

  Example:

  struct TimeState
    Hours     db
    Minutes   db
    TimeSpeed db
    ; ... other vars ...
    BlueVal   dw
    GreenVal  dw
    RedVal    dw
  endstruct
  
  ; Then access with:
  LDA TimeState.Hours, X
  

• Benefit: This provides a clear, high-level definition of the data structure, improves readability, and makes it easier to manage memory layout.

3. Use subroutine for Code Blocks

• Observation: The file consists of many large, labeled blocks of code (e.g., RunClock, DrawClockToHud, ColorSubEffect).
• Suggestion: Convert these blocks to use subroutine/endsubroutine.
• Benefit: This clearly defines the scope of each piece of logic, makes labels within them local by default, and improves overall code structure.

4. Refactor Large Subroutines

• Observation: RunClock is a very large and complex subroutine with multiple responsibilities and deep nesting.
• Suggestion: Break RunClock into smaller, more focused subroutines.
  • TimeSystem_CheckCanRun: A subroutine to check the game state ($10, $11) and decide if the clock should tick.
  • TimeSystem_IncrementTime: A subroutine to handle the core logic of incrementing minutes and hours.
  • TimeSystem_UpdatePalettes: A subroutine to call the palette update logic when the hour changes.
• Benefit: Smaller, single-purpose functions are easier to read, debug, and maintain.

5. Replace Magic Numbers with Constants

• Observation: The code is replete with hardcoded values for time, palettes, and game states.

• Suggestion: Define constants for these values using ! or define().

  Example:

  !TIME_SPEED_NORMAL = $3F
  !GAME_STATE_OVERWORLD = $09
  
  LDA.b #!TIME_SPEED_NORMAL : STA.l TimeSpeed
  LDA $10 : CMP #!GAME_STATE_OVERWORLD : BEQ .overworld
  

• Benefit: Makes the code self-documenting and reduces the risk of errors when modifying these values.