yaze/docs/internal/architecture

YAZE Architecture Documentation

This directory contains detailed architectural documentation for the YAZE (Yet Another Zelda3 Editor) codebase. These documents describe the design patterns, component interactions, and best practices used throughout the project.

Core Architecture Guides

ROM and Game Data

• rom_architecture.md - Decoupled ROM architecture
  • Generic SNES ROM container (src/rom/)
  • Zelda3-specific GameData struct (src/zelda3/game_data.h)
  • Editor integration and GameData propagation
  • Transaction-based ROM access patterns
  • Migration guide from old architecture

Graphics System

• graphics_system_architecture.md - Complete guide to the graphics rendering pipeline
  • Arena resource manager for 223 graphics sheets
  • Bitmap class and texture management
  • LC-LZ2 compression/decompression pipeline
  • Rendering workflow from ROM loading to display
  • Canvas interactions and drawing operations
  • Best practices for graphics modifications

UI and Layout System

• editor_card_layout_system.md - Card-based editor and layout architecture
  • EditorCardRegistry for centralized card management
  • LayoutManager for ImGui DockBuilder layouts
  • LayoutPresets for default per-editor configurations
  • VSCode-style Activity Bar and Side Panel
  • Agent UI system (multi-agent sessions, pop-out cards)
  • Card validation system for development debugging
  • Session-aware card ID prefixing
  • Workspace preset save/load
• layout-designer.md - WYSIWYG layout designer (panel & widget modes), integration points, and current limitations

Editors

Dungeon Editor

• dungeon_editor_system.md - Architecture of the dungeon room editor
  • Component-based design (DungeonEditorV2, DungeonObjectEditor, DungeonCanvasViewer)
  • Object editing workflow (insert, delete, move, resize, layer operations)
  • Coordinate systems and conversion methods
  • Best practices for extending editor modes
  • Contributing guidelines for new features

Overworld Editor

• overworld_editor_system.md - Architecture of the overworld map editor
  • Overworld system structure (Light World, Dark World, Special Areas)
  • Map properties and large map configuration
  • Entity handling (sprites, entrances, exits, items)
  • Deferred texture loading for performance
  • ZSCustomOverworld integration

Data Structures & Persistence

• overworld_map_data.md - Overworld map internal structure

  • OverworldMap data model (tiles, graphics, properties)
  • ZSCustomOverworld custom properties and storage
  • Loading and saving process
  • Multi-area map configuration
  • Overlay system for interactive map layers

• room_data_persistence.md - Dungeon room loading and saving

  • ROM pointer table system
  • Room decompression and object parsing
  • Multithreaded bulk loading (up to 8 threads)
  • Room size calculation for safe editing
  • Repointing logic for data overflow
  • Bank boundary considerations

Systems & Utilities

• undo_redo_system.md - Undo/redo architecture for editors

  • Snapshot-based undo implementation
  • DungeonObjectEditor undo stack
  • DungeonEditorSystem coordinator integration
  • Batch operation handling
  • Best practices for state management

• zscustomoverworld_integration.md - ZSCustomOverworld v3 support

  • Multi-area map sizing (1x1, 2x1, 1x2, 2x2)
  • Custom graphics and palette per-map
  • Visual effects (mosaic, subscreen overlay)
  • ASM patching and ROM version detection
  • Feature-specific UI adaptation

Quick Reference by Component

ROM (src/rom/)

• See: rom_architecture.md
• Key Classes: Rom, ReadTransaction, WriteTransaction
• Key Files: rom.h, rom.cc, transaction.h, snes.h

Game Data (src/zelda3/game_data.h)

• See: rom_architecture.md
• Key Struct: GameData
• Key Functions: LoadGameData(), SaveGameData()

Graphics (src/app/gfx/)

• See: graphics_system_architecture.md
• Key Classes: Arena, Bitmap, SnesPalette, IRenderer
• Key Files: resource/arena.h, core/bitmap.h, util/compression.h

Dungeon Editor (src/app/editor/dungeon/, src/zelda3/dungeon/)

• See: dungeon_editor_system.md, room_data_persistence.md
• Key Classes: DungeonEditorV2, DungeonObjectEditor, Room, DungeonRoomLoader
• Key Files: dungeon_editor_v2.h, dungeon_object_editor.h, room.h

Overworld Editor (src/app/editor/overworld/, src/zelda3/overworld/)

• See: overworld_editor_system.md, overworld_map_data.md
• Key Classes: OverworldEditor, Overworld, OverworldMap, OverworldEntityRenderer
• Key Files: overworld_editor.h, overworld.h, overworld_map.h

Undo/Redo

• See: undo_redo_system.md
• Key Classes: DungeonObjectEditor (UndoPoint structure)
• Key Files: dungeon_object_editor.h

UI/Layout System (src/app/editor/system/, src/app/editor/ui/)

• See: editor_card_layout_system.md
• Key Classes: EditorCardRegistry, LayoutManager, LayoutPresets, UICoordinator
• Key Files: editor_card_registry.h, layout_manager.h, layout_presets.h, ui_coordinator.h

Agent UI System (src/app/editor/agent/)

• See: editor_card_layout_system.md
• Key Classes: AgentUiController, AgentSessionManager, AgentSidebar, AgentChatCard, AgentChatView
• Key Files: agent_ui_controller.h, agent_session.h, agent_sidebar.h, agent_chat_card.h

ZSCustomOverworld

• See: zscustomoverworld_integration.md, overworld_map_data.md
• Key Classes: OverworldMap, Overworld, OverworldVersionHelper
• Key Files: overworld.cc, overworld_map.cc, overworld_version_helper.h

Design Patterns Used

1. Modular/Component-Based Design

Large systems are decomposed into smaller, single-responsibility classes:

• Example: DungeonEditorV2 (coordinator) → DungeonRoomLoader, DungeonCanvasViewer, DungeonObjectEditor (components)
• See: dungeon_editor_system.md

2. Callback-Based Communication

Components communicate without circular dependencies:

• Example: ObjectEditorCard receives callbacks from DungeonObjectEditor
• See: dungeon_editor_system.md

3. Singleton Pattern

Global resource management via Arena:

• Example: gfx::Arena::Get() for all graphics sheet access
• See: graphics_system_architecture.md

4. Progressive/Deferred Loading

Heavy operations performed asynchronously to maintain responsiveness:

• Example: Graphics sheets loaded on-demand with priority queue
• Example: Overworld map textures created when visible
• See: overworld_editor_system.md

5. Snapshot-Based Undo/Redo

State snapshots before destructive operations:

• Example: UndoPoint structure captures entire room object state
• See: undo_redo_system.md

6. Card-Based UI Architecture

VSCode-style dockable card system with centralized registry:

• Example: EditorCardRegistry manages all editor window metadata
• Example: LayoutManager uses DockBuilder to arrange cards
• See: editor_card_layout_system.md

7. Multi-Session State Management

Support for multiple concurrent sessions (ROMs, agents):

• Example: AgentSessionManager maintains multiple agent sessions with shared context
• Example: Card IDs prefixed with session ID for isolation
• See: editor_card_layout_system.md

Contributing Guidelines

When adding new functionality:

1. Follow Existing Patterns: Use component-based design, callbacks, and RAII principles
2. Update Documentation: Add architectural notes to relevant documents
3. Write Tests: Create unit tests in test/unit/ for new components
4. Use Proper Error Handling: Employ absl::Status and absl::StatusOr<T>
5. Coordinate with State: Use Arena/Singleton patterns for shared state
6. Enable Undo/Redo: Snapshot state before destructive operations
7. Defer Heavy Work: Use texture queues and async loading for performance

For detailed guidelines, see the Best Practices sections in individual architecture documents.

Related Documents

• ../../CLAUDE.md - Project overview and development guidelines
• ../../README.md - Project introduction
• ../release-checklist.md - Release process documentation

Architecture Evolution

This architecture reflects the project's maturity at the time of documentation. Key evolution points:

• DungeonEditorV2: Replacement for older monolithic DungeonEditor with proper component delegation
• Arena System: Centralized graphics resource management replacing scattered SDL operations
• ZSCustomOverworld v3 Support: Extended OverworldMap and Overworld to support expanded ROM features
• Progressive Loading: Deferred texture creation to prevent UI freezes during large ROM loads
• EditorCardRegistry: VSCode-style card management replacing ad-hoc window visibility tracking
• Multi-Agent Sessions: Support for concurrent AI agents with shared context and pop-out cards
• Unified Visibility Management: Single source of truth for component visibility (emulator, cards)

Status and Maintenance

All architecture documents are maintained alongside the code:

• Documents are reviewed during code reviews
• Architecture changes require documentation updates
• Status field indicates completeness (Draft/In Progress/Complete)
• Last updated timestamp indicates freshness

For questions about architecture decisions, consult:

1. Relevant architecture document
2. Source code comments
3. Commit history for design rationale