overworld.h

Go to the documentation of this file.

#ifndef YAZE_APP_DATA_OVERWORLD_H
#define YAZE_APP_DATA_OVERWORLD_H
 
#include <array>
#include <cstddef>
#include <cstdint>
#include <deque>
#include <map>
#include <mutex>
#include <unordered_map>
#include <vector>
 
#include "absl/status/status.h"
#include "absl/status/statusor.h"
#include "app/gfx/types/snes_tile.h"
#include "core/rom_settings.h"
#include "imgui.h"
#include "rom/rom.h"
#include "zelda3/common.h"
#include "zelda3/game_data.h"
#include "zelda3/overworld/diggable_tiles.h"
#include "zelda3/overworld/overworld_entrance.h"
#include "zelda3/overworld/overworld_exit.h"
#include "zelda3/overworld/overworld_item.h"
#include "zelda3/overworld/overworld_map.h"
#include "zelda3/overworld/overworld_sprite_io.h"
#include "zelda3/overworld/overworld_version_helper.h"
#include "zelda3/overworld/zscream_custom_layout.h"
#include "zelda3/sprite/sprite.h"
 
// =============================================================================
// Overworld Data Layer
// =============================================================================
//
// ARCHITECTURE OVERVIEW:
// ----------------------
// The Overworld class is the central data manager for A Link to the Past's
// overworld system. It handles 160 map screens across three worlds:
//   - Light World: Maps 0x00-0x3F (64 maps)
//   - Dark World: Maps 0x40-0x7F (64 maps)
//   - Special World: Maps 0x80-0x9F (32 maps, expandable to 0xBF with patches)
//
// DATA ORGANIZATION:
// ------------------
// The overworld uses a hierarchical tile system:
//   - Tile32: 32x32 pixel blocks composed of four Tile16s
//   - Tile16: 16x16 pixel blocks composed of four Tile8s
//   - Tile8: 8x8 pixel base tiles from graphics sheets
//
// Map tile data is stored as arrays of Tile16 IDs in OverworldBlockset:
//   - map_tiles_.light_world: 64 maps of 32x32 tile16 IDs each
//   - map_tiles_.dark_world: 64 maps of 32x32 tile16 IDs each
//   - map_tiles_.special_world: 32+ maps of 32x32 tile16 IDs each
//
// SAVE SYSTEM DOCUMENTATION:
// --------------------------
// The save workflow is controlled by feature flags in OverworldEditor::Save().
// Each component saves independently but some have ordering dependencies.
//
// SAVE ORDER AND DEPENDENCIES:
//
// 1. TILE DEFINITIONS (must be saved first, others depend on these IDs):
//    - CreateTile32Tilemap(): Build tile32 from current tile16 data
//    - SaveMap32Tiles(): Write tile32 definitions to ROM
//    - SaveMap16Tiles(): Write tile16 definitions to ROM
//    - SaveOverworldMaps(): Write compressed map tile data
//
// 2. ENTITIES (independent, can save in any order):
//    - SaveEntrances(): Entrance warps to underworld
//    - SaveExits(): Exit points returning from underworld
//    - SaveItems(): Hidden items on overworld
//
// 3. PROPERTIES (independent, can save in any order):
//    - SaveMapProperties(): Graphics, palettes, messages per area
//    - SaveMusic(): Music IDs per area and game state
//    - SaveAreaSizes(): Area size enum for v3+ ROMs
//
// 4. CUSTOM FEATURES (v2+/v3+ only):
//    - SaveCustomOverworldASM(): Custom feature enable flags
//    - SaveAreaSpecificBGColors(): Per-area background colors (v2+)
//    - SaveMapOverlays(): Interactive overlay data
//
// TESTING SAVE FUNCTIONALITY:
// ---------------------------
// To test individual save components:
//   1. Enable only one feature flag at a time in core::FeatureFlags
//   2. Make changes to that component in the editor
//   3. Save ROM and verify changes in an emulator
//   4. Check for corruption by loading saved ROM back into editor
//
// Round-trip testing:
//   1. Load vanilla ROM
//   2. Make changes to all components
//   3. Save ROM
//   4. Close and reopen ROM
//   5. Verify all changes persisted correctly
//
// See app/editor/overworld/README.md for complete workflow documentation.
// =============================================================================
 
namespace yaze::zelda3 {
 
inline constexpr int kEssentialMapsPerWorld = 1;
 
constexpr int GravesYTilePos = 0x49968;          // short (0x0F entries)
constexpr int GravesXTilePos = 0x49986;          // short (0x0F entries)
constexpr int GravesTilemapPos = 0x499A4;        // short (0x0F entries)
constexpr int GravesGFX = 0x499C2;               // short (0x0F entries)
constexpr int GravesXPos = 0x4994A;              // short (0x0F entries)
constexpr int GravesYLine = 0x4993A;             // short (0x08 entries)
constexpr int GravesCountOnY = 0x499E0;          // Byte 0x09 entries
constexpr int GraveLinkSpecialHole = 0x46DD9;    // short
constexpr int GraveLinkSpecialStairs = 0x46DE0;  // short
 
constexpr int kOverworldMapPaletteIds = 0x7D1C;
constexpr int kOverworldSpritePaletteIds = 0x7B41;
constexpr int kOverworldSpritePaletteGroup = 0x75580;
constexpr int kOverworldSpriteset = 0x7A41;
constexpr int kOverworldSpecialGfxGroup = 0x16821;
constexpr int kOverworldSpecialPalGroup = 0x16831;
constexpr int kOverworldSpritesBeginning = 0x4C881;
constexpr int kOverworldSpritesAgahnim = 0x4CA21;
constexpr int kOverworldSpritesZelda = 0x4C901;
 
constexpr int kAreaGfxIdPtr = 0x7C9C;
constexpr int kOverworldMessageIds = 0x3F51D;
 
constexpr int kOverworldMusicBeginning = 0x14303;
constexpr int kOverworldMusicZelda = 0x14303 + 0x40;
constexpr int kOverworldMusicMasterSword = 0x14303 + 0x80;
constexpr int kOverworldMusicAgahnim = 0x14303 + 0xC0;
constexpr int kOverworldMusicDarkWorld = 0x14403;
constexpr int kOverworldEntranceAllowedTilesLeft = 0xDB8C1;
constexpr int kOverworldEntranceAllowedTilesRight = 0xDB917;
 
// 0x00 = small maps, 0x20 = large maps
constexpr int kOverworldMapSize = 0x12844;
 
// 0x01 = small maps, 0x03 = large maps
constexpr int kOverworldMapSizeHighByte = 0x12884;
 
// relative to the WORLD + 0x200 per map
// large map that are not == parent id = same position as their parent!
// eg for X position small maps :
// 0000, 0200, 0400, 0600, 0800, 0A00, 0C00, 0E00
// all Large map would be :
// 0000, 0000, 0400, 0400, 0800, 0800, 0C00, 0C00
constexpr int kOverworldMapParentId = 0x125EC;
constexpr int kOverworldTransitionPositionY = 0x128C4;
constexpr int kOverworldTransitionPositionX = 0x12944;
constexpr int kOverworldScreenSize = 0x1788D;
constexpr int kOverworldScreenSizeForLoading = 0x4C635;
 
constexpr int kOverworldScreenTileMapChangeByScreen1 = 0x12634;
constexpr int kOverworldScreenTileMapChangeByScreen2 = 0x126B4;
constexpr int kOverworldScreenTileMapChangeByScreen3 = 0x12734;
constexpr int kOverworldScreenTileMapChangeByScreen4 = 0x127B4;
 
constexpr int kOverworldMapDataOverflow = 0x130000;
 
constexpr int kTransitionTargetNorth = 0x13EE2;
constexpr int kTransitionTargetWest = 0x13F62;
constexpr int overworldCustomMosaicASM = 0x1301D0;
constexpr int overworldCustomMosaicArray = 0x1301F0;
 
// Expanded tile16 and tile32
constexpr int kMap16TilesExpanded = 0x1E8000;
constexpr int kMap32TileTRExpanded = 0x020000;
constexpr int kMap32TileBLExpanded = 0x1F0000;
constexpr int kMap32TileBRExpanded = 0x1F8000;
constexpr int kMap32TileCountExpanded = 0x0067E0;
constexpr int kMap32ExpandedFlagPos = 0x01772E;  // 0x04
constexpr int kMap16ExpandedFlagPos = 0x02FD28;  // 0x0F
 
constexpr int overworldSpritesBeginingExpanded = 0x141438;
constexpr int overworldSpritesZeldaExpanded = 0x141578;
constexpr int overworldSpritesAgahnimExpanded = 0x1416B8;
constexpr int overworldSpritesDataStartExpanded = 0x04C881;
 
constexpr int overworldSpecialSpriteGFXGroupExpandedTemp = 0x0166E1;
constexpr int overworldSpecialSpritePaletteExpandedTemp = 0x016701;
 
constexpr int ExpandedOverlaySpace = 0x120000;
 
// Expanded pointer table markers for tail map support (maps 0xA0-0xBF)
// Set by TailMapExpansion.asm patch after ZSCustomOverworld v3
constexpr int kExpandedPtrTableMarker = 0x1423FF;  // Location of marker byte
constexpr uint8_t kExpandedPtrTableMagic = 0xEA;   // Marker value when applied
constexpr int kExpandedPtrTableHigh = 0x142400;    // New high table location
constexpr int kExpandedPtrTableLow = 0x142640;     // New low table location
// kExpandedMapCount is defined in zelda3/common.h
 
constexpr int overworldTilesType = 0x071459;
constexpr int overworldMessages = 0x03F51D;
constexpr int overworldMessagesExpanded = 0x1417F8;
 
inline int GetMap16TilesExpanded() {
  return static_cast<int>(core::RomSettings::Get().GetAddressOr(
      core::RomAddressKey::kOverworldMap16Expanded, kMap16TilesExpanded));
}
 
inline int GetMap32TileTRExpanded() {
  return static_cast<int>(core::RomSettings::Get().GetAddressOr(
      core::RomAddressKey::kOverworldMap32TrExpanded, kMap32TileTRExpanded));
}
 
inline int GetMap32TileBLExpanded() {
  return static_cast<int>(core::RomSettings::Get().GetAddressOr(
      core::RomAddressKey::kOverworldMap32BlExpanded, kMap32TileBLExpanded));
}
 
inline int GetMap32TileBRExpanded() {
  return static_cast<int>(core::RomSettings::Get().GetAddressOr(
      core::RomAddressKey::kOverworldMap32BrExpanded, kMap32TileBRExpanded));
}
 
inline int GetExpandedPtrTableMarker() {
  return static_cast<int>(core::RomSettings::Get().GetAddressOr(
      core::RomAddressKey::kOverworldExpandedPtrMarker,
      kExpandedPtrTableMarker));
}
 
inline uint8_t GetExpandedPtrTableMagic() {
  return static_cast<uint8_t>(core::RomSettings::Get().GetAddressOr(
      core::RomAddressKey::kOverworldExpandedPtrMagic, kExpandedPtrTableMagic));
}
 
inline int GetExpandedPtrTableHigh() {
  return static_cast<int>(core::RomSettings::Get().GetAddressOr(
      core::RomAddressKey::kOverworldExpandedPtrHigh, kExpandedPtrTableHigh));
}
 
inline int GetExpandedPtrTableLow() {
  return static_cast<int>(core::RomSettings::Get().GetAddressOr(
      core::RomAddressKey::kOverworldExpandedPtrLow, kExpandedPtrTableLow));
}
 
constexpr int kOverworldCompressedMapPos = 0x058000;
constexpr int kOverworldCompressedOverflowPos = 0x137FFF;
 
constexpr int kNumTileTypes = 0x200;
constexpr int kMap16Tiles = 0x78000;
 
constexpr int kNumTile16Individual = 4096;
constexpr int Map32PerScreen = 256;
constexpr int NumberOfMap16 = 3752;    // 4096
constexpr int NumberOfMap16Ex = 4096;  // 4096
// Tile32 definitions are packed four-at-a-time into six bytes in each of the
// four quadrant tables. Keep byte spans and definition capacities distinct:
// the expanded table length is a byte count, not a Tile32 count.
constexpr int kMap32DefinitionsPerPackedGroup = 4;
constexpr int kMap32BytesPerPackedGroup = 6;
constexpr int kMap32TileStorageBytesVanilla = 0x33F0;
constexpr int kMap32TileStorageBytesExpanded = kMap32TileCountExpanded;
 
constexpr int Map32DefinitionCapacityForStorageBytes(int storage_bytes) {
  return storage_bytes <= 0 ? 0
                            : (storage_bytes / kMap32BytesPerPackedGroup) *
                                  kMap32DefinitionsPerPackedGroup;
}
 
constexpr int kMap32DefinitionCapacityVanilla =
    Map32DefinitionCapacityForStorageBytes(kMap32TileStorageBytesVanilla);
constexpr int kMap32DefinitionCapacityExpanded =
    Map32DefinitionCapacityForStorageBytes(kMap32TileStorageBytesExpanded);
 
// Compatibility alias for callers that still use the historical name.
constexpr int LimitOfMap32 = kMap32DefinitionCapacityVanilla;
constexpr int NumberOfOWSprites = 352;
constexpr int NumberOfMap32 = Map32PerScreen * kNumOverworldMaps;
constexpr int kNumMapsPerWorld = 0x40;
 
struct OverworldRomProfile {
  enum class LayoutKind {
    kLegacy,
    kOlderTailEa,
    kLyraOffline,
    kZScreamPerSheet,
    kUnknownCustom,
  };
  LayoutKind layout_kind = LayoutKind::kLegacy;
  zscream::LayoutDialect zscream_layout = zscream::LayoutDialect::kUnmarked;
  rom::LyraLayoutInspection lyra_layout;
  uint8_t asm_version = 0xFF;
  OverworldVersion version = OverworldVersion::kVanilla;
  bool is_vanilla = true;
  bool supports_expanded_space = false;
  bool supports_area_enum = false;
  bool supports_custom_bg_colors = false;
  bool has_expanded_tile16 = false;
  bool has_expanded_tile32 = false;
  bool has_expanded_entrances = false;
  bool has_tail_map_expansion = false;
  int editable_map_count = kSpecialWorldMapIdStart + 0x20;
};
 
inline int Map32StorageBytesForProfile(const OverworldRomProfile& profile) {
  return profile.has_expanded_tile32 ? kMap32TileStorageBytesExpanded
                                     : kMap32TileStorageBytesVanilla;
}
 
inline int Map32DefinitionCapacityForProfile(
    const OverworldRomProfile& profile) {
  return Map32DefinitionCapacityForStorageBytes(
      Map32StorageBytesForProfile(profile));
}
 
inline bool IsValidRomAddress(const Rom& rom, int address) {
  return address >= 0 && static_cast<size_t>(address) < rom.size();
}
 
inline uint8_t ReadRomByteOr(const Rom& rom, int address, uint8_t fallback) {
  if (!IsValidRomAddress(rom, address)) {
    return fallback;
  }
  return rom.data()[address];
}
 
inline bool IsSpecialTailMapExpansionEnabled(const Rom& rom) {
  return zscream::CanUseTailExpansion(rom) &&
         ReadRomByteOr(rom, GetExpandedPtrTableMarker(), 0x00) ==
             GetExpandedPtrTableMagic();
}
 
inline OverworldRomProfile DetectOverworldRomProfile(const Rom& rom) {
  OverworldRomProfile profile;
  profile.zscream_layout = zscream::DetectLayout(rom);
  profile.lyra_layout = rom.InspectLyraLayout();
  profile.asm_version = OverworldVersionHelper::GetAsmVersion(rom);
  profile.version = OverworldVersionHelper::GetVersion(rom);
  profile.is_vanilla = profile.version == OverworldVersion::kVanilla;
  profile.supports_expanded_space =
      OverworldVersionHelper::SupportsExpandedSpace(profile.version);
  profile.supports_area_enum =
      OverworldVersionHelper::SupportsAreaEnum(profile.version);
  profile.supports_custom_bg_colors =
      OverworldVersionHelper::SupportsCustomBGColors(profile.version);
 
  const uint8_t tile16_flag = ReadRomByteOr(rom, kMap16ExpandedFlagPos, 0x0F);
  const uint8_t tile32_flag = ReadRomByteOr(rom, kMap32ExpandedFlagPos, 0x04);
  const uint8_t entrance_flag =
      ReadRomByteOr(rom, GetOverworldEntranceFlagExpanded(), 0xB8);
 
  profile.has_expanded_tile16 =
      !profile.is_vanilla &&
      (profile.supports_area_enum || tile16_flag != 0x0F);
  profile.has_expanded_tile32 =
      !profile.is_vanilla &&
      (profile.supports_area_enum || tile32_flag != 0x04);
  profile.has_expanded_entrances = !profile.is_vanilla && entrance_flag != 0xB8;
  profile.has_tail_map_expansion =
      profile.supports_area_enum && IsSpecialTailMapExpansionEnabled(rom);
  if (profile.lyra_layout.presence != yaze::rom::LyraLayoutPresence::kAbsent) {
    profile.layout_kind = OverworldRomProfile::LayoutKind::kLyraOffline;
    // The 192-record descriptor is not the older editable $EA tail format.
    profile.has_tail_map_expansion = false;
  } else if (profile.has_tail_map_expansion) {
    profile.layout_kind = OverworldRomProfile::LayoutKind::kOlderTailEa;
  } else if (profile.zscream_layout == zscream::LayoutDialect::kZScreamV5) {
    profile.layout_kind = OverworldRomProfile::LayoutKind::kZScreamPerSheet;
  } else if (profile.zscream_layout == zscream::LayoutDialect::kUnknown) {
    profile.layout_kind = OverworldRomProfile::LayoutKind::kUnknownCustom;
  }
  profile.editable_map_count =
      profile.has_tail_map_expansion ? kExpandedMapCount : kNumOverworldMaps;
  return profile;
}
 
inline int WorldForOverworldMap(int map_index) {
  if (map_index >= kSpecialWorldMapIdStart) {
    return 2;
  }
  if (map_index >= kDarkWorldMapIdStart) {
    return 1;
  }
  return 0;
}
 
inline bool IsSameOverworldWorld(int a, int b) {
  return WorldForOverworldMap(a) == WorldForOverworldMap(b);
}
 
inline bool CanPersistLegacyMultiAreaMap(int map_index) {
  return map_index >= 0 && map_index < kSpecialWorldMapIdStart;
}
 
inline bool CanPersistLegacyScreenSize(int map_index) {
  return map_index >= 0 && map_index < kSpecialWorldMapIdStart;
}
 
inline int LegacyParentTableIndexForMap(int map_index) {
  return map_index & 0x3F;
}
 
inline uint8_t LegacyParentTableValueForMap(int parent_index) {
  return static_cast<uint8_t>(parent_index & 0x3F);
}
 
inline int LegacyScreenSizeTableIndexForMap(int map_index) {
  return map_index;
}
 
absl::StatusOr<std::vector<gfx::Tile16>> ReadMap16Tiles(
    const Rom& rom, bool* expanded = nullptr);
 
class Overworld {
 public:
  Overworld(Rom* rom, GameData* game_data = nullptr)
      : rom_(rom), game_data_(game_data) {}
 
  void SetGameData(GameData* game_data) { game_data_ = game_data; }
 
  zelda3_version_pointers version_constants() const {
    return kVersionConstantsMap.at(game_data_ ? game_data_->version
                                              : zelda3_version::US);
  }
 
  // ===========================================================================
  // Loading Methods
  // ===========================================================================
 
  absl::Status Load(Rom* rom);
  // Explicit descriptor terrain path. The normal model loader remains
  // legacy-only; the editor admits this path only to its read-only canvas.
  absl::Status LoadLyraTerrainPreview(Rom* rom);
  bool is_lyra_preview() const {
    return descriptor_layout_.presence == rom::LyraLayoutPresence::kValid;
  }
  int inspected_map_count() const {
    if (is_lyra_preview()) {
      return descriptor_layout_.capacity;
    }
    if (has_tail_map_expansion_) {
      return kExpandedMapCount;
    }
    return kNumOverworldMaps;
  }
  bool descriptor_sprite_display_available() const { return false; }
  bool lyra_a0_terrain_writable() const {
    return is_lyra_preview() && descriptor_layout_.a0_terrain_write_supported;
  }
  const std::array<uint16_t, 256>& lyra_a0_tiles() const {
    return lyra_a0_tiles_;
  }
  absl::Status SetLyraA0Tile32(int x, int y, uint16_t tile);
 
  absl::Status LoadOverworldMaps();
 
  void LoadTileTypes();
  // Resolve collision metadata for the selected map. Custom per-sheet data is
  // read-only until a matching writer has been qualified with the team editor.
  absl::StatusOr<std::array<uint8_t, kNumTileTypes>> GetTile8CollisionTypes(
      int map_id) const;
 
  absl::Status LoadSprites();
  absl::StatusOr<OverworldSpriteSavePlan> PrepareSpriteSave() const;
  absl::Status SaveSprites();
 
  absl::Status LoadSpritesFromMap(int sprite_start, int sprite_count,
                                  int sprite_index);
 
  // ===========================================================================
  // Lazy Loading / Caching
  // ===========================================================================
 
  absl::Status EnsureMapBuilt(int map_index);
 
  void SyncAreaProperties(int map_index);
  void SetGraphicsPreview(OverworldGraphicsPreview preview);
 
  struct SubscreenOverlayLayer {
    uint16_t overlay_id = 0x00FF;
    int overlay_screen = -1;      // -1: the area has no subscreen overlay
    bool background = false;      // drawn over backdrop pixels only
    std::vector<uint8_t> pixels;  // 512x512, 0 = transparent
  };
 
  absl::StatusOr<SubscreenOverlayLayer> BuildSubscreenOverlayLayer(
      int map_index);
 
  // ---------------------------------------------------------------------------
  // Shared tileset cache
  //
  // Maps whose 17 sheet ids match (OverworldMap::tileset_key(): 16 static
  // sheets + animated sheet) share the same 64KB tileset and, for the same
  // tile16 definitions, the same 1MB tile16 blockset. The cache keeps both so
  // a map build only redoes the palette and its own 512x512 bitmap.
  // ---------------------------------------------------------------------------
 
  void ClearGraphicsConfigCache() { tileset_cache_.clear(); }
 
  void InvalidateTilesetCacheForSheet(int sheet);
 
  size_t tileset_cache_size() const { return tileset_cache_.size(); }
 
  void InvalidateMapCache(int map_index);
 
  void InvalidateSiblingMapCaches(int map_index);
 
  // ===========================================================================
  // Save Methods - Tile Data (Order Matters!)
  // ===========================================================================
  // These methods must be called in order because later saves depend on
  // tile definitions being written first.
  //
  // Required order:
  //   1. CreateTile32Tilemap() - Build tile32 from tile16 data
  //   2. SaveMap32Tiles() - Write tile32 definitions
  //   3. SaveMap16Tiles() - Write tile16 definitions
  //   4. SaveOverworldMaps() - Write compressed map data
 
  absl::Status Save(Rom* rom);
 
  absl::Status SaveOverworldMaps();
  absl::Status ValidatePrivateNativeTerrainSave() const;
 
  // Map-grid identity for skipping recompression. SaveOverworldMaps stages the
  // grids it serialized; the editor save transaction publishes that stage only
  // after the ROM transaction and disk write both commit.
  void StageSavedMapTiles();
  void CommitSavedMapTiles();
  void RollbackSavedMapTiles();
 
  absl::Status SaveLargeMaps();
 
  absl::Status SaveLargeMapsExpanded();
 
  absl::Status SaveSmallAreaTransitions(
      int i, int parent_x_pos, int parent_y_pos, int transition_target_north,
      int transition_target_west, int transition_pos_x, int transition_pos_y,
      int screen_change_1, int screen_change_2, int screen_change_3,
      int screen_change_4);
 
  absl::Status SaveLargeAreaTransitions(
      int i, int parent_x_pos, int parent_y_pos, int transition_target_north,
      int transition_target_west, int transition_pos_x, int transition_pos_y,
      int screen_change_1, int screen_change_2, int screen_change_3,
      int screen_change_4);
 
  absl::Status SaveWideAreaTransitions(
      int i, int parent_x_pos, int parent_y_pos, int transition_target_north,
      int transition_target_west, int transition_pos_x, int transition_pos_y,
      int screen_change_1, int screen_change_2, int screen_change_3,
      int screen_change_4);
 
  absl::Status SaveTallAreaTransitions(
      int i, int parent_x_pos, int parent_y_pos, int transition_target_north,
      int transition_target_west, int transition_pos_x, int transition_pos_y,
      int screen_change_1, int screen_change_2, int screen_change_3,
      int screen_change_4);
 
  // ===========================================================================
  // Save Methods - Entities (Independent, any order)
  // ===========================================================================
 
  absl::Status SaveEntrances();
 
  absl::Status SaveExits();
 
  absl::Status SaveItems();
 
  absl::Status SaveMapOverlays();
 
  absl::Status SaveOverworldTilesType();
 
  // ===========================================================================
  // Save Methods - Custom Features (v2+/v3+)
  // ===========================================================================
 
  absl::Status SaveCustomOverworldASM(bool enable_bg_color,
                                      bool enable_main_palette,
                                      bool enable_mosaic,
                                      bool enable_gfx_groups,
                                      bool enable_subscreen_overlay,
                                      bool enable_animated);
 
  absl::Status SaveAreaSpecificBGColors();
 
  absl::Status SaveCustomOverworldData();
 
  // ===========================================================================
  // Save Methods - Tile Definitions
  // ===========================================================================
 
  absl::Status CreateTile32Tilemap();
 
  absl::Status SaveMap16Expanded();
 
  absl::Status SaveMap16Tiles();
 
  absl::Status SaveMap32Expanded();
 
  absl::Status SaveMap32Tiles();
 
  // ===========================================================================
  // Save Methods - Properties
  // ===========================================================================
 
  absl::Status SaveMapProperties();
 
  absl::Status SaveMusic();
 
  absl::Status SaveAreaSizes();
 
  void AssignMapSizes(std::vector<OverworldMap>& maps);
 
  absl::Status ConfigureMultiAreaMap(int parent_index, AreaSizeEnum size);
 
  auto rom() const { return rom_; }
  auto mutable_rom() { return rom_; }
 
  std::vector<std::pair<uint32_t, uint32_t>> GetProjectedWriteRanges() const;
 
  bool HasExpandedPointerTables() const {
    const int marker_addr = GetExpandedPtrTableMarker();
    if (!rom_ || !zscream::CanUseTailExpansion(*rom_) ||
        marker_addr >= rom_->size()) {
      return false;
    }
    return rom_->data()[marker_addr] == GetExpandedPtrTableMagic();
  }
 
  void Destroy() {
    for (auto& map : overworld_maps_) {
      map.Destroy();
    }
    overworld_maps_.clear();
    all_entrances_.clear();
    all_exits_.clear();
    all_items_.clear();
    for (auto& sprites : all_sprites_) {
      sprites.clear();
    }
    sprite_maps_loaded_ = {};
    built_map_lru_.clear();
    tileset_cache_.clear();
    descriptor_layout_ = {};
    loaded_map_tiles_valid_ = false;
    tiles16_.clear();
    tiles32_.clear();
    tiles32_unique_.clear();
    is_loaded_ = false;
  }
 
  int GetTileFromPosition(ImVec2 position) const {
    if (current_world_ == 0) {
      return map_tiles_.light_world[position.x][position.y];
    } else if (current_world_ == 1) {
      return map_tiles_.dark_world[position.x][position.y];
    } else {
      return map_tiles_.special_world[position.x][position.y];
    }
  }
 
  OverworldBlockset& GetMapTiles(int world_type) {
    switch (world_type) {
      case 0:
        return map_tiles_.light_world;
      case 1:
        return map_tiles_.dark_world;
      case 2:
        return map_tiles_.special_world;
      default:
        return map_tiles_.light_world;
    }
  }
 
  const std::vector<OverworldMap>& overworld_maps() const {
    return overworld_maps_;
  }
  auto overworld_map(int i) const {
    if (i < 0 || i >= static_cast<int>(overworld_maps_.size())) {
      return static_cast<const OverworldMap*>(nullptr);
    }
    return &overworld_maps_[i];
  }
  auto mutable_overworld_map(int i) {
    if (i < 0 || i >= static_cast<int>(overworld_maps_.size())) {
      return static_cast<OverworldMap*>(nullptr);
    }
    return &overworld_maps_[i];
  }
  auto exits() const { return &all_exits_; }
  auto mutable_exits() { return &all_exits_; }
  const std::vector<gfx::Tile16>& tiles16() const { return tiles16_; }
  auto tiles32_unique() const { return tiles32_unique_; }
  auto mutable_tiles16() { return &tiles16_; }
  auto sprites(int state) const {
    if (state < 0 || state >= 3)
      return std::vector<Sprite>{};
    return all_sprites_[state];
  }
  auto mutable_sprites(int state) {
    if (state < 0 || state >= 3)
      return static_cast<std::vector<Sprite>*>(nullptr);
    return &all_sprites_[state];
  }
  const std::vector<uint8_t>& current_graphics() const {
    static const std::vector<uint8_t> kEmpty;
    if (!is_current_map_valid())
      return kEmpty;
    return overworld_maps_[current_map_].current_graphics();
  }
  const std::vector<OverworldEntrance>& entrances() const {
    return all_entrances_;
  }
  auto& entrances() { return all_entrances_; }
  auto mutable_entrances() { return &all_entrances_; }
  const std::vector<OverworldEntrance>& holes() const { return all_holes_; }
  auto& holes() { return all_holes_; }
  auto mutable_holes() { return &all_holes_; }
  auto deleted_entrances() const { return deleted_entrances_; }
  auto mutable_deleted_entrances() { return &deleted_entrances_; }
  const gfx::SnesPalette& current_area_palette() const {
    static const gfx::SnesPalette kEmpty;
    if (!is_current_map_valid())
      return kEmpty;
    return overworld_maps_[current_map_].current_palette();
  }
  const std::vector<uint8_t>& current_map_bitmap_data() const {
    static const std::vector<uint8_t> kEmpty;
    if (!is_current_map_valid())
      return kEmpty;
    return overworld_maps_[current_map_].bitmap_data();
  }
  const std::vector<uint8_t>& tile16_blockset_data() const {
    static const std::vector<uint8_t> kEmpty;
    if (!is_current_map_valid())
      return kEmpty;
    return overworld_maps_[current_map_].current_tile16_blockset();
  }
 
  bool is_current_map_valid() const {
    return current_map_ >= 0 &&
           current_map_ < static_cast<int>(overworld_maps_.size());
  }
  auto is_loaded() const { return is_loaded_; }
  auto expanded_tile16() const { return expanded_tile16_; }
  auto expanded_tile32() const { return expanded_tile32_; }
  auto expanded_entrances() const { return expanded_entrances_; }
  bool has_tail_map_expansion() const { return has_tail_map_expansion_; }
  void set_has_tail_map_expansion(bool v) { has_tail_map_expansion_ = v; }
  int current_map_id() const { return current_map_; }
  int current_world() const { return current_world_; }
  void set_current_map(int i) { current_map_ = i; }
  void set_current_world(int world) { current_world_ = world; }
  // Select the state for future builds; editor refresh owns bitmap invalidation.
  void set_game_state(int state);
  uint16_t GetTile(int x, int y) const {
    if (current_world_ == 0) {
      return map_tiles_.light_world[x][y];
    } else if (current_world_ == 1) {
      return map_tiles_.dark_world[x][y];
    } else {
      return map_tiles_.special_world[x][y];
    }
  }
  void SetTile(int x, int y, uint16_t tile_id) {
    if (current_world_ == 0) {
      map_tiles_.light_world[x][y] = tile_id;
    } else if (current_world_ == 1) {
      map_tiles_.dark_world[x][y] = tile_id;
    } else {
      map_tiles_.special_world[x][y] = tile_id;
    }
  }
  auto map_tiles() const { return map_tiles_; }
  auto mutable_map_tiles() { return &map_tiles_; }
  auto all_items() const { return all_items_; }
  auto mutable_all_items() { return &all_items_; }
  auto all_tiles_types() const { return all_tiles_types_; }
  auto mutable_all_tiles_types() { return &all_tiles_types_; }
  auto all_sprites() const { return all_sprites_; }
 
  // Diggable tiles management
  const DiggableTiles& diggable_tiles() const { return diggable_tiles_; }
  DiggableTiles* mutable_diggable_tiles() { return &diggable_tiles_; }
  absl::Status LoadDiggableTiles();
  absl::Status SaveDiggableTiles();
  absl::Status AutoDetectDiggableTiles();
 
 private:
  enum Dimension {
    map32TilesTL = 0,
    map32TilesTR = 1,
    map32TilesBL = 2,
    map32TilesBR = 3
  };
 
  void FetchLargeMaps();
  absl::StatusOr<uint16_t> GetTile16ForTile32(int index, int quadrant,
                                              int dimension,
                                              const uint32_t* map32address);
  absl::Status AssembleMap32Tiles();
  absl::Status AssembleMap16Tiles();
  void AssignWorldTiles(int x, int y, int sx, int sy, int tpos,
                        OverworldBlockset& world);
  void FillBlankMapTiles(int map_index);
  OverworldBlockset& SelectWorldBlockset(int world_type);
  void OrganizeMapTiles(std::vector<uint8_t>& bytes,
                        std::vector<uint8_t>& bytes2, int i, int sx, int sy,
                        int& ttpos);
  absl::Status DecompressAllMapTilesParallel();
  absl::Status BuildLyraTerrainPreview(Rom* rom,
                                       rom::LyraLayoutInspection layout);
 
  Rom* rom_;
  GameData* game_data_ = nullptr;
 
  bool is_loaded_ = false;
  bool expanded_tile16_ = false;
  bool expanded_tile32_ = false;
  bool expanded_entrances_ = false;
  bool has_tail_map_expansion_ = false;
 
  int game_state_ = 0;
  int current_map_ = 0;
  int current_world_ = 0;
 
  // Cached ROM version to avoid repeated detection during loading
  OverworldVersion cached_version_ = OverworldVersion::kVanilla;
 
  OverworldMapTiles map_tiles_;
  rom::LyraLayoutInspection descriptor_layout_;
  std::array<uint16_t, 256> lyra_a0_tiles_{};
  // Grids last published by a committed save, or captured at load. Recompressing
  // maps rewrites pointer tables that overlap Oracle overworld ASM hooks, and
  // resaving tile32 reorders expanded definitions. An unchanged grid leaves
  // both on disk. The staged copy is not this identity: a failed save rolls
  // the ROM back and must not treat the unsaved edit as already written.
  std::vector<gfx::Tile16> private_loaded_tiles16_;
  std::vector<uint8_t> private_loaded_overlays_;
  OverworldMapTiles loaded_map_tiles_;
  bool loaded_map_tiles_valid_ = false;
  OverworldMapTiles staged_map_tiles_;
  bool staged_map_tiles_valid_ = false;
  bool MapTilesUnchanged() const;
 
  // Thread safety for parallel operations
  mutable std::mutex map_tiles_mutex_;
 
  // LRU cache for built maps to prevent memory exhaustion.
  // Keep this aligned with the essential preload set so the default startup
  // world stays warm without permanently retaining dozens of maps.
  static constexpr int kMaxBuiltMaps = 8;
  std::deque<int> built_map_lru_;
 
  // Shared tileset cache (see ClearGraphicsConfigCache()).
  // GraphicsSheetStore revision of each sheet in an OverworldTilesetKey.
  using TilesetRevisions =
      std::array<uint64_t, std::tuple_size_v<OverworldTilesetKey>>;
  TilesetRevisions SheetRevisionsForKey(const OverworldTilesetKey& key) const;
 
  struct TilesetCacheEntry {
    TilesetRevisions sheet_revisions{};    // store revisions when built
    std::vector<uint8_t> current_gfx;      // 64KB tileset
    std::vector<uint8_t> tile16_blockset;  // 1MB tile16 pixels (may be empty)
    uint64_t tiles16_fingerprint = 0;      // tile16 defs the blockset used
    uint64_t last_use = 0;
  };
  std::map<OverworldTilesetKey, TilesetCacheEntry> tileset_cache_;
  uint64_t tileset_cache_clock_ = 0;
#ifdef __EMSCRIPTEN__
  static constexpr size_t kMaxCachedTilesets = 8;  // ~8.5MB
#else
  static constexpr size_t kMaxCachedTilesets = 24;  // ~26MB
#endif
 
  uint64_t Tiles16Fingerprint() const;
  absl::Status BuildMapWithTilesetCache(int map_index, int world_type);
 
  std::vector<OverworldMap> overworld_maps_;
  OverworldGraphicsPreview graphics_preview_;
  std::vector<OverworldEntrance> all_entrances_;
  std::vector<OverworldEntrance> all_holes_;
  std::vector<OverworldExit> all_exits_;
  std::vector<OverworldItem> all_items_;
 
  std::vector<gfx::Tile16> tiles16_;
  std::vector<gfx::Tile32> tiles32_;
  std::vector<gfx::Tile32> tiles32_unique_;
 
  std::vector<uint16_t> tiles32_list_;
  std::vector<uint64_t> deleted_entrances_;
 
  std::array<uint8_t, kNumOverworldMaps> map_parent_ = {0};
  std::array<uint8_t, kNumTileTypes> all_tiles_types_ = {0};
  std::array<std::vector<Sprite>, 3> all_sprites_;
  std::array<std::array<bool, 160>, 3> sprite_maps_loaded_{};
  DiggableTiles diggable_tiles_;
  std::array<std::vector<uint8_t>, kNumOverworldMaps> map_data_p1;
  std::array<std::vector<uint8_t>, kNumOverworldMaps> map_data_p2;
  std::array<int, kNumOverworldMaps> map_pointers1_id;
  std::array<int, kNumOverworldMaps> map_pointers2_id;
  std::array<int, kNumOverworldMaps> map_pointers1;
  std::array<int, kNumOverworldMaps> map_pointers2;
};
 
}  // namespace yaze::zelda3
 
#endif