Zelda3 Dungeon Core Module (<tt>src/zelda3/dungeon</tt>)

This directory contains the core business logic, data structures, and rendering algorithms for the The Legend of Zelda: A Link to the Past dungeon system. It serves as the backend for the editor UI found in src/app/editor/dungeon.

Architecture Overview

The module is designed to replicate the SNES game engine's logic for loading, parsing, and rendering dungeon rooms, while providing high-level editing capabilities.

Core Domain Entities

• **Room**: The aggregate root representing a single dungeon room (IDs 0-295). It manages:
  • **RoomObject** list (walls, floors, interactables).
  • **Sprite** list (enemies, NPCs).
  • Header data (collision, palette, blockset).
  • State (chests, doors, etc.).
• **RoomObject**: Represents a tile-based object. It handles the complex bit-packing of the three object subtypes used by the SNES engine:
  • Type 1 (0x00-0xFF): Standard scalable objects.
  • Type 2 (0x100-0x1FF): Complex/Preset objects.
  • Type 3 (0xF80-0xFFF): Special objects and paths.
• **RoomLayout**: Represents the structural layout of a room (walls and floor) separately from the mutable object list.

The Rendering Pipeline

This module implements a faithful recreation of the ALTTP dungeon rendering engine to ensure what you see in the editor matches the game.

graph TD
    Rom[ROM Data] --> Parser[ObjectParser]
    Parser -->|Tile Data| Drawer[ObjectDrawer]
    
    subgraph "Draw Routine System"
        Drawer --> RoutineLookup{Routine ID}
        RoutineLookup -->|ID 0-4| Rightwards[Rightwards Routines]
        RoutineLookup -->|ID 7-15| Downwards[Downwards Routines]
        RoutineLookup -->|ID 5-6| Diagonal[Diagonal Routines]
        RoutineLookup -->|ID 14-19| Corner[Corner Routines]
        RoutineLookup -->|ID 39+| Special[Special Routines]
    end
    
    Rightwards --> Bitmap[BackgroundBuffer]
    Downwards --> Bitmap
    
    Bitmap --> LayerMgr[RoomLayerManager]
    LayerMgr -->|Composite| FinalImage

• **ObjectParser**: Reads raw tile data directly from the ROM's graphics banks based on object IDs.
• **ObjectDrawer**: The core rendering engine. It maps Object IDs to specific "Draw Routines".
• **draw_routines/**: A collection of pure functions that mirror the ASM routines from bank_01.asm. They calculate tile positions based on object size and orientation.
  • Example: DrawRightwards2x2_1to15or32 draws a 2x2 block repeated N times horizontally.

Editing Subsystems

• **DungeonEditorSystem**: The high-level facade for the application layer. It manages the editing session, undo/redo history, and coordination between different editing modes (Objects, Sprites, Entrances).
• **DungeonObjectEditor**: Specialized logic for manipulating RoomObject entities (Insert, Delete, Move, Resize). Handles grid snapping and collision checks.
• **ObjectDimensionTable**: Provides hit-testing bounds for objects. This is distinct from the visual rendering size and is derived from ROM data tables.
• **ObjectTemplateManager**: Allows creating and instantiating groups of objects (templates).

Key Files & Components

Data & State

• **dungeon_rom_addresses.h**: Central registry of ROM memory offsets.
• **dungeon_state.h / editor_dungeon_state.h**: Abstracts game state (e.g., "Is chest X open?") to allow the editor to simulate different gameplay scenarios.
• **room_entrance.h**: Defines entrance/exit data structures.

Rendering

• **room_layer_manager.h**: Controls the visibility and blending of the SNES background layers (BG1, BG2, BG3). Handles complex "Layer Merge" logic used in the game.
• **palette_debug.cc/h**: Instrumentation tools for diagnosing palette loading and application issues.

Logic

• **dungeon_validator.cc/h**: Enforces game limits (e.g., max sprites per room, max chests).
• **dungeon_object_registry.cc/h**: A registry for object names and metadata.

Comparison: Backend vs. Frontend

Feature	src/zelda3/dungeon (Backend)	src/app/editor/dungeon (Frontend)
Focus	Logic, Data, Rendering Algorithms	UI, Input, State Coordination
Dependencies	rom/, app/gfx/ (Base types)	zelda3/dungeon, imgui
Rendering	Draws tiles to memory buffers	Displays buffers on Canvas, handles Pan/Zoom
Input	N/A	Handles Mouse/Keyboard events
State	Holds the "Truth" (Room data)	Manages Selection state, Tool modes

Areas for Improvement

1. Unified Dimension Logic: Currently, ObjectDimensionTable (hitboxes) and draw_routines (visuals) maintain separate logic for object sizes. This can lead to desyncs where the click area doesn't match the drawn object. Action: Consolidate logic so ObjectDimensionTable queries the draw routines or vice-versa.
2. Hardcoded ROM Offsets: dungeon_rom_addresses.h contains hardcoded offsets for the US ROM. Action: Move these to a version-aware configuration system to support JP/EU ROMs.
3. Sprite Rendering: While RoomObject rendering is highly advanced, Sprite rendering is currently rudimentary (simple boxes in some views). Action: Implement a SpriteDrawer similar to ObjectDrawer using the game's sprite OAM tables.
4. Legacy Code: Some classes (e.g., in room.cc) contain legacy loading logic that might duplicate the newer ObjectParser. Action: Audit and deprecate old loading paths in favor of the robust parser.