# Overworld Map Data Structure

**Status**: Draft
**Last Updated**: 2025-11-21
**Related Code**: `src/zelda3/overworld/overworld_map.h`, `src/zelda3/overworld/overworld_map.cc`

This document details the internal structure of an Overworld Map in YAZE.

## Overview

An `OverworldMap` represents a single screen of the overworld. In vanilla ALttP, these are indexed 0x00 to 0xBF.

### Key Data Structures

*   **Map Index**: unique identifier (0-159).
*   **Parent Index**: For large maps, points to the "main" map that defines properties.
*   **Graphics**:
    *   `current_gfx_`: The raw graphics tiles loaded for this map.
    *   `current_palette_`: The 16-color palette rows used by this map.
    *   `bitmap_data_`: The rendered pixels (indexed color).
*   **Properties**:
    *   `message_id_`: ID of the text message displayed when entering.
    *   `area_music_`: Music track IDs.
    *   `sprite_graphics_`: Which sprite sheets are loaded.

### Persistence (Loading/Saving)

*   **Loading**:
    *   `Overworld::LoadOverworldMaps` iterates through all map IDs.
    *   `OverworldMap` constructor initializes basic data.
    *   `BuildMap` decompresses the tile data from ROM (Map32/Map16 conversion).
*   **Saving**:
    *   `Overworld::SaveOverworldMaps` serializes the tile data back to the compressed format.
    *   It handles checking for space and repointing if the data size increases.

### ZSCustomOverworld Integration

The `OverworldMap` class has been extended to support ZSCustomOverworld (ZSO) features.

*   **Custom Properties**:
    *   `area_specific_bg_color_`: Custom background color per map.
    *   `subscreen_overlay_`: ID for custom cloud/fog overlays.
    *   `animated_gfx_`: ID for custom animated tiles (water, flowers).
    *   `mosaic_expanded_`: Flags for per-map mosaic effects.
*   **Data Storage**:
    *   These properties are stored in expanded ROM areas defined by ZSO.
    *   `LoadCustomOverworldData` reads these values from their specific ROM addresses.

### Overlay System

Some maps have interactive overlays (e.g., the cloud layer in the Desert Palace entrance).
*   `overlay_id_`: ID of the overlay.
*   `overlay_data_`: The compressed tile data for the overlay layer.
*   The editor renders this on top of the base map if enabled.