yaze/docs/internal/architecture/overworld_editor_system.md

Overworld Editor Architecture

Status: Draft Last Updated: 2025-11-21 Related Code: src/app/editor/overworld/, src/zelda3/overworld/

This document outlines the architecture of the Overworld Editor in YAZE.

High-Level Overview

The Overworld Editor allows users to view and modify the game's overworld maps, including terrain (tiles), entities (sprites, entrances, exits, items), and map properties.

Key Components

Component	Location	Responsibility
OverworldEditor	src/app/editor/overworld/	Main UI coordinator. Manages the Overworld data object, handles user input (mouse/keyboard), manages sub-editors (Tile16, GfxGroup), and renders the main view.
Overworld	src/zelda3/overworld/	System coordinator. Manages the collection of OverworldMap objects, global tilesets, palettes, and loading/saving of the entire overworld structure.
OverworldMap	src/zelda3/overworld/	Data model for a single overworld screen (Area). Manages its own graphics, properties, and ZSCustomOverworld data.
OverworldEntityRenderer	src/app/editor/overworld/	Helper class to render entities (sprites, entrances, etc.) onto the canvas.
MapPropertiesSystem	src/app/editor/overworld/	UI component for editing map-specific properties (music, palette, etc.).
Tile16Editor	src/app/editor/overworld/	Sub-editor for modifying the 16x16 tile definitions.

Interaction Flow

1. Initialization:

   • OverworldEditor is initialized with a Rom pointer.
   • It calls overworld_.Load(rom) which triggers the loading of all maps and global data.

2. Rendering:

   • OverworldEditor::DrawOverworldCanvas is the main rendering loop.
   • It iterates through visible OverworldMap objects.
   • Each OverworldMap maintains a Bitmap of its visual state.
   • OverworldEditor draws these bitmaps onto a gui::Canvas.
   • OverworldEntityRenderer draws entities on top of the map.

3. Editing:

   • Tile Painting: User selects a tile from the Tile16Selector (or scratch pad) and clicks on the map. OverworldEditor updates the Overworld data model (SetTile).
   • Entity Manipulation: User can drag/drop entities. OverworldEditor updates the corresponding data structures in Overworld.
   • Properties: Changes in the MapPropertiesSystem update the OverworldMap state and trigger a re-render.

Coordinate Systems

• Global Coordinates: The overworld is conceptually a large grid.
  • Light World: 8x8 maps.
  • Dark World: 8x8 maps.
  • Special Areas: Independent maps.
• Map Coordinates: Each map is 512x512 pixels (32x32 tiles of 16x16 pixels).
• Tile Coordinates: Objects are placed on a 16x16 grid within a map.

Large Maps

ALttP combines smaller maps into larger scrolling areas (e.g., 2x2).

• Parent Map: The top-left map typically holds the main properties.
• Child Maps: The other 3 maps inherit properties from the parent but contain their own tile data.
• ZSCustomOverworld: Introduces more flexible map sizing (Wide, Tall, Large). The Overworld class handles the logic for configuring these (ConfigureMultiAreaMap).

Deferred Loading

To improve performance, OverworldEditor implements a deferred texture creation system.

• Map data is loaded from ROM, but textures are not created immediately.
• EnsureMapTexture is called only when a map becomes visible, creating the SDL texture on-demand.
• ProcessDeferredTextures creates a batch of textures each frame to avoid stalling the UI.