B6-zelda3-library-refactoring

YAZE zelda3 Library Refactoring & Migration Plan

Author: Gemini Date: 2025-10-11 Status: Proposed

1. Introduction & Motivation

The zelda3 library, currently located at src/app/zelda3, encapsulates all the data models and logic specific to "A Link to the Past." It serves as the foundational data layer for both the yaze GUI application and the z3ed command-line tool.

Its current structure and location present two primary challenges:

1. Monolithic Design: Like the gfx and gui libraries, zelda3 is a single, large static library. This creates a tightly-coupled module where a change to any single component (e.g., dungeon objects) forces a relink of the entire library and all its dependents.
2. Incorrect Location: The library resides within src/app/, which is designated for the GUI application's specific code. However, its logic is shared with the cli target. This violates architectural principles and creates an improper dependency from the cli module into the app module's subdirectory.

This document proposes a comprehensive plan to both refactor the zelda3 library into logical sub-modules and migrate it to a top-level directory (src/zelda3) to correctly establish it as a shared, core component.

1. Goals
   • Establish as a Core Shared Library: Physically and logically move the library to src/zelda3 to reflect its role as a foundational component for both the application and the CLI.
   • Improve Incremental Build Times: Decompose the library into smaller, focused modules to minimize the scope of rebuilds and relinks.
   • Clarify Domain Boundaries: Create a clear separation between the major game systems (Overworld, Dungeon, Sprites, etc.) to improve code organization and maintainability.
   • Isolate Legacy Code: Encapsulate the legacy Hyrule Magic music tracker code into its own module to separate it from the modern C++ codebase.
2. Proposed Architecture

The zelda3 library will be moved to src/zelda3/ and broken down into six distinct, layered libraries.

1 +-----------------------------------------------------------------+
2 | Executables (yaze, z3ed, tests)                                 |
3 +-----------------------------------------------------------------+
4       ^
5       | Links against
6       v
7 +-----------------------------------------------------------------+
8 | zelda3 (INTERFACE Library)                                      |
9 +-----------------------------------------------------------------+
10       ^
11       | Aggregates
12       |-----------------------------------------------------------|
13       |                           |                               |
14       v                           v                               v
15 +-----------------+   +-----------------+   +---------------------+
16 | zelda3_screen   |-->| zelda3_dungeon  |-->| zelda3_overworld    |
17 +-----------------+   +-----------------+   +---------------------+
18       |                 |         ^         |         ^
19       |                 |         |         |         |
20       |-----------------|---------|---------|---------|
21       |                 |         |         |         |
22       v                 v         |         v         v
23 +-----------------+   +-----------------+   +---------------------+
24 | zelda3_music    |-->| zelda3_sprite   |-->| zelda3_core         |
25 +-----------------+   +-----------------+   +---------------------+

3.1. zelda3_core (Foundation)

• Responsibility: Contains fundamental data structures, constants, and labels used across all other zelda3 modules.
• Contents: common.h, zelda3_labels.h/.cc, dungeon/dungeon_rom_addresses.h.
• Dependencies: yaze_util.

3.2. zelda3_sprite (Shared Game Entity)

• Responsibility: Manages the logic and data for sprites, which are used in both dungeons and the overworld.
• Contents: sprite/sprite.h/.cc, sprite/sprite_builder.h/.cc, sprite/overlord.h.
• Dependencies: zelda3_core.

3.3. zelda3_dungeon (Dungeon System)

• Responsibility: The complete, self-contained system for all dungeon-related data and logic.
• Contents: All files from dungeon/ (room.h/.cc, room_object.h/.cc, dungeon_editor_system.h/.cc, etc.).
• Dependencies: zelda3_core, zelda3_sprite.

3.4. zelda3_overworld (Overworld System)

• Responsibility: The complete, self-contained system for all overworld-related data and logic.
• Contents: All files from overworld/ (overworld.h/.cc, overworld_map.h/.cc, etc.).
• Dependencies: zelda3_core, zelda3_sprite.

3.5. zelda3_screen (Specific Game Screens)

• Responsibility: High-level components representing specific, non-gameplay screens.
• Contents: All files from screen/ (dungeon_map.h/.cc, inventory.h/.cc, title_screen.h/.cc).
• Dependencies: zelda3_dungeon, zelda3_overworld.

3.6. zelda3_music (Legacy Isolation)

• Responsibility: Encapsulates the legacy Hyrule Magic music tracker code.
• Contents: music/tracker.h/.cc.
• Dependencies: zelda3_core.

Migration Plan

This plan details the steps to move the library from src/app/zelda3 to src/zelda3.

1. Physical File Move:
   • Move the directory /Users/scawful/Code/yaze/src/app/zelda3 to /Users/scawful/Code/yaze/src/zelda3.
2. Update CMake Configuration:
   • In src/CMakeLists.txt, change the line include(zelda3/zelda3_library.cmake) to include(zelda3/zelda3_library.cmake).
   • In the newly moved src/zelda3/zelda3_library.cmake, update all target_include_directories paths to remove the app/ prefix (e.g., change ${CMAKE_SOURCE_DIR}/src/app to ${CMAKE_SOURCE_DIR}/src).
3. Update Include Directives (Global):
   • Perform a project-wide search-and-replace for all occurrences of #include "zelda3/ and change them to #include "zelda3/.
   • This will be the most extensive step, touching files in src/app/, src/cli/, and test/.
4. Verification:
   • After the changes, run a full CMake configure and build (cmake –preset mac-dev -B build_ai && cmake –build build_ai) to ensure all paths are correctly resolved and the project compiles successfully.

Implementation Plan (CMake)

The refactoring will be implemented within the new src/zelda3/zelda3_library.cmake file.

1. Define Source Groups: Create set() commands for each new library (ZELDA3_CORE_SRC, ZELDA3_DUNGEON_SRC, etc.).
2. Create Static Libraries: Use add_library(yaze_zelda3_core STATIC ...) for each module.
3. Establish Link Dependencies: Use target_link_libraries to define the dependencies outlined in section 3.
4. Create Aggregate Interface Library: The yaze_zelda3 target will be converted to an INTERFACE library that links against all the new sub-libraries, providing a single, convenient link target for yaze_gui, yaze_cli, and the test suites.

Expected Outcomes

This refactoring and migration will establish the zelda3 library as a true core component of the application. The result will be a more logical and maintainable architecture, significantly faster incremental build times, and a clear separation of concerns that will benefit future development.