overworld_map.cc

Go to the documentation of this file.

#include "overworld_map.h"
 
#include <algorithm>
#include <array>
#include <atomic>
#include <cstddef>
#include <cstdint>
#include <unordered_map>
#include <vector>
 
#include "absl/status/status.h"
#include "absl/status/statusor.h"
#include "app/gfx/types/snes_color.h"
#include "app/gfx/types/snes_palette.h"
#include "app/gfx/types/snes_tile.h"
#include "core/features.h"
#include "rom/rom.h"
#include "util/macro.h"
#include "zelda3/common.h"
#include "zelda3/overworld/overworld.h"
#include "zelda3/overworld/overworld_version_helper.h"
 
namespace yaze::zelda3 {
 
namespace {
 
bool IsDeathMountainArea(int area) {
  return area == 0x03 || area == 0x05 || area == 0x07 || area == 0x43 ||
         area == 0x45 || area == 0x47;
}
 
// Vanilla subscreen overlay per screen (fog, sky, lava, pyramid, curtains).
// Matches the vanilla ZSCustomOverworld OverlayTable and ZScream defaults.
uint16_t VanillaSubscreenOverlay(int index) {
  switch (index) {
    case 0x00:
    case 0x01:
    case 0x08:
    case 0x09:
    case 0x40:
    case 0x41:
    case 0x48:
    case 0x49:
      return 0x009D;  // Fog 2: Lost Woods / Skull Woods
    case 0x03:
    case 0x04:
    case 0x0B:
    case 0x0C:
    case 0x05:
    case 0x06:
    case 0x0D:
    case 0x0E:
    case 0x07:
      return 0x0095;  // Sky background: LW Death Mountain
    case 0x43:
    case 0x44:
    case 0x4B:
    case 0x4C:
    case 0x45:
    case 0x46:
    case 0x4D:
    case 0x4E:
    case 0x47:
      return 0x009C;  // Lava background: DW Death Mountain
    case 0x5B:
    case 0x5C:
    case 0x63:
    case 0x64:
      return 0x0096;  // Pyramid background
    case 0x80:
      return 0x0097;  // Fog 1: Master Sword area
    case 0x88:
      return 0x0093;  // Triforce room curtains
    default:
      return 0x00FF;
  }
}
 
}  // namespace
 
OverworldMap::OverworldMap(int index, Rom* rom, GameData* game_data)
    : OverworldMap(index, rom, game_data, /*seed_area_parent=*/true) {}
 
OverworldMap::OverworldMap(int index, Rom* rom, GameData* game_data,
                           bool seed_area_parent, bool skip_legacy_data)
    : index_(index), parent_(index), rom_(rom), game_data_(game_data) {
  if (skip_legacy_data) {
    return;
  }
  // Load parent ID from ROM data for all versions
  // This is critical for proper large map sibling coordination
  auto version = OverworldVersionHelper::GetVersion(*rom_);
  if (OverworldVersionHelper::SupportsAreaEnum(version)) {
    // For v3+, parent ID is stored in expanded table (0x140998) with 160 entries
    parent_ = (*rom_)[GetOverworldMapParentIdExpanded() + index_];
  } else {
    // For vanilla/v1/v2, parent ID table at 0x125EC only has 64 entries (LW only)
    // DW maps mirror LW parents with +0x40 offset
    // SW maps use hardcoded parent values based on vanilla game behavior
    if (index_ < kDarkWorldMapIdStart) {
      // Light World: direct lookup from 64-entry table
      parent_ = (*rom_)[kOverworldMapParentId + index_];
    } else if (index_ < kSpecialWorldMapIdStart) {
      // Dark World: mirror LW parent structure with +0x40 offset
      // DW map 0x43's parent = LW map 0x03's parent (from table) + 0x40
      uint8_t lw_equivalent = index_ - kDarkWorldMapIdStart;
      uint8_t lw_parent = (*rom_)[kOverworldMapParentId + lw_equivalent];
      parent_ = lw_parent + kDarkWorldMapIdStart;
    } else {
      // Special World: hardcoded parents for vanilla compatibility
      // Zora's Domain (0x81, 0x82, 0x89, 0x8A) is a large area with parent 0x81
      if (index_ == 0x81 || index_ == 0x82 || index_ == 0x89 ||
          index_ == 0x8A) {
        parent_ = 0x81;
      } else {
        // All other SW maps are small areas - parent is self
        parent_ = index_;
      }
    }
  }
 
  LoadAreaInfo();
 
  if (version != OverworldVersion::kVanilla) {
    // For ALL custom ASM versions (v1-v3), read from custom arrays
    // SetupCustomTileset checks enable flags and falls back to vanilla if disabled
    SetupCustomTileset(OverworldVersionHelper::GetAsmVersion(*rom_));
  } else if (core::FeatureFlags::get().overworld.kLoadCustomOverworld) {
    // Pure vanilla ROM but flag enabled - set up hardcoded vanilla defaults
    LoadCustomOverworldData();
  } else {
    // Pure vanilla ROM: the subscreen overlays are hardcoded in the game.
    subscreen_overlay_ = VanillaSubscreenOverlay(index_);
  }
 
  // Child screens of a multi-screen area render with the parent's area
  // settings (the game reads the tables with $8A = parent). Seed them from
  // the parent's ROM entries; Overworld re-syncs from the live parent map
  // before builds so unsaved parent edits reach the children.
  if (seed_area_parent && parent_ != index_ && parent_ >= 0 &&
      parent_ < kNumOverworldMaps) {
    OverworldMap area_parent(parent_, rom_, game_data_,
                             /*seed_area_parent=*/false);
    InheritAreaProperties(area_parent);
  }
  CaptureAreaInfoBaseline();
}
 
absl::StatusOr<OverworldMap> OverworldMap::CreateLyraPreview(
    int index, Rom* rom, GameData* game_data,
    const rom::LyraLayoutInspection* layout) {
  if (rom == nullptr || layout == nullptr ||
      layout->presence != rom::LyraLayoutPresence::kValid || index < 0 ||
      index >= layout->capacity) {
    return absl::InvalidArgumentError("Invalid Lyra preview map");
  }
  OverworldMap map(index, rom, game_data, /*seed_area_parent=*/false,
                   /*skip_legacy_data=*/true);
  map.descriptor_layout_ = layout;
  RETURN_IF_ERROR(map.LoadLyraPreviewProperties());
  return map;
}
 
absl::Status OverworldMap::LoadLyraPreviewProperties() {
  auto read = [this](uint16_t id,
                     size_t index) -> absl::StatusOr<std::span<const uint8_t>> {
    auto record = rom::LyraLayoutRecord(*descriptor_layout_, rom_->data(),
                                        rom_->size(), id, index);
    if (!record) {
      return absl::FailedPreconditionError("Lyra preview property unavailable");
    }
    return *record;
  };
  ASSIGN_OR_RETURN(auto parent, read(7, index_));
  parent_ = parent[0];
  if (parent_ >= descriptor_layout_->capacity) {
    return absl::FailedPreconditionError("Lyra preview parent out of range");
  }
  ASSIGN_OR_RETURN(auto size, read(30, index_));
  if (size[0] > 3) {
    return absl::FailedPreconditionError("Lyra preview area size invalid");
  }
  area_size_ = static_cast<AreaSizeEnum>(size[0]);
  large_map_ = area_size_ == AreaSizeEnum::LargeArea;
  ASSIGN_OR_RETURN(auto bg, read(1, parent_));
  area_specific_bg_color_ = static_cast<uint16_t>(bg[0] | (bg[1] << 8));
  ASSIGN_OR_RETURN(auto palette, read(2, parent_));
  main_palette_ = palette[0];
  ASSIGN_OR_RETURN(auto mosaic, read(3, parent_));
  mosaic_ = mosaic[0] != 0;
  for (int i = 0; i < 4; ++i) {
    mosaic_expanded_[i] = (mosaic[0] & (0x08 >> i)) != 0;
  }
  ASSIGN_OR_RETURN(auto animated, read(4, parent_));
  animated_gfx_ = animated[0];
  ASSIGN_OR_RETURN(auto overlay, read(5, parent_));
  subscreen_overlay_ = static_cast<uint16_t>(overlay[0] | (overlay[1] << 8));
  ASSIGN_OR_RETURN(auto gfx, read(6, parent_));
  std::copy_n(gfx.begin(), custom_gfx_ids_.size(), custom_gfx_ids_.begin());
  ASSIGN_OR_RETURN(auto area_gfx, read(26, parent_));
  area_graphics_ = area_gfx[0];
  ASSIGN_OR_RETURN(auto palette_set, read(31, parent_));
  area_palette_ = palette_set[0];
  if (parent_ >= kSpecialWorldMapIdStart) {
    const size_t special = parent_ - kSpecialWorldMapIdStart;
    ASSIGN_OR_RETURN(auto sprite_gfx, read(24, special));
    ASSIGN_OR_RETURN(auto sprite_palette, read(25, special));
    sprite_graphics_.fill(sprite_gfx[0]);
    sprite_palette_.fill(sprite_palette[0]);
  }
  return absl::OkStatus();
}
 
AreaRenderProperties OverworldMap::area_render_properties() const {
  if (inherited_area_.has_value()) {
    return *inherited_area_;
  }
  AreaRenderProperties props;
  props.main_palette = main_palette_;
  props.animated_gfx = animated_gfx_;
  props.custom_gfx_ids = custom_gfx_ids_;
  props.subscreen_overlay = subscreen_overlay_;
  props.area_specific_bg_color = area_specific_bg_color_;
  return props;
}
 
void OverworldMap::InheritAreaProperties(const OverworldMap& area_parent) {
  if (&area_parent == this || area_parent.index_ == index_) {
    inherited_area_.reset();
    return;
  }
  AreaRenderProperties props;
  props.main_palette = area_parent.main_palette_;
  props.animated_gfx = area_parent.animated_gfx_;
  props.custom_gfx_ids = area_parent.custom_gfx_ids_;
  props.subscreen_overlay = area_parent.subscreen_overlay_;
  props.area_specific_bg_color = area_parent.area_specific_bg_color_;
  inherited_area_ = props;
}
 
OverworldTilesetKey OverworldMap::tileset_key() const {
  OverworldTilesetKey key{};
  for (int i = 0; i < 16; ++i) {
    key[i] = static_graphics_[i];
  }
  key[16] = animated_sheet_;
  return key;
}
 
absl::Status OverworldMap::BuildMap(int count, int game_state, int world,
                                    std::vector<gfx::Tile16>& tiles16,
                                    OverworldBlockset& world_blockset) {
  // Delegate to cached version with no cache
  return BuildMapWithCache(count, game_state, world, tiles16, world_blockset,
                           nullptr);
}
 
absl::Status OverworldMap::BuildMapWithCache(
    int count, int game_state, int world, std::vector<gfx::Tile16>& tiles16,
    OverworldBlockset& world_blockset,
    const std::vector<uint8_t>* cached_tileset,
    const std::vector<uint8_t>* cached_tile16_blockset) {
  game_state_ = game_state;
  world_ = world;
  auto version = OverworldVersionHelper::GetVersion(*rom_);
 
  // For large maps in vanilla ROMs, we need to handle special world graphics
  // This ensures proper rendering of special overworld areas like Zora's Domain
  // NOTE: Callers (LoadOverworldMaps, EnsureMapBuilt) also handle this and call
  // LoadAreaGraphics() before BuildMapWithCache. This block is kept for the
  // native async path which calls BuildMap() -> BuildMapWithCache() directly.
  if (large_map_ && (version == OverworldVersion::kVanilla)) {
    if (parent_ != index_ && !initialized_) {
      if (index_ >= kSpecialWorldMapIdStart && index_ <= 0x8A &&
          index_ != 0x88) {
        // Zora's Domain children - set sprite_graphics and area graphics
        sprite_graphics_[0] = 0x0E;
        sprite_graphics_[1] = 0x0E;
        sprite_graphics_[2] = 0x0E;
        area_graphics_ = (*rom_)[kOverworldSpecialGfxGroup +
                                 (parent_ - kSpecialWorldMapIdStart)];
        area_palette_ = (*rom_)[kOverworldSpecialPalGroup + 1];
      } else if (index_ == 0x88) {
        // Triforce room has special hardcoded values
        area_graphics_ = 0x51;
        area_palette_ = 0x00;
      } else if (index_ < kSpecialWorldMapIdStart) {
        // LW/DW large map child - use parent's graphics
        area_graphics_ = (*rom_)[kAreaGfxIdPtr + parent_];
        area_palette_ = (*rom_)[kOverworldMapPaletteIds + parent_];
      }
      // Note: Other SW maps (>0x8A) keep their LoadAreaInfo values
 
      initialized_ = true;
    }
  }
 
  LoadAreaGraphics();
 
  // Use cached tileset if available, otherwise build from scratch
  if (cached_tileset && !cached_tileset->empty()) {
    UseCachedTileset(*cached_tileset);
  } else {
    RETURN_IF_ERROR(BuildTileset())
  }
 
  // The tile16 blockset only depends on the tileset and the tile16
  // definitions, so a shared copy can be reused (see Overworld's tileset
  // cache).
  if (!HasGraphicsPreview() && cached_tileset && !cached_tileset->empty() &&
      cached_tile16_blockset && !cached_tile16_blockset->empty()) {
    current_blockset_ = *cached_tile16_blockset;
  } else {
    RETURN_IF_ERROR(BuildTiles16Gfx(tiles16, count))
  }
  RETURN_IF_ERROR(LoadPalette());
  RETURN_IF_ERROR(LoadOverlay());
  RETURN_IF_ERROR(BuildBitmap(world_blockset))
  built_ = true;
  return absl::OkStatus();
}
 
void OverworldMap::LoadAreaInfo() {
  auto version = OverworldVersionHelper::GetVersion(*rom_);
 
  // ZSCustomOverworld ASM Version System:
  // 0x00-0x02: Legacy versions with limited features
  // 0x03: Current version with full area size expansion and custom data support
  // 0xFF: Pure vanilla ROM (no ASM applied)
 
  // Load message ID and area size based on ASM version. v1+ moves message
  // ids into expanded space, but only v3 supports per-map area-size enums.
  if (OverworldVersionHelper::SupportsExpandedSpace(version)) {
    // Keep persistent per-screen metadata separate from parent-derived display
    // state. Unused child slots can contain distinct authored values.
    message_id_ =
        (*rom_)[GetOverworldMessagesExpanded() + (index_ * 2)] |
        ((*rom_)[GetOverworldMessagesExpanded() + (index_ * 2) + 1] << 8);
  } else {
    message_id_ = (*rom_)[kOverworldMessageIds + (parent_ * 2)] |
                  ((*rom_)[kOverworldMessageIds + (parent_ * 2) + 1] << 8);
  }
 
  // Persistent colors must be loaded even when this map is never rendered.
  // LoadPalette must not replace this value during visual refreshes.
  if (OverworldVersionHelper::SupportsCustomBGColors(version)) {
    area_specific_bg_color_ =
        (*rom_)[OverworldCustomAreaSpecificBGPalette + (index_ * 2)] |
        ((*rom_)[OverworldCustomAreaSpecificBGPalette + (index_ * 2) + 1] << 8);
  }
 
  if (OverworldVersionHelper::SupportsAreaEnum(version)) {
    switch ((*rom_)[kOverworldScreenSize + index_]) {
      case 1:
        area_size_ = AreaSizeEnum::LargeArea;
        break;
      case 2:
        area_size_ = AreaSizeEnum::WideArea;
        break;
      case 3:
        area_size_ = AreaSizeEnum::TallArea;
        break;
      case 0:
      default:
        area_size_ = AreaSizeEnum::SmallArea;
        break;
    }
  } else {
    if (index_ < 0x80) {
      // For LW and DW, check the world-specific screen size byte. The legacy
      // parent table is shared/local, but screen-size data has separate
      // Light/Dark entries.
      uint8_t size_byte = (*rom_)[kOverworldScreenSize +
                                  LegacyScreenSizeTableIndexForMap(index_)];
      switch (size_byte) {
        case 0:
          area_size_ = AreaSizeEnum::LargeArea;
          break;
        case 1:
        default:
          area_size_ = AreaSizeEnum::SmallArea;
          break;
      }
    } else {
      // For SW, use hardcoded values for vanilla/v1/v2 compatibility
      // Zora's Domain areas (0x81, 0x82, 0x89, 0x8A) are large areas
      area_size_ =
          (index_ == 0x81 || index_ == 0x82 || index_ == 0x89 || index_ == 0x8A)
              ? AreaSizeEnum::LargeArea
              : AreaSizeEnum::SmallArea;
    }
  }
 
  // Update large_map_ based on area size
  large_map_ = (area_size_ == AreaSizeEnum::LargeArea);
 
  // Load area-specific data based on index range
  if (index_ < kDarkWorldMapIdStart) {
    // Light World (LW) areas
    sprite_graphics_[0] = (*rom_)[kOverworldSpriteset + parent_];
    sprite_graphics_[1] =
        (*rom_)[kOverworldSpriteset + parent_ + kDarkWorldMapIdStart];
    sprite_graphics_[2] =
        (*rom_)[kOverworldSpriteset + parent_ + kSpecialWorldMapIdStart];
 
    area_graphics_ = (*rom_)[kAreaGfxIdPtr + parent_];
    area_palette_ = (*rom_)[kOverworldPalettesScreenToSetNew + parent_];
 
    sprite_palette_[0] = (*rom_)[kOverworldSpritePaletteIds + parent_];
    sprite_palette_[1] =
        (*rom_)[kOverworldSpritePaletteIds + parent_ + kDarkWorldMapIdStart];
    sprite_palette_[2] =
        (*rom_)[kOverworldSpritePaletteIds + parent_ + kSpecialWorldMapIdStart];
 
    area_music_[0] = (*rom_)[kOverworldMusicBeginning + parent_];
    area_music_[1] = (*rom_)[kOverworldMusicZelda + parent_];
    area_music_[2] = (*rom_)[kOverworldMusicMasterSword + parent_];
    area_music_[3] = (*rom_)[kOverworldMusicAgahnim + parent_];
 
    // For v2/vanilla, use original palette table
    if (version < OverworldVersion::kZSCustomV2 ||
        version == OverworldVersion::kVanilla) {
      area_palette_ = (*rom_)[kOverworldMapPaletteIds + parent_];
    }
  } else if (index_ < kSpecialWorldMapIdStart) {
    // Dark World (DW) areas
    sprite_graphics_[0] =
        (*rom_)[kOverworldSpriteset + parent_ + kSpecialWorldMapIdStart];
    sprite_graphics_[1] =
        (*rom_)[kOverworldSpriteset + parent_ + kSpecialWorldMapIdStart];
    sprite_graphics_[2] =
        (*rom_)[kOverworldSpriteset + parent_ + kSpecialWorldMapIdStart];
 
    area_graphics_ = (*rom_)[kAreaGfxIdPtr + parent_];
    area_palette_ = (*rom_)[kOverworldPalettesScreenToSetNew + parent_];
 
    sprite_palette_[0] =
        (*rom_)[kOverworldSpritePaletteIds + parent_ + kSpecialWorldMapIdStart];
    sprite_palette_[1] =
        (*rom_)[kOverworldSpritePaletteIds + parent_ + kSpecialWorldMapIdStart];
    sprite_palette_[2] =
        (*rom_)[kOverworldSpritePaletteIds + parent_ + kSpecialWorldMapIdStart];
 
    area_music_[0] =
        (*rom_)[kOverworldMusicDarkWorld + (parent_ - kDarkWorldMapIdStart)];
 
    // For v2/vanilla, use original palette table
    if (version < OverworldVersion::kZSCustomV2 ||
        version == OverworldVersion::kVanilla) {
      area_palette_ = (*rom_)[kOverworldMapPaletteIds + parent_];
    }
  } else {
    // Special World (SW) areas (index >= 0x80)
    // Message ID already loaded above based on ASM version
 
    // For v3, use expanded sprite tables with full customization support
    if (version == OverworldVersion::kZSCustomV3) {
      sprite_graphics_[0] =
          (*rom_)[kOverworldSpecialSpriteGfxGroupExpandedTemp + parent_ -
                  kSpecialWorldMapIdStart];
      sprite_graphics_[1] =
          (*rom_)[kOverworldSpecialSpriteGfxGroupExpandedTemp + parent_ -
                  kSpecialWorldMapIdStart];
      sprite_graphics_[2] =
          (*rom_)[kOverworldSpecialSpriteGfxGroupExpandedTemp + parent_ -
                  kSpecialWorldMapIdStart];
 
      sprite_palette_[0] = (*rom_)[kOverworldSpecialSpritePaletteExpandedTemp +
                                   parent_ - kSpecialWorldMapIdStart];
      sprite_palette_[1] = (*rom_)[kOverworldSpecialSpritePaletteExpandedTemp +
                                   parent_ - kSpecialWorldMapIdStart];
      sprite_palette_[2] = (*rom_)[kOverworldSpecialSpritePaletteExpandedTemp +
                                   parent_ - kSpecialWorldMapIdStart];
    } else {
      // For v2/vanilla, use original sprite tables
      sprite_graphics_[0] = (*rom_)[kOverworldSpecialSpriteGFXGroup + parent_ -
                                    kSpecialWorldMapIdStart];
      sprite_graphics_[1] = (*rom_)[kOverworldSpecialSpriteGFXGroup + parent_ -
                                    kSpecialWorldMapIdStart];
      sprite_graphics_[2] = (*rom_)[kOverworldSpecialSpriteGFXGroup + parent_ -
                                    kSpecialWorldMapIdStart];
 
      sprite_palette_[0] = (*rom_)[kOverworldSpecialSpritePalette + parent_ -
                                   kSpecialWorldMapIdStart];
      sprite_palette_[1] = (*rom_)[kOverworldSpecialSpritePalette + parent_ -
                                   kSpecialWorldMapIdStart];
      sprite_palette_[2] = (*rom_)[kOverworldSpecialSpritePalette + parent_ -
                                   kSpecialWorldMapIdStart];
    }
 
    area_graphics_ = (*rom_)[kAreaGfxIdPtr + parent_];
    area_palette_ = (*rom_)[kOverworldPalettesScreenToSetNew + parent_];
 
    // For v2/vanilla, use original palette table and handle special cases
    // These hardcoded cases are needed for vanilla compatibility
    if (version < OverworldVersion::kZSCustomV2 ||
        version == OverworldVersion::kVanilla) {
      area_palette_ = (*rom_)[kOverworldMapPaletteIds + parent_];
 
      // Handle special world area cases based on ZScream documentation
      if (index_ == 0x88 || index_ == 0x93) {
        // Triforce room - special graphics and palette
        area_graphics_ = 0x51;
        area_palette_ = 0x00;
      } else if (index_ == 0x80) {
        // Master Sword area - use special graphics group
        area_graphics_ = (*rom_)[kOverworldSpecialGfxGroup +
                                 (parent_ - kSpecialWorldMapIdStart)];
        area_palette_ = (*rom_)[kOverworldSpecialPalGroup + 1];
      } else if (index_ == 0x81 || index_ == 0x82 || index_ == 0x89 ||
                 index_ == 0x8A) {
        // Zora's Domain areas - use special sprite graphics and area graphics
        // Note: These are the large area maps that were causing crashes
        sprite_graphics_[0] = 0x0E;
        sprite_graphics_[1] = 0x0E;
        sprite_graphics_[2] = 0x0E;
 
        area_graphics_ = (*rom_)[kOverworldSpecialGfxGroup +
                                 (parent_ - kSpecialWorldMapIdStart)];
        area_palette_ = (*rom_)[kOverworldSpecialPalGroup + 1];
      } else if (index_ == 0x94) {
        // Make this the same GFX as the true master sword area
        area_graphics_ = (*rom_)[kOverworldSpecialGfxGroup +
                                 (0x80 - kSpecialWorldMapIdStart)];
        area_palette_ = (*rom_)[kOverworldSpecialPalGroup + 1];
      } else if (index_ == 0x95) {
        // Make this the same GFX as the LW death mountain areas
        area_graphics_ = (*rom_)[kAreaGfxIdPtr + 0x03];
        area_palette_ = (*rom_)[kOverworldMapPaletteIds + 0x03];
      } else if (index_ == 0x96) {
        // Make this the same GFX as the pyramid areas
        area_graphics_ = (*rom_)[kAreaGfxIdPtr + 0x5B];
        area_palette_ = (*rom_)[kOverworldMapPaletteIds + 0x5B];
      } else if (index_ == 0x9C) {
        // Make this the same GFX as the DW death mountain areas
        area_graphics_ = (*rom_)[kAreaGfxIdPtr + 0x43];
        area_palette_ = (*rom_)[kOverworldMapPaletteIds + 0x43];
      } else {
        // Default case - use basic graphics
        area_graphics_ = (*rom_)[kAreaGfxIdPtr + 0x00];
        area_palette_ = (*rom_)[kOverworldMapPaletteIds + 0x00];
      }
    }
  }
}
 
void OverworldMap::CaptureAreaInfoBaseline() {
  const auto version = OverworldVersionHelper::GetVersion(*rom_);
  loaded_area_info_parent_ = parent_;
  loaded_area_info_ = {area_graphics_,      area_palette_,
                       sprite_graphics_[0], sprite_graphics_[1],
                       sprite_graphics_[2], sprite_palette_[0],
                       sprite_palette_[1],  sprite_palette_[2]};
  const int palette_table =
      OverworldVersionHelper::SupportsCustomBGColors(version)
          ? kOverworldPalettesScreenToSetNew
          : kOverworldMapPaletteIds;
  raw_area_info_[0] = (*rom_)[kAreaGfxIdPtr + index_];
  raw_area_info_[1] = (*rom_)[palette_table + index_];
  for (int state = 0; state < 3; ++state) {
    if (index_ < kSpecialWorldMapIdStart) {
      const int slot = index_ < kDarkWorldMapIdStart
                           ? index_ + state * kDarkWorldMapIdStart
                           : index_ + kSpecialWorldMapIdStart;
      raw_area_info_[2 + state] = (*rom_)[kOverworldSpriteset + slot];
      raw_area_info_[5 + state] = (*rom_)[kOverworldSpritePaletteIds + slot];
    } else {
      const bool expanded = OverworldVersionHelper::SupportsAreaEnum(version);
      const int gfx_table = expanded
                                ? kOverworldSpecialSpriteGfxGroupExpandedTemp
                                : kOverworldSpecialSpriteGFXGroup;
      const int palette_table = expanded
                                    ? kOverworldSpecialSpritePaletteExpandedTemp
                                    : kOverworldSpecialSpritePalette;
      const int slot = index_ - kSpecialWorldMapIdStart;
      raw_area_info_[2 + state] = (*rom_)[gfx_table + slot];
      raw_area_info_[5 + state] = (*rom_)[palette_table + slot];
    }
  }
  area_info_baseline_valid_ = true;
}
 
void OverworldMap::LoadCustomOverworldData() {
  // Set the main palette values based on ZScream logic
  // Use parent_ to ensure all sibling maps in a large area share the same palette
  if (parent_ < 0x40 || parent_ == 0x95) {  // LW
    main_palette_ = 0;
  } else if ((parent_ >= 0x40 && parent_ < 0x80) || parent_ == 0x96) {  // DW
    main_palette_ = 1;
  } else if (parent_ >= 0x80 && parent_ < 0xA0) {  // SW
    main_palette_ = 0;
  }
 
  // Death Mountain / special overrides - use parent_ so siblings get correct palette
  if (parent_ == 0x03 || parent_ == 0x05 ||
      parent_ == 0x07) {  // LW Death Mountain
    main_palette_ = 2;
  } else if (parent_ == 0x43 || parent_ == 0x45 ||
             parent_ == 0x47) {  // DW Death Mountain
    main_palette_ = 3;
  } else if (parent_ == 0x88 || parent_ == 0x93) {  // Triforce room
    main_palette_ = 4;
  }
 
  // Set the mosaic values based on ZScream logic
  switch (index_) {
    case 0x00:  // Leaving Skull Woods / Lost Woods
    case 0x40:
      mosaic_expanded_ = {false, true, false, true};
      break;
    case 0x02:  // Going into Skull woods / Lost Woods west
    case 0x0A:
    case 0x42:
    case 0x4A:
      mosaic_expanded_ = {false, false, true, false};
      break;
    case 0x0F:  // Going into Zora's Domain North
    case 0x10:  // Going into Skull Woods / Lost Woods North
    case 0x11:
    case 0x50:
    case 0x51:
      mosaic_expanded_ = {true, false, false, false};
      break;
    case 0x80:  // Leaving Zora's Domain, the Master Sword area, and the
                // Triforce area
    case 0x81:
    case 0x88:
      mosaic_expanded_ = {false, true, false, false};
      break;
    default:
      mosaic_expanded_ = {false, false, false, false};
      break;
  }
 
  // Set up world index for GFX groups
  int index_world = 0x20;
  if (parent_ >= kDarkWorldMapIdStart &&
      parent_ < kSpecialWorldMapIdStart) {  // DW
    index_world = 0x21;
  } else if (parent_ == 0x88 || parent_ == 0x93) {  // Triforce room
    index_world = 0x24;
  }
 
  const auto overworld_gfx_groups2 = version_constants().kOverworldGfxGroups2;
 
  // Main Blocksets
  for (int i = 0; i < 8; i++) {
    custom_gfx_ids_[i] =
        (uint8_t)(*rom_)[overworld_gfx_groups2 + (index_world * 8) + i];
  }
 
  const auto overworldgfxGroups = version_constants().kOverworldGfxGroups1;
 
  // Replace the variable tiles with the variable ones
  uint8_t temp = (*rom_)[overworldgfxGroups + (area_graphics_ * 4)];
  if (temp != 0) {
    custom_gfx_ids_[3] = temp;
  } else {
    custom_gfx_ids_[3] = 0xFF;
  }
 
  temp = (*rom_)[overworldgfxGroups + (area_graphics_ * 4) + 1];
  if (temp != 0) {
    custom_gfx_ids_[4] = temp;
  } else {
    custom_gfx_ids_[4] = 0xFF;
  }
 
  temp = (*rom_)[overworldgfxGroups + (area_graphics_ * 4) + 2];
  if (temp != 0) {
    custom_gfx_ids_[5] = temp;
  } else {
    custom_gfx_ids_[5] = 0xFF;
  }
 
  temp = (*rom_)[overworldgfxGroups + (area_graphics_ * 4) + 3];
  if (temp != 0) {
    custom_gfx_ids_[6] = temp;
  } else {
    custom_gfx_ids_[6] = 0xFF;
  }
 
  // Set the animated GFX values - use parent_ so siblings get correct animated sheet
  // Death Mountain uses sheet 0x59, others use 0x5B
  if (parent_ == 0x03 || parent_ == 0x05 || parent_ == 0x07 ||
      parent_ == 0x43 || parent_ == 0x45 || parent_ == 0x47 ||
      parent_ == 0x95) {
    animated_gfx_ = 0x59;
  } else {
    animated_gfx_ = 0x5B;
  }
 
  // Set the subscreen overlay values
  subscreen_overlay_ = 0x00FF;
 
  if (index_ == 0x00 || index_ == 0x01 || index_ == 0x08 || index_ == 0x09 ||
      index_ == 0x40 || index_ == 0x41 || index_ == 0x48 ||
      index_ == 0x49) {  // Add fog 2 to the lost woods and skull woods
    subscreen_overlay_ = 0x009D;
  } else if (index_ == 0x03 || index_ == 0x04 || index_ == 0x0B ||
             index_ == 0x0C || index_ == 0x05 || index_ == 0x06 ||
             index_ == 0x0D || index_ == 0x0E ||
             index_ == 0x07) {  // Add the sky BG to LW death mountain
    subscreen_overlay_ = 0x0095;
  } else if (index_ == 0x43 || index_ == 0x44 || index_ == 0x4B ||
             index_ == 0x4C || index_ == 0x45 || index_ == 0x46 ||
             index_ == 0x4D || index_ == 0x4E ||
             index_ == 0x47) {  // Add the lava to DW death mountain
    subscreen_overlay_ = 0x009C;
  } else if (index_ == 0x5B || index_ == 0x5C || index_ == 0x63 ||
             index_ == 0x64) {  // TODO: Might need this one too "index == 0x1B"
                                // but for now I don't think so
    subscreen_overlay_ = 0x0096;
  } else if (index_ == 0x80) {  // Add fog 1 to the master sword area
    subscreen_overlay_ = 0x0097;
  } else if (index_ ==
             0x88) {  // Add the triforce room curtains to the triforce room
    subscreen_overlay_ = 0x0093;
  }
}
 
uint8_t OverworldMap::ComputeWorldBasedMainPalette() const {
  uint8_t palette = 0;
 
  // Base world selection - use parent_ to ensure siblings share the same palette
  if (parent_ < 0x40 || parent_ == 0x95) {  // LW
    palette = 0;
  } else if ((parent_ >= 0x40 && parent_ < 0x80) || parent_ == 0x96) {  // DW
    palette = 1;
  } else if (parent_ >= 0x80 && parent_ < 0xA0) {  // SW
    palette = 0;
  }
 
  // Death Mountain / special overrides - use parent_ to ensure all siblings
  // in a large area get the correct palette (brown grass for DM)
  // LW DM parents: 0x03, 0x05, 0x07 (children: 0x04, 0x06, 0x0B-0x0E)
  // DW DM parents: 0x43, 0x45, 0x47 (children: 0x44, 0x46, 0x4B-0x4E)
  if (parent_ == 0x03 || parent_ == 0x05 || parent_ == 0x07) {
    palette = 2;  // LW Death Mountain
  } else if (parent_ == 0x43 || parent_ == 0x45 || parent_ == 0x47) {
    palette = 3;  // DW Death Mountain
  } else if (parent_ == 0x88 || parent_ == 0x93) {
    palette = 4;  // Triforce room
  }
 
  return palette;
}
 
void OverworldMap::SetupCustomTileset(uint8_t asm_version) {
  // Load area size for v3
  if (OverworldVersionHelper::SupportsAreaEnum(
          OverworldVersionHelper::GetVersion(*rom_))) {
    uint8_t size_byte = (*rom_)[kOverworldScreenSize + index_];
    area_size_ = static_cast<AreaSizeEnum>(size_byte);
    large_map_ = (area_size_ == AreaSizeEnum::LargeArea);
  }
 
  // Main Palette - check enable flag before reading from custom array
  if ((*rom_)[OverworldCustomMainPaletteEnabled] != 0x00) {
    main_palette_ = (*rom_)[OverworldCustomMainPaletteArray + index_];
  } else {
    // Fall back to world-based hardcoded logic
    main_palette_ = ComputeWorldBasedMainPalette();
  }
 
  // Mosaic - check enable flag before reading from custom array
  if ((*rom_)[OverworldCustomMosaicEnabled] != 0x00) {
    mosaic_ = (*rom_)[OverworldCustomMosaicArray + index_] != 0x00;
    uint8_t mosaicByte = (*rom_)[OverworldCustomMosaicArray + index_];
    mosaic_expanded_ = {
        (mosaicByte & 0x08) != 0x00, (mosaicByte & 0x04) != 0x00,
        (mosaicByte & 0x02) != 0x00, (mosaicByte & 0x01) != 0x00};
  } else {
    // Fall back to hardcoded vanilla mosaic values
    mosaic_ = false;
    mosaic_expanded_ = {false, false, false, false};
    switch (index_) {
      case 0x00:  // Leaving Skull Woods / Lost Woods
      case 0x40:
        mosaic_expanded_ = {false, true, false, true};
        break;
      case 0x02:  // Going into Skull woods / Lost Woods west
      case 0x0A:
      case 0x42:
      case 0x4A:
        mosaic_expanded_ = {false, false, true, false};
        break;
      case 0x0F:  // Going into Zora's Domain North
      case 0x10:  // Going into Skull Woods / Lost Woods North
      case 0x11:
      case 0x50:
      case 0x51:
        mosaic_expanded_ = {true, false, false, false};
        break;
      case 0x80:  // Leaving Zora's Domain, Master Sword area, Triforce area
      case 0x81:
      case 0x88:
        mosaic_expanded_ = {false, true, false, false};
        break;
    }
  }
 
  // Animated GFX - check enable flag before reading from custom array
  if ((*rom_)[OverworldCustomAnimatedGFXEnabled] != 0x00) {
    animated_gfx_ = (*rom_)[OverworldCustomAnimatedGFXArray + index_];
  } else {
    // Death mountain uses 0x59, others use 0x5B
    // Use parent_ to ensure siblings in large areas share the same animated sheet
    if (parent_ == 0x03 || parent_ == 0x05 || parent_ == 0x07 ||
        parent_ == 0x43 || parent_ == 0x45 || parent_ == 0x47 ||
        parent_ == 0x95) {
      animated_gfx_ = 0x59;
    } else {
      animated_gfx_ = 0x5B;
    }
  }
 
  // Tile GFX Groups - check enable flag before reading from custom array
  if ((*rom_)[OverworldCustomTileGFXGroupEnabled] != 0x00) {
    for (int i = 0; i < 8; i++) {
      custom_gfx_ids_[i] =
          (*rom_)[OverworldCustomTileGFXGroupArray + (index_ * 8) + i];
    }
  } else {
    // Fall back to world-based GFX groups
    int index_world = 0x20;
    if (parent_ >= kDarkWorldMapIdStart &&
        parent_ < kSpecialWorldMapIdStart) {  // DW
      index_world = 0x21;
    } else if (parent_ == 0x88 || parent_ == 0x93) {  // Triforce room
      index_world = 0x24;
    }
 
    // Main Blocksets
    for (int i = 0; i < 8; i++) {
      custom_gfx_ids_[i] =
          (uint8_t)(*rom_)[version_constants().kOverworldGfxGroups2 +
                           (index_world * 8) + i];
    }
 
    const auto overworldgfxGroups = version_constants().kOverworldGfxGroups1;
 
    // Replace the variable tiles with the variable ones
    // If the variable is 00 set it to 0xFF which is the new "don't load
    // anything" value
    uint8_t temp = (*rom_)[overworldgfxGroups + (area_graphics_ * 4)];
    if (temp != 0x00) {
      custom_gfx_ids_[3] = temp;
    } else {
      custom_gfx_ids_[3] = 0xFF;
    }
 
    temp = (*rom_)[overworldgfxGroups + (area_graphics_ * 4) + 1];
    if (temp != 0x00) {
      custom_gfx_ids_[4] = temp;
    } else {
      custom_gfx_ids_[4] = 0xFF;
    }
 
    temp = (*rom_)[overworldgfxGroups + (area_graphics_ * 4) + 2];
    if (temp != 0x00) {
      custom_gfx_ids_[5] = temp;
    } else {
      custom_gfx_ids_[5] = 0xFF;
    }
 
    temp = (*rom_)[overworldgfxGroups + (area_graphics_ * 4) + 3];
    if (temp != 0x00) {
      custom_gfx_ids_[6] = temp;
    } else {
      custom_gfx_ids_[6] = 0xFF;
    }
  }
 
  // Subscreen Overlay - check enable flag before reading from custom array
  if ((*rom_)[OverworldCustomSubscreenOverlayEnabled] != 0x00) {
    subscreen_overlay_ =
        (*rom_)[OverworldCustomSubscreenOverlayArray + (index_ * 2)] |
        ((*rom_)[OverworldCustomSubscreenOverlayArray + (index_ * 2) + 1] << 8);
  } else {
    // Fall back to hardcoded overlay values
    subscreen_overlay_ = 0x00FF;
    if (index_ == 0x00 || index_ == 0x01 || index_ == 0x08 || index_ == 0x09 ||
        index_ == 0x40 || index_ == 0x41 || index_ == 0x48 || index_ == 0x49) {
      // Add fog 2 to the lost woods and skull woods
      subscreen_overlay_ = 0x009D;
    } else if (index_ == 0x03 || index_ == 0x04 || index_ == 0x0B ||
               index_ == 0x0C || index_ == 0x05 || index_ == 0x06 ||
               index_ == 0x0D || index_ == 0x0E || index_ == 0x07) {
      // Add the sky BG to LW death mountain
      subscreen_overlay_ = 0x0095;
    } else if (index_ == 0x43 || index_ == 0x44 || index_ == 0x4B ||
               index_ == 0x4C || index_ == 0x45 || index_ == 0x46 ||
               index_ == 0x4D || index_ == 0x4E || index_ == 0x47) {
      // Add the lava to DW death mountain
      subscreen_overlay_ = 0x009C;
    } else if (index_ == 0x5B || index_ == 0x5C || index_ == 0x63 ||
               index_ == 0x64) {
      subscreen_overlay_ = 0x0096;
    } else if (index_ == 0x80) {
      // Add fog 1 to the master sword area
      subscreen_overlay_ = 0x0097;
    } else if (index_ == 0x88) {
      // Add the triforce room curtains to the triforce room
      subscreen_overlay_ = 0x0093;
    }
  }
}
 
void OverworldMap::LoadMainBlocksetId() {
  main_gfx_id_ = ComputeMainBlocksetId();
}
 
int OverworldMap::ComputeMainBlocksetId() const {
  if (parent_ < kDarkWorldMapIdStart) {
    return 0x20;
  } else if (parent_ >= kDarkWorldMapIdStart &&
             parent_ < kSpecialWorldMapIdStart) {
    return 0x21;
  } else if (parent_ >= kSpecialWorldMapIdStart) {
    // Special world maps - use appropriate graphics ID based on the specific
    // map
    if (parent_ == 0x88) {
      return 0x24;
    } else {
      // Default special world graphics ID
      return 0x20;
    }
  }
  return 0x20;
}
 
bool OverworldMap::UsesSessionMainGraphicsGroup() const {
  // Dungeon groups may be relocated independently of the overworld table.
  return game_data_ && game_data_->gfx_groups_loaded &&
         game_data_->gfx_main_group_address ==
             version_constants().kOverworldGfxGroups2 &&
         ComputeMainBlocksetId() < game_data_->main_blockset_ids.size();
}
 
bool OverworldMap::UsesSessionAreaGraphicsGroup() const {
  // JP's overworld area table differs from the dungeon's room table.
  return game_data_ && game_data_->gfx_groups_loaded &&
         kEntranceGfxGroup == version_constants().kOverworldGfxGroups1 &&
         area_graphics_ < game_data_->room_blockset_ids.size();
}
 
OverworldRoomsetSource OverworldMap::roomset_source() const {
  if (descriptor_layout_ != nullptr) {
    return OverworldRoomsetSource::kCustomTileGroups;
  }
  if (rom_ &&
      OverworldVersionHelper::SupportsCustomTileGFX(
          OverworldVersionHelper::GetVersion(*rom_)) &&
      (*rom_)[OverworldCustomTileGFXGroupEnabled] != 0) {
    return OverworldRoomsetSource::kCustomTileGroups;
  }
  return UsesSessionAreaGraphicsGroup()
             ? OverworldRoomsetSource::kSharedSessionGroup
             : OverworldRoomsetSource::kIndependentRomGroup;
}
 
bool OverworldMap::UsesSessionSpriteGraphicsGroup() const {
  return game_data_ && game_data_->gfx_groups_loaded &&
         sprite_graphics_[game_state_] < game_data_->spriteset_ids.size();
}
 
std::array<uint8_t, 8> OverworldMap::ResolveMainGraphicsGroup() const {
  const int main_group_id = ComputeMainBlocksetId();
  if (UsesSessionMainGraphicsGroup()) {
    return game_data_->main_blockset_ids[main_group_id];
  }
  std::array<uint8_t, 8> sheets{};
  for (int i = 0; i < 8; ++i) {
    sheets[i] = (*rom_)[version_constants().kOverworldGfxGroups2 +
                        main_group_id * 8 + i];
  }
  return sheets;
}
 
OverworldMainSlotProvenance OverworldMap::MainSlotProvenance(int slot) const {
  OverworldMainSlotProvenance result;
  if (slot < 0 || slot >= 8) {
    return result;
  }
  result.main_group_id = ComputeMainBlocksetId();
  result.main_sheet = ResolveMainGraphicsGroup()[slot];
  result.effective_sheet = ResolveStaticGraphics()[slot];
  result.bottom_half_only = slot == 7;
  if (roomset_source() == OverworldRoomsetSource::kCustomTileGroups) {
    result.source = OverworldMainSlotSource::kCustomTileGroups;
  } else if (slot >= 3 && slot <= 6 &&
             ResolveAreaGraphicsGroup()[slot - 3] != 0) {
    result.source = OverworldMainSlotSource::kAreaOverride;
  } else if (UsesSessionMainGraphicsGroup()) {
    result.source = OverworldMainSlotSource::kSharedSessionGroup;
  } else {
    result.source = OverworldMainSlotSource::kIndependentRomGroup;
  }
  return result;
}
 
std::array<uint8_t, 4> OverworldMap::ResolveAreaGraphicsGroup() const {
  if (UsesSessionAreaGraphicsGroup()) {
    return game_data_->room_blockset_ids[area_graphics_];
  }
  std::array<uint8_t, 4> sheets{};
  for (int i = 0; i < 4; ++i) {
    sheets[i] = (*rom_)[version_constants().kOverworldGfxGroups1 +
                        area_graphics_ * 4 + i];
  }
  return sheets;
}
 
std::array<uint8_t, 4> OverworldMap::ResolveSpriteGraphicsGroup() const {
  const int set = sprite_graphics_[game_state_];
  if (UsesSessionSpriteGraphicsGroup()) {
    return game_data_->spriteset_ids[set];
  }
  std::array<uint8_t, 4> sheets{};
  for (int i = 0; i < 4; ++i) {
    sheets[i] =
        (*rom_)[version_constants().kSpriteBlocksetPointer + set * 4 + i];
  }
  return sheets;
}
 
std::array<uint8_t, 16> OverworldMap::ResolveStaticGraphics() const {
  std::array<uint8_t, 16> sheets{};
  const auto main = ResolveMainGraphicsGroup();
  const auto area = ResolveAreaGraphicsGroup();
  const auto sprites = ResolveSpriteGraphicsGroup();
  std::copy(main.begin(), main.end(), sheets.begin());
  for (int i = 0; i < 4; ++i) {
    if (area[i] != 0) {
      sheets[3 + i] = area[i];
    }
    sheets[12 + i] = static_cast<uint8_t>(sprites[i] + 0x73);
  }
  sheets[8] = 0x73;
  sheets[9] = 0x74;
  sheets[10] = 0x79;
  sheets[11] = 0x7A;
 
  // v3 explicit tile groups replace the shared background assignment in full.
  // $FF inherits the world's custom defaults; $00 is an explicit sheet ID.
  if (roomset_source() == OverworldRoomsetSource::kCustomTileGroups) {
    const auto area_props = area_render_properties();
    const int world_offset = (parent_ & 0xC0) >> 3;
    for (int i = 0; i < 8; ++i) {
      const uint8_t custom_sheet = area_props.custom_gfx_ids[i];
      sheets[i] =
          custom_sheet == 0xFF
              ? (*rom_)[OverworldCustomDefaultGFXGroups + world_offset + i]
              : custom_sheet;
    }
  }
  return sheets;
}
 
// For animating water tiles on the overworld map.
// We want to swap out static_graphics_[07] with the next sheet
// Usually it is 5A, so we make it 5B instead.
// There is a middle frame which contains tiles from the bottom half
// of the 5A sheet, so this will need some special manipulation to make work
// during the BuildBitmap step (or a new one specifically for animating).
void OverworldMap::DrawAnimatedTiles() {
  if (static_graphics_[7] == 0x5B) {
    static_graphics_[7] = 0x5A;
  } else {
    if (static_graphics_[7] == 0x59) {
      static_graphics_[7] = 0x58;
    }
    static_graphics_[7] = 0x5B;
  }
}
 
// Resolves the animated tile sheet. Graphics slot 7 is a composite in game:
// the bottom half (door frames) comes from the area's sheet 7 and the top half
// holds frame 0 of the animated tiles (water/lava/clouds) decompressed from
// the animated sheet. Vanilla picks $59 on Death Mountain ($8A & $BF in
// 03/05/07) and $5B elsewhere; ZSCustomOverworld reads its AnimatedTable with
// $8A and falls back to the world's default sheet 7 for 0x00/0xFF.
void OverworldMap::LoadDeathMountainGFX() {
  const auto version = OverworldVersionHelper::GetVersion(*rom_);
  uint8_t sheet = area_render_properties().animated_gfx;
  const bool custom_animated =
      descriptor_layout_ != nullptr ||
      (version != OverworldVersion::kVanilla &&
       (*rom_)[OverworldCustomAnimatedGFXEnabled] != 0);
  if (custom_animated) {
    if (sheet == 0x00 || sheet == 0xFF) {
      const int world_offset = (parent_ & 0xC0) >> 3;
      sheet = (*rom_)[OverworldCustomDefaultGFXGroups + world_offset + 7];
    }
  } else if (sheet == 0x00 || sheet == 0xFF) {
    sheet = IsDeathMountainArea(parent_) ? 0x59 : 0x5B;
  }
  animated_sheet_ = sheet;
}
 
void OverworldMap::LoadAreaGraphics() {
  LoadMainBlocksetId();
  static_graphics_ = ResolveStaticGraphics();
  LoadDeathMountainGFX();
}
 
namespace palette_internal {
 
absl::Status SetColorsPalette(Rom& rom, GameData* game_data, int index,
                              gfx::SnesPalette& current, gfx::SnesPalette main,
                              gfx::SnesPalette animated, gfx::SnesPalette aux1,
                              gfx::SnesPalette aux2, gfx::SnesPalette hud,
                              gfx::SnesColor bgrcolor, gfx::SnesPalette spr,
                              gfx::SnesPalette spr2,
                              PaletteAddressMap* addresses,
                              std::array<int, 3> palette_ids) {
  // Palettes infos, color 0 of a palette is always transparent (the arrays
  // contains 7 colors width wide) There is 16 color per line so 16*Y
 
  // Left side of the palette - Main, Animated
  std::array<gfx::SnesColor, 256> new_palette = {};
  *addresses = {};
 
  // Main Palette, Location 0,2 : 35 colors [7x5]
  int k = 0;
  for (int y = 2; y < 7; y++) {
    for (int x = 1; x < 8; x++) {
      new_palette[x + (16 * y)] = main[k];
      (*addresses)[x + 16 * y] = PaletteColorAddress{
          PaletteAddressGroup::kOverworldMain, palette_ids[0], k};
      k++;
    }
  }
 
  // Animated Palette, Location 0,7 : 7colors
  for (int x = 1; x < 8; x++) {
    new_palette[(16 * 7) + (x)] = animated[(x - 1)];
  }
 
  // Right side of the palette - Aux1, Aux2
 
  // Aux1 Palette, Location 8,2 : 21 colors [7x3]
  k = 0;
  for (int y = 2; y < 5; y++) {
    for (int x = 9; x < 16; x++) {
      new_palette[x + (16 * y)] = aux1[k];
      (*addresses)[x + 16 * y] = PaletteColorAddress{
          PaletteAddressGroup::kOverworldAux, palette_ids[1], k};
      k++;
    }
  }
 
  // Aux2 Palette, Location 8,5 : 21 colors [7x3]
  k = 0;
  for (int y = 5; y < 8; y++) {
    for (int x = 9; x < 16; x++) {
      new_palette[x + (16 * y)] = aux2[k];
      (*addresses)[x + 16 * y] = PaletteColorAddress{
          PaletteAddressGroup::kOverworldAux, palette_ids[2], k};
      k++;
    }
  }
 
  // Hud Palette, Location 0,0 : 32 colors [16x2]
  for (int i = 0; i < 32; i++) {
    new_palette[i] = hud[i];
  }
 
  // Hardcoded grass color (that might change to become invisible instead)
  for (int i = 0; i < 8; i++) {
    new_palette[(i * 16)] = bgrcolor;
    new_palette[(i * 16) + 8] = bgrcolor;
  }
 
  // Sprite Palettes
  k = 0;
  for (int y = 8; y < 9; y++) {
    for (int x = 1; x < 8; x++) {
      new_palette[x + (16 * y)] = game_data->palette_groups.sprites_aux1[1][k];
      k++;
    }
  }
 
  // Sprite Palettes
  k = 0;
  for (int y = 8; y < 9; y++) {
    for (int x = 9; x < 16; x++) {
      new_palette[x + (16 * y)] = game_data->palette_groups.sprites_aux3[0][k];
      k++;
    }
  }
 
  // Sprite Palettes
  k = 0;
  for (int y = 9; y < 13; y++) {
    for (int x = 1; x < 16; x++) {
      new_palette[x + (16 * y)] =
          game_data->palette_groups.global_sprites[0][k];
      k++;
    }
  }
 
  // Sprite Palettes
  k = 0;
  for (int y = 13; y < 14; y++) {
    for (int x = 1; x < 8; x++) {
      new_palette[x + (16 * y)] = spr[k];
      k++;
    }
  }
 
  // Sprite Palettes
  k = 0;
  for (int y = 14; y < 15; y++) {
    for (int x = 1; x < 8; x++) {
      new_palette[x + (16 * y)] = spr2[k];
      k++;
    }
  }
 
  // Sprite Palettes
  k = 0;
  for (int y = 15; y < 16; y++) {
    for (int x = 1; x < 16; x++) {
      new_palette[x + (16 * y)] = game_data->palette_groups.armors[0][k];
      k++;
    }
  }
 
  for (int i = 0; i < 256; i++) {
    current[i] = new_palette[i];
    current[(i / 16) * 16].set_transparent(true);
  }
 
  current.set_size(256);
  return absl::OkStatus();
}
}  // namespace palette_internal
 
absl::StatusOr<gfx::SnesPalette> OverworldMap::GetPalette(
    const gfx::PaletteGroup& palette_group, int index, int previous_index,
    int limit, int* resolved_index) {
  if (index == 255) {
    index = (*rom_)[version_constants().kOverworldMapPaletteGroup +
                    (previous_index * 4)];
  }
  if (index >= limit) {
    index = limit - 1;
  }
  if (resolved_index)
    *resolved_index = index;
  return palette_group[index];
}
 
absl::Status OverworldMap::LoadPalette() {
  palette_addresses_ = {};
  if (!game_data_) {
    current_palette_.clear();
    return absl::OkStatus();
  }
 
  uint8_t asm_version = OverworldVersionHelper::GetAsmVersion(*rom_);
  auto version = OverworldVersionHelper::GetVersion(*rom_);
 
  int previous_pal_id = 0;
  int previous_spr_pal_id = 0;
 
  if (index_ > 0 && (descriptor_layout_ == nullptr || parent_ > 0)) {
    // Load previous palette ID based on ASM version
    if (descriptor_layout_ != nullptr) {
      auto previous = rom::LyraLayoutRecord(*descriptor_layout_, rom_->data(),
                                            rom_->size(), 31, parent_ - 1);
      if (!previous) {
        return absl::FailedPreconditionError(
            "Lyra preview previous palette unavailable");
      }
      previous_pal_id = (*previous)[0];
      if (parent_ > kSpecialWorldMapIdStart) {
        auto previous_sprite = rom::LyraLayoutRecord(
            *descriptor_layout_, rom_->data(), rom_->size(), 25,
            parent_ - kSpecialWorldMapIdStart - 1);
        if (!previous_sprite) {
          return absl::FailedPreconditionError(
              "Lyra preview previous sprite palette unavailable");
        }
        previous_spr_pal_id = (*previous_sprite)[0];
      }
    } else if (OverworldVersionHelper::SupportsAreaEnum(version)) {
      // v3 uses expanded palette table
      previous_pal_id = (*rom_)[kOverworldPalettesScreenToSetNew + parent_ - 1];
    } else {
      previous_pal_id = (*rom_)[kOverworldMapPaletteIds + parent_ - 1];
    }
 
    if (descriptor_layout_ == nullptr) {
      previous_spr_pal_id = (*rom_)[kOverworldSpritePaletteIds + parent_ - 1];
    }
  }
 
  const int render_area_palette = std::min((int)area_palette_, 0xA3);
 
  uint8_t pal0 = 0;
  uint8_t pal1 = (*rom_)[version_constants().kOverworldMapPaletteGroup +
                         (render_area_palette * 4)];
  uint8_t pal2 = (*rom_)[version_constants().kOverworldMapPaletteGroup +
                         (render_area_palette * 4) + 1];
  uint8_t pal3 = (*rom_)[version_constants().kOverworldMapPaletteGroup +
                         (render_area_palette * 4) + 2];
  uint8_t pal4 = (*rom_)[kOverworldSpritePaletteGroup +
                         (sprite_palette_[game_state_] * 2)];
  uint8_t pal5 = (*rom_)[kOverworldSpritePaletteGroup +
                         (sprite_palette_[game_state_] * 2) + 1];
 
  auto& grass_pal_group = game_data_->palette_groups.grass;
  auto bgr = grass_pal_group[0][0];
 
  // Handle 0xFF palette references (use previous palette)
  if (pal1 == 0xFF) {
    pal1 = (*rom_)[version_constants().kOverworldMapPaletteGroup +
                   (previous_pal_id * 4)];
  }
 
  if (pal2 == 0xFF) {
    pal2 = (*rom_)[version_constants().kOverworldMapPaletteGroup +
                   (previous_pal_id * 4) + 1];
  }
 
  if (pal3 == 0xFF) {
    pal3 = (*rom_)[version_constants().kOverworldMapPaletteGroup +
                   (previous_pal_id * 4) + 2];
  }
 
  std::array<int, 3>
      palette_ids{};  // Main, aux1, aux2 after all loader fallbacks.
  auto& ow_aux_pal_group = game_data_->palette_groups.overworld_aux;
  ASSIGN_OR_RETURN(
      gfx::SnesPalette aux1,
      GetPalette(ow_aux_pal_group, pal1, previous_pal_id, 20, &palette_ids[1]));
  ASSIGN_OR_RETURN(
      gfx::SnesPalette aux2,
      GetPalette(ow_aux_pal_group, pal2, previous_pal_id, 20, &palette_ids[2]));
 
  // Set background color based on world type and area-specific settings
  bool use_area_specific_bg =
      descriptor_layout_ != nullptr ||
      (OverworldVersionHelper::SupportsCustomBGColors(version) &&
       (*rom_)[OverworldCustomAreaSpecificBGEnabled] != 0x00);
  if (use_area_specific_bg) {
    // Rendering inherits the parent; the raw child color stays saveable.
    bgr = gfx::SnesColor(area_render_properties().area_specific_bg_color);
  } else {
    // Use default world-based background colors
    if (parent_ < kDarkWorldMapIdStart) {
      bgr = grass_pal_group[0][0];  // LW
    } else if (parent_ >= kDarkWorldMapIdStart &&
               parent_ < kSpecialWorldMapIdStart) {
      bgr = grass_pal_group[0][1];  // DW
    } else if (parent_ >= 128 && parent_ < kNumOverworldMaps) {
      bgr = grass_pal_group[0][2];  // SW
    }
  }
 
  // Use main palette from the overworld map data (matches ZScream logic).
  // Child screens use the area parent's entry, like the game ($8A).
  if (version == OverworldVersion::kVanilla) {
    // Vanilla ROMs never write main_palette_ elsewhere; ensure world defaults
    main_palette_ = ComputeWorldBasedMainPalette();
    pal0 = main_palette_;
  } else {
    pal0 = area_render_properties().main_palette;
  }
 
  auto& ow_main_pal_group = game_data_->palette_groups.overworld_main;
  ASSIGN_OR_RETURN(gfx::SnesPalette main,
                   GetPalette(ow_main_pal_group, pal0, previous_pal_id, 255,
                              &palette_ids[0]));
  auto& ow_animated_pal_group = game_data_->palette_groups.overworld_animated;
  ASSIGN_OR_RETURN(gfx::SnesPalette animated,
                   GetPalette(ow_animated_pal_group, std::min((int)pal3, 13),
                              previous_pal_id, 14));
 
  auto& hud_pal_group = game_data_->palette_groups.hud;
  gfx::SnesPalette hud = hud_pal_group[0];
 
  // Handle 0xFF sprite palette references (use previous sprite palette)
  if (pal4 == 0xFF) {
    pal4 = (*rom_)[kOverworldSpritePaletteGroup + (previous_spr_pal_id * 2)];
  }
 
  if (pal4 == 0xFF) {
    pal4 = 0;  // Fallback to 0 if still 0xFF
  }
 
  if (pal5 == 0xFF) {
    pal5 =
        (*rom_)[kOverworldSpritePaletteGroup + (previous_spr_pal_id * 2) + 1];
  }
 
  if (pal5 == 0xFF) {
    pal5 = 0;  // Fallback to 0 if still 0xFF
  }
 
  ASSIGN_OR_RETURN(gfx::SnesPalette spr,
                   GetPalette(game_data_->palette_groups.sprites_aux3, pal4,
                              previous_spr_pal_id, 24));
  ASSIGN_OR_RETURN(gfx::SnesPalette spr2,
                   GetPalette(game_data_->palette_groups.sprites_aux3, pal5,
                              previous_spr_pal_id, 24));
 
  RETURN_IF_ERROR(palette_internal::SetColorsPalette(
      *rom_, game_data_, parent_, current_palette_, main, animated, aux1, aux2,
      hud, bgr, spr, spr2, &palette_addresses_, palette_ids));
 
  // current_palette_ is this map's resolved palette. Do not populate the
  // unused process-wide GfxContext cache here: maps load concurrently, and
  // unsynchronized insertions can corrupt its unordered_map during rehash.
  return absl::OkStatus();
}
 
absl::Status OverworldMap::LoadOverlay() {
  // Load overlays based on ROM version
  if (OverworldVersionHelper::GetVersion(*rom_) == OverworldVersion::kVanilla) {
    // Vanilla ROM - load overlay from overlay pointers
    return LoadVanillaOverlayData();
  }
 
  // Custom overworld ROM - use the area's subscreen overlay (parent's entry
  // for child screens, like the game)
  overlay_id_ = area_render_properties().subscreen_overlay;
  has_overlay_ = (overlay_id_ != 0x00FF);
  overlay_data_.clear();
  return absl::OkStatus();
}
 
absl::Status OverworldMap::LoadVanillaOverlayData() {
  // Load vanilla overlay for this map (interactive overlays for revealing
  // holes/changing elements)
  int address = (kOverlayPointersBank << 16) +
                ((*rom_)[kOverlayPointers + (index_ * 2) + 1] << 8) +
                (*rom_)[kOverlayPointers + (index_ * 2)];
 
  // Convert SNES address to PC address
  address = ((address & 0x7F0000) >> 1) | (address & 0x7FFF);
 
  // Check if custom overlay code is present
  if ((*rom_)[kOverlayData1] == 0x6B) {
    // Use custom overlay data pointer
    address = ((*rom_)[kOverlayData2 + 2 + (index_ * 3)] << 16) +
              ((*rom_)[kOverlayData2 + 1 + (index_ * 3)] << 8) +
              (*rom_)[kOverlayData2 + (index_ * 3)];
    address = ((address & 0x7F0000) >> 1) | (address & 0x7FFF);
  }
 
  // Validate address
  if (address >= rom_->size()) {
    has_overlay_ = false;
    overlay_id_ = 0;
    overlay_data_.clear();
    return absl::OkStatus();
  }
 
  // Parse overlay data (interactive overlays)
  overlay_data_.clear();
  uint8_t b = (*rom_)[address];
 
  // Parse overlay commands until we hit END (0x60)
  while (b != 0x60 && address < rom_->size()) {
    overlay_data_.push_back(b);
 
    // Handle different overlay commands
    switch (b) {
      case 0xA9:  // LDA #$
        if (address + 2 < rom_->size()) {
          overlay_data_.push_back((*rom_)[address + 1]);
          overlay_data_.push_back((*rom_)[address + 2]);
          address += 3;
        } else {
          address++;
        }
        break;
      case 0xA2:  // LDX #$
        if (address + 2 < rom_->size()) {
          overlay_data_.push_back((*rom_)[address + 1]);
          overlay_data_.push_back((*rom_)[address + 2]);
          address += 3;
        } else {
          address++;
        }
        break;
      case 0x8D:  // STA $xxxx
        if (address + 3 < rom_->size()) {
          overlay_data_.push_back((*rom_)[address + 1]);
          overlay_data_.push_back((*rom_)[address + 2]);
          overlay_data_.push_back((*rom_)[address + 3]);
          address += 4;
        } else {
          address++;
        }
        break;
      case 0x9D:  // STA $xxxx,x
        if (address + 3 < rom_->size()) {
          overlay_data_.push_back((*rom_)[address + 1]);
          overlay_data_.push_back((*rom_)[address + 2]);
          overlay_data_.push_back((*rom_)[address + 3]);
          address += 4;
        } else {
          address++;
        }
        break;
      case 0x8F:  // STA $xxxxxx
        if (address + 4 < rom_->size()) {
          overlay_data_.push_back((*rom_)[address + 1]);
          overlay_data_.push_back((*rom_)[address + 2]);
          overlay_data_.push_back((*rom_)[address + 3]);
          overlay_data_.push_back((*rom_)[address + 4]);
          address += 5;
        } else {
          address++;
        }
        break;
      case 0x1A:  // INC A
        address++;
        break;
      case 0x4C:  // JMP
        if (address + 3 < rom_->size()) {
          overlay_data_.push_back((*rom_)[address + 1]);
          overlay_data_.push_back((*rom_)[address + 2]);
          overlay_data_.push_back((*rom_)[address + 3]);
          address += 4;
        } else {
          address++;
        }
        break;
      default:
        address++;
        break;
    }
 
    if (address < rom_->size()) {
      b = (*rom_)[address];
    } else {
      break;
    }
  }
 
  // Add the END command if we found it
  if (b == 0x60) {
    overlay_data_.push_back(0x60);
  }
 
  // Set overlay ID based on map index (simplified)
  overlay_id_ = index_;
  has_overlay_ = !overlay_data_.empty();
 
  return absl::OkStatus();
}
 
uint16_t OverworldMap::SourceSheetForRevision(int i) const {
  // Entries 0-15 are the static slots; entry 16 is the animated sheet whose
  // first frame CopyAnimatedSheetIntoSlot7() copies into slot 7.
  return i < 16 ? static_graphics_[i] : animated_sheet_;
}
 
void OverworldMap::RecordSourceSheetRevisions() {
  source_assignments_recorded_ = true;
  for (int i = 0; i < kNumSourceSheets; i++) {
    const uint16_t sheet = SourceSheetForRevision(i);
    source_sheet_revisions_[i] =
        game_data_ != nullptr && sheet != 0 &&
                graphics_sheet_overrides_.count(sheet) == 0
            ? game_data_->sheet_store.Revision(sheet)
            : 0;
  }
}
 
bool OverworldMap::SourceSheetsChanged() const {
  if (game_data_ == nullptr) {
    return false;
  }
  if (source_assignments_recorded_ && rom_ && game_data_->gfx_groups_loaded &&
      ResolveStaticGraphics() != static_graphics_) {
    return true;
  }
  for (int i = 0; i < kNumSourceSheets; i++) {
    const uint16_t sheet = SourceSheetForRevision(i);
    if (source_sheet_revisions_[i] != 0 && sheet != 0 &&
        graphics_sheet_overrides_.count(sheet) == 0 &&
        game_data_->sheet_store.Revision(sheet) != source_sheet_revisions_[i]) {
      return true;
    }
  }
  return false;
}
 
void OverworldMap::ProcessGraphicsBuffer(int index, int static_graphics_offset,
                                         int size, const uint8_t* all_gfx) {
  if (const auto it = graphics_sheet_overrides_.find(
          static_cast<uint16_t>(static_graphics_offset));
      it != graphics_sheet_overrides_.end() &&
      it->second.size() == static_cast<size_t>(size)) {
    all_gfx = it->second.data();
    static_graphics_offset = 0;
  } else if (static_graphics_offset * size + size >
             static_cast<int>(game_data_ ? game_data_->graphics_buffer.size()
                                         : 0)) {
    // Fill with zeros if out of bounds
    for (int i = 0; i < size; i++) {
      current_gfx_[(index * size) + i] = 0x00;
    }
    return;
  }
  for (int i = 0; i < size; i++) {
    auto byte = all_gfx[i + (static_graphics_offset * size)];
    switch (index) {
      case 0:
      case 3:
      case 4:
      case 5:
        byte += 0x88;
        break;
    }
    current_gfx_[(index * size) + i] = byte;
  }
}
 
absl::Status OverworldMap::BuildTileset() {
  // Rebuild ordinary sources so cleared previews cannot leave stale pixels.
  current_gfx_.assign(0x10000, 0x00);
 
  if (!game_data_) {
    // Headless/tests: allow map builds without graphics by keeping zeroed data.
    ApplyGraphicsPreview(graphics_preview_, current_gfx_);
    return absl::OkStatus();
  }
 
  // Process the 8 main graphics sheets (slots 0-7)
  for (int i = 0; i < 8; i++) {
    if (static_graphics_[i] != 0) {
      ProcessGraphicsBuffer(i, static_graphics_[i], 0x1000,
                            game_data_->graphics_buffer.data());
    }
  }
 
  // Process sprite graphics (slots 8-15)
  for (int i = 8; i < 16; i++) {
    if (static_graphics_[i] != 0) {
      ProcessGraphicsBuffer(i, static_graphics_[i], 0x1000,
                            game_data_->graphics_buffer.data());
    }
  }
 
  // The top of slot 7 shows frame 0 of the animated tiles (ZScream does the
  // same with its StaticGFX[16]); the bottom keeps the area's sheet 7.
  CopyAnimatedSheetIntoSlot7();
 
  // Remember what each slot (and the animated sheet copied into slot 7) was
  // built from, so an unsaved sheet edit can be detected
  // (SourceSheetsChanged).
  RecordSourceSheetRevisions();
  ApplyGraphicsPreview(graphics_preview_, current_gfx_);
 
  return absl::OkStatus();
}
 
void OverworldMap::CopyAnimatedSheetIntoSlot7() {
  if (!game_data_ || animated_sheet_ == 0) {
    return;
  }
  const size_t dst = 7 * 0x1000;
  // A preview override (SetGraphicsSheetOverrides) wins over the store.
  if (const auto it = graphics_sheet_overrides_.find(animated_sheet_);
      it != graphics_sheet_overrides_.end()) {
    if (it->second.size() >= kAnimatedSheetSlotBytes &&
        dst + kAnimatedSheetSlotBytes <= current_gfx_.size()) {
      std::copy_n(it->second.begin(), kAnimatedSheetSlotBytes,
                  current_gfx_.begin() + dst);
    }
    return;
  }
  const size_t src = static_cast<size_t>(animated_sheet_) * 0x1000;
  if (src + kAnimatedSheetSlotBytes > game_data_->graphics_buffer.size() ||
      dst + kAnimatedSheetSlotBytes > current_gfx_.size()) {
    return;
  }
  std::copy_n(game_data_->graphics_buffer.begin() + src,
              kAnimatedSheetSlotBytes, current_gfx_.begin() + dst);
}
 
absl::Status OverworldMap::BuildTiles16Gfx(std::vector<gfx::Tile16>& tiles16,
                                           int count) {
  constexpr size_t kBlocksetBytes = 0x100000;
  constexpr size_t kTilesetBytes = 0x10000;
  if (current_blockset_.size() == 0)
    current_blockset_.resize(kBlocksetBytes, 0x00);
  if (current_gfx_.size() < kTilesetBytes)
    current_gfx_.resize(kTilesetBytes, 0x00);
 
  // Each row of 8 tile16s takes 0x800 bytes of the 128px-wide blockset.
  const int capacity = static_cast<int>(current_blockset_.size() / 0x800) * 8;
  count = std::min({count, static_cast<int>(tiles16.size()), capacity});
 
  const int offsets[] = {0x00, 0x08, 0x400, 0x408};
  const uint8_t* gfx = current_gfx_.data();
  const size_t gfx_size = current_gfx_.size();
  uint8_t* blockset = current_blockset_.data();
 
  for (int i = 0; i < count; i++) {
    const size_t tile_base =
        static_cast<size_t>(i / 8) * 0x800 + static_cast<size_t>(i % 8) * 0x10;
    for (int tile = 0; tile < 4; tile++) {
      const gfx::TileInfo& info = tiles16[i].tiles_info[tile];
      const size_t src_base = static_cast<size_t>(info.id_ / 0x10) * 0x400 +
                              static_cast<size_t>(info.id_ % 0x10) * 0x08;
      uint8_t* dst_tile = blockset + tile_base + offsets[tile];
      if (src_base + 7 * 0x80 + 8 > gfx_size) {
        for (int y = 0; y < 8; ++y) {
          std::fill_n(dst_tile + y * 0x80, 8, 0x00);
        }
        continue;
      }
      const uint8_t palette = static_cast<uint8_t>(info.palette_ * 0x10);
      for (int y = 0; y < 8; ++y) {
        const int my = info.vertical_mirror_ != 0 ? 7 - y : y;
        const uint8_t* src = gfx + src_base + y * 0x80;
        uint8_t* dst = dst_tile + my * 0x80;
        if (info.horizontal_mirror_ != 0) {
          for (int x = 0; x < 8; ++x) {
            dst[7 - x] = static_cast<uint8_t>((src[x] & 0x0F) + palette);
          }
        } else {
          for (int x = 0; x < 8; ++x) {
            dst[x] = static_cast<uint8_t>((src[x] & 0x0F) + palette);
          }
        }
      }
    }
  }
 
  return absl::OkStatus();
}
 
absl::Status OverworldMap::BuildBitmap(OverworldBlockset& world_blockset) {
  bitmap_data_.assign(0x40000, 0x00);
 
  // BuildBitmap is used by both full map builds and editor refresh paths.
  // Refresh paths can run after LRU eviction reset runtime fields, so derive
  // the world/local coordinate from the stable map id instead of trusting
  // world_ to still be populated.
  world_ = WorldForOverworldMap(index_);
  const int local_index = index_ - (world_ * kNumMapsPerWorld);
  if (local_index < 0) {
    return absl::InvalidArgumentError("Invalid overworld map index");
  }
 
  int superY = local_index / 0x08;
  int superX = local_index - (superY * 0x08);
 
  for (int y = 0; y < 0x20; y++) {
    for (int x = 0; x < 0x20; x++) {
      auto xt = x + (superX * 0x20);
      auto yt = y + (superY * 0x20);
      if (xt < 0 || yt < 0 || xt >= static_cast<int>(world_blockset.size()) ||
          yt >= static_cast<int>(world_blockset[xt].size())) {
        return absl::InvalidArgumentError(
            "Overworld blockset is too small for map bitmap build");
      }
      gfx::CopyTile8bpp16((x * 0x10), (y * 0x10), world_blockset[xt][yt],
                          bitmap_data_, current_blockset_);
    }
  }
  static std::atomic<uint64_t> next_bitmap_serial{1};
  bitmap_serial_ = next_bitmap_serial.fetch_add(1);
  return absl::OkStatus();
}
 
absl::Status OverworldMap::BuildSubscreenOverlayLayer(
    const OverworldBlockset& overlay_world_blockset, int overlay_screen,
    bool background, std::vector<uint8_t>* out) const {
  if (out == nullptr) {
    return absl::InvalidArgumentError("Overlay layer output is null");
  }
  constexpr int kSize = 0x200;
  if (bitmap_data_.size() < static_cast<size_t>(kSize) * kSize ||
      current_blockset_.empty()) {
    return absl::FailedPreconditionError(
        "Map must be built before its overlay layer");
  }
  const int local = overlay_screen & 0x3F;
  const int super_x = local % 8;
  const int super_y = local / 8;
 
  out->assign(static_cast<size_t>(kSize) * kSize, 0);
  std::vector<uint8_t> tile_pixels(static_cast<size_t>(kSize) * kSize, 0);
  for (int y = 0; y < 0x20; ++y) {
    for (int x = 0; x < 0x20; ++x) {
      const int xt = x + super_x * 0x20;
      const int yt = y + super_y * 0x20;
      if (xt >= static_cast<int>(overlay_world_blockset.size()) ||
          yt >= static_cast<int>(overlay_world_blockset[xt].size())) {
        return absl::InvalidArgumentError(
            "Overlay blockset is too small for the overlay screen");
      }
      gfx::CopyTile8bpp16(x * 0x10, y * 0x10, overlay_world_blockset[xt][yt],
                          tile_pixels, current_blockset_);
    }
  }
  for (size_t i = 0; i < tile_pixels.size(); ++i) {
    const uint8_t overlay = tile_pixels[i];
    if (IsOverworldBackdropPixel(overlay)) {
      continue;
    }
    if (background && !IsOverworldBackdropPixel(bitmap_data_[i])) {
      continue;
    }
    (*out)[i] = overlay;
  }
  return absl::OkStatus();
}
 
}  // namespace yaze::zelda3