overworld.cc

Go to the documentation of this file.

#include "overworld.h"
 
#include <algorithm>
#include <array>
#include <cstddef>
#include <cstdint>
#include <future>
#include <iostream>
#include <limits>
#include <ostream>
#include <set>
#include <string>
#include <unordered_map>
#include <vector>
 
#include "absl/status/status.h"
#include "absl/status/statusor.h"
#include "absl/strings/str_format.h"
#include "app/gfx/debug/performance/performance_profiler.h"
#include "app/gfx/types/snes_tile.h"
#include "app/gfx/util/compression.h"
#include "core/features.h"
#include "rom/rom.h"
#include "rom/snes.h"
#include "rom/transaction.h"
#include "util/hex.h"
#include "util/log.h"
#include "util/macro.h"
#include "zelda3/common.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_version_helper.h"
#include "zelda3/overworld/zscream_custom_layout.h"
#include "zelda3/resource_labels.h"
 
namespace yaze::zelda3 {
 
namespace {
 
std::vector<uint8_t> PrivateOverlaySnapshot(
    const std::vector<OverworldMap>& maps) {
  std::vector<uint8_t> bytes;
  const auto append = [&bytes](uint32_t value) {
    for (int shift = 0; shift < 32; shift += 8)
      bytes.push_back(static_cast<uint8_t>(value >> shift));
  };
  append(static_cast<uint32_t>(maps.size()));
  for (const auto& map : maps) {
    append(map.overlay_id());
    append(map.has_overlay() ? 1 : 0);
    append(map.subscreen_overlay());
    append(map.render_subscreen_overlay());
    append(static_cast<uint32_t>(map.overlay_data().size()));
    bytes.insert(bytes.end(), map.overlay_data().begin(),
                 map.overlay_data().end());
  }
  return bytes;
}
 
struct Map32StorageLayout {
  std::array<int, 4> destinations{};
  int storage_bytes_per_quadrant = 0;
  int definition_capacity = 0;
  bool expanded = false;
};
 
absl::StatusOr<Map32StorageLayout> ResolveMap32StorageLayout(
    const Rom& rom, const zelda3_version_pointers& version_constants) {
  const auto profile = DetectOverworldRomProfile(rom);
 
  Map32StorageLayout layout;
  layout.expanded = profile.has_expanded_tile32;
  layout.destinations = {
      static_cast<int>(version_constants.kMap32TileTL),
      layout.expanded ? GetMap32TileTRExpanded()
                      : static_cast<int>(version_constants.kMap32TileTR),
      layout.expanded ? GetMap32TileBLExpanded()
                      : static_cast<int>(version_constants.kMap32TileBL),
      layout.expanded ? GetMap32TileBRExpanded()
                      : static_cast<int>(version_constants.kMap32TileBR),
  };
 
  int usable_bytes = Map32StorageBytesForProfile(profile);
  for (int destination : layout.destinations) {
    if (destination < 0 || static_cast<size_t>(destination) >= rom.size()) {
      return absl::OutOfRangeError(absl::StrFormat(
          "Tile32 destination 0x%06X is outside the ROM", destination));
    }
    const size_t available = rom.size() - static_cast<size_t>(destination);
    usable_bytes = std::min(usable_bytes,
                            static_cast<int>(std::min<size_t>(
                                available, std::numeric_limits<int>::max())));
  }
 
  // ROM EOF is not the only boundary: quadrant tables must not grow into the
  // next configured destination. This matters for layouts such as the JP ROM,
  // whose vanilla TL/TR and BL/BR spans are 0x33C0 rather than 0x33F0 bytes.
  auto ordered_destinations = layout.destinations;
  std::sort(ordered_destinations.begin(), ordered_destinations.end());
  for (size_t i = 1; i < ordered_destinations.size(); ++i) {
    const int span = ordered_destinations[i] - ordered_destinations[i - 1];
    if (span <= 0) {
      return absl::FailedPreconditionError(
          "Tile32 destinations overlap or share the same address");
    }
    usable_bytes = std::min(usable_bytes, span);
  }
 
  // A partial packed group cannot store any additional definitions.
  usable_bytes -= usable_bytes % kMap32BytesPerPackedGroup;
  if (usable_bytes <= 0) {
    return absl::ResourceExhaustedError(
        "Tile32 destinations have no usable packed storage");
  }
 
  layout.storage_bytes_per_quadrant = usable_bytes;
  layout.definition_capacity =
      Map32DefinitionCapacityForStorageBytes(usable_bytes);
  return layout;
}
 
absl::Status ValidateMap32DefinitionCount(size_t definition_count,
                                          const Map32StorageLayout& layout) {
  if (definition_count % kMap32DefinitionsPerPackedGroup != 0) {
    return absl::InvalidArgumentError(absl::StrFormat(
        "Tile32 definition count %zu is not aligned to a packed group of %d",
        definition_count, kMap32DefinitionsPerPackedGroup));
  }
  if (definition_count > static_cast<size_t>(layout.definition_capacity)) {
    return absl::ResourceExhaustedError(absl::StrFormat(
        "Number of unique Tiles32: %zu Out of: %d\n"
        "Unique Tile32 count exceeds the %s destination capacity; the ROM has "
        "not been written",
        definition_count, layout.definition_capacity,
        layout.expanded ? "expanded" : "vanilla"));
  }
 
  const size_t required_bytes =
      (definition_count / kMap32DefinitionsPerPackedGroup) *
      kMap32BytesPerPackedGroup;
  if (required_bytes > static_cast<size_t>(layout.storage_bytes_per_quadrant)) {
    return absl::ResourceExhaustedError(absl::StrFormat(
        "Tile32 definitions require %zu bytes per quadrant; destination "
        "capacity is %d bytes",
        required_bytes, layout.storage_bytes_per_quadrant));
  }
  return absl::OkStatus();
}
 
}  // namespace
 
void Overworld::set_game_state(int state) {
  game_state_ = std::clamp(state, 0, 2);
}
 
absl::Status Overworld::Load(Rom* rom) {
  gfx::ScopedTimer timer("Overworld::Load");
 
  if (rom->size() == 0) {
    return absl::InvalidArgumentError("ROM file not loaded");
  }
  if (const auto* manifest = GetResourceLabels().hack_manifest()) {
    RETURN_IF_ERROR(rom->AttachLyraPrivateReservation(*manifest));
  }
  const auto layout = rom->InspectLyraLayout();
  if (layout.presence == yaze::rom::LyraLayoutPresence::kInvalid) {
    return absl::FailedPreconditionError(
        "Invalid Lyra descriptor; overworld loading refused");
  }
  if (layout.presence == yaze::rom::LyraLayoutPresence::kValid) {
    return absl::FailedPreconditionError(
        "Lyra descriptor canvas loading is not yet supported");
  }
  // Reload replaces ROM-derived state. In particular, CreateTile32Tilemap()
  // may have reordered the in-memory definitions during an unchanged save;
  // appending the ROM definitions would retain that stale index prefix.
  // Destroy preserves the bound GameData, selection and graphics preview.
  Destroy();
  tiles32_list_.clear();
  map_tiles_ = {};
  loaded_map_tiles_ = {};
  RollbackSavedMapTiles();
  expanded_tile16_ = false;
  expanded_tile32_ = false;
  descriptor_layout_ = {};
  rom_ = rom;
 
  const auto profile = DetectOverworldRomProfile(*rom_);
  // Cache ROM version to avoid repeated detection (called 160+ times otherwise)
  cached_version_ = profile.version;
  expanded_entrances_ = profile.has_expanded_entrances;
  has_tail_map_expansion_ = profile.has_tail_map_expansion;
 
  // Phase 1: Tile Assembly (can be parallelized)
  {
    gfx::ScopedTimer assembly_timer("AssembleTiles");
    RETURN_IF_ERROR(AssembleMap32Tiles());
    RETURN_IF_ERROR(AssembleMap16Tiles());
  }
 
  // Phase 2: Map Decompression (major bottleneck - now parallelized)
  {
    gfx::ScopedTimer decompression_timer("DecompressAllMapTiles");
    RETURN_IF_ERROR(DecompressAllMapTilesParallel());
  }
 
  // Phase 3: Map Object Creation (fast)
  {
    gfx::ScopedTimer map_creation_timer("CreateOverworldMapObjects");
    for (int map_index = 0; map_index < kNumOverworldMaps; ++map_index)
      overworld_maps_.emplace_back(map_index, rom_, game_data_);
 
    // Populate map_parent_ array with parent information from each map
    for (int map_index = 0; map_index < kNumOverworldMaps; ++map_index) {
      map_parent_[map_index] = overworld_maps_[map_index].parent();
    }
  }
 
  // Phase 4: Map Configuration (uses cached_version_ for performance)
  if (OverworldVersionHelper::SupportsAreaEnum(cached_version_)) {
    AssignMapSizes(overworld_maps_);
  } else {
    FetchLargeMaps();
  }
 
  // Phase 5: Data Loading (with individual timing)
  {
    gfx::ScopedTimer data_loading_timer("LoadOverworldData");
 
    {
      gfx::ScopedTimer tile_types_timer("LoadTileTypes");
      LoadTileTypes();
    }
 
    {
      gfx::ScopedTimer diggable_tiles_timer("LoadDiggableTiles");
      RETURN_IF_ERROR(LoadDiggableTiles());
    }
 
    {
      gfx::ScopedTimer entrances_timer("LoadEntrances");
      ASSIGN_OR_RETURN(all_entrances_, LoadEntrances(rom_));
    }
 
    {
      gfx::ScopedTimer holes_timer("LoadHoles");
      ASSIGN_OR_RETURN(all_holes_, LoadHoles(rom_));
    }
 
    {
      gfx::ScopedTimer exits_timer("LoadExits");
      ASSIGN_OR_RETURN(all_exits_, LoadExits(rom_));
    }
 
    {
      gfx::ScopedTimer items_timer("LoadItems");
      ASSIGN_OR_RETURN(all_items_, LoadItems(rom_, overworld_maps_));
    }
 
    {
      gfx::ScopedTimer overworld_maps_timer("LoadOverworldMaps");
      RETURN_IF_ERROR(LoadOverworldMaps());
    }
 
    {
      gfx::ScopedTimer sprites_timer("LoadSprites");
      RETURN_IF_ERROR(LoadSprites());
    }
  }
 
  if (rom_->has_lyra_private_reservation()) {
    // Overlay caches are otherwise lazy. Resolve every native map before the
    // snapshot so browsing an unbuilt map cannot look like an authored edit.
    for (auto& map : overworld_maps_)
      RETURN_IF_ERROR(map.LoadOverlay());
    private_loaded_overlays_ = PrivateOverlaySnapshot(overworld_maps_);
  }
  private_loaded_tiles16_ = tiles16_;
  loaded_map_tiles_ = map_tiles_;
  loaded_map_tiles_valid_ = true;
  is_loaded_ = true;
  return absl::OkStatus();
}
 
absl::Status Overworld::LoadLyraTerrainPreview(Rom* rom) {
  if (rom == nullptr || rom->size() == 0) {
    return absl::InvalidArgumentError("ROM file not loaded");
  }
  if (is_loaded_) {
    return absl::FailedPreconditionError(
        "Lyra terrain preview requires a fresh overworld model");
  }
  auto layout = rom->InspectLyraLayout();
  if (layout.presence != yaze::rom::LyraLayoutPresence::kValid) {
    return absl::FailedPreconditionError(
        "Valid Lyra descriptor required for terrain preview");
  }
  return BuildLyraTerrainPreview(rom, std::move(layout));
}
 
absl::Status Overworld::BuildLyraTerrainPreview(
    Rom* rom, rom::LyraLayoutInspection layout) {
  // This path materializes descriptor terrain and render properties only.
  // Sprite display and every serializer remain unavailable for this format.
  rom_ = rom;
  descriptor_layout_ = std::move(layout);
  const auto profile = DetectOverworldRomProfile(*rom_);
  cached_version_ = profile.version;
  expanded_entrances_ = profile.has_expanded_entrances;
  has_tail_map_expansion_ = profile.has_tail_map_expansion;
  tiles16_.clear();
  tiles32_unique_.clear();
  overworld_maps_.clear();
  built_map_lru_.clear();
  tileset_cache_.clear();
  RETURN_IF_ERROR(AssembleMap32Tiles());
  RETURN_IF_ERROR(AssembleMap16Tiles());
  for (int map_index = 0; map_index < descriptor_layout_.capacity;
       ++map_index) {
    auto tiles = rom::LyraMapTile32(descriptor_layout_, rom_->data(),
                                    rom_->size(), map_index);
    if (!tiles) {
      return absl::FailedPreconditionError(
          absl::StrFormat("Lyra map %02X stream is invalid", map_index));
    }
    if (map_index == 0xA0) {
      lyra_a0_tiles_ = *tiles;
    }
    const int local = map_index & 0x3F;
    const int sx = local % 8;
    const int sy = local / 8;
    auto& world = SelectWorldBlockset(WorldForOverworldMap(map_index));
    for (int y = 0; y < 16; ++y) {
      for (int x = 0; x < 16; ++x) {
        const int tile = (*tiles)[y * 16 + x];
        if (tile >= static_cast<int>(tiles32_unique_.size())) {
          return absl::FailedPreconditionError(
              "Lyra Tile32 definition unavailable");
        }
        AssignWorldTiles(x, y, sx, sy, tile, world);
      }
    }
    ASSIGN_OR_RETURN(
        auto map, OverworldMap::CreateLyraPreview(map_index, rom_, game_data_,
                                                  &descriptor_layout_));
    overworld_maps_.push_back(std::move(map));
    if (map_index < kNumOverworldMaps) {
      map_parent_[map_index] = overworld_maps_.back().parent();
    }
  }
  loaded_map_tiles_ = map_tiles_;
  loaded_map_tiles_valid_ = true;
  is_loaded_ = true;
  return absl::OkStatus();
}
 
absl::Status Overworld::SetLyraA0Tile32(int x, int y, uint16_t tile) {
  if (!lyra_a0_terrain_writable()) {
    return absl::FailedPreconditionError("Lyra A0 terrain is read-only");
  }
  if (x < 0 || x >= 16 || y < 0 || y >= 16 ||
      (tile != 0x2103 && tile != 0x20B2) || tile >= tiles32_unique_.size()) {
    return absl::InvalidArgumentError("Unsupported Lyra A0 terrain edit");
  }
  if ((x == 7 || x == 8) && (y == 7 || y == 8) && tile != 0x2103) {
    return absl::FailedPreconditionError(
        "Lyra A0 entry and return anchors must remain walkable");
  }
  if (lyra_a0_tiles_[y * 16 + x] == tile) {
    return absl::OkStatus();
  }
  // Reuse one existing Tile32 definition; never rebuild shared definitions.
  AssignWorldTiles(x, y, 0, 4, tile, map_tiles_.special_world);
  lyra_a0_tiles_[y * 16 + x] = tile;
  overworld_maps_[0xA0].SetNotBuilt();
  return absl::OkStatus();
}
 
void Overworld::FetchLargeMaps() {
  // For vanilla/v1/v2 ROMs, parent IDs are already loaded from ROM in the
  // OverworldMap constructor. This function now uses those ROM values instead
  // of recalculating them, ensuring custom parent mappings are respected.
  //
  // The function determines large_index_ (quadrant) based on the relationship
  // between map index and its parent, rather than grid-walking.
 
  // First pass: Set up special world maps using ROM data
  for (int i = 128; i < kNumOverworldMaps; i++) {
    int parent = overworld_maps_[i].parent();
 
    if (overworld_maps_[i].is_large_map()) {
      // Calculate quadrant based on position relative to parent
      int quadrant = 0;
      if (i == parent) {
        quadrant = 0;  // Top-left (parent itself)
      } else if (i == parent + 1) {
        quadrant = 1;  // Top-right
      } else if (i == parent + 8) {
        quadrant = 2;  // Bottom-left
      } else if (i == parent + 9) {
        quadrant = 3;  // Bottom-right
      }
      // Use SetAsLargeMap but pass the ROM parent value, not a calculated one
      overworld_maps_[i].SetAsLargeMap(parent, quadrant);
    } else {
      overworld_maps_[i].SetAsSmallMap(i);
    }
  }
 
  // Track visited maps across LW/DW (0x00-0x7F)
  std::array<bool, kNumOverworldMaps> map_checked{};
  std::ranges::fill(map_checked, false);
 
  // Second pass: Process LW/DW maps using ROM parent values
  for (int world_offset = 0; world_offset < 128; world_offset += 64) {
    for (int local = 0; local < 64; local++) {
      int i = world_offset + local;
 
      if (map_checked[i])
        continue;
 
      int parent = overworld_maps_[i].parent();
 
      if (overworld_maps_[i].is_large_map()) {
        // This map is part of a large area - set up all 4 quadrants
        // The parent value from ROM tells us which map is the parent
 
        // Calculate quadrant based on position relative to parent
        int quadrant = 0;
        if (i == parent) {
          quadrant = 0;  // This IS the parent (top-left)
        } else if (i == parent + 1) {
          quadrant = 1;  // Top-right
        } else if (i == parent + 8) {
          quadrant = 2;  // Bottom-left
        } else if (i == parent + 9) {
          quadrant = 3;  // Bottom-right
        }
 
        overworld_maps_[i].SetAsLargeMap(parent, quadrant);
        map_checked[i] = true;
 
        // Mark siblings as checked and set their quadrants
        // Use the ROM parent value for all siblings
        // Ensure siblings stay within the same world to prevent cross-world issues
        std::array<int, 4> siblings = {parent, parent + 1, parent + 8,
                                       parent + 9};
        int world_start = world_offset;
        int world_end = world_offset + 64;
        for (int q = 0; q < 4; q++) {
          int sibling = siblings[q];
          // Check sibling is within the same world (LW: 0-63, DW: 64-127)
          if (sibling >= world_start && sibling < world_end &&
              !map_checked[sibling]) {
            overworld_maps_[sibling].SetAsLargeMap(parent, q);
            map_checked[sibling] = true;
          }
        }
      } else {
        // Small map - parent should be itself
        overworld_maps_[i].SetAsSmallMap(i);
        map_checked[i] = true;
      }
    }
  }
}
 
void Overworld::AssignMapSizes(std::vector<OverworldMap>& maps) {
  std::vector<bool> map_checked(kNumOverworldMaps, false);
 
  int xx = 0;
  int yy = 0;
  int world = 0;
 
  while (true) {
    int i = world + xx + (yy * 8);
 
    if (i >= static_cast<int>(map_checked.size())) {
      break;
    }
 
    if (!map_checked[i]) {
      switch (maps[i].area_size()) {
        case AreaSizeEnum::SmallArea:
          map_checked[i] = true;
          maps[i].SetAreaSize(AreaSizeEnum::SmallArea);
          break;
 
        case AreaSizeEnum::LargeArea:
          map_checked[i] = true;
          maps[i].SetAsLargeMap(i, 0);
 
          if (i + 1 < static_cast<int>(maps.size())) {
            map_checked[i + 1] = true;
            maps[i + 1].SetAsLargeMap(i, 1);
          }
 
          if (i + 8 < static_cast<int>(maps.size())) {
            map_checked[i + 8] = true;
            maps[i + 8].SetAsLargeMap(i, 2);
          }
 
          if (i + 9 < static_cast<int>(maps.size())) {
            map_checked[i + 9] = true;
            maps[i + 9].SetAsLargeMap(i, 3);
          }
 
          xx++;
          break;
 
        case AreaSizeEnum::WideArea:
          map_checked[i] = true;
          // Map i is parent (left, quadrant 0), map i+1 is child (right,
          // quadrant 1).
          maps[i].SetAsWideMap(i, 0);
 
          if (i + 1 < static_cast<int>(maps.size())) {
            map_checked[i + 1] = true;
            maps[i + 1].SetAsWideMap(i, 1);
          }
 
          xx++;
          break;
 
        case AreaSizeEnum::TallArea:
          map_checked[i] = true;
          // Map i is parent (top, quadrant 0), map i+8 is child (bottom,
          // quadrant 2).
          maps[i].SetAsTallMap(i, 0);
 
          if (i + 8 < static_cast<int>(maps.size())) {
            map_checked[i + 8] = true;
            maps[i + 8].SetAsTallMap(i, 2);
          }
          break;
      }
    }
 
    xx++;
    if (xx >= 8) {
      xx = 0;
      yy += 1;
 
      if (yy >= 8) {
        yy = 0;
        world += 0x40;
      }
    }
  }
}
 
absl::Status Overworld::ConfigureMultiAreaMap(int parent_index,
                                              AreaSizeEnum size) {
  if (parent_index < 0 || parent_index >= kNumOverworldMaps) {
    return absl::InvalidArgumentError(
        absl::StrFormat("Invalid parent index: %d", parent_index));
  }
 
  // Version requirements:
  // - Vanilla (0xFF): Supports Small and Large only
  // - v1-v2: Supports Small and Large only
  // - v3+: Supports all 4 sizes (Small, Large, Wide, Tall)
  if ((size == AreaSizeEnum::WideArea || size == AreaSizeEnum::TallArea) &&
      !OverworldVersionHelper::SupportsAreaEnum(cached_version_)) {
    return absl::FailedPreconditionError(
        "Wide and Tall areas require ZSCustomOverworld v3+");
  }
  if (!OverworldVersionHelper::SupportsAreaEnum(cached_version_) &&
      !CanPersistLegacyMultiAreaMap(parent_index)) {
    return absl::FailedPreconditionError(
        "Special World multi-area changes require ZSCustomOverworld v3+");
  }
 
  LOG_DEBUG("Overworld",
            "ConfigureMultiAreaMap: parent=%d, current_size=%d, new_size=%d, "
            "version=%s",
            parent_index,
            static_cast<int>(overworld_maps_[parent_index].area_size()),
            static_cast<int>(size),
            OverworldVersionHelper::GetVersionName(cached_version_));
 
  // CRITICAL: First, get OLD siblings (before changing) so we can reset them
  std::vector<int> old_siblings;
  auto old_size = overworld_maps_[parent_index].area_size();
  int old_parent = overworld_maps_[parent_index].parent();
 
  switch (old_size) {
    case AreaSizeEnum::LargeArea:
      old_siblings = {old_parent, old_parent + 1, old_parent + 8,
                      old_parent + 9};
      break;
    case AreaSizeEnum::WideArea:
      old_siblings = {old_parent, old_parent + 1};
      break;
    case AreaSizeEnum::TallArea:
      old_siblings = {old_parent, old_parent + 8};
      break;
    default:
      old_siblings = {parent_index};  // Was small, just this map
      break;
  }
 
  // Validate the NEW sibling set before mutating so invalid edge maps do not
  // partially reset the old area.
  std::vector<int> new_siblings;
  switch (size) {
    case AreaSizeEnum::SmallArea:
      new_siblings = {parent_index};
      break;
    case AreaSizeEnum::LargeArea:
      new_siblings = {parent_index, parent_index + 1, parent_index + 8,
                      parent_index + 9};
      break;
    case AreaSizeEnum::WideArea:
      new_siblings = {parent_index, parent_index + 1};
      break;
    case AreaSizeEnum::TallArea:
      new_siblings = {parent_index, parent_index + 8};
      break;
  }
  for (int sibling : new_siblings) {
    if (sibling < 0 || sibling >= kNumOverworldMaps ||
        !IsSameOverworldWorld(parent_index, sibling)) {
      return absl::FailedPreconditionError(
          absl::StrFormat("Area size crosses an overworld boundary: parent=%d "
                          "sibling=%d",
                          parent_index, sibling));
    }
  }
 
  // Reset all old siblings to SmallArea first (clean slate).
  for (int old_sibling : old_siblings) {
    if (old_sibling >= 0 && old_sibling < kNumOverworldMaps) {
      overworld_maps_[old_sibling].SetAsSmallMap(old_sibling);
    }
  }
 
  // Now configure NEW siblings based on requested size.
  switch (size) {
    case AreaSizeEnum::SmallArea:
      overworld_maps_[parent_index].SetParent(parent_index);
      overworld_maps_[parent_index].SetAreaSize(AreaSizeEnum::SmallArea);
      break;
 
    case AreaSizeEnum::LargeArea:
      for (size_t i = 0; i < new_siblings.size(); ++i) {
        overworld_maps_[new_siblings[i]].SetAsLargeMap(parent_index, i);
      }
      break;
 
    case AreaSizeEnum::WideArea:
      overworld_maps_[new_siblings[0]].SetAsWideMap(parent_index, 0);
      overworld_maps_[new_siblings[1]].SetAsWideMap(parent_index, 1);
      break;
 
    case AreaSizeEnum::TallArea:
      overworld_maps_[new_siblings[0]].SetAsTallMap(parent_index, 0);
      overworld_maps_[new_siblings[1]].SetAsTallMap(parent_index, 2);
      break;
  }
 
  // Update ROM data for ALL affected siblings (old + new)
  std::set<int> all_affected;
  for (int sibling : old_siblings) {
    all_affected.insert(sibling);
  }
  for (int sibling : new_siblings) {
    all_affected.insert(sibling);
  }
 
  if (OverworldVersionHelper::SupportsAreaEnum(cached_version_)) {
    // v3+: Update expanded tables
    for (int sibling : all_affected) {
      if (sibling < 0 || sibling >= kNumOverworldMaps)
        continue;
 
      RETURN_IF_ERROR(
          rom()->WriteByte(GetOverworldMapParentIdExpanded() + sibling,
                           overworld_maps_[sibling].parent()));
      RETURN_IF_ERROR(rom()->WriteByte(
          kOverworldScreenSize + sibling,
          static_cast<uint8_t>(overworld_maps_[sibling].area_size())));
    }
  } else {
    // Vanilla/v1/v2: the parent and size tables are 64-entry legacy tables
    // shared by Light World and Dark World. Store local indices only; writing
    // full map ids would run into adjacent ROM data and cannot persist Special
    // World layout changes.
    for (int sibling : all_affected) {
      if (!CanPersistLegacyMultiAreaMap(sibling)) {
        continue;
      }
 
      const int parent_table_index = LegacyParentTableIndexForMap(sibling);
      RETURN_IF_ERROR(rom()->WriteByte(
          kOverworldMapParentId + parent_table_index,
          LegacyParentTableValueForMap(overworld_maps_[sibling].parent())));
      if (CanPersistLegacyScreenSize(sibling)) {
        const int screen_size_index = LegacyScreenSizeTableIndexForMap(sibling);
        RETURN_IF_ERROR(rom()->WriteByte(
            kOverworldScreenSize + screen_size_index,
            (overworld_maps_[sibling].area_size() == AreaSizeEnum::LargeArea)
                ? 0x00
                : 0x01));
      }
    }
  }
 
  LOG_DEBUG("Overworld",
            "Configured %s area: parent=%d, old_siblings=%zu, new_siblings=%zu",
            (size == AreaSizeEnum::LargeArea)  ? "Large"
            : (size == AreaSizeEnum::WideArea) ? "Wide"
            : (size == AreaSizeEnum::TallArea) ? "Tall"
                                               : "Small",
            parent_index, old_siblings.size(), new_siblings.size());
 
  return absl::OkStatus();
}
 
absl::StatusOr<uint16_t> Overworld::GetTile16ForTile32(
    int index, int quadrant, int dimension, const uint32_t* map32address) {
  ASSIGN_OR_RETURN(
      auto arg1, rom()->ReadByte(map32address[dimension] + quadrant + (index)));
  ASSIGN_OR_RETURN(auto arg2,
                   rom()->ReadByte(map32address[dimension] + (index) +
                                   (quadrant <= 1 ? 4 : 5)));
  return (uint16_t)(arg1 +
                    (((arg2 >> (quadrant % 2 == 0 ? 4 : 0)) & 0x0F) * 256));
}
 
absl::Status Overworld::AssembleMap32Tiles() {
  constexpr int kMap32TilesLength = 0x33F0;
  int num_tile32 = kMap32TilesLength;
  uint32_t map32address[4] = {
      version_constants().kMap32TileTL, version_constants().kMap32TileTR,
      version_constants().kMap32TileBL, version_constants().kMap32TileBR};
 
  // Check if expanded tile32 data is actually present in ROM
  // The flag position should contain 0x04 for vanilla, something else for
  // expanded
  const auto profile = DetectOverworldRomProfile(*rom());
  uint8_t expanded_flag = ReadRomByteOr(*rom(), kMap32ExpandedFlagPos, 0x04);
  util::logf("Expanded tile32 flag: %d", expanded_flag);
  if (profile.has_expanded_tile32) {
    // ROM has expanded tile32 data - use expanded addresses
    map32address[0] = version_constants().kMap32TileTL;
    map32address[1] = GetMap32TileTRExpanded();
    map32address[2] = GetMap32TileBLExpanded();
    map32address[3] = GetMap32TileBRExpanded();
    num_tile32 = kMap32TileCountExpanded;
    expanded_tile32_ = true;
  }
  // Otherwise use vanilla addresses (already set above)
 
  // Loop through each 32x32 pixel tile in the rom
  for (int i = 0; i < num_tile32; i += 6) {
    // Loop through each quadrant of the 32x32 pixel tile.
    for (int k = 0; k < 4; k++) {
      // Generate the 16-bit tile for the current quadrant of the current
      // 32x32 pixel tile.
      ASSIGN_OR_RETURN(
          uint16_t tl,
          GetTile16ForTile32(i, k, (int)Dimension::map32TilesTL, map32address));
      ASSIGN_OR_RETURN(
          uint16_t tr,
          GetTile16ForTile32(i, k, (int)Dimension::map32TilesTR, map32address));
      ASSIGN_OR_RETURN(
          uint16_t bl,
          GetTile16ForTile32(i, k, (int)Dimension::map32TilesBL, map32address));
      ASSIGN_OR_RETURN(
          uint16_t br,
          GetTile16ForTile32(i, k, (int)Dimension::map32TilesBR, map32address));
 
      // Add the generated 16-bit tiles to the tiles32 vector.
      tiles32_unique_.emplace_back(gfx::Tile32(tl, tr, bl, br));
    }
  }
 
  map_tiles_.light_world.resize(0x200);
  map_tiles_.dark_world.resize(0x200);
  map_tiles_.special_world.resize(0x200);
  for (int i = 0; i < 0x200; i++) {
    map_tiles_.light_world[i].resize(0x200);
    map_tiles_.dark_world[i].resize(0x200);
    map_tiles_.special_world[i].resize(0x200);
  }
 
  return absl::OkStatus();
}
 
absl::StatusOr<std::vector<gfx::Tile16>> ReadMap16Tiles(const Rom& rom,
                                                        bool* expanded) {
  int tpos = kMap16Tiles;
  int num_tile16 = kNumTile16Individual;
 
  // Check if expanded tile16 data is actually present in ROM
  // The flag position should contain 0x0F for vanilla, something else for
  // expanded
  const auto profile = DetectOverworldRomProfile(rom);
  uint8_t expanded_flag = ReadRomByteOr(rom, kMap16ExpandedFlagPos, 0x0F);
  util::logf("Expanded tile16 flag: %d", expanded_flag);
  if (expanded != nullptr) {
    *expanded = profile.has_expanded_tile16;
  }
  if (profile.has_expanded_tile16) {
    // ROM has expanded tile16 data - use expanded addresses
    tpos = GetMap16TilesExpanded();
    num_tile16 = NumberOfMap16Ex;
  }
  // Otherwise use vanilla addresses (already set above)
 
  std::vector<gfx::Tile16> tiles16;
  tiles16.reserve(num_tile16);
  for (int i = 0; i < num_tile16; i += 1) {
    ASSIGN_OR_RETURN(auto t0_data, rom.ReadWord(tpos));
    gfx::TileInfo t0 = gfx::GetTilesInfo(t0_data);
    tpos += 2;
    ASSIGN_OR_RETURN(auto t1_data, rom.ReadWord(tpos));
    gfx::TileInfo t1 = gfx::GetTilesInfo(t1_data);
    tpos += 2;
    ASSIGN_OR_RETURN(auto t2_data, rom.ReadWord(tpos));
    gfx::TileInfo t2 = gfx::GetTilesInfo(t2_data);
    tpos += 2;
    ASSIGN_OR_RETURN(auto t3_data, rom.ReadWord(tpos));
    gfx::TileInfo t3 = gfx::GetTilesInfo(t3_data);
    tpos += 2;
    tiles16.emplace_back(t0, t1, t2, t3);
  }
  return tiles16;
}
 
absl::Status Overworld::AssembleMap16Tiles() {
  bool expanded = false;
  ASSIGN_OR_RETURN(auto tiles16, ReadMap16Tiles(*rom(), &expanded));
  if (expanded) {
    expanded_tile16_ = true;
  }
  for (auto& tile16 : tiles16) {
    tiles16_.push_back(tile16);
  }
  return absl::OkStatus();
}
 
void Overworld::AssignWorldTiles(int x, int y, int sx, int sy, int tpos,
                                 OverworldBlockset& world) {
  int position_x1 = (x * 2) + (sx * 32);
  int position_y1 = (y * 2) + (sy * 32);
  int position_x2 = (x * 2) + 1 + (sx * 32);
  int position_y2 = (y * 2) + 1 + (sy * 32);
  world[position_x1][position_y1] = tiles32_unique_[tpos].tile0_;
  world[position_x2][position_y1] = tiles32_unique_[tpos].tile1_;
  world[position_x1][position_y2] = tiles32_unique_[tpos].tile2_;
  world[position_x2][position_y2] = tiles32_unique_[tpos].tile3_;
}
 
OverworldBlockset& Overworld::SelectWorldBlockset(int world_type) {
  switch (world_type) {
    case 0:
      return map_tiles_.light_world;
    case 1:
      return map_tiles_.dark_world;
    default:
      return map_tiles_.special_world;
  }
}
 
void Overworld::FillBlankMapTiles(int map_index) {
  int world_type = 0;
  if (map_index >= kDarkWorldMapIdStart &&
      map_index < kSpecialWorldMapIdStart) {
    world_type = 1;
  } else if (map_index >= kSpecialWorldMapIdStart) {
    world_type = 2;
  }
 
  int local_index = map_index % 64;
  int sx = local_index % 8;
  int sy = local_index / 8;
 
  auto& world = SelectWorldBlockset(world_type);
  // Fill the 32x32 tile16 region for this map with tile 0
  for (int y = 0; y < 32; ++y) {
    for (int x = 0; x < 32; ++x) {
      world[(sx * 32) + x][(sy * 32) + y] = 0;
    }
  }
}
 
void Overworld::OrganizeMapTiles(std::vector<uint8_t>& bytes,
                                 std::vector<uint8_t>& bytes2, int i, int sx,
                                 int sy, int& ttpos) {
  for (int y = 0; y < 16; y++) {
    for (int x = 0; x < 16; x++) {
      auto tidD = (uint16_t)((bytes2[ttpos] << 8) + bytes[ttpos]);
      if (int tpos = tidD; tpos < tiles32_unique_.size()) {
        if (i < kDarkWorldMapIdStart) {
          AssignWorldTiles(x, y, sx, sy, tpos, map_tiles_.light_world);
        } else if (i < kSpecialWorldMapIdStart && i >= kDarkWorldMapIdStart) {
          AssignWorldTiles(x, y, sx, sy, tpos, map_tiles_.dark_world);
        } else {
          AssignWorldTiles(x, y, sx, sy, tpos, map_tiles_.special_world);
        }
      }
      ttpos += 1;
    }
  }
}
 
absl::Status Overworld::DecompressAllMapTilesParallel() {
  const auto get_ow_map_gfx_ptr = [this](int index, uint32_t map_ptr) {
    int p = (rom()->data()[map_ptr + 2 + (3 * index)] << 16) +
            (rom()->data()[map_ptr + 1 + (3 * index)] << 8) +
            (rom()->data()[map_ptr + (3 * index)]);
    return SnesToPc(p);
  };
 
  constexpr uint32_t kBaseLowest = 0x0FFFFF;
  constexpr uint32_t kBaseHighest = 0x0F8000;
 
  uint32_t lowest = kBaseLowest;
  uint32_t highest = kBaseHighest;
  int sx = 0;
  int sy = 0;
  int c = 0;
  // Tail maps (0xA0-0xBF) require BOTH:
  // 1. Feature flag enabled in settings
  // 2. TailMapExpansion.asm patch applied to ROM (marker at 0x1423FF)
  const bool allow_special_tail =
      core::FeatureFlags::get().overworld.kEnableSpecialWorldExpansion &&
      HasExpandedPointerTables();
 
  for (int i = 0; i < kNumOverworldMaps; i++) {
    // Guard: skip building tail special maps unless expansion is available
    if (!allow_special_tail &&
        i >= kSpecialWorldMapIdStart + 0x20) {  // 0xA0-0xBF
      FillBlankMapTiles(i);
      sx++;
      if (sx >= 8) {
        sy++;
        sx = 0;
      }
      c++;
      if (c >= 64) {
        sx = 0;
        sy = 0;
        c = 0;
      }
      continue;
    }
 
    auto p1 = get_ow_map_gfx_ptr(
        i, version_constants().kCompressedAllMap32PointersHigh);
    auto p2 = get_ow_map_gfx_ptr(
        i, version_constants().kCompressedAllMap32PointersLow);
 
    int ttpos = 0;
 
    bool pointers_valid =
        (p1 > 0 && p2 > 0 && p1 < rom()->size() && p2 < rom()->size());
    if (!pointers_valid) {
      // Missing/invalid pointers -> use blank map tiles to avoid crashes
      FillBlankMapTiles(i);
      sx++;
      if (sx >= 8) {
        sy++;
        sx = 0;
      }
      c++;
      if (c >= 64) {
        sx = 0;
        sy = 0;
        c = 0;
      }
      continue;
    }
 
    if (p1 >= highest)
      highest = p1;
    if (p2 >= highest)
      highest = p2;
 
    if (p1 <= lowest && p1 > kBaseHighest)
      lowest = p1;
    if (p2 <= lowest && p2 > kBaseHighest)
      lowest = p2;
 
    int size1, size2;
    size_t max_size_p2 = rom()->size() - p2;
    auto bytes =
        gfx::HyruleMagicDecompress(rom()->data() + p2, &size1, 1, max_size_p2);
    size_t max_size_p1 = rom()->size() - p1;
    auto bytes2 =
        gfx::HyruleMagicDecompress(rom()->data() + p1, &size2, 1, max_size_p1);
 
    // If decompression fails, use blank tiles to keep map index usable
    if (bytes.empty() || bytes2.empty()) {
      FillBlankMapTiles(i);
    } else {
      OrganizeMapTiles(bytes, bytes2, i, sx, sy, ttpos);
    }
 
    sx++;
    if (sx >= 8) {
      sy++;
      sx = 0;
    }
 
    c++;
    if (c >= 64) {
      sx = 0;
      sy = 0;
      c = 0;
    }
  }
 
  return absl::OkStatus();
}
 
absl::Status Overworld::LoadOverworldMaps() {
  [[maybe_unused]] auto size = tiles16_.size();  // native async path
 
  // Performance optimization: Only build essential maps initially
  // Essential maps are the first few maps of each world that are commonly
  // accessed
  constexpr int kLightWorldEssential = yaze::zelda3::kEssentialMapsPerWorld;
  constexpr int kDarkWorldEssential =
      kDarkWorldMapIdStart + yaze::zelda3::kEssentialMapsPerWorld;
  constexpr int kSpecialWorldEssential =
      kSpecialWorldMapIdStart + yaze::zelda3::kEssentialMapsPerWorld;
  std::vector<int> essential_map_ids;
  essential_map_ids.reserve(yaze::zelda3::kEssentialMapsPerWorld * 3);
 
  util::logf(
      "Building essential maps only (first %d maps per world) for faster "
      "loading",
      yaze::zelda3::kEssentialMapsPerWorld);
 
#ifdef __EMSCRIPTEN__
  // WASM: Use sequential loading to avoid spawning excessive Web Workers
  // and blocking the main thread. std::async creates new pthreads which
  // become Web Workers, and future.wait() blocks the main thread which
  // is dangerous in browsers.
  for (int i = 0; i < kNumOverworldMaps; ++i) {
    bool is_essential = false;
 
    if (i < kLightWorldEssential) {
      is_essential = true;
    } else if (i >= kDarkWorldMapIdStart && i < kDarkWorldEssential) {
      is_essential = true;
    } else if (i >= kSpecialWorldMapIdStart && i < kSpecialWorldEssential) {
      is_essential = true;
    }
 
    if (is_essential) {
      essential_map_ids.push_back(i);
      int world_type = 0;
      if (i >= kDarkWorldMapIdStart && i < kSpecialWorldMapIdStart) {
        world_type = 1;
      } else if (i >= kSpecialWorldMapIdStart) {
        world_type = 2;
      }
 
      // CRITICAL: Set game_state_ BEFORE LoadAreaGraphics() because
      // LoadSpritesBlocksets() uses game_state_ to determine static_graphics_[12-15]
      overworld_maps_[i].set_game_state(game_state_);
 
      // Apply large map child handling BEFORE computing hash
      // Must match LoadAreaInfo() logic exactly for SW maps
      auto* map = &overworld_maps_[i];
      if (map->is_large_map() &&
          cached_version_ == OverworldVersion::kVanilla) {
        if (map->parent() != i && !map->is_initialized()) {
          if (i >= kSpecialWorldMapIdStart && i <= 0x8A && i != 0x88) {
            // Zora's Domain children - also set sprite_graphics
            map->set_sprite_graphics(0, 0x0E);
            map->set_sprite_graphics(1, 0x0E);
            map->set_sprite_graphics(2, 0x0E);
            map->set_area_graphics(
                (*rom_)[kOverworldSpecialGfxGroup +
                        (map->parent() - kSpecialWorldMapIdStart)]);
            map->set_area_palette((*rom_)[kOverworldSpecialPalGroup + 1]);
          } else if (i == 0x88 || i == 0x93) {
            map->set_area_graphics(0x51);
            map->set_area_palette(0x00);
          } else if (i < kSpecialWorldMapIdStart) {
            // LW/DW large map child - use parent's graphics
            map->set_area_graphics((*rom_)[kAreaGfxIdPtr + map->parent()]);
            map->set_area_palette(
                (*rom_)[kOverworldMapPaletteIds + map->parent()]);
          }
          // Note: Other SW maps (>0x8A) keep their LoadAreaInfo values
        }
      }
 
      // Reuse cached tilesets to reduce load time on WASM
      SyncAreaProperties(i);
      RETURN_IF_ERROR(BuildMapWithTilesetCache(i, world_type));
      built_map_lru_.push_front(i);
    } else {
      overworld_maps_[i].SetNotBuilt();
    }
  }
#else
  // Native: Use parallel loading with std::async for faster performance
  std::vector<std::future<absl::Status>> futures;
 
  // Build essential maps only
  for (int i = 0; i < kNumOverworldMaps; ++i) {
    bool is_essential = false;
 
    // Check if this is an essential map
    if (i < kLightWorldEssential) {
      is_essential = true;
    } else if (i >= kDarkWorldMapIdStart && i < kDarkWorldEssential) {
      is_essential = true;
    } else if (i >= kSpecialWorldMapIdStart && i < kSpecialWorldEssential) {
      is_essential = true;
    }
 
    if (is_essential) {
      int world_type = 0;
      if (i >= kDarkWorldMapIdStart && i < kSpecialWorldMapIdStart) {
        world_type = 1;
      } else if (i >= kSpecialWorldMapIdStart) {
        world_type = 2;
      }
 
      SyncAreaProperties(i);
      auto task_function = [this, i, size, world_type]() {
        return overworld_maps_[i].BuildMap(size, game_state_, world_type,
                                           tiles16_, GetMapTiles(world_type));
      };
      futures.emplace_back(std::async(std::launch::async, task_function));
    } else {
      // Mark non-essential maps as not built yet
      overworld_maps_[i].SetNotBuilt();
    }
  }
 
  // Wait for essential maps to complete
  for (auto& future : futures) {
    future.wait();
    RETURN_IF_ERROR(future.get());
  }
 
  built_map_lru_.clear();
  for (int map_index : essential_map_ids) {
    built_map_lru_.push_front(map_index);
  }
#endif
 
  util::logf("Essential maps built. Remaining maps will be built on-demand.");
  return absl::OkStatus();
}
 
absl::Status Overworld::EnsureMapBuilt(int map_index) {
  const bool descriptor_preview = is_lyra_preview();
  const int map_count =
      descriptor_preview ? descriptor_layout_.capacity : kNumOverworldMaps;
  if (map_index < 0 || map_index >= map_count) {
    return absl::InvalidArgumentError("Invalid map index");
  }
 
  // Tail maps (0xA0-0xBF) require BOTH:
  // 1. Feature flag enabled in settings
  // 2. TailMapExpansion.asm patch applied to ROM (marker at 0x1423FF)
  const bool allow_special_tail =
      core::FeatureFlags::get().overworld.kEnableSpecialWorldExpansion &&
      HasExpandedPointerTables();
  if (!descriptor_preview && !allow_special_tail &&
      map_index >= kSpecialWorldMapIdStart + 0x20) {  // 0xA0-0xBF
    // Do not attempt to build disabled special-tail maps; keep them blank-safe.
    // This prevents pointer table corruption from attempting to access
    // non-existent entries beyond vanilla's 160-entry limit.
    FillBlankMapTiles(map_index);
    return absl::OkStatus();
  }
 
  // Check if map is already built
  if (overworld_maps_[map_index].is_built()) {
    // Move to front of LRU (most recently used)
    auto it =
        std::find(built_map_lru_.begin(), built_map_lru_.end(), map_index);
    if (it != built_map_lru_.end()) {
      built_map_lru_.erase(it);
    }
    built_map_lru_.push_front(map_index);
    return absl::OkStatus();
  }
 
  // Evict oldest maps if cache is full (LRU eviction)
  while (static_cast<int>(built_map_lru_.size()) >= kMaxBuiltMaps) {
    int oldest_map = built_map_lru_.back();
    built_map_lru_.pop_back();
    // Destroy the oldest map to free memory. Its shared tileset cache entry
    // stays: entries are keyed by sheet ids, not by map.
    overworld_maps_[oldest_map].Destroy();
  }
 
  // Build the map on-demand
  int world_type = 0;
  if (map_index >= kDarkWorldMapIdStart &&
      map_index < kSpecialWorldMapIdStart) {
    world_type = 1;
  } else if (map_index >= kSpecialWorldMapIdStart) {
    world_type = 2;
  }
 
  // CRITICAL: Set game_state_ BEFORE LoadAreaGraphics() because
  // LoadSpritesBlocksets() uses game_state_ to determine static_graphics_[12-15]
  overworld_maps_[map_index].set_game_state(game_state_);
 
  // Apply large map child handling BEFORE computing hash
  // This mirrors the logic in BuildMapWithCache that modifies area_graphics_
  // for large map children in vanilla ROMs - must happen before hash
  auto* map = &overworld_maps_[map_index];
  if (map->is_large_map() && cached_version_ == OverworldVersion::kVanilla) {
    if (map->parent() != map_index && !map->is_initialized()) {
      // Large map child in vanilla ROM - apply special graphics handling
      // Must match LoadAreaInfo() logic exactly for SW maps
      if (map_index >= kSpecialWorldMapIdStart && map_index <= 0x8A &&
          map_index != 0x88) {
        // Zora's Domain children - also set sprite_graphics
        map->set_sprite_graphics(0, 0x0E);
        map->set_sprite_graphics(1, 0x0E);
        map->set_sprite_graphics(2, 0x0E);
        map->set_area_graphics(
            (*rom_)[kOverworldSpecialGfxGroup +
                    (map->parent() - kSpecialWorldMapIdStart)]);
        map->set_area_palette((*rom_)[kOverworldSpecialPalGroup + 1]);
      } else if (map_index == 0x88 || map_index == 0x93) {
        map->set_area_graphics(0x51);
        map->set_area_palette(0x00);
      } else if (map_index < kSpecialWorldMapIdStart) {
        // LW/DW large map child - use parent's graphics
        map->set_area_graphics((*rom_)[kAreaGfxIdPtr + map->parent()]);
        map->set_area_palette((*rom_)[kOverworldMapPaletteIds + map->parent()]);
      }
      // Note: Other SW maps (>0x8A) keep their LoadAreaInfo values
    }
  }
 
  // Child screens render with the area parent's settings (game reads $8A).
  if (map_index < kNumOverworldMaps) {
    SyncAreaProperties(map_index);
  }
 
  auto status = BuildMapWithTilesetCache(map_index, world_type);
  if (status.ok()) {
    // Add to front of LRU cache
    built_map_lru_.push_front(map_index);
  }
  return status;
}
 
uint64_t Overworld::Tiles16Fingerprint() const {
  uint64_t hash = 0xcbf29ce484222325ULL;
  auto mix = [&hash](uint64_t value) {
    hash ^= value;
    hash *= 0x100000001b3ULL;
  };
  mix(tiles16_.size());
  for (const auto& tile16 : tiles16_) {
    for (const auto& info : tile16.tiles_info) {
      mix(static_cast<uint64_t>(info.id_) | (uint64_t{info.palette_} << 16) |
          (uint64_t{info.vertical_mirror_} << 24) |
          (uint64_t{info.horizontal_mirror_} << 25) |
          (uint64_t{info.over_} << 26));
    }
  }
  return hash;
}
 
// Builds a map, reusing the 64KB tileset and 1MB tile16 blockset of any
// earlier map that loaded the same 17 sheets. Only the palette, overlay data,
// and the map's own bitmap are rebuilt on a cache hit.
absl::Status Overworld::BuildMapWithTilesetCache(int map_index,
                                                 int world_type) {
  auto& map = overworld_maps_[map_index];
  map.LoadAreaGraphics();
  // Preview-only DMA pixels must never enter the shared ordinary-sheet cache.
  if (map.HasGraphicsPreview()) {
    return map.BuildMapWithCache(static_cast<int>(tiles16_.size()), game_state_,
                                 world_type, tiles16_, GetMapTiles(world_type),
                                 nullptr);
  }
  const OverworldTilesetKey key = map.tileset_key();
  const uint64_t fingerprint = Tiles16Fingerprint();
 
  const TilesetRevisions revisions = SheetRevisionsForKey(key);
 
  const std::vector<uint8_t>* cached_gfx = nullptr;
  const std::vector<uint8_t>* cached_blockset = nullptr;
  auto it = tileset_cache_.find(key);
  if (it != tileset_cache_.end() && it->second.sheet_revisions != revisions) {
    // An unsaved Graphics editor edit changed one of the key's sheets since
    // this entry was built; drop it so the map re-reads the store.
    tileset_cache_.erase(it);
    it = tileset_cache_.end();
  }
  if (it != tileset_cache_.end()) {
    cached_gfx = &it->second.current_gfx;
    if (it->second.tiles16_fingerprint == fingerprint &&
        !it->second.tile16_blockset.empty()) {
      cached_blockset = &it->second.tile16_blockset;
    }
  }
 
  RETURN_IF_ERROR(map.BuildMapWithCache(
      static_cast<int>(tiles16_.size()), game_state_, world_type, tiles16_,
      GetMapTiles(world_type), cached_gfx, cached_blockset));
 
  if (it == tileset_cache_.end()) {
    while (tileset_cache_.size() >= kMaxCachedTilesets) {
      auto oldest = tileset_cache_.begin();
      for (auto e = tileset_cache_.begin(); e != tileset_cache_.end(); ++e) {
        if (e->second.last_use < oldest->second.last_use) {
          oldest = e;
        }
      }
      tileset_cache_.erase(oldest);
    }
    it = tileset_cache_.emplace(key, TilesetCacheEntry{}).first;
    it->second.current_gfx = map.current_graphics();
    it->second.sheet_revisions = revisions;
  }
  if (cached_blockset == nullptr) {
    it->second.tile16_blockset = map.current_tile16_blockset();
    it->second.tiles16_fingerprint = fingerprint;
  }
  it->second.last_use = ++tileset_cache_clock_;
  return absl::OkStatus();
}
 
Overworld::TilesetRevisions Overworld::SheetRevisionsForKey(
    const OverworldTilesetKey& key) const {
  TilesetRevisions revisions{};
  if (game_data_ == nullptr) {
    return revisions;
  }
  for (size_t i = 0; i < key.size(); ++i) {
    if (key[i] != 0) {
      revisions[i] = game_data_->sheet_store.Revision(key[i]);
    }
  }
  return revisions;
}
 
void Overworld::InvalidateTilesetCacheForSheet(int sheet) {
  for (auto it = tileset_cache_.begin(); it != tileset_cache_.end();) {
    const auto& key = it->first;
    if (std::find(key.begin(), key.end(), static_cast<uint8_t>(sheet)) !=
        key.end()) {
      it = tileset_cache_.erase(it);
    } else {
      ++it;
    }
  }
}
 
void Overworld::SetGraphicsPreview(OverworldGraphicsPreview preview) {
  graphics_preview_ = std::move(preview);
  for (int i = 0; i < static_cast<int>(overworld_maps_.size()); ++i) {
    SyncAreaProperties(i);
  }
}
 
void Overworld::SyncAreaProperties(int map_index) {
  if (map_index < 0 ||
      static_cast<size_t>(map_index) >= overworld_maps_.size()) {
    return;
  }
  auto& map = overworld_maps_[map_index];
  const int parent = map.parent();
  const auto preview = graphics_preview_.find(parent);
  map.SetGraphicsPreview(preview == graphics_preview_.end()
                             ? AreaGraphicsPreview{}
                             : preview->second);
  if (parent == map_index || parent < 0 ||
      static_cast<size_t>(parent) >= overworld_maps_.size()) {
    map.ClearInheritedAreaProperties();
    return;
  }
  map.InheritAreaProperties(overworld_maps_[parent]);
}
 
absl::StatusOr<Overworld::SubscreenOverlayLayer>
Overworld::BuildSubscreenOverlayLayer(int map_index) {
  if (map_index < 0 || map_index >= kNumOverworldMaps) {
    return absl::InvalidArgumentError("Invalid map index");
  }
  RETURN_IF_ERROR(EnsureMapBuilt(map_index));
  const auto& map = overworld_maps_[map_index];
  SubscreenOverlayLayer layer;
  layer.overlay_id = map.render_subscreen_overlay();
  const int screen = SubscreenOverlayScreen(layer.overlay_id);
  if (screen < 0 || screen >= kNumOverworldMaps || screen == map_index) {
    return layer;
  }
  layer.overlay_screen = screen;
  layer.background = IsBackgroundSubscreenOverlay(layer.overlay_id);
  RETURN_IF_ERROR(
      map.BuildSubscreenOverlayLayer(GetMapTiles(WorldForOverworldMap(screen)),
                                     screen, layer.background, &layer.pixels));
  return layer;
}
 
void Overworld::LoadTileTypes() {
  all_tiles_types_.fill(0);
  if (!rom_) {
    return;
  }
  const auto layout = zscream::DetectLayout(*rom_);
  if (layout == zscream::LayoutDialect::kZScreamV5 ||
      layout == zscream::LayoutDialect::kUnknown) {
    // There is no global 512-byte collision table for this dialect. Consumers
    // must request the selected map's resolved sheets; never show vanilla bytes.
    return;
  }
  const size_t offset = version_constants().kOverworldTilesType;
  if (offset > rom_->vector().size() ||
      rom_->vector().size() - offset < all_tiles_types_.size()) {
    return;
  }
  std::copy_n(rom_->vector().begin() + offset, all_tiles_types_.size(),
              all_tiles_types_.begin());
}
 
absl::StatusOr<std::array<uint8_t, kNumTileTypes>>
Overworld::GetTile8CollisionTypes(int map_id) const {
  if (!rom_) {
    return absl::FailedPreconditionError("No ROM for collision preview");
  }
  if (map_id < 0 || map_id >= inspected_map_count()) {
    return absl::InvalidArgumentError("Invalid map ID for collision preview");
  }
  if (is_lyra_preview()) {
    return absl::FailedPreconditionError(
        "Descriptor collision preview is not supported by this reader");
  }
  const auto layout = zscream::DetectLayout(*rom_);
  if (layout == zscream::LayoutDialect::kUnknown) {
    return absl::FailedPreconditionError(
        "Unknown ZScream collision layout; no vanilla fallback");
  }
  if (layout == zscream::LayoutDialect::kZScreamV5) {
    RETURN_IF_ERROR(zscream::ValidateSheetCollisionTable(*rom_));
    const auto* map = overworld_map(map_id);
    if (!map) {
      return absl::FailedPreconditionError(
          "Map must be loaded before resolving per-sheet collisions");
    }
    zscream::ResolvedSheetIds sheets{};
    for (size_t slot = 0; slot < sheets.size(); ++slot) {
      // Public provenance resolves the same private ResolveStaticGraphics()
      // slots as the display. Slots 0..7 are BG PriorSheets; 8..15 are sprites.
      sheets[slot] =
          map->MainSlotProvenance(static_cast<int>(slot)).effective_sheet;
    }
    return zscream::ComposeTile8Collisions(*rom_, sheets);
  }
  const size_t offset = version_constants().kOverworldTilesType;
  if (offset > rom_->vector().size() ||
      rom_->vector().size() - offset < all_tiles_types_.size()) {
    return absl::OutOfRangeError("Incomplete legacy collision table");
  }
  std::array<uint8_t, kNumTileTypes> types{};
  std::copy_n(rom_->vector().begin() + offset, types.size(), types.begin());
  return types;
}
 
void Overworld::InvalidateMapCache(int map_index) {
  if (map_index < 0 || map_index >= kNumOverworldMaps) {
    return;
  }
 
  // Drop the shared tileset entry for this map's sheet set so the next build
  // re-reads the graphics buffer.
  if (static_cast<size_t>(map_index) < overworld_maps_.size()) {
    tileset_cache_.erase(overworld_maps_[map_index].tileset_key());
  }
 
  // Also mark the map as needing rebuild
  if (static_cast<size_t>(map_index) < overworld_maps_.size()) {
    overworld_maps_[map_index].SetNotBuilt();
  }
}
 
void Overworld::InvalidateSiblingMapCaches(int map_index) {
  if (map_index < 0 || map_index >= kNumOverworldMaps) {
    return;
  }
 
  auto* map = mutable_overworld_map(map_index);
  if (!map)
    return;
 
  // Get parent and determine all sibling maps
  int parent_id = map->parent();
  std::vector<int> siblings;
 
  bool use_v3_sizes = OverworldVersionHelper::SupportsAreaEnum(cached_version_);
 
  if (use_v3_sizes) {
    // v3: Use area_size enum
    switch (map->area_size()) {
      case AreaSizeEnum::LargeArea:
        siblings = {parent_id, parent_id + 1, parent_id + 8, parent_id + 9};
        break;
      case AreaSizeEnum::WideArea:
        siblings = {parent_id, parent_id + 1};
        break;
      case AreaSizeEnum::TallArea:
        siblings = {parent_id, parent_id + 8};
        break;
      default:
        siblings = {map_index};  // Small area - just this map
        break;
    }
  } else {
    // Vanilla/v1/v2: Use large_map flag
    if (map->is_large_map()) {
      siblings = {parent_id, parent_id + 1, parent_id + 8, parent_id + 9};
    } else {
      siblings = {map_index};  // Small area - just this map
    }
  }
 
  // Invalidate cache for all siblings
  for (int sibling : siblings) {
    if (sibling >= 0 && sibling < kNumOverworldMaps) {
      InvalidateMapCache(sibling);
    }
  }
}
 
absl::Status Overworld::LoadSprites() {
  // Table locations and per-state map counts come from the ROM's ASM version:
  // vanilla has 64/144/144 entries; ZSCustomOverworld v3 expands every game
  // state to 160 entries (state 0 then covers the Dark World too).
  const auto layout = GetOverworldSpriteLayout(*rom_);
 
#ifdef __EMSCRIPTEN__
  // WASM: Sequential loading to avoid Web Worker explosion
  for (int state = 0; state < 3; ++state) {
    RETURN_IF_ERROR(
        LoadSpritesFromMap(layout.tables[state], layout.counts[state], state));
  }
#else
  // Native: Parallel loading for performance
  std::vector<std::future<absl::Status>> futures;
  for (int state = 0; state < 3; ++state) {
    futures.emplace_back(
        std::async(std::launch::async, [this, layout, state]() {
          return LoadSpritesFromMap(layout.tables[state], layout.counts[state],
                                    state);
        }));
  }
 
  for (auto& future : futures) {
    future.wait();
    RETURN_IF_ERROR(future.get());
  }
#endif
  return absl::OkStatus();
}
 
absl::Status Overworld::LoadSpritesFromMap(int sprites_per_gamestate_ptr,
                                           int num_maps_per_gamestate,
                                           int game_state) {
  if (!rom_ || game_state < 0 || game_state >= 3 ||
      num_maps_per_gamestate < 0 || num_maps_per_gamestate > 160 ||
      overworld_maps_.size() < static_cast<size_t>(num_maps_per_gamestate)) {
    return absl::FailedPreconditionError(
        "Sprite loading requires initialized maps");
  }
  std::vector<Sprite> loaded;
  std::array<bool, 160> loaded_maps{};
  for (int i = 0; i < num_maps_per_gamestate; ++i) {
    if (map_parent_[i] != i)
      continue;
    ASSIGN_OR_RETURN(auto bytes, ReadOverworldSpriteList(
                                     *rom_, sprites_per_gamestate_ptr + i * 2));
    loaded_maps[i] = true;
    const int screen = i % 64;
    for (size_t pos = 0; pos + 1 < bytes.size(); pos += 3) {
      const auto y = bytes[pos];
      const auto x = bytes[pos + 1];
      loaded.emplace_back(*overworld_maps_[i].mutable_current_graphics(),
                          static_cast<uint8_t>(i), bytes[pos + 2], x & 0x3F,
                          y & 0x3F, (x & 0x3F) * 16 + (screen % 8) * 512,
                          (y & 0x3F) * 16 + (screen / 8) * 512);
      loaded.back().set_overworld_coordinate_flags(x, y);
      if (!overworld_maps_[i].current_graphics().empty())
        loaded.back().Draw();
    }
  }
  all_sprites_[game_state] = std::move(loaded);
  sprite_maps_loaded_[game_state] = loaded_maps;
  return absl::OkStatus();
}
 
absl::StatusOr<OverworldSpriteSavePlan> Overworld::PrepareSpriteSave() const {
  if (!rom_)
    return absl::FailedPreconditionError("No ROM for overworld sprites");
  OverworldSpriteEdits edits;
  bool loaded = false;
  for (int state = 0; state < 3; ++state) {
    for (int map = 0; map < 160; ++map) {
      if (sprite_maps_loaded_[state][map]) {
        edits[state][map] = OverworldSpriteBytes{};
        loaded = true;
      }
    }
    for (const auto& sprite : all_sprites_[state]) {
      if (sprite.deleted())
        continue;
      const int map = sprite.map_id();
      if (map >= 160 || !edits[state][map]) {
        return absl::FailedPreconditionError(
            "Sprite belongs to an unloaded or unsupported map/game state");
      }
      // World-space position is authoritative: drag/property edits do not
      // update Sprite::nx()/ny(). Encode relative to the owning parent map.
      const int x = sprite.x() - (map % 8) * 512;
      const int y = sprite.y() - ((map % 64) / 8) * 512;
      if (x < 0 || x >= 1024 || y < 0 || y >= 1024 || x % 16 || y % 16) {
        return absl::InvalidArgumentError(
            "Overworld sprite must be on a 16-pixel grid within its parent "
            "area");
      }
      auto& bytes = *edits[state][map];
      bytes.push_back(static_cast<uint8_t>(y / 16) |
                      sprite.overworld_y_flags());
      bytes.push_back(static_cast<uint8_t>(x / 16) |
                      sprite.overworld_x_flags());
      bytes.push_back(sprite.id());
    }
    for (auto& bytes : edits[state])
      if (bytes)
        bytes->push_back(0xFF);
  }
  if (!loaded)
    return OverworldSpriteSavePlan{};
  return PlanOverworldSpriteSave(*rom_, edits);
}
 
absl::Status Overworld::SaveSprites() {
  ASSIGN_OR_RETURN(auto plan, PrepareSpriteSave());
  return ApplyOverworldSpriteSave(*rom_, plan);
}
 
absl::Status Overworld::Save(Rom* rom) {
  if (rom == nullptr) {
    return absl::FailedPreconditionError("No ROM for overworld sprites");
  }
  RETURN_IF_ERROR(rom->CheckLayoutWritable());
  rom_ = rom;
  RETURN_IF_ERROR(ValidatePrivateNativeTerrainSave());
  ASSIGN_OR_RETURN(auto sprite_plan, PrepareSpriteSave());
  ScopedRomTransaction transaction(*rom_);
  RETURN_IF_ERROR(CreateTile32Tilemap())
  if (expanded_tile16_) {
    RETURN_IF_ERROR(SaveMap16Expanded())
  } else {
    RETURN_IF_ERROR(SaveMap16Tiles())
  }
  if (expanded_tile32_) {
    RETURN_IF_ERROR(SaveMap32Expanded())
  } else {
    RETURN_IF_ERROR(SaveMap32Tiles())
  }
  RETURN_IF_ERROR(SaveOverworldMaps())
  RETURN_IF_ERROR(SaveEntrances())
  RETURN_IF_ERROR(SaveExits())
  RETURN_IF_ERROR(SaveItems())
  RETURN_IF_ERROR(ApplyOverworldSpriteSave(*rom_, sprite_plan))
  RETURN_IF_ERROR(SaveMapOverlays())
  RETURN_IF_ERROR(SaveOverworldTilesType())
  RETURN_IF_ERROR(SaveDiggableTiles())
  RETURN_IF_ERROR(SaveMusic())
  RETURN_IF_ERROR(SaveCustomOverworldData())
  transaction.Commit();
  return absl::OkStatus();
}
 
absl::Status Overworld::ValidatePrivateNativeTerrainSave() const {
  if (!rom_ || !rom_->has_lyra_private_reservation())
    return absl::OkStatus();
  RETURN_IF_ERROR(rom_->ValidateLyraPrivateReservation());
  if (!MapTilesUnchanged() || tiles16_ != private_loaded_tiles16_) {
    return absl::FailedPreconditionError(
        "Private Lyra producer reservation refuses changed native terrain "
        "before serialization");
  }
  if (PrivateOverlaySnapshot(overworld_maps_) != private_loaded_overlays_) {
    return absl::FailedPreconditionError(
        "Private Lyra reservation refuses changed overlay model before "
        "serialization");
  }
  return absl::OkStatus();
}
 
bool Overworld::MapTilesUnchanged() const {
  return loaded_map_tiles_valid_ &&
         map_tiles_.light_world == loaded_map_tiles_.light_world &&
         map_tiles_.dark_world == loaded_map_tiles_.dark_world &&
         map_tiles_.special_world == loaded_map_tiles_.special_world;
}
 
void Overworld::StageSavedMapTiles() {
  staged_map_tiles_ = map_tiles_;
  staged_map_tiles_valid_ = true;
}
 
void Overworld::CommitSavedMapTiles() {
  if (!staged_map_tiles_valid_) {
    return;
  }
  loaded_map_tiles_ = std::move(staged_map_tiles_);
  loaded_map_tiles_valid_ = true;
  staged_map_tiles_ = OverworldMapTiles{};
  staged_map_tiles_valid_ = false;
}
 
void Overworld::RollbackSavedMapTiles() {
  staged_map_tiles_ = OverworldMapTiles{};
  staged_map_tiles_valid_ = false;
}
 
absl::Status Overworld::SaveOverworldMaps() {
  RETURN_IF_ERROR(ValidatePrivateNativeTerrainSave());
  if (rom_ && rom_->has_lyra_private_reservation())
    return absl::OkStatus();
  util::logf("Saving Overworld Maps");
 
  if (MapTilesUnchanged()) {
    util::logf("Overworld tiles unchanged; preserving compressed map pointers");
    RETURN_IF_ERROR(SaveLargeMaps());
    StageSavedMapTiles();
    return absl::OkStatus();
  }
 
  if (tiles32_list_.size() < NumberOfMap32) {
    RETURN_IF_ERROR(CreateTile32Tilemap())
  }
 
  // Initialize map pointers
  std::fill(map_pointers1_id.begin(), map_pointers1_id.end(), -1);
  std::fill(map_pointers2_id.begin(), map_pointers2_id.end(), -1);
 
  // Compress and save each map
  int pos = kOverworldCompressedMapPos;
  for (int i = 0; i < kNumOverworldMaps; i++) {
    std::vector<uint8_t> single_map_1(512);
    std::vector<uint8_t> single_map_2(512);
 
    // Copy tiles32 data to single_map_1 and single_map_2
    int npos = 0;
    for (int y = 0; y < 16; y++) {
      for (int x = 0; x < 16; x++) {
        auto packed = tiles32_list_[npos + (i * 256)];
        single_map_1[npos] = packed & 0xFF;         // Lower 8 bits
        single_map_2[npos] = (packed >> 8) & 0xFF;  // Next 8 bits
        npos++;
      }
    }
 
    int size_a, size_b;
    // Compress single_map_1 and single_map_2
    auto a = gfx::HyruleMagicCompress(single_map_1.data(), 256, &size_a, 1);
    auto b = gfx::HyruleMagicCompress(single_map_2.data(), 256, &size_b, 1);
    if (a.empty() || b.empty()) {
      return absl::AbortedError("Error compressing map gfx.");
    }
 
    // Save compressed data and pointers
    map_data_p1[i] = std::vector<uint8_t>(size_a);
    map_data_p2[i] = std::vector<uint8_t>(size_b);
 
    if ((pos + size_a) >= 0x5FE70 && (pos + size_a) <= 0x60000) {
      pos = 0x60000;
    }
 
    if ((pos + size_a) >= 0x6411F && (pos + size_a) <= 0x70000) {
      util::logf("Pos set to overflow region for map %s at %s",
                 std::to_string(i), util::HexLong(pos));
      pos = kOverworldMapDataOverflow;  // 0x0F8780;
    }
 
    const auto compare_array = [](const std::vector<uint8_t>& array1,
                                  const std::vector<uint8_t>& array2) -> bool {
      if (array1.size() != array2.size()) {
        return false;
      }
 
      for (size_t i = 0; i < array1.size(); i++) {
        if (array1[i] != array2[i]) {
          return false;
        }
      }
 
      return true;
    };
 
    for (int j = 0; j < i; j++) {
      if (compare_array(a, map_data_p1[j])) {
        // Reuse pointer id j for P1 (a)
        map_pointers1_id[i] = j;
      }
 
      if (compare_array(b, map_data_p2[j])) {
        map_pointers2_id[i] = j;
        // Reuse pointer id j for P2 (b)
      }
    }
 
    if (map_pointers1_id[i] == -1) {
      // Save compressed data and pointer for map1
      std::copy(a.begin(), a.end(), map_data_p1[i].begin());
      int snes_pos = PcToSnes(pos);
      map_pointers1[i] = snes_pos;
      util::logf("Saving map pointers1 and compressed data for map %s at %s",
                 util::HexByte(i), util::HexLong(snes_pos));
      RETURN_IF_ERROR(rom()->WriteLong(
          version_constants().kCompressedAllMap32PointersLow + (3 * i),
          snes_pos));
      RETURN_IF_ERROR(rom()->WriteVector(pos, a));
      pos += size_a;
    } else {
      // Save pointer for map1
      int snes_pos = map_pointers1[map_pointers1_id[i]];
      util::logf("Saving map pointers1 for map %s at %s", util::HexByte(i),
                 util::HexLong(snes_pos));
      RETURN_IF_ERROR(rom()->WriteLong(
          version_constants().kCompressedAllMap32PointersLow + (3 * i),
          snes_pos));
    }
 
    if ((pos + b.size()) >= 0x5FE70 && (pos + b.size()) <= 0x60000) {
      pos = 0x60000;
    }
 
    if ((pos + b.size()) >= 0x6411F && (pos + b.size()) <= 0x70000) {
      util::logf("Pos set to overflow region for map %s at %s",
                 util::HexByte(i), util::HexLong(pos));
      pos = kOverworldMapDataOverflow;
    }
 
    if (map_pointers2_id[i] == -1) {
      // Save compressed data and pointer for map2
      std::copy(b.begin(), b.end(), map_data_p2[i].begin());
      int snes_pos = PcToSnes(pos);
      map_pointers2[i] = snes_pos;
      util::logf("Saving map pointers2 and compressed data for map %s at %s",
                 util::HexByte(i), util::HexLong(snes_pos));
      RETURN_IF_ERROR(rom()->WriteLong(
          version_constants().kCompressedAllMap32PointersHigh + (3 * i),
          snes_pos));
      RETURN_IF_ERROR(rom()->WriteVector(pos, b));
      pos += size_b;
    } else {
      // Save pointer for map2
      int snes_pos = map_pointers2[map_pointers2_id[i]];
      util::logf("Saving map pointers2 for map %s at %s", util::HexByte(i),
                 util::HexLong(snes_pos));
      RETURN_IF_ERROR(rom()->WriteLong(
          version_constants().kCompressedAllMap32PointersHigh + (3 * i),
          snes_pos));
    }
  }
 
  // Check if too many maps data
  if (pos > kOverworldCompressedOverflowPos) {
    util::logf("Too many maps data %s", util::HexLong(pos));
    return absl::AbortedError("Too many maps data " + std::to_string(pos));
  }
 
  RETURN_IF_ERROR(SaveLargeMaps());
  StageSavedMapTiles();
  return absl::OkStatus();
}
 
std::vector<std::pair<uint32_t, uint32_t>> Overworld::GetProjectedWriteRanges()
    const {
  std::vector<std::pair<uint32_t, uint32_t>> ranges;
 
  // 1) Map32 Tiles (4 quadrants)
  uint32_t map32address[4] = {
      version_constants().kMap32TileTL, version_constants().kMap32TileTR,
      version_constants().kMap32TileBL, version_constants().kMap32TileBR};
  int map32_len = 0x33F0;  // Vanilla length
 
  // Mirror AssembleMap32Tiles() logic: if expanded tile32 is present, the three
  // non-TL quadrants are relocated and the logical length changes.
  if (expanded_tile32_) {
    map32address[1] = GetMap32TileTRExpanded();
    map32address[2] = GetMap32TileBLExpanded();
    map32address[3] = GetMap32TileBRExpanded();
    map32_len = kMap32TileCountExpanded;
  }
 
  for (int i = 0; i < 4; ++i) {
    if (map32address[i] > 0) {  // Valid address
      ranges.emplace_back(map32address[i], map32address[i] + map32_len);
    }
  }
 
  // 2) Map16 Tiles
  int map16_addr = kMap16Tiles;
  int map16_len = kNumTile16Individual * 8;  // Vanilla: 4096 * 8 = 32KB
  if (expanded_tile16_) {
    map16_addr = GetMap16TilesExpanded();
    map16_len = NumberOfMap16Ex * 8;
  }
  ranges.emplace_back(map16_addr, map16_addr + map16_len);
 
  // 3) Overworld map compressed pointer tables + data regions.
  // SaveOverworldMaps() writes two 3-byte pointer tables for all maps, plus the
  // compressed data itself. This is a conservative superset of the possible
  // write footprint.
  constexpr uint32_t kCompressedBank0bEnd = 0x5FE70;
  constexpr uint32_t kCompressedBank0cStart = 0x60000;
  constexpr uint32_t kCompressedBank0cEnd = 0x6411F;
 
  const uint32_t ptr_low = version_constants().kCompressedAllMap32PointersLow;
  const uint32_t ptr_high = version_constants().kCompressedAllMap32PointersHigh;
  ranges.emplace_back(ptr_low, ptr_low + (3 * kNumOverworldMaps));
  ranges.emplace_back(ptr_high, ptr_high + (3 * kNumOverworldMaps));
 
  ranges.emplace_back(kOverworldCompressedMapPos,
                      kCompressedBank0bEnd);                          // Bank 0B
  ranges.emplace_back(kCompressedBank0cStart, kCompressedBank0cEnd);  // Bank 0C
  ranges.emplace_back(kOverworldMapDataOverflow,
                      kOverworldCompressedOverflowPos);  // Overflow Area
 
  return ranges;
}
 
absl::Status Overworld::SaveLargeMaps() {
  util::logf("Saving Large Maps");
 
  // Check if this is a v3+ ROM to use expanded transition system
  bool use_expanded_transitions =
      OverworldVersionHelper::SupportsAreaEnum(cached_version_);
 
  if (use_expanded_transitions) {
    // Use new v3+ complex transition system with neighbor awareness
    return SaveLargeMapsExpanded();
  }
 
  // Original vanilla/v2 logic preserved
  std::vector<uint8_t> checked_map;
 
  for (int i = 0; i < kNumMapsPerWorld; ++i) {
    int y_pos = i / 8;
    int x_pos = i % 8;
    int parent_y_pos = overworld_maps_[i].parent() / 8;
    int parent_x_pos = overworld_maps_[i].parent() % 8;
 
    // Always write the map parent since it should not matter
    RETURN_IF_ERROR(rom()->WriteByte(kOverworldMapParentId + i,
                                     overworld_maps_[i].parent()))
 
    if (std::find(checked_map.begin(), checked_map.end(), i) !=
        checked_map.end()) {
      continue;
    }
 
    // If it's large then save parent pos *
    // 0x200 otherwise pos * 0x200
    if (overworld_maps_[i].is_large_map()) {
      const uint8_t large_map_offsets[] = {0, 1, 8, 9};
      for (const auto& offset : large_map_offsets) {
        // Check 1
        RETURN_IF_ERROR(rom()->WriteByte(kOverworldMapSize + i + offset, 0x20));
        // Check 2
        RETURN_IF_ERROR(
            rom()->WriteByte(kOverworldMapSizeHighByte + i + offset, 0x03));
        // Check 3
        RETURN_IF_ERROR(
            rom()->WriteByte(kOverworldScreenSize + i + offset, 0x00));
        RETURN_IF_ERROR(
            rom()->WriteByte(kOverworldScreenSize + i + offset + 64, 0x00));
        // Check 4
        RETURN_IF_ERROR(rom()->WriteByte(
            kOverworldScreenSizeForLoading + i + offset, 0x04));
        RETURN_IF_ERROR(rom()->WriteByte(
            kOverworldScreenSizeForLoading + i + offset + kDarkWorldMapIdStart,
            0x04));
        RETURN_IF_ERROR(rom()->WriteByte(kOverworldScreenSizeForLoading + i +
                                             offset + kSpecialWorldMapIdStart,
                                         0x04));
      }
 
      // Check 5 and 6 - transition targets
      RETURN_IF_ERROR(
          rom()->WriteShort(kTransitionTargetNorth + (i * 2),
                            (uint16_t)((parent_y_pos * 0x200) - 0xE0)));
      RETURN_IF_ERROR(
          rom()->WriteShort(kTransitionTargetWest + (i * 2),
                            (uint16_t)((parent_x_pos * 0x200) - 0x100)));
 
      RETURN_IF_ERROR(
          rom()->WriteShort(kTransitionTargetNorth + (i * 2) + 2,
                            (uint16_t)((parent_y_pos * 0x200) - 0xE0)));
      RETURN_IF_ERROR(
          rom()->WriteShort(kTransitionTargetWest + (i * 2) + 2,
                            (uint16_t)((parent_x_pos * 0x200) - 0x100)));
 
      RETURN_IF_ERROR(
          rom()->WriteShort(kTransitionTargetNorth + (i * 2) + 16,
                            (uint16_t)((parent_y_pos * 0x200) - 0xE0)));
      RETURN_IF_ERROR(
          rom()->WriteShort(kTransitionTargetWest + (i * 2) + 16,
                            (uint16_t)((parent_x_pos * 0x200) - 0x100)));
 
      RETURN_IF_ERROR(
          rom()->WriteShort(kTransitionTargetNorth + (i * 2) + 18,
                            (uint16_t)((parent_y_pos * 0x200) - 0xE0)));
      RETURN_IF_ERROR(
          rom()->WriteShort(kTransitionTargetWest + (i * 2) + 18,
                            (uint16_t)((parent_x_pos * 0x200) - 0x100)));
 
      // Check 7 and 8 - transition positions
      RETURN_IF_ERROR(rom()->WriteShort(kOverworldTransitionPositionX + (i * 2),
                                        (parent_x_pos * 0x200)));
      RETURN_IF_ERROR(rom()->WriteShort(kOverworldTransitionPositionY + (i * 2),
                                        (parent_y_pos * 0x200)));
 
      RETURN_IF_ERROR(
          rom()->WriteShort(kOverworldTransitionPositionX + (i * 2) + 02,
                            (parent_x_pos * 0x200)));
      RETURN_IF_ERROR(
          rom()->WriteShort(kOverworldTransitionPositionY + (i * 2) + 02,
                            (parent_y_pos * 0x200)));
 
      RETURN_IF_ERROR(
          rom()->WriteShort(kOverworldTransitionPositionX + (i * 2) + 16,
                            (parent_x_pos * 0x200)));
      RETURN_IF_ERROR(
          rom()->WriteShort(kOverworldTransitionPositionY + (i * 2) + 16,
                            (parent_y_pos * 0x200)));
 
      RETURN_IF_ERROR(
          rom()->WriteShort(kOverworldTransitionPositionX + (i * 2) + 18,
                            (parent_x_pos * 0x200)));
      RETURN_IF_ERROR(
          rom()->WriteShort(kOverworldTransitionPositionY + (i * 2) + 18,
                            (parent_y_pos * 0x200)));
 
      // Check 9 - simple vanilla large area transitions
      RETURN_IF_ERROR(rom()->WriteShort(
          kOverworldScreenTileMapChangeByScreen1 + (i * 2) + 00, 0x0060));
      RETURN_IF_ERROR(rom()->WriteShort(
          kOverworldScreenTileMapChangeByScreen1 + (i * 2) + 02, 0x0060));
 
      // If parentX == 0 then lower submaps == 0x0060 too
      if (parent_x_pos == 0) {
        RETURN_IF_ERROR(rom()->WriteShort(
            kOverworldScreenTileMapChangeByScreen1 + (i * 2) + 16, 0x0060));
        RETURN_IF_ERROR(rom()->WriteShort(
            kOverworldScreenTileMapChangeByScreen1 + (i * 2) + 18, 0x0060));
      } else {
        // Otherwise lower submaps == 0x1060
        RETURN_IF_ERROR(rom()->WriteShort(
            kOverworldScreenTileMapChangeByScreen1 + (i * 2) + 16, 0x1060));
        RETURN_IF_ERROR(rom()->WriteShort(
            kOverworldScreenTileMapChangeByScreen1 + (i * 2) + 18, 0x1060));
 
        // If the area to the left is a large map, we don't need to add an
        // offset to it. otherwise leave it the same. Just to make sure where
        // don't try to read outside of the array.
        if ((i - 1) >= 0) {
          // If the area to the left is a large area.
          if (overworld_maps_[i - 1].is_large_map()) {
            // If the area to the left is the bottom right of a large area.
            if (overworld_maps_[i - 1].large_index() == 1) {
              RETURN_IF_ERROR(rom()->WriteShort(
                  kOverworldScreenTileMapChangeByScreen1 + (i * 2) + 16,
                  0x0060));
            }
          }
        }
      }
 
      // Always 0x0080
      RETURN_IF_ERROR(rom()->WriteShort(
          kOverworldScreenTileMapChangeByScreen2 + (i * 2) + 00, 0x0080));
      RETURN_IF_ERROR(rom()->WriteShort(
          kOverworldScreenTileMapChangeByScreen2 + (i * 2) + 2, 0x0080));
      // Lower always 0x1080
      RETURN_IF_ERROR(rom()->WriteShort(
          kOverworldScreenTileMapChangeByScreen2 + (i * 2) + 16, 0x1080));
      RETURN_IF_ERROR(rom()->WriteShort(
          kOverworldScreenTileMapChangeByScreen2 + (i * 2) + 18, 0x1080));
 
      // If the area to the right is a large map, we don't need to add an offset
      // to it. otherwise leave it the same. Just to make sure where don't try
      // to read outside of the array.
      if ((i + 2) < 64) {
        // If the area to the right is a large area.
        if (overworld_maps_[i + 2].is_large_map()) {
          // If the area to the right is the top left of a large area.
          if (overworld_maps_[i + 2].large_index() == 0) {
            RETURN_IF_ERROR(rom()->WriteShort(
                kOverworldScreenTileMapChangeByScreen2 + (i * 2) + 18, 0x0080));
          }
        }
      }
 
      // Always 0x1800
      RETURN_IF_ERROR(rom()->WriteShort(
          kOverworldScreenTileMapChangeByScreen3 + (i * 2), 0x1800));
      RETURN_IF_ERROR(rom()->WriteShort(
          kOverworldScreenTileMapChangeByScreen3 + (i * 2) + 16, 0x1800));
      // Right side is always 0x1840
      RETURN_IF_ERROR(rom()->WriteShort(
          kOverworldScreenTileMapChangeByScreen3 + (i * 2) + 2, 0x1840));
      RETURN_IF_ERROR(rom()->WriteShort(
          kOverworldScreenTileMapChangeByScreen3 + (i * 2) + 18, 0x1840));
 
      // If the area above is a large map, we don't need to add an offset to it.
      // otherwise leave it the same.
      // Just to make sure where don't try to read outside of the array.
      if (i - 8 >= 0) {
        // If the area just above us is a large area.
        if (overworld_maps_[i - 8].is_large_map()) {
          // If the area just above us is the bottom left of a large area.
          if (overworld_maps_[i - 8].large_index() == 2) {
            RETURN_IF_ERROR(rom()->WriteShort(
                kOverworldScreenTileMapChangeByScreen3 + (i * 2) + 02, 0x1800));
          }
        }
      }
 
      // Always 0x2000
      RETURN_IF_ERROR(rom()->WriteShort(
          kOverworldScreenTileMapChangeByScreen4 + (i * 2) + 00, 0x2000));
      RETURN_IF_ERROR(rom()->WriteShort(
          kOverworldScreenTileMapChangeByScreen4 + (i * 2) + 16, 0x2000));
      // Right side always 0x2040
      RETURN_IF_ERROR(rom()->WriteShort(
          kOverworldScreenTileMapChangeByScreen4 + (i * 2) + 2, 0x2040));
      RETURN_IF_ERROR(rom()->WriteShort(
          kOverworldScreenTileMapChangeByScreen4 + (i * 2) + 18, 0x2040));
 
      // If the area below is a large map, we don't need to add an offset to it.
      // otherwise leave it the same.
      // Just to make sure where don't try to read outside of the array.
      if (i + 16 < 64) {
        // If the area just below us is a large area.
        if (overworld_maps_[i + 16].is_large_map()) {
          // If the area just below us is the top left of a large area.
          if (overworld_maps_[i + 16].large_index() == 0) {
            RETURN_IF_ERROR(rom()->WriteShort(
                kOverworldScreenTileMapChangeByScreen4 + (i * 2) + 18, 0x2000));
          }
        }
      }
 
      checked_map.emplace_back(i);
      checked_map.emplace_back((i + 1));
      checked_map.emplace_back((i + 8));
      checked_map.emplace_back((i + 9));
 
    } else {
      RETURN_IF_ERROR(rom()->WriteByte(kOverworldMapSize + i, 0x00));
      RETURN_IF_ERROR(rom()->WriteByte(kOverworldMapSizeHighByte + i, 0x01));
 
      RETURN_IF_ERROR(rom()->WriteByte(kOverworldScreenSize + i, 0x01));
      RETURN_IF_ERROR(rom()->WriteByte(kOverworldScreenSize + i + 64, 0x01));
 
      RETURN_IF_ERROR(
          rom()->WriteByte(kOverworldScreenSizeForLoading + i, 0x02));
      RETURN_IF_ERROR(rom()->WriteByte(
          kOverworldScreenSizeForLoading + i + kDarkWorldMapIdStart, 0x02));
      RETURN_IF_ERROR(rom()->WriteByte(
          kOverworldScreenSizeForLoading + i + kSpecialWorldMapIdStart, 0x02));
 
      RETURN_IF_ERROR(rom()->WriteShort(
          kOverworldScreenTileMapChangeByScreen1 + (i * 2), 0x0060));
 
      // If the area to the left is a large map, we don't need to add an offset
      // to it. otherwise leave it the same.
      // Just to make sure where don't try to read outside of the array.
      if (i - 1 >= 0 && parent_x_pos != 0) {
        if (overworld_maps_[i - 1].is_large_map()) {
          if (overworld_maps_[i - 1].large_index() == 3) {
            RETURN_IF_ERROR(rom()->WriteShort(
                kOverworldScreenTileMapChangeByScreen1 + (i * 2), 0xF060));
          }
        }
      }
 
      RETURN_IF_ERROR(rom()->WriteShort(
          kOverworldScreenTileMapChangeByScreen2 + (i * 2), 0x0040));
 
      if (i + 1 < 64 && parent_x_pos != 7) {
        if (overworld_maps_[i + 1].is_large_map()) {
          if (overworld_maps_[i + 1].large_index() == 2) {
            RETURN_IF_ERROR(rom()->WriteShort(
                kOverworldScreenTileMapChangeByScreen2 + (i * 2), 0xF040));
          }
        }
      }
 
      RETURN_IF_ERROR(rom()->WriteShort(
          kOverworldScreenTileMapChangeByScreen3 + (i * 2), 0x1800));
 
      // If the area above is a large map, we don't need to add an offset to it.
      // otherwise leave it the same.
      // Just to make sure where don't try to read outside of the array.
      if (i - 8 >= 0) {
        // If the area just above us is a large area.
        if (overworld_maps_[i - 8].is_large_map()) {
          // If we are under the bottom right of the large area.
          if (overworld_maps_[i - 8].large_index() == 3) {
            RETURN_IF_ERROR(rom()->WriteShort(
                kOverworldScreenTileMapChangeByScreen3 + (i * 2), 0x17C0));
          }
        }
      }
 
      RETURN_IF_ERROR(rom()->WriteShort(
          kOverworldScreenTileMapChangeByScreen4 + (i * 2), 0x1000));
 
      // If the area below is a large map, we don't need to add an offset to it.
      // otherwise leave it the same.
      // Just to make sure where don't try to read outside of the array.
      if (i + 8 < 64) {
        // If the area just below us is a large area.
        if (overworld_maps_[i + 8].is_large_map()) {
          // If we are on top of the top right of the large area.
          if (overworld_maps_[i + 8].large_index() == 1) {
            RETURN_IF_ERROR(rom()->WriteShort(
                kOverworldScreenTileMapChangeByScreen4 + (i * 2), 0x0FC0));
          }
        }
      }
 
      RETURN_IF_ERROR(rom()->WriteShort(kTransitionTargetNorth + (i * 2),
                                        (uint16_t)((y_pos * 0x200) - 0xE0)));
      RETURN_IF_ERROR(rom()->WriteShort(kTransitionTargetWest + (i * 2),
                                        (uint16_t)((x_pos * 0x200) - 0x100)));
 
      RETURN_IF_ERROR(rom()->WriteShort(kOverworldTransitionPositionX + (i * 2),
                                        (x_pos * 0x200)));
      RETURN_IF_ERROR(rom()->WriteShort(kOverworldTransitionPositionY + (i * 2),
                                        (y_pos * 0x200)));
 
      checked_map.emplace_back(i);
    }
  }
 
  // The legacy parent and transition tables are 64-entry local tables, but the
  // screen-size bytes are stored per Light/Dark world. The original loop above
  // mirrors Light World sizes into Dark World while calculating transitions;
  // correct those world-specific bytes from the actual map objects before
  // returning so a Light/Special edit cannot silently clobber Dark World sizes.
  const auto legacy_size_byte = [this](int map_index) -> uint8_t {
    return overworld_maps_[map_index].is_large_map() ? 0x00 : 0x01;
  };
  const auto legacy_loading_size_byte = [this](int map_index) -> uint8_t {
    return overworld_maps_[map_index].is_large_map() ? 0x04 : 0x02;
  };
 
  for (int map_index = 0; map_index < kSpecialWorldMapIdStart; ++map_index) {
    RETURN_IF_ERROR(rom()->WriteByte(kOverworldScreenSize + map_index,
                                     legacy_size_byte(map_index)));
    RETURN_IF_ERROR(rom()->WriteByte(kOverworldScreenSizeForLoading + map_index,
                                     legacy_loading_size_byte(map_index)));
  }
 
  for (int map_index = kSpecialWorldMapIdStart; map_index < kNumOverworldMaps;
       ++map_index) {
    RETURN_IF_ERROR(rom()->WriteByte(kOverworldScreenSizeForLoading + map_index,
                                     legacy_loading_size_byte(map_index)));
  }
 
  constexpr int OverworldScreenTileMapChangeMask = 0x1262C;
 
  RETURN_IF_ERROR(
      rom()->WriteShort(OverworldScreenTileMapChangeMask + 0, 0x1F80));
  RETURN_IF_ERROR(
      rom()->WriteShort(OverworldScreenTileMapChangeMask + 2, 0x1F80));
  RETURN_IF_ERROR(
      rom()->WriteShort(OverworldScreenTileMapChangeMask + 4, 0x007F));
  RETURN_IF_ERROR(
      rom()->WriteShort(OverworldScreenTileMapChangeMask + 6, 0x007F));
 
  return absl::OkStatus();
}
 
absl::Status Overworld::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) {
  // Set basic transition targets
  RETURN_IF_ERROR(
      rom()->WriteShort(transition_target_north + (i * 2),
                        (uint16_t)((parent_y_pos * 0x0200) - 0x00E0)));
  RETURN_IF_ERROR(
      rom()->WriteShort(transition_target_west + (i * 2),
                        (uint16_t)((parent_x_pos * 0x0200) - 0x0100)));
 
  RETURN_IF_ERROR(
      rom()->WriteShort(transition_pos_x + (i * 2), parent_x_pos * 0x0200));
  RETURN_IF_ERROR(
      rom()->WriteShort(transition_pos_y + (i * 2), parent_y_pos * 0x0200));
 
  // byScreen1 = Transitioning right
  uint16_t by_screen1_small = 0x0060;
 
  // Check west neighbor for transition adjustments
  if ((i % 0x40) - 1 >= 0) {
    auto& west_neighbor = overworld_maps_[i - 1];
 
    // Transition from bottom right quadrant of large area to small area
    if (west_neighbor.area_size() == AreaSizeEnum::LargeArea &&
        west_neighbor.large_index() == 3) {
      by_screen1_small = 0xF060;
    }
    // Transition from bottom quadrant of tall area to small area
    else if (west_neighbor.area_size() == AreaSizeEnum::TallArea &&
             west_neighbor.large_index() == 2) {
      by_screen1_small = 0xF060;
    }
  }
 
  RETURN_IF_ERROR(
      rom()->WriteShort(screen_change_1 + (i * 2), by_screen1_small));
 
  // byScreen2 = Transitioning left
  uint16_t by_screen2_small = 0x0040;
 
  // Check east neighbor for transition adjustments
  if ((i % 0x40) + 1 < 0x40 && i + 1 < kNumOverworldMaps) {
    auto& east_neighbor = overworld_maps_[i + 1];
 
    // Transition from bottom left quadrant of large area to small area
    if (east_neighbor.area_size() == AreaSizeEnum::LargeArea &&
        east_neighbor.large_index() == 2) {
      by_screen2_small = 0xF040;
    }
    // Transition from bottom quadrant of tall area to small area
    else if (east_neighbor.area_size() == AreaSizeEnum::TallArea &&
             east_neighbor.large_index() == 2) {
      by_screen2_small = 0xF040;
    }
  }
 
  RETURN_IF_ERROR(
      rom()->WriteShort(screen_change_2 + (i * 2), by_screen2_small));
 
  // byScreen3 = Transitioning down
  uint16_t by_screen3_small = 0x1800;
 
  // Check north neighbor for transition adjustments
  if ((i % 0x40) - 8 >= 0) {
    auto& north_neighbor = overworld_maps_[i - 8];
 
    // Transition from bottom right quadrant of large area to small area
    if (north_neighbor.area_size() == AreaSizeEnum::LargeArea &&
        north_neighbor.large_index() == 3) {
      by_screen3_small = 0x17C0;
    }
    // Transition from right quadrant of wide area to small area
    else if (north_neighbor.area_size() == AreaSizeEnum::WideArea &&
             north_neighbor.large_index() == 1) {
      by_screen3_small = 0x17C0;
    }
  }
 
  RETURN_IF_ERROR(
      rom()->WriteShort(screen_change_3 + (i * 2), by_screen3_small));
 
  // byScreen4 = Transitioning up
  uint16_t by_screen4_small = 0x1000;
 
  // Check south neighbor for transition adjustments
  if ((i % 0x40) + 8 < 0x40 && i + 8 < kNumOverworldMaps) {
    auto& south_neighbor = overworld_maps_[i + 8];
 
    // Transition from top right quadrant of large area to small area
    if (south_neighbor.area_size() == AreaSizeEnum::LargeArea &&
        south_neighbor.large_index() == 1) {
      by_screen4_small = 0x0FC0;
    }
    // Transition from right quadrant of wide area to small area
    else if (south_neighbor.area_size() == AreaSizeEnum::WideArea &&
             south_neighbor.large_index() == 1) {
      by_screen4_small = 0x0FC0;
    }
  }
 
  RETURN_IF_ERROR(
      rom()->WriteShort(screen_change_4 + (i * 2), by_screen4_small));
 
  return absl::OkStatus();
}
 
absl::Status Overworld::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) {
  // Set transition targets for all 4 quadrants
  const uint16_t offsets[] = {0, 2, 16, 18};
  for (auto offset : offsets) {
    RETURN_IF_ERROR(
        rom()->WriteShort(transition_target_north + (i * 2) + offset,
                          (uint16_t)((parent_y_pos * 0x0200) - 0x00E0)));
    RETURN_IF_ERROR(
        rom()->WriteShort(transition_target_west + (i * 2) + offset,
                          (uint16_t)((parent_x_pos * 0x0200) - 0x0100)));
    RETURN_IF_ERROR(rom()->WriteShort(transition_pos_x + (i * 2) + offset,
                                      parent_x_pos * 0x0200));
    RETURN_IF_ERROR(rom()->WriteShort(transition_pos_y + (i * 2) + offset,
                                      parent_y_pos * 0x0200));
  }
 
  // Complex neighbor-aware transition calculations for large areas
  // byScreen1 = Transitioning right
  std::array<uint16_t, 4> by_screen1_large = {0x0060, 0x0060, 0x1060, 0x1060};
 
  // Check west neighbor
  if ((i % 0x40) - 1 >= 0) {
    auto& west_neighbor = overworld_maps_[i - 1];
 
    if (west_neighbor.area_size() == AreaSizeEnum::LargeArea) {
      switch (west_neighbor.large_index()) {
        case 1:  // From bottom right to bottom left of large area
          by_screen1_large[2] = 0x0060;
          break;
        case 3:  // From bottom right to top left of large area
          by_screen1_large[0] = 0xF060;
          break;
      }
    } else if (west_neighbor.area_size() == AreaSizeEnum::TallArea) {
      switch (west_neighbor.large_index()) {
        case 0:  // From bottom of tall to bottom left of large
          by_screen1_large[2] = 0x0060;
          break;
        case 2:  // From bottom of tall to top left of large
          by_screen1_large[0] = 0xF060;
          break;
      }
    }
  }
 
  for (int j = 0; j < 4; j++) {
    RETURN_IF_ERROR(rom()->WriteShort(screen_change_1 + (i * 2) + offsets[j],
                                      by_screen1_large[j]));
  }
 
  // byScreen2 = Transitioning left
  std::array<uint16_t, 4> by_screen2_large = {0x0080, 0x0080, 0x1080, 0x1080};
 
  // Check east neighbor
  if ((i % 0x40) + 2 < 0x40 && i + 2 < kNumOverworldMaps) {
    auto& east_neighbor = overworld_maps_[i + 2];
 
    if (east_neighbor.area_size() == AreaSizeEnum::LargeArea) {
      switch (east_neighbor.large_index()) {
        case 0:  // From bottom left to bottom right of large area
          by_screen2_large[3] = 0x0080;
          break;
        case 2:  // From bottom left to top right of large area
          by_screen2_large[1] = 0xF080;
          break;
      }
    } else if (east_neighbor.area_size() == AreaSizeEnum::TallArea) {
      switch (east_neighbor.large_index()) {
        case 0:  // From bottom of tall to bottom right of large
          by_screen2_large[3] = 0x0080;
          break;
        case 2:  // From bottom of tall to top right of large
          by_screen2_large[1] = 0xF080;
          break;
      }
    }
  }
 
  for (int j = 0; j < 4; j++) {
    RETURN_IF_ERROR(rom()->WriteShort(screen_change_2 + (i * 2) + offsets[j],
                                      by_screen2_large[j]));
  }
 
  // byScreen3 = Transitioning down
  std::array<uint16_t, 4> by_screen3_large = {0x1800, 0x1840, 0x1800, 0x1840};
 
  // Check north neighbor
  if ((i % 0x40) - 8 >= 0) {
    auto& north_neighbor = overworld_maps_[i - 8];
 
    if (north_neighbor.area_size() == AreaSizeEnum::LargeArea) {
      switch (north_neighbor.large_index()) {
        case 2:  // From bottom right to top right of large area
          by_screen3_large[1] = 0x1800;
          break;
        case 3:  // From bottom right to top left of large area
          by_screen3_large[0] = 0x17C0;
          break;
      }
    } else if (north_neighbor.area_size() == AreaSizeEnum::WideArea) {
      switch (north_neighbor.large_index()) {
        case 0:  // From right of wide to top right of large
          by_screen3_large[1] = 0x1800;
          break;
        case 1:  // From right of wide to top left of large
          by_screen3_large[0] = 0x17C0;
          break;
      }
    }
  }
 
  for (int j = 0; j < 4; j++) {
    RETURN_IF_ERROR(rom()->WriteShort(screen_change_3 + (i * 2) + offsets[j],
                                      by_screen3_large[j]));
  }
 
  // byScreen4 = Transitioning up
  std::array<uint16_t, 4> by_screen4_large = {0x2000, 0x2040, 0x2000, 0x2040};
 
  // Check south neighbor
  if ((i % 0x40) + 16 < 0x40 && i + 16 < kNumOverworldMaps) {
    auto& south_neighbor = overworld_maps_[i + 16];
 
    if (south_neighbor.area_size() == AreaSizeEnum::LargeArea) {
      switch (south_neighbor.large_index()) {
        case 0:  // From top right to bottom right of large area
          by_screen4_large[3] = 0x2000;
          break;
        case 1:  // From top right to bottom left of large area
          by_screen4_large[2] = 0x1FC0;
          break;
      }
    } else if (south_neighbor.area_size() == AreaSizeEnum::WideArea) {
      switch (south_neighbor.large_index()) {
        case 0:  // From right of wide to bottom right of large
          by_screen4_large[3] = 0x2000;
          break;
        case 1:  // From right of wide to bottom left of large
          by_screen4_large[2] = 0x1FC0;
          break;
      }
    }
  }
 
  for (int j = 0; j < 4; j++) {
    RETURN_IF_ERROR(rom()->WriteShort(screen_change_4 + (i * 2) + offsets[j],
                                      by_screen4_large[j]));
  }
 
  return absl::OkStatus();
}
 
absl::Status Overworld::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) {
  // Set transition targets for both quadrants
  const uint16_t offsets[] = {0, 2};
  for (auto offset : offsets) {
    RETURN_IF_ERROR(
        rom()->WriteShort(transition_target_north + (i * 2) + offset,
                          (uint16_t)((parent_y_pos * 0x0200) - 0x00E0)));
    RETURN_IF_ERROR(
        rom()->WriteShort(transition_target_west + (i * 2) + offset,
                          (uint16_t)((parent_x_pos * 0x0200) - 0x0100)));
    RETURN_IF_ERROR(rom()->WriteShort(transition_pos_x + (i * 2) + offset,
                                      parent_x_pos * 0x0200));
    RETURN_IF_ERROR(rom()->WriteShort(transition_pos_y + (i * 2) + offset,
                                      parent_y_pos * 0x0200));
  }
 
  // byScreen1 = Transitioning right
  std::array<uint16_t, 2> by_screen1_wide = {0x0060, 0x0060};
 
  // Check west neighbor
  if ((i % 0x40) - 1 >= 0) {
    auto& west_neighbor = overworld_maps_[i - 1];
 
    // From bottom right of large to left of wide
    if (west_neighbor.area_size() == AreaSizeEnum::LargeArea &&
        west_neighbor.large_index() == 3) {
      by_screen1_wide[0] = 0xF060;
    }
    // From bottom of tall to left of wide
    else if (west_neighbor.area_size() == AreaSizeEnum::TallArea &&
             west_neighbor.large_index() == 2) {
      by_screen1_wide[0] = 0xF060;
    }
  }
 
  for (int j = 0; j < 2; j++) {
    RETURN_IF_ERROR(rom()->WriteShort(screen_change_1 + (i * 2) + offsets[j],
                                      by_screen1_wide[j]));
  }
 
  // byScreen2 = Transitioning left
  std::array<uint16_t, 2> by_screen2_wide = {0x0080, 0x0080};
 
  // Check east neighbor
  if ((i % 0x40) + 2 < 0x40 && i + 2 < kNumOverworldMaps) {
    auto& east_neighbor = overworld_maps_[i + 2];
 
    // From bottom left of large to right of wide
    if (east_neighbor.area_size() == AreaSizeEnum::LargeArea &&
        east_neighbor.large_index() == 2) {
      by_screen2_wide[1] = 0xF080;
    }
    // From bottom of tall to right of wide
    else if (east_neighbor.area_size() == AreaSizeEnum::TallArea &&
             east_neighbor.large_index() == 2) {
      by_screen2_wide[1] = 0xF080;
    }
  }
 
  for (int j = 0; j < 2; j++) {
    RETURN_IF_ERROR(rom()->WriteShort(screen_change_2 + (i * 2) + offsets[j],
                                      by_screen2_wide[j]));
  }
 
  // byScreen3 = Transitioning down
  std::array<uint16_t, 2> by_screen3_wide = {0x1800, 0x1840};
 
  // Check north neighbor
  if ((i % 0x40) - 8 >= 0) {
    auto& north_neighbor = overworld_maps_[i - 8];
 
    if (north_neighbor.area_size() == AreaSizeEnum::LargeArea) {
      switch (north_neighbor.large_index()) {
        case 2:  // From bottom right of large to right of wide
          by_screen3_wide[1] = 0x1800;
          break;
        case 3:  // From bottom right of large to left of wide
          by_screen3_wide[0] = 0x17C0;
          break;
      }
    } else if (north_neighbor.area_size() == AreaSizeEnum::WideArea) {
      switch (north_neighbor.large_index()) {
        case 0:  // From right of wide to right of wide
          by_screen3_wide[1] = 0x1800;
          break;
        case 1:  // From right of wide to left of wide
          by_screen3_wide[0] = 0x17C0;
          break;
      }
    }
  }
 
  for (int j = 0; j < 2; j++) {
    RETURN_IF_ERROR(rom()->WriteShort(screen_change_3 + (i * 2) + offsets[j],
                                      by_screen3_wide[j]));
  }
 
  // byScreen4 = Transitioning up
  std::array<uint16_t, 2> by_screen4_wide = {0x1000, 0x1040};
 
  // Check south neighbor
  if ((i % 0x40) + 8 < 0x40 && i + 8 < kNumOverworldMaps) {
    auto& south_neighbor = overworld_maps_[i + 8];
 
    if (south_neighbor.area_size() == AreaSizeEnum::LargeArea) {
      switch (south_neighbor.large_index()) {
        case 0:  // From top right of large to right of wide
          by_screen4_wide[1] = 0x1000;
          break;
        case 1:  // From top right of large to left of wide
          by_screen4_wide[0] = 0x0FC0;
          break;
      }
    } else if (south_neighbor.area_size() == AreaSizeEnum::WideArea) {
      if (south_neighbor.large_index() == 1) {
        by_screen4_wide[0] = 0x0FC0;
      }
      switch (south_neighbor.large_index()) {
        case 0:  // From right of wide to right of wide
          by_screen4_wide[1] = 0x1000;
          break;
        case 1:  // From right of wide to left of wide
          by_screen4_wide[0] = 0x0FC0;
          break;
      }
    }
  }
 
  for (int j = 0; j < 2; j++) {
    RETURN_IF_ERROR(rom()->WriteShort(screen_change_4 + (i * 2) + offsets[j],
                                      by_screen4_wide[j]));
  }
 
  return absl::OkStatus();
}
 
absl::Status Overworld::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) {
  // Set transition targets for both quadrants
  const uint16_t offsets[] = {0, 16};
  for (auto offset : offsets) {
    RETURN_IF_ERROR(
        rom()->WriteShort(transition_target_north + (i * 2) + offset,
                          (uint16_t)((parent_y_pos * 0x0200) - 0x00E0)));
    RETURN_IF_ERROR(
        rom()->WriteShort(transition_target_west + (i * 2) + offset,
                          (uint16_t)((parent_x_pos * 0x0200) - 0x0100)));
    RETURN_IF_ERROR(rom()->WriteShort(transition_pos_x + (i * 2) + offset,
                                      parent_x_pos * 0x0200));
    RETURN_IF_ERROR(rom()->WriteShort(transition_pos_y + (i * 2) + offset,
                                      parent_y_pos * 0x0200));
  }
 
  // byScreen1 = Transitioning right
  std::array<uint16_t, 2> by_screen1_tall = {0x0060, 0x1060};
 
  // Check west neighbor
  if ((i % 0x40) - 1 >= 0) {
    auto& west_neighbor = overworld_maps_[i - 1];
 
    if (west_neighbor.area_size() == AreaSizeEnum::LargeArea) {
      switch (west_neighbor.large_index()) {
        case 1:  // From bottom right of large to bottom of tall
          by_screen1_tall[1] = 0x0060;
          break;
        case 3:  // From bottom right of large to top of tall
          by_screen1_tall[0] = 0xF060;
          break;
      }
    } else if (west_neighbor.area_size() == AreaSizeEnum::TallArea) {
      switch (west_neighbor.large_index()) {
        case 0:  // From bottom of tall to bottom of tall
          by_screen1_tall[1] = 0x0060;
          break;
        case 2:  // From bottom of tall to top of tall
          by_screen1_tall[0] = 0xF060;
          break;
      }
    }
  }
 
  for (int j = 0; j < 2; j++) {
    RETURN_IF_ERROR(rom()->WriteShort(screen_change_1 + (i * 2) + offsets[j],
                                      by_screen1_tall[j]));
  }
 
  // byScreen2 = Transitioning left
  std::array<uint16_t, 2> by_screen2_tall = {0x0040, 0x1040};
 
  // Check east neighbor
  if ((i % 0x40) + 1 < 0x40 && i + 1 < kNumOverworldMaps) {
    auto& east_neighbor = overworld_maps_[i + 1];
 
    if (east_neighbor.area_size() == AreaSizeEnum::LargeArea) {
      switch (east_neighbor.large_index()) {
        case 0:  // From bottom left of large to bottom of tall
          by_screen2_tall[1] = 0x0040;
          break;
        case 2:  // From bottom left of large to top of tall
          by_screen2_tall[0] = 0xF040;
          break;
      }
    } else if (east_neighbor.area_size() == AreaSizeEnum::TallArea) {
      switch (east_neighbor.large_index()) {
        case 0:  // From bottom of tall to bottom of tall
          by_screen2_tall[1] = 0x0040;
          break;
        case 2:  // From bottom of tall to top of tall
          by_screen2_tall[0] = 0xF040;
          break;
      }
    }
  }
 
  for (int j = 0; j < 2; j++) {
    RETURN_IF_ERROR(rom()->WriteShort(screen_change_2 + (i * 2) + offsets[j],
                                      by_screen2_tall[j]));
  }
 
  // byScreen3 = Transitioning down
  std::array<uint16_t, 2> by_screen3_tall = {0x1800, 0x1800};
 
  // Check north neighbor
  if ((i % 0x40) - 8 >= 0) {
    auto& north_neighbor = overworld_maps_[i - 8];
 
    // From bottom right of large to top of tall
    if (north_neighbor.area_size() == AreaSizeEnum::LargeArea &&
        north_neighbor.large_index() == 3) {
      by_screen3_tall[0] = 0x17C0;
    }
    // From right of wide to top of tall
    else if (north_neighbor.area_size() == AreaSizeEnum::WideArea &&
             north_neighbor.large_index() == 1) {
      by_screen3_tall[0] = 0x17C0;
    }
  }
 
  for (int j = 0; j < 2; j++) {
    RETURN_IF_ERROR(rom()->WriteShort(screen_change_3 + (i * 2) + offsets[j],
                                      by_screen3_tall[j]));
  }
 
  // byScreen4 = Transitioning up
  std::array<uint16_t, 2> by_screen4_tall = {0x2000, 0x2000};
 
  // Check south neighbor
  if ((i % 0x40) + 16 < 0x40 && i + 16 < kNumOverworldMaps) {
    auto& south_neighbor = overworld_maps_[i + 16];
 
    // From top right of large to bottom of tall
    if (south_neighbor.area_size() == AreaSizeEnum::LargeArea &&
        south_neighbor.large_index() == 1) {
      by_screen4_tall[1] = 0x1FC0;
    }
    // From right of wide to bottom of tall
    else if (south_neighbor.area_size() == AreaSizeEnum::WideArea &&
             south_neighbor.large_index() == 1) {
      by_screen4_tall[1] = 0x1FC0;
    }
  }
 
  for (int j = 0; j < 2; j++) {
    RETURN_IF_ERROR(rom()->WriteShort(screen_change_4 + (i * 2) + offsets[j],
                                      by_screen4_tall[j]));
  }
 
  return absl::OkStatus();
}
 
absl::Status Overworld::SaveLargeMapsExpanded() {
  util::logf("Saving Large Maps (v3+ Expanded)");
 
  // Use expanded memory locations for v3+
  int transition_target_north = zelda3::transition_target_northExpanded;
  int transition_target_west = zelda3::transition_target_westExpanded;
  int transition_pos_x = zelda3::GetOverworldTransitionPositionXExpanded();
  int transition_pos_y = zelda3::GetOverworldTransitionPositionYExpanded();
  int screen_change_1 = zelda3::GetOverworldScreenChange1Expanded();
  int screen_change_2 = zelda3::GetOverworldScreenChange2Expanded();
  int screen_change_3 = zelda3::GetOverworldScreenChange3Expanded();
  int screen_change_4 = zelda3::GetOverworldScreenChange4Expanded();
 
  std::vector<uint8_t> checked_map;
 
  // Process all overworld maps (0xA0 for v3)
  for (int i = 0; i < kNumOverworldMaps; ++i) {
    // Skip if this map was already processed as part of a multi-area structure
    if (std::find(checked_map.begin(), checked_map.end(), i) !=
        checked_map.end()) {
      continue;
    }
 
    int parent_y_pos = (overworld_maps_[i].parent() % 0x40) / 8;
    int parent_x_pos = (overworld_maps_[i].parent() % 0x40) % 8;
 
    // Write the map parent ID to expanded parent table
    RETURN_IF_ERROR(
        rom()->WriteByte(zelda3::GetOverworldMapParentIdExpanded() + i,
                         overworld_maps_[i].parent()));
 
    // Handle transitions based on area size
    switch (overworld_maps_[i].area_size()) {
      case AreaSizeEnum::SmallArea:
        RETURN_IF_ERROR(SaveSmallAreaTransitions(
            i, parent_x_pos, parent_y_pos, transition_target_north,
            transition_target_west, transition_pos_x, transition_pos_y,
            screen_change_1, screen_change_2, screen_change_3,
            screen_change_4));
        checked_map.emplace_back(i);
        break;
 
      case AreaSizeEnum::LargeArea:
        RETURN_IF_ERROR(SaveLargeAreaTransitions(
            i, parent_x_pos, parent_y_pos, transition_target_north,
            transition_target_west, transition_pos_x, transition_pos_y,
            screen_change_1, screen_change_2, screen_change_3,
            screen_change_4));
        // Mark all 4 quadrants as processed
        checked_map.emplace_back(i);
        checked_map.emplace_back(i + 1);
        checked_map.emplace_back(i + 8);
        checked_map.emplace_back(i + 9);
        break;
 
      case AreaSizeEnum::WideArea:
        RETURN_IF_ERROR(SaveWideAreaTransitions(
            i, parent_x_pos, parent_y_pos, transition_target_north,
            transition_target_west, transition_pos_x, transition_pos_y,
            screen_change_1, screen_change_2, screen_change_3,
            screen_change_4));
        // Mark both horizontal quadrants as processed
        checked_map.emplace_back(i);
        checked_map.emplace_back(i + 1);
        break;
 
      case AreaSizeEnum::TallArea:
        RETURN_IF_ERROR(SaveTallAreaTransitions(
            i, parent_x_pos, parent_y_pos, transition_target_north,
            transition_target_west, transition_pos_x, transition_pos_y,
            screen_change_1, screen_change_2, screen_change_3,
            screen_change_4));
        // Mark both vertical quadrants as processed
        checked_map.emplace_back(i);
        checked_map.emplace_back(i + 8);
        break;
    }
  }
 
  return absl::OkStatus();
}
 
namespace {
std::vector<uint64_t> GetAllTile16(OverworldMapTiles& map_tiles_) {
  std::vector<uint64_t> all_tile_16;  // Ensure it's 64 bits
 
  int sx = 0;
  int sy = 0;
  int c = 0;
  OverworldBlockset tiles_used;
  for (int i = 0; i < kNumOverworldMaps; i++) {
    if (i < kDarkWorldMapIdStart) {
      tiles_used = map_tiles_.light_world;
    } else if (i < kSpecialWorldMapIdStart && i >= kDarkWorldMapIdStart) {
      tiles_used = map_tiles_.dark_world;
    } else {
      tiles_used = map_tiles_.special_world;
    }
 
    for (int y = 0; y < 32; y += 2) {
      for (int x = 0; x < 32; x += 2) {
        gfx::Tile32 current_tile(
            tiles_used[x + (sx * 32)][y + (sy * 32)],
            tiles_used[x + 1 + (sx * 32)][y + (sy * 32)],
            tiles_used[x + (sx * 32)][y + 1 + (sy * 32)],
            tiles_used[x + 1 + (sx * 32)][y + 1 + (sy * 32)]);
 
        all_tile_16.emplace_back(current_tile.GetPackedValue());
      }
    }
 
    sx++;
    if (sx >= 8) {
      sy++;
      sx = 0;
    }
 
    c++;
    if (c >= 64) {
      sx = 0;
      sy = 0;
      c = 0;
    }
  }
 
  return all_tile_16;
}
}  // namespace
 
absl::Status Overworld::CreateTile32Tilemap() {
  RETURN_IF_ERROR(ValidatePrivateNativeTerrainSave());
  if (rom_ && rom_->has_lyra_private_reservation())
    return absl::OkStatus();
  tiles32_unique_.clear();
  tiles32_list_.clear();
 
  ASSIGN_OR_RETURN(const auto storage_layout,
                   ResolveMap32StorageLayout(*rom(), version_constants()));
 
  // Get all tiles16 and packs them into tiles32
  std::vector<uint64_t> all_tile_16 = GetAllTile16(map_tiles_);
 
  // Convert to set then back to vector
  std::set<uint64_t> unique_tiles_set(all_tile_16.begin(), all_tile_16.end());
 
  std::vector<uint64_t> unique_tiles(all_tile_16);
  unique_tiles.assign(unique_tiles_set.begin(), unique_tiles_set.end());
 
  // Create the indexed tiles list
  std::unordered_map<uint64_t, uint16_t> all_tiles_indexed;
  for (size_t tile32_id = 0; tile32_id < unique_tiles.size(); tile32_id++) {
    all_tiles_indexed.insert(
        {unique_tiles[tile32_id], static_cast<uint16_t>(tile32_id)});
  }
 
  // Add all tiles32 from all maps.
  // Convert all tiles32 non-unique IDs into unique array of IDs.
  for (int j = 0; j < NumberOfMap32; j++) {
    tiles32_list_.emplace_back(all_tiles_indexed[all_tile_16[j]]);
  }
 
  // Create the unique tiles list
  for (size_t i = 0; i < unique_tiles.size(); ++i) {
    tiles32_unique_.emplace_back(gfx::Tile32(unique_tiles[i]));
  }
 
  while (tiles32_unique_.size() % 4 != 0) {
    gfx::Tile32 padding_tile(0, 0, 0, 0);
    tiles32_unique_.emplace_back(padding_tile.GetPackedValue());
  }
 
  RETURN_IF_ERROR(
      ValidateMap32DefinitionCount(tiles32_unique_.size(), storage_layout));
 
  if (core::FeatureFlags::get().kLogToConsole) {
    std::cout << "Number of unique Tiles32: " << tiles32_unique_.size()
              << " Saved:" << tiles32_unique_.size()
              << " Out of: " << storage_layout.definition_capacity << std::endl;
  }
 
  return absl::OkStatus();
}
 
absl::Status Overworld::SaveMap32Expanded() {
  RETURN_IF_ERROR(ValidatePrivateNativeTerrainSave());
  if (rom_ && rom_->has_lyra_private_reservation())
    return absl::OkStatus();
  if (MapTilesUnchanged()) {
    util::logf("Overworld tiles unchanged; preserving expanded tile32");
    return absl::OkStatus();
  }
  ASSIGN_OR_RETURN(const auto storage_layout,
                   ResolveMap32StorageLayout(*rom(), version_constants()));
  if (!storage_layout.expanded) {
    return absl::FailedPreconditionError(
        "Expanded Tile32 save requested for a vanilla Tile32 layout");
  }
  // Capacity and alignment must be checked before updating relocation pointers
  // or writing any quadrant bytes.
  RETURN_IF_ERROR(
      ValidateMap32DefinitionCount(tiles32_unique_.size(), storage_layout));
 
  const int bottomLeft = GetMap32TileBLExpanded();
  const int bottomRight = GetMap32TileBRExpanded();
  const int topRight = GetMap32TileTRExpanded();
 
  // Point the bank $02 tile32 loaders at the expanded quadrants. An operand
  // that already addresses its target is left alone: ZScream and Oracle of
  // Secrets write the FastROM mirror ($84:8000), and rewriting it as the
  // equivalent $04:8000 would change ASM-owned code bytes for no effect.
  const auto relocate = [this](int operand_pc, int target_pc) -> absl::Status {
    ASSIGN_OR_RETURN(const uint32_t current, rom()->ReadLong(operand_pc));
    if (SnesToPc(current) == static_cast<uint32_t>(target_pc)) {
      return absl::OkStatus();
    }
    return rom()->WriteLong(operand_pc, PcToSnes(target_pc));
  };
  constexpr int kTopRightOperands[] = {0x0176EC, 0x0176F3, 0x0176FA,
                                       0x017701, 0x017708, 0x01771A};
  constexpr int kBottomLeftOperands[] = {0x01772C, 0x017733, 0x01773A,
                                         0x017741, 0x017748, 0x01775A};
  constexpr int kBottomRightOperands[] = {0x01776C, 0x017773, 0x01777A,
                                          0x017781, 0x017788, 0x01779A};
  for (int i = 0; i < 6; ++i) {
    RETURN_IF_ERROR(relocate(kTopRightOperands[i], topRight + i));
    RETURN_IF_ERROR(relocate(kBottomLeftOperands[i], bottomLeft + i));
    RETURN_IF_ERROR(relocate(kBottomRightOperands[i], bottomRight + i));
  }
 
  int unique_tile_index = 0;
  const int encoded_bytes = static_cast<int>(tiles32_unique_.size() /
                                             kMap32DefinitionsPerPackedGroup) *
                            kMap32BytesPerPackedGroup;
 
  for (int i = 0; i < encoded_bytes; i += kMap32BytesPerPackedGroup) {
    // Top Left.
    auto top_left = version_constants().kMap32TileTL;
    RETURN_IF_ERROR(rom()->WriteByte(
        top_left + i,
        (uint8_t)(tiles32_unique_[unique_tile_index].tile0_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        top_left + (i + 1),
        (uint8_t)(tiles32_unique_[unique_tile_index + 1].tile0_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        top_left + (i + 2),
        (uint8_t)(tiles32_unique_[unique_tile_index + 2].tile0_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        top_left + (i + 3),
        (uint8_t)(tiles32_unique_[unique_tile_index + 3].tile0_ & 0xFF)));
 
    RETURN_IF_ERROR(rom()->WriteByte(
        top_left + (i + 4),
        (uint8_t)(((tiles32_unique_[unique_tile_index].tile0_ >> 4) & 0xF0) +
                  ((tiles32_unique_[unique_tile_index + 1].tile0_ >> 8) &
                   0x0F))));
    RETURN_IF_ERROR(rom()->WriteByte(
        top_left + (i + 5),
        (uint8_t)(((tiles32_unique_[unique_tile_index + 2].tile0_ >> 4) &
                   0xF0) +
                  ((tiles32_unique_[unique_tile_index + 3].tile0_ >> 8) &
                   0x0F))));
 
    // Top Right.
    auto top_right = topRight;
    RETURN_IF_ERROR(rom()->WriteByte(
        top_right + i,
        (uint8_t)(tiles32_unique_[unique_tile_index].tile1_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        top_right + (i + 1),
        (uint8_t)(tiles32_unique_[unique_tile_index + 1].tile1_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        top_right + (i + 2),
        (uint8_t)(tiles32_unique_[unique_tile_index + 2].tile1_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        top_right + (i + 3),
        (uint8_t)(tiles32_unique_[unique_tile_index + 3].tile1_ & 0xFF)));
 
    RETURN_IF_ERROR(rom()->WriteByte(
        top_right + (i + 4),
        (uint8_t)(((tiles32_unique_[unique_tile_index].tile1_ >> 4) & 0xF0) |
                  ((tiles32_unique_[unique_tile_index + 1].tile1_ >> 8) &
                   0x0F))));
    RETURN_IF_ERROR(rom()->WriteByte(
        top_right + (i + 5),
        (uint8_t)(((tiles32_unique_[unique_tile_index + 2].tile1_ >> 4) &
                   0xF0) |
                  ((tiles32_unique_[unique_tile_index + 3].tile1_ >> 8) &
                   0x0F))));
 
    // Bottom Left.
    auto bottom_left = bottomLeft;
    RETURN_IF_ERROR(rom()->WriteByte(
        bottom_left + i,
        (uint8_t)(tiles32_unique_[unique_tile_index].tile2_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        bottom_left + (i + 1),
        (uint8_t)(tiles32_unique_[unique_tile_index + 1].tile2_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        bottom_left + (i + 2),
        (uint8_t)(tiles32_unique_[unique_tile_index + 2].tile2_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        bottom_left + (i + 3),
        (uint8_t)(tiles32_unique_[unique_tile_index + 3].tile2_ & 0xFF)));
 
    RETURN_IF_ERROR(rom()->WriteByte(
        bottom_left + (i + 4),
        (uint8_t)(((tiles32_unique_[unique_tile_index].tile2_ >> 4) & 0xF0) |
                  ((tiles32_unique_[unique_tile_index + 1].tile2_ >> 8) &
                   0x0F))));
    RETURN_IF_ERROR(rom()->WriteByte(
        bottom_left + (i + 5),
        (uint8_t)(((tiles32_unique_[unique_tile_index + 2].tile2_ >> 4) &
                   0xF0) |
                  ((tiles32_unique_[unique_tile_index + 3].tile2_ >> 8) &
                   0x0F))));
 
    // Bottom Right.
    auto bottom_right = bottomRight;
    RETURN_IF_ERROR(rom()->WriteByte(
        bottom_right + i,
        (uint8_t)(tiles32_unique_[unique_tile_index].tile3_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        bottom_right + (i + 1),
        (uint8_t)(tiles32_unique_[unique_tile_index + 1].tile3_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        bottom_right + (i + 2),
        (uint8_t)(tiles32_unique_[unique_tile_index + 2].tile3_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        bottom_right + (i + 3),
        (uint8_t)(tiles32_unique_[unique_tile_index + 3].tile3_ & 0xFF)));
 
    RETURN_IF_ERROR(rom()->WriteByte(
        bottom_right + (i + 4),
        (uint8_t)(((tiles32_unique_[unique_tile_index].tile3_ >> 4) & 0xF0) |
                  ((tiles32_unique_[unique_tile_index + 1].tile3_ >> 8) &
                   0x0F))));
    RETURN_IF_ERROR(rom()->WriteByte(
        bottom_right + (i + 5),
        (uint8_t)(((tiles32_unique_[unique_tile_index + 2].tile3_ >> 4) &
                   0xF0) |
                  ((tiles32_unique_[unique_tile_index + 3].tile3_ >> 8) &
                   0x0F))));
 
    unique_tile_index += 4;
  }
 
  return absl::OkStatus();
}
 
absl::Status Overworld::SaveMap32Tiles() {
  RETURN_IF_ERROR(ValidatePrivateNativeTerrainSave());
  if (rom_ && rom_->has_lyra_private_reservation())
    return absl::OkStatus();
  if (MapTilesUnchanged()) {
    util::logf("Overworld tiles unchanged; preserving tile32 definitions");
    return absl::OkStatus();
  }
  util::logf("Saving Map32 Tiles");
  ASSIGN_OR_RETURN(const auto storage_layout,
                   ResolveMap32StorageLayout(*rom(), version_constants()));
  if (storage_layout.expanded) {
    return absl::FailedPreconditionError(
        "Vanilla Tile32 save requested for an expanded Tile32 layout");
  }
  RETURN_IF_ERROR(
      ValidateMap32DefinitionCount(tiles32_unique_.size(), storage_layout));
 
  int unique_tile_index = 0;
  const int encoded_bytes = static_cast<int>(tiles32_unique_.size() /
                                             kMap32DefinitionsPerPackedGroup) *
                            kMap32BytesPerPackedGroup;
 
  for (int i = 0; i < encoded_bytes; i += kMap32BytesPerPackedGroup) {
    // Top Left.
    auto top_left = version_constants().kMap32TileTL;
 
    RETURN_IF_ERROR(rom()->WriteByte(
        top_left + i,
        (uint8_t)(tiles32_unique_[unique_tile_index].tile0_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        top_left + (i + 1),
        (uint8_t)(tiles32_unique_[unique_tile_index + 1].tile0_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        top_left + (i + 2),
        (uint8_t)(tiles32_unique_[unique_tile_index + 2].tile0_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        top_left + (i + 3),
        (uint8_t)(tiles32_unique_[unique_tile_index + 3].tile0_ & 0xFF)));
 
    RETURN_IF_ERROR(rom()->WriteByte(
        top_left + (i + 4),
        (uint8_t)(((tiles32_unique_[unique_tile_index].tile0_ >> 4) & 0xF0) +
                  ((tiles32_unique_[unique_tile_index + 1].tile0_ >> 8) &
                   0x0F))));
    RETURN_IF_ERROR(rom()->WriteByte(
        top_left + (i + 5),
        (uint8_t)(((tiles32_unique_[unique_tile_index + 2].tile0_ >> 4) &
                   0xF0) +
                  ((tiles32_unique_[unique_tile_index + 3].tile0_ >> 8) &
                   0x0F))));
 
    // Top Right.
    auto top_right = version_constants().kMap32TileTR;
    RETURN_IF_ERROR(rom()->WriteByte(
        top_right + i,
        (uint8_t)(tiles32_unique_[unique_tile_index].tile1_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        top_right + (i + 1),
        (uint8_t)(tiles32_unique_[unique_tile_index + 1].tile1_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        top_right + (i + 2),
        (uint8_t)(tiles32_unique_[unique_tile_index + 2].tile1_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        top_right + (i + 3),
        (uint8_t)(tiles32_unique_[unique_tile_index + 3].tile1_ & 0xFF)));
 
    RETURN_IF_ERROR(rom()->WriteByte(
        top_right + (i + 4),
        (uint8_t)(((tiles32_unique_[unique_tile_index].tile1_ >> 4) & 0xF0) |
                  ((tiles32_unique_[unique_tile_index + 1].tile1_ >> 8) &
                   0x0F))));
    RETURN_IF_ERROR(rom()->WriteByte(
        top_right + (i + 5),
        (uint8_t)(((tiles32_unique_[unique_tile_index + 2].tile1_ >> 4) &
                   0xF0) |
                  ((tiles32_unique_[unique_tile_index + 3].tile1_ >> 8) &
                   0x0F))));
 
    // Bottom Left.
    const auto map32TilesBL = version_constants().kMap32TileBL;
    RETURN_IF_ERROR(rom()->WriteByte(
        map32TilesBL + i,
        (uint8_t)(tiles32_unique_[unique_tile_index].tile2_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        map32TilesBL + (i + 1),
        (uint8_t)(tiles32_unique_[unique_tile_index + 1].tile2_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        map32TilesBL + (i + 2),
        (uint8_t)(tiles32_unique_[unique_tile_index + 2].tile2_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        map32TilesBL + (i + 3),
        (uint8_t)(tiles32_unique_[unique_tile_index + 3].tile2_ & 0xFF)));
 
    RETURN_IF_ERROR(rom()->WriteByte(
        map32TilesBL + (i + 4),
        (uint8_t)(((tiles32_unique_[unique_tile_index].tile2_ >> 4) & 0xF0) |
                  ((tiles32_unique_[unique_tile_index + 1].tile2_ >> 8) &
                   0x0F))));
    RETURN_IF_ERROR(rom()->WriteByte(
        map32TilesBL + (i + 5),
        (uint8_t)(((tiles32_unique_[unique_tile_index + 2].tile2_ >> 4) &
                   0xF0) |
                  ((tiles32_unique_[unique_tile_index + 3].tile2_ >> 8) &
                   0x0F))));
 
    // Bottom Right.
    const auto map32TilesBR = version_constants().kMap32TileBR;
    RETURN_IF_ERROR(rom()->WriteByte(
        map32TilesBR + i,
        (uint8_t)(tiles32_unique_[unique_tile_index].tile3_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        map32TilesBR + (i + 1),
        (uint8_t)(tiles32_unique_[unique_tile_index + 1].tile3_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        map32TilesBR + (i + 2),
        (uint8_t)(tiles32_unique_[unique_tile_index + 2].tile3_ & 0xFF)));
    RETURN_IF_ERROR(rom()->WriteByte(
        map32TilesBR + (i + 3),
        (uint8_t)(tiles32_unique_[unique_tile_index + 3].tile3_ & 0xFF)));
 
    RETURN_IF_ERROR(rom()->WriteByte(
        map32TilesBR + (i + 4),
        (uint8_t)(((tiles32_unique_[unique_tile_index].tile3_ >> 4) & 0xF0) |
                  ((tiles32_unique_[unique_tile_index + 1].tile3_ >> 8) &
                   0x0F))));
    RETURN_IF_ERROR(rom()->WriteByte(
        map32TilesBR + (i + 5),
        (uint8_t)(((tiles32_unique_[unique_tile_index + 2].tile3_ >> 4) &
                   0xF0) |
                  ((tiles32_unique_[unique_tile_index + 3].tile3_ >> 8) &
                   0x0F))));
 
    unique_tile_index += 4;
  }
 
  return absl::OkStatus();
}
 
absl::Status Overworld::SaveMap16Expanded() {
  RETURN_IF_ERROR(ValidatePrivateNativeTerrainSave());
  if (rom_ && rom_->has_lyra_private_reservation())
    return absl::OkStatus();
  const int map16_expanded = GetMap16TilesExpanded();
  const auto write_pointer = [this](int address,
                                    uint32_t target) -> absl::Status {
    ASSIGN_OR_RETURN(auto current, rom()->ReadLong(address));
    // FastROM and low-bank aliases address the same data. Retain the original
    // instruction operand when no relocation is needed.
    if (SnesToPc(current) == SnesToPc(target)) {
      return absl::OkStatus();
    }
    return rom()->WriteLong(address, target);
  };
  const auto write_bank = [this](int address, uint8_t bank) -> absl::Status {
    ASSIGN_OR_RETURN(auto current, rom()->ReadByte(address));
    if ((current & 0x7F) == (bank & 0x7F)) {
      return absl::OkStatus();
    }
    return rom()->WriteByte(address, bank);
  };
  RETURN_IF_ERROR(write_pointer(SnesToPc(0x008865), PcToSnes(map16_expanded)));
  RETURN_IF_ERROR(write_pointer(SnesToPc(0x0EDE4F), PcToSnes(map16_expanded)));
  RETURN_IF_ERROR(write_pointer(SnesToPc(0x0EDEE9), PcToSnes(map16_expanded)));
 
  RETURN_IF_ERROR(
      write_pointer(SnesToPc(0x1BBC2D), PcToSnes(map16_expanded + 2)));
  RETURN_IF_ERROR(write_pointer(SnesToPc(0x1BBC4C), PcToSnes(map16_expanded)));
  RETURN_IF_ERROR(
      write_pointer(SnesToPc(0x1BBCC2), PcToSnes(map16_expanded + 4)));
  RETURN_IF_ERROR(
      write_pointer(SnesToPc(0x1BBCCB), PcToSnes(map16_expanded + 6)));
 
  RETURN_IF_ERROR(write_pointer(SnesToPc(0x1BBEF6), PcToSnes(map16_expanded)));
  RETURN_IF_ERROR(write_pointer(SnesToPc(0x1BBF23), PcToSnes(map16_expanded)));
  RETURN_IF_ERROR(write_pointer(SnesToPc(0x1BC041), PcToSnes(map16_expanded)));
  RETURN_IF_ERROR(write_pointer(SnesToPc(0x1BC9B3), PcToSnes(map16_expanded)));
 
  RETURN_IF_ERROR(
      write_pointer(SnesToPc(0x1BC9BA), PcToSnes(map16_expanded + 2)));
  RETURN_IF_ERROR(
      write_pointer(SnesToPc(0x1BC9C1), PcToSnes(map16_expanded + 4)));
  RETURN_IF_ERROR(
      write_pointer(SnesToPc(0x1BC9C8), PcToSnes(map16_expanded + 6)));
 
  RETURN_IF_ERROR(write_pointer(SnesToPc(0x1BCA40), PcToSnes(map16_expanded)));
  RETURN_IF_ERROR(
      write_pointer(SnesToPc(0x1BCA47), PcToSnes(map16_expanded + 2)));
  RETURN_IF_ERROR(
      write_pointer(SnesToPc(0x1BCA4E), PcToSnes(map16_expanded + 4)));
  RETURN_IF_ERROR(
      write_pointer(SnesToPc(0x1BCA55), PcToSnes(map16_expanded + 6)));
 
  RETURN_IF_ERROR(write_pointer(SnesToPc(0x02F457), PcToSnes(map16_expanded)));
  RETURN_IF_ERROR(
      write_pointer(SnesToPc(0x02F45E), PcToSnes(map16_expanded + 2)));
  RETURN_IF_ERROR(
      write_pointer(SnesToPc(0x02F467), PcToSnes(map16_expanded + 4)));
  RETURN_IF_ERROR(
      write_pointer(SnesToPc(0x02F46E), PcToSnes(map16_expanded + 6)));
  RETURN_IF_ERROR(write_pointer(SnesToPc(0x02F51F), PcToSnes(map16_expanded)));
  RETURN_IF_ERROR(
      write_pointer(SnesToPc(0x02F526), PcToSnes(map16_expanded + 4)));
  RETURN_IF_ERROR(
      write_pointer(SnesToPc(0x02F52F), PcToSnes(map16_expanded + 2)));
  RETURN_IF_ERROR(
      write_pointer(SnesToPc(0x02F536), PcToSnes(map16_expanded + 6)));
 
  RETURN_IF_ERROR(
      rom()->WriteShort(SnesToPc(0x02FE1C), PcToSnes(map16_expanded)));
  RETURN_IF_ERROR(
      rom()->WriteShort(SnesToPc(0x02FE23), PcToSnes(map16_expanded + 4)));
  RETURN_IF_ERROR(
      rom()->WriteShort(SnesToPc(0x02FE2C), PcToSnes(map16_expanded + 2)));
  RETURN_IF_ERROR(
      rom()->WriteShort(SnesToPc(0x02FE33), PcToSnes(map16_expanded + 6)));
 
  RETURN_IF_ERROR(
      write_bank(SnesToPc(0x02FD28),
                 static_cast<uint8_t>(PcToSnes(map16_expanded) >> 16)));
  RETURN_IF_ERROR(
      write_bank(SnesToPc(0x02FD39),
                 static_cast<uint8_t>(PcToSnes(map16_expanded) >> 16)));
 
  int tpos = map16_expanded;
  for (int i = 0; i < NumberOfMap16Ex; i += 1)  // 4096
  {
    RETURN_IF_ERROR(
        rom()->WriteShort(tpos, TileInfoToShort(tiles16_[i].tile0_)));
    tpos += 2;
    RETURN_IF_ERROR(
        rom()->WriteShort(tpos, TileInfoToShort(tiles16_[i].tile1_)));
    tpos += 2;
    RETURN_IF_ERROR(
        rom()->WriteShort(tpos, TileInfoToShort(tiles16_[i].tile2_)));
    tpos += 2;
    RETURN_IF_ERROR(
        rom()->WriteShort(tpos, TileInfoToShort(tiles16_[i].tile3_)));
    tpos += 2;
  }
 
  return absl::OkStatus();
}
 
absl::Status Overworld::SaveMap16Tiles() {
  RETURN_IF_ERROR(ValidatePrivateNativeTerrainSave());
  if (rom_ && rom_->has_lyra_private_reservation())
    return absl::OkStatus();
  util::logf("Saving Map16 Tiles");
  int tpos = kMap16Tiles;
  // 3760
  for (int i = 0; i < NumberOfMap16; i += 1) {
    RETURN_IF_ERROR(
        rom()->WriteShort(tpos, TileInfoToShort(tiles16_[i].tile0_)))
    tpos += 2;
    RETURN_IF_ERROR(
        rom()->WriteShort(tpos, TileInfoToShort(tiles16_[i].tile1_)))
    tpos += 2;
    RETURN_IF_ERROR(
        rom()->WriteShort(tpos, TileInfoToShort(tiles16_[i].tile2_)))
    tpos += 2;
    RETURN_IF_ERROR(
        rom()->WriteShort(tpos, TileInfoToShort(tiles16_[i].tile3_)))
    tpos += 2;
  }
  return absl::OkStatus();
}
 
absl::Status Overworld::SaveEntrances() {
  if (!rom_) {
    return absl::InvalidArgumentError("Cannot save entrances without a ROM");
  }
  const bool expanded = DetectOverworldRomProfile(*rom_).has_expanded_entrances;
  if (expanded) {
    if (all_holes_.size() != kNumOverworldHoles) {
      return absl::FailedPreconditionError(
          "Legacy hole source rows are missing");
    }
    for (size_t i = 0; i < all_holes_.size(); ++i) {
      if (!all_holes_[i].HasUnchangedHoleSourceState(i)) {
        return absl::FailedPreconditionError(
            "Legacy holes were edited; use the expanded entrance table rows");
      }
    }
  }
  RETURN_IF_ERROR(
      ::yaze::zelda3::SaveEntrances(rom_, all_entrances_, expanded));
  if (!expanded) {
    RETURN_IF_ERROR(SaveHoles(rom_, all_holes_));
  }
  return absl::OkStatus();
}
 
absl::Status Overworld::SaveExits() {
  RETURN_IF_ERROR(::yaze::zelda3::SaveExits(rom_, all_exits_));
  return absl::OkStatus();
}
 
absl::Status Overworld::SaveItems() {
  // A no-op item save must retain the existing allocation and pointer aliases.
  // Compare serialized fields (including duplicates and map identity). Record
  // order within each map controls the first matching secret, while
  // interleaving records from different maps has no effect. Read from current
  // ROM bytes so this also supports edits and Undo after an earlier successful
  // save.
  ASSIGN_OR_RETURN(auto stored_items, LoadItems(rom_, overworld_maps_));
  const auto serialized_items = [](const std::vector<OverworldItem>& items) {
    std::vector<std::array<int, 4>> records;
    for (const auto& item : items) {
      if (!item.deleted) {
        records.push_back(
            {item.room_map_id_, item.game_x_, item.game_y_, item.id_});
      }
    }
    std::stable_sort(records.begin(), records.end(),
                     [](const auto& a, const auto& b) { return a[0] < b[0]; });
    return records;
  };
  if (serialized_items(stored_items) == serialized_items(all_items_)) {
    return absl::OkStatus();
  }
  RETURN_IF_ERROR(::yaze::zelda3::SaveItems(rom_, all_items_));
 
  // Compact the in-memory vector: physically remove items flagged as deleted
  // so they don't accumulate across save cycles or leak through the API.
  all_items_.erase(
      std::remove_if(all_items_.begin(), all_items_.end(),
                     [](const OverworldItem& item) { return item.deleted; }),
      all_items_.end());
 
  return absl::OkStatus();
}
 
absl::Status Overworld::SaveMapOverlays() {
  if (rom_ && rom_->has_lyra_private_reservation()) {
    // This private transfer does not admit the legacy renderer generator.
    // Preserve a loaded no-op and reject edits rather than installing code.
    RETURN_IF_ERROR(ValidatePrivateNativeTerrainSave());
    return absl::OkStatus();
  }
 
  util::logf("Saving Map Overlays");
 
  // Generate the new overlay code that handles interactive overlays
  std::vector<uint8_t> new_overlay_code = {
      0xC2, 0x30,              // REP #$30
      0xA5, 0x8A,              // LDA $8A
      0x0A, 0x18,              // ASL : CLC
      0x65, 0x8A,              // ADC $8A
      0xAA,                    // TAX
      0xBF, 0x00, 0x00, 0x00,  // LDA, X
      0x85, 0x00,              // STA $00
      0xBF, 0x00, 0x00, 0x00,  // LDA, X +2
      0x85, 0x02,              // STA $02
      0x4B,                    // PHK
      0xF4, 0x00, 0x00,        // This position +3 ?
      0xDC, 0x00, 0x00,        // JML [$00 00]
      0xE2, 0x30,              // SEP #$30
      0xAB,                    // PLB
      0x6B,                    // RTL
  };
 
  // Write overlay code to ROM
  constexpr int kOverlayCodeStart = 0x077657;
  RETURN_IF_ERROR(rom()->WriteVector(kOverlayCodeStart, new_overlay_code));
 
  // Set up overlay pointers
  int ptr_start = kOverlayCodeStart + 0x20;
  int snes_ptr_start = PcToSnes(ptr_start);
 
  // Write overlay pointer addresses in the code
  RETURN_IF_ERROR(rom()->WriteLong(kOverlayCodeStart + 10, snes_ptr_start));
  RETURN_IF_ERROR(rom()->WriteLong(kOverlayCodeStart + 16, snes_ptr_start + 2));
 
  int pea_addr = PcToSnes(kOverlayCodeStart + 27);
  RETURN_IF_ERROR(rom()->WriteShort(kOverlayCodeStart + 23, pea_addr));
 
  // Write overlay data to expanded space
  constexpr int kExpandedOverlaySpace = 0x120000;
  int pos = kExpandedOverlaySpace;
  int ptr_pos = kOverlayCodeStart + 32;
 
  for (int i = 0; i < kNumOverworldMaps; i++) {
    int snes_addr = PcToSnes(pos);
    RETURN_IF_ERROR(rom()->WriteLong(ptr_pos, snes_addr & 0xFFFFFF));
    ptr_pos += 3;
 
    // Write overlay data for each map that has overlays
    if (overworld_maps_[i].has_overlay()) {
      const auto& overlay_data = overworld_maps_[i].overlay_data();
      for (size_t t = 0; t < overlay_data.size(); t += 3) {
        if (t + 2 < overlay_data.size()) {
          // Generate LDA/STA sequence for each overlay tile
          RETURN_IF_ERROR(rom()->WriteByte(pos, 0xA9));  // LDA #$
          RETURN_IF_ERROR(rom()->WriteShort(
              pos + 1, overlay_data[t] | (overlay_data[t + 1] << 8)));
          pos += 3;
 
          RETURN_IF_ERROR(rom()->WriteByte(pos, 0x8D));  // STA $xxxx
          RETURN_IF_ERROR(rom()->WriteShort(pos + 1, overlay_data[t + 2]));
          pos += 3;
        }
      }
    }
 
    RETURN_IF_ERROR(rom()->WriteByte(pos, 0x6B));  // RTL
    pos++;
  }
 
  return absl::OkStatus();
}
 
absl::Status Overworld::SaveOverworldTilesType() {
  if (!rom_) {
    return absl::FailedPreconditionError("No ROM for collision save");
  }
  const auto layout = zscream::DetectLayout(*rom_);
  if (layout == zscream::LayoutDialect::kZScreamV5 ||
      layout == zscream::LayoutDialect::kUnknown) {
    return absl::FailedPreconditionError(
        "Legacy collision save is disabled for per-sheet or unknown ZScream "
        "layouts");
  }
  if (static_cast<size_t>(overworldTilesType) > rom_->vector().size() ||
      rom_->vector().size() - static_cast<size_t>(overworldTilesType) <
          all_tiles_types_.size()) {
    return absl::OutOfRangeError("Incomplete legacy collision save range");
  }
  util::logf("Saving Overworld Tiles Types");
 
  for (int i = 0; i < kNumTileTypes; i++) {
    RETURN_IF_ERROR(
        rom()->WriteByte(overworldTilesType + i, all_tiles_types_[i]));
  }
 
  return absl::OkStatus();
}
 
absl::Status Overworld::LoadDiggableTiles() {
  // Diggable tiles have no ROM storage yet. The addresses in
  // diggable_tiles.h are ZSCustomOverworld v3 data: 0x140149 sits in its
  // settings block, and 0x140980-0x1409BF is OverworldCustomDefaultGFXGroups
  // followed by the expanded parent table (kOverworldMapParentIdExpanded).
  // Reading them as a diggable bitfield yields garbage, so the table always
  // starts from the vanilla list.
  diggable_tiles_.SetVanillaDefaults();
  return absl::OkStatus();
}
 
absl::Status Overworld::SaveDiggableTiles() {
  // Later steps of Save() read cached_version_.
  cached_version_ = OverworldVersionHelper::GetVersion(*rom_);
  // Writing the diggable table would overwrite the ZSCustomOverworld v3
  // tables described in LoadDiggableTiles(), corrupting default GFX groups
  // and the bridge color on hacks such as Oracle of Secrets. Diggable edits
  // ship through the exported ASM patch until a non-colliding table exists.
  return absl::OkStatus();
}
 
absl::Status Overworld::AutoDetectDiggableTiles() {
  util::logf("Auto-detecting Diggable Tiles");
 
  diggable_tiles_.Clear();
 
  // Iterate through all Map16 tiles and check if they're diggable
  for (uint16_t tile_id = 0; tile_id < static_cast<uint16_t>(tiles16_.size()) &&
                             tile_id < kMaxDiggableTileId;
       ++tile_id) {
    if (DiggableTiles::IsTile16Diggable(tiles16_[tile_id], all_tiles_types_)) {
      diggable_tiles_.SetDiggable(tile_id, true);
    }
  }
 
  util::logf("Auto-detected %d diggable tiles",
             diggable_tiles_.GetDiggableCount());
  return absl::OkStatus();
}
 
absl::Status Overworld::SaveCustomOverworldASM(bool enable_bg_color,
                                               bool enable_main_palette,
                                               bool enable_mosaic,
                                               bool enable_gfx_groups,
                                               bool enable_subscreen_overlay,
                                               bool enable_animated) {
  // Check ROM version - this function requires at least v2 for basic features
  if (cached_version_ == OverworldVersion::kVanilla ||
      cached_version_ == OverworldVersion::kZSCustomV1) {
    return absl::OkStatus();  // Cannot apply custom ASM settings to vanilla/v1
  }
 
  util::logf("Applying Custom Overworld ASM");
 
  const auto write_enable_flag = [this](int address,
                                        bool enabled) -> absl::Status {
    ASSIGN_OR_RETURN(const uint8_t current, rom()->ReadByte(address));
    if ((current != 0x00) == enabled) {
      return absl::OkStatus();
    }
    return rom()->WriteByte(address, enabled ? 0xFF : 0x00);
  };
 
  // v2+ features: BG color, main palette enable flags
  if (OverworldVersionHelper::SupportsCustomBGColors(cached_version_)) {
    RETURN_IF_ERROR(write_enable_flag(OverworldCustomAreaSpecificBGEnabled,
                                      enable_bg_color));
    RETURN_IF_ERROR(write_enable_flag(OverworldCustomMainPaletteEnabled,
                                      enable_main_palette));
 
    // Write the main palette table
    if (enable_main_palette) {
      for (int i = 0; i < kNumOverworldMaps; i++) {
        RETURN_IF_ERROR(rom()->WriteByte(OverworldCustomMainPaletteArray + i,
                                         overworld_maps_[i].main_palette()));
      }
    }
  }
 
  // v3+ features: mosaic, gfx groups, animated, overlays
  if (OverworldVersionHelper::SupportsAreaEnum(cached_version_)) {
    RETURN_IF_ERROR(
        write_enable_flag(OverworldCustomMosaicEnabled, enable_mosaic));
    RETURN_IF_ERROR(write_enable_flag(OverworldCustomTileGFXGroupEnabled,
                                      enable_gfx_groups));
    RETURN_IF_ERROR(
        write_enable_flag(OverworldCustomAnimatedGFXEnabled, enable_animated));
    RETURN_IF_ERROR(write_enable_flag(OverworldCustomSubscreenOverlayEnabled,
                                      enable_subscreen_overlay));
 
    // Write the mosaic table
    if (enable_mosaic) {
      for (int i = 0; i < kNumOverworldMaps; i++) {
        const auto& mosaic = overworld_maps_[i].mosaic_expanded();
        // .... udlr bit format
        uint8_t mosaic_byte = (mosaic[0] ? 0x08 : 0x00) |  // up
                              (mosaic[1] ? 0x04 : 0x00) |  // down
                              (mosaic[2] ? 0x02 : 0x00) |  // left
                              (mosaic[3] ? 0x01 : 0x00);   // right
 
        RETURN_IF_ERROR(
            rom()->WriteByte(OverworldCustomMosaicArray + i, mosaic_byte));
      }
    }
 
    if (enable_gfx_groups) {
      for (int i = 0; i < kNumOverworldMaps; i++) {
        for (int j = 0; j < 8; j++) {
          RETURN_IF_ERROR(
              rom()->WriteByte(OverworldCustomTileGFXGroupArray + (i * 8) + j,
                               overworld_maps_[i].custom_tileset(j)));
        }
      }
    }
    if (enable_animated) {
      for (int i = 0; i < kNumOverworldMaps; i++) {
        RETURN_IF_ERROR(rom()->WriteByte(OverworldCustomAnimatedGFXArray + i,
                                         overworld_maps_[i].animated_gfx()));
      }
    }
 
    // Write the subscreen overlay table
    if (enable_subscreen_overlay) {
      for (int i = 0; i < kNumOverworldMaps; i++) {
        RETURN_IF_ERROR(
            rom()->WriteShort(OverworldCustomSubscreenOverlayArray + (i * 2),
                              overworld_maps_[i].subscreen_overlay()));
      }
    }
  }
 
  return absl::OkStatus();
}
 
absl::Status Overworld::SaveAreaSpecificBGColors() {
  // Only write to custom address space for v2+ ROMs
  if (!OverworldVersionHelper::SupportsCustomBGColors(cached_version_)) {
    return absl::OkStatus();  // Vanilla/v1 ROM - skip custom address writes
  }
 
  util::logf("Saving Area Specific Background Colors");
 
  // Write area-specific background colors if enabled
  for (int i = 0; i < kNumOverworldMaps; i++) {
    uint16_t bg_color = overworld_maps_[i].area_specific_bg_color();
    RETURN_IF_ERROR(rom()->WriteShort(
        OverworldCustomAreaSpecificBGPalette + (i * 2), bg_color));
  }
 
  return absl::OkStatus();
}
 
absl::Status Overworld::SaveCustomOverworldData() {
  if (!rom_ || !rom_->is_loaded()) {
    return absl::FailedPreconditionError("ROM not loaded");
  }
 
  cached_version_ = OverworldVersionHelper::GetVersion(*rom_);
  if (cached_version_ == OverworldVersion::kVanilla ||
      cached_version_ == OverworldVersion::kZSCustomV1) {
    return absl::OkStatus();
  }
 
  const auto enabled = [this](int address) {
    return ReadRomByteOr(*rom_, address, 0x00) != 0x00;
  };
  const bool bg_color_enabled = enabled(OverworldCustomAreaSpecificBGEnabled);
  const bool main_palette_enabled = enabled(OverworldCustomMainPaletteEnabled);
  const bool mosaic_enabled = enabled(OverworldCustomMosaicEnabled);
  const bool gfx_groups_enabled = enabled(OverworldCustomTileGFXGroupEnabled);
  const bool subscreen_overlay_enabled =
      enabled(OverworldCustomSubscreenOverlayEnabled);
  const bool animated_enabled = enabled(OverworldCustomAnimatedGFXEnabled);
  RETURN_IF_ERROR(SaveCustomOverworldASM(
      bg_color_enabled, main_palette_enabled, mosaic_enabled,
      gfx_groups_enabled, subscreen_overlay_enabled, animated_enabled));
  if (bg_color_enabled) {
    RETURN_IF_ERROR(SaveAreaSpecificBGColors());
  }
  RETURN_IF_ERROR(SaveAreaSizes());
  return absl::OkStatus();
}
 
absl::Status Overworld::SaveMapProperties() {
  util::logf("Saving Map Properties");
  const auto version = OverworldVersionHelper::GetVersion(*rom_);
  const bool use_zscustom_palette_table =
      OverworldVersionHelper::SupportsCustomBGColors(version);
  const bool use_zscustom_special_tables =
      OverworldVersionHelper::SupportsAreaEnum(version);
  const int palette_table = use_zscustom_palette_table
                                ? kOverworldPalettesScreenToSetNew
                                : kOverworldMapPaletteIds;
 
  for (int i = 0; i < kDarkWorldMapIdStart; i++) {
    RETURN_IF_ERROR(rom()->WriteByte(
        kAreaGfxIdPtr + i, overworld_maps_[i].area_graphics_for_save()));
    RETURN_IF_ERROR(rom()->WriteByte(
        palette_table + i, overworld_maps_[i].area_palette_for_save()));
    RETURN_IF_ERROR(
        rom()->WriteByte(kOverworldSpriteset + i,
                         overworld_maps_[i].sprite_graphics_for_save(0)));
    RETURN_IF_ERROR(
        rom()->WriteByte(kOverworldSpriteset + kDarkWorldMapIdStart + i,
                         overworld_maps_[i].sprite_graphics_for_save(1)));
    RETURN_IF_ERROR(
        rom()->WriteByte(kOverworldSpriteset + kSpecialWorldMapIdStart + i,
                         overworld_maps_[i].sprite_graphics_for_save(2)));
    RETURN_IF_ERROR(
        rom()->WriteByte(kOverworldSpritePaletteIds + i,
                         overworld_maps_[i].sprite_palette_for_save(0)));
    RETURN_IF_ERROR(
        rom()->WriteByte(kOverworldSpritePaletteIds + kDarkWorldMapIdStart + i,
                         overworld_maps_[i].sprite_palette_for_save(1)));
    RETURN_IF_ERROR(rom()->WriteByte(
        kOverworldSpritePaletteIds + kSpecialWorldMapIdStart + i,
        overworld_maps_[i].sprite_palette_for_save(2)));
  }
 
  for (int i = kDarkWorldMapIdStart; i < kSpecialWorldMapIdStart; i++) {
    RETURN_IF_ERROR(rom()->WriteByte(
        kAreaGfxIdPtr + i, overworld_maps_[i].area_graphics_for_save()));
    RETURN_IF_ERROR(
        rom()->WriteByte(kOverworldSpriteset + kSpecialWorldMapIdStart + i,
                         overworld_maps_[i].sprite_graphics_for_save(0)));
    RETURN_IF_ERROR(rom()->WriteByte(
        palette_table + i, overworld_maps_[i].area_palette_for_save()));
    RETURN_IF_ERROR(rom()->WriteByte(
        kOverworldSpritePaletteIds + kSpecialWorldMapIdStart + i,
        overworld_maps_[i].sprite_palette_for_save(0)));
  }
 
  for (int i = kSpecialWorldMapIdStart; i < kSpecialWorldMapIdStart + 0x20;
       i++) {
    if (use_zscustom_special_tables) {
      RETURN_IF_ERROR(rom()->WriteByte(
          kAreaGfxIdPtr + i, overworld_maps_[i].area_graphics_for_save()));
    }
    if (use_zscustom_palette_table) {
      RETURN_IF_ERROR(rom()->WriteByte(
          palette_table + i, overworld_maps_[i].area_palette_for_save()));
    }
 
    const int local_index = i - kSpecialWorldMapIdStart;
    const int sprite_gfx_table =
        use_zscustom_special_tables
            ? kOverworldSpecialSpriteGfxGroupExpandedTemp
            : kOverworldSpecialSpriteGFXGroup;
    const int sprite_palette_table =
        use_zscustom_special_tables ? kOverworldSpecialSpritePaletteExpandedTemp
                                    : kOverworldSpecialSpritePalette;
    RETURN_IF_ERROR(
        rom()->WriteByte(sprite_gfx_table + local_index,
                         overworld_maps_[i].sprite_graphics_for_save(0)));
    RETURN_IF_ERROR(
        rom()->WriteByte(sprite_palette_table + local_index,
                         overworld_maps_[i].sprite_palette_for_save(0)));
  }
 
  return absl::OkStatus();
}
 
absl::Status Overworld::SaveMusic() {
  util::logf("Saving Music Data");
 
  // Music is loaded and played by parent screen. A child of a large, wide, or
  // tall area carries its parent's track in memory, so writing that track into
  // the child slot replaces bytes the game does not use as music. Oracle keeps
  // overworld ASM hooks in part of the light-world beginning table.
  const auto owns_slot = [this](int map_index) {
    const int parent = overworld_maps_[map_index].parent();
    // A parent of 0xFF is not a table index. Music for that screen was not
    // loaded from its own slot, so leave the slot untouched.
    return parent == map_index;
  };
 
  for (int i = 0; i < kDarkWorldMapIdStart; i++) {
    if (!owns_slot(i)) {
      continue;
    }
    RETURN_IF_ERROR(rom()->WriteByte(kOverworldMusicBeginning + i,
                                     overworld_maps_[i].area_music(0)));
    RETURN_IF_ERROR(rom()->WriteByte(kOverworldMusicZelda + i,
                                     overworld_maps_[i].area_music(1)));
    RETURN_IF_ERROR(rom()->WriteByte(kOverworldMusicMasterSword + i,
                                     overworld_maps_[i].area_music(2)));
    RETURN_IF_ERROR(rom()->WriteByte(kOverworldMusicAgahnim + i,
                                     overworld_maps_[i].area_music(3)));
  }
 
  for (int i = kDarkWorldMapIdStart; i < kSpecialWorldMapIdStart; i++) {
    if (!owns_slot(i)) {
      continue;
    }
    RETURN_IF_ERROR(
        rom()->WriteByte(kOverworldMusicDarkWorld + (i - kDarkWorldMapIdStart),
                         overworld_maps_[i].area_music(0)));
  }
 
  return absl::OkStatus();
}
 
absl::Status Overworld::SaveAreaSizes() {
  util::logf("Saving V3 Area Sizes");
 
  // Check if this is a v3 ROM
  uint8_t asm_version = (*rom_)[zelda3::OverworldCustomASMHasBeenApplied];
  if (asm_version < 3 || asm_version == 0xFF) {
    return absl::OkStatus();  // Not a v3 ROM, nothing to do
  }
 
  // Save area sizes to the expanded table
  for (int i = 0; i < kNumOverworldMaps; i++) {
    uint8_t area_size_byte =
        static_cast<uint8_t>(overworld_maps_[i].area_size());
    RETURN_IF_ERROR(rom()->WriteByte(kOverworldScreenSize + i, area_size_byte));
  }
 
  // Save message IDs to expanded table
  for (int i = 0; i < kNumOverworldMaps; i++) {
    uint16_t message_id = overworld_maps_[i].message_id();
    RETURN_IF_ERROR(rom()->WriteShort(GetOverworldMessagesExpanded() + (i * 2),
                                      message_id));
  }
 
  return absl::OkStatus();
}
 
}  // namespace yaze::zelda3