overworld_map.h

Go to the documentation of this file.

#ifndef YAZE_APP_ZELDA3_OVERWORLD_MAP_H
#define YAZE_APP_ZELDA3_OVERWORLD_MAP_H
 
#include <array>
#include <cstddef>
#include <cstdint>
#include <map>
#include <optional>
#include <vector>
 
#include "absl/status/status.h"
#include "absl/status/statusor.h"
#include "app/gfx/types/snes_palette.h"
#include "app/gfx/types/snes_tile.h"
#include "core/rom_settings.h"
#include "rom/rom.h"
#include "zelda3/game_data.h"
#include "zelda3/graphics/resolved_graphics_context.h"
#include "zelda3/overworld/graphics_preview.h"
#include "zelda3/overworld/overworld_version_helper.h"
 
namespace yaze {
namespace zelda3 {
 
static constexpr int kTileOffsets[] = {0, 8, 4096, 4104};
 
// 2 bytes for each overworld area (0x140)
constexpr int OverworldCustomAreaSpecificBGPalette = 0x140000;
 
// 1 byte, not 0 if enabled
constexpr int OverworldCustomAreaSpecificBGEnabled = 0x140140;
 
// Additional v3 constants
constexpr int OverworldCustomSubscreenOverlayArray =
    0x140340;  // 2 bytes for each overworld area (0x140)
constexpr int OverworldCustomSubscreenOverlayEnabled =
    0x140144;  // 1 byte, not 0 if enabled
constexpr int OverworldCustomAnimatedGFXArray =
    0x1402A0;  // 1 byte for each overworld area (0xA0)
constexpr int OverworldCustomAnimatedGFXEnabled =
    0x140143;  // 1 byte, not 0 if enabled
constexpr int OverworldCustomTileGFXGroupArray =
    0x140480;  // 8 bytes for each overworld area (0x500)
constexpr int OverworldCustomTileGFXGroupEnabled =
    0x140148;  // 1 byte, not 0 if enabled
constexpr int OverworldCustomMosaicArray =
    0x140200;  // 1 byte for each overworld area (0xA0)
constexpr int OverworldCustomMosaicEnabled =
    0x140142;  // 1 byte, not 0 if enabled
 
// Vanilla overlay constants
constexpr int kOverlayPointers =
    0x77664;  // 2 bytes for each overworld area (0x100)
constexpr int kOverlayPointersBank = 0x0E;  // Bank for overlay pointers
constexpr int kOverlayData1 = 0x77676;      // Check for custom overlay code
constexpr int kOverlayData2 = 0x77677;      // Custom overlay data pointer
constexpr int kOverlayCodeStart = 0x77657;  // Start of overlay code
 
// 1 byte for each overworld area (0xA0)
constexpr int OverworldCustomMainPaletteArray = 0x140160;
// 1 byte, not 0 if enabled
constexpr int OverworldCustomMainPaletteEnabled = 0x140141;
 
// ZSCustomOverworld default GFX groups (8 sheets each for LW, DW, SW). The
// game falls back to the world's sheet 7 entry when an area's animated GFX
// value is 0x00 or 0xFF (ReadAnimatedTable).
constexpr int OverworldCustomDefaultGFXGroups = 0x140980;
 
// Number of bytes at the top of graphics slot 7 that come from the animated
// tile sheet rather than the area's sheet 7 (the first two tile rows, 32
// tiles, in the 8bpp 128px-wide layout). The game keeps the door frames in
// the bottom half and streams the animated water/lava frames into the top.
constexpr int kAnimatedSheetSlotBytes = 0x800;
 
// v3 expanded constants
constexpr int kOverworldMessagesExpanded = 0x1417F8;
constexpr int kOverworldMapParentIdExpanded = 0x140998;
constexpr int kOverworldTransitionPositionYExpanded = 0x140F38;
constexpr int kOverworldTransitionPositionXExpanded = 0x141078;
constexpr int kOverworldScreenTileMapChangeByScreen1Expanded = 0x140A38;
constexpr int kOverworldScreenTileMapChangeByScreen2Expanded = 0x140B78;
constexpr int kOverworldScreenTileMapChangeByScreen3Expanded = 0x140CB8;
constexpr int kOverworldScreenTileMapChangeByScreen4Expanded = 0x140DF8;
 
inline int GetOverworldMessagesExpanded() {
  return static_cast<int>(core::RomSettings::Get().GetAddressOr(
      core::RomAddressKey::kOverworldMessagesExpanded,
      kOverworldMessagesExpanded));
}
 
inline int GetOverworldMapParentIdExpanded() {
  return static_cast<int>(core::RomSettings::Get().GetAddressOr(
      core::RomAddressKey::kOverworldMapParentExpanded,
      kOverworldMapParentIdExpanded));
}
 
inline int GetOverworldTransitionPositionYExpanded() {
  return static_cast<int>(core::RomSettings::Get().GetAddressOr(
      core::RomAddressKey::kOverworldTransitionPosYExpanded,
      kOverworldTransitionPositionYExpanded));
}
 
inline int GetOverworldTransitionPositionXExpanded() {
  return static_cast<int>(core::RomSettings::Get().GetAddressOr(
      core::RomAddressKey::kOverworldTransitionPosXExpanded,
      kOverworldTransitionPositionXExpanded));
}
 
inline int GetOverworldScreenChange1Expanded() {
  return static_cast<int>(core::RomSettings::Get().GetAddressOr(
      core::RomAddressKey::kOverworldScreenChange1Expanded,
      kOverworldScreenTileMapChangeByScreen1Expanded));
}
 
inline int GetOverworldScreenChange2Expanded() {
  return static_cast<int>(core::RomSettings::Get().GetAddressOr(
      core::RomAddressKey::kOverworldScreenChange2Expanded,
      kOverworldScreenTileMapChangeByScreen2Expanded));
}
 
inline int GetOverworldScreenChange3Expanded() {
  return static_cast<int>(core::RomSettings::Get().GetAddressOr(
      core::RomAddressKey::kOverworldScreenChange3Expanded,
      kOverworldScreenTileMapChangeByScreen3Expanded));
}
 
inline int GetOverworldScreenChange4Expanded() {
  return static_cast<int>(core::RomSettings::Get().GetAddressOr(
      core::RomAddressKey::kOverworldScreenChange4Expanded,
      kOverworldScreenTileMapChangeByScreen4Expanded));
}
 
constexpr int kOverworldSpecialSpriteGFXGroup = 0x016811;
constexpr int kOverworldSpecialGFXGroup = 0x016821;
constexpr int kOverworldSpecialPALGroup = 0x016831;
constexpr int kOverworldSpecialSpritePalette = 0x016841;
constexpr int kOverworldPalettesScreenToSetNew = 0x4C635;
constexpr int kOverworldSpecialSpriteGfxGroupExpandedTemp = 0x0166E1;
constexpr int kOverworldSpecialSpritePaletteExpandedTemp = 0x016701;
 
constexpr int transition_target_northExpanded = 0x1411B8;
constexpr int transition_target_westExpanded = 0x1412F8;
 
constexpr int kDarkWorldMapIdStart = 0x40;
constexpr int kSpecialWorldMapIdStart = 0x80;
 
using OverworldBlockset = std::vector<std::vector<uint16_t>>;
 
typedef struct OverworldMapTiles {
  OverworldBlockset light_world;    // 64 maps
  OverworldBlockset dark_world;     // 64 maps
  OverworldBlockset special_world;  // 32 maps
} OverworldMapTiles;
 
struct AreaRenderProperties {
  uint8_t main_palette = 0;
  uint8_t animated_gfx = 0;
  std::array<uint8_t, 8> custom_gfx_ids = {};
  uint16_t subscreen_overlay = 0x00FF;
  uint16_t area_specific_bg_color = 0;
};
 
enum class OverworldRoomsetSource {
  kSharedSessionGroup,
  kCustomTileGroups,
  kIndependentRomGroup,
};
 
enum class OverworldMainSlotSource {
  kSharedSessionGroup,
  kIndependentRomGroup,
  kAreaOverride,
  kCustomTileGroups,
};
 
struct OverworldMainSlotProvenance {
  int main_group_id = 0;
  uint8_t main_sheet = 0;
  uint8_t effective_sheet = 0;
  OverworldMainSlotSource source =
      OverworldMainSlotSource::kIndependentRomGroup;
  // Overworld slot 7 retains the main/area sheet in the bottom half; its top
  // half is replaced with animated tiles when the map is rendered.
  bool bottom_half_only = false;
};
 
inline int SubscreenOverlayScreen(uint16_t overlay_id) {
  if (overlay_id >= kSpecialWorldMapIdStart && overlay_id < 0xA0) {
    return overlay_id;
  }
  return -1;
}
 
inline bool IsBackgroundSubscreenOverlay(uint16_t overlay_id) {
  return overlay_id == 0x0095 || overlay_id == 0x0096 || overlay_id == 0x009C;
}
 
inline bool IsOverworldBackdropPixel(uint8_t index) {
  return (index & 0x07) == 0;
}
 
using OverworldTilesetKey = std::array<uint8_t, 17>;
 
class OverworldMap : public gfx::GfxContext {
 public:
  OverworldMap() = default;
  OverworldMap(int index, Rom* rom, GameData* game_data = nullptr);
  static absl::StatusOr<OverworldMap> CreateLyraPreview(
      int index, Rom* rom, GameData* game_data,
      const rom::LyraLayoutInspection* layout);
 
  void SetGraphicsPreview(const AreaGraphicsPreview& preview) {
    if (graphics_preview_ == preview)
      return;
    graphics_preview_ = preview;
    built_ = false;
  }
  bool HasGraphicsPreview() const { return !graphics_preview_.empty(); }
 
  const GameData* game_data() const { return game_data_; }
  void SetGameData(GameData* game_data) {
    if (game_data_ != game_data)
      palette_addresses_ = {};
    game_data_ = game_data;
  }
 
  void SetGraphicsSheetOverrides(
      std::map<uint16_t, std::vector<uint8_t>> overrides) {
    graphics_sheet_overrides_ = std::move(overrides);
  }
 
  bool SourceSheetsChanged() const;
 
  absl::Status BuildMap(int count, int game_state, int world,
                        std::vector<gfx::Tile16>& tiles16,
                        OverworldBlockset& world_blockset);
 
  absl::Status 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 = nullptr);
 
  void LoadAreaGraphics();
  friend ResolvedGraphicsContext DescribeOverworldGraphicsContext(
      const OverworldMap& map, const GraphicsContextIdentity& identity);
  absl::Status LoadPalette();
  absl::Status LoadOverlay();
  absl::Status LoadVanillaOverlayData();
  absl::Status BuildTileset();
  absl::Status BuildTiles16Gfx(std::vector<gfx::Tile16>& tiles16, int count);
  absl::Status BuildBitmap(OverworldBlockset& world_blockset);
 
  absl::Status BuildSubscreenOverlayLayer(
      const OverworldBlockset& overlay_world_blockset, int overlay_screen,
      bool background, std::vector<uint8_t>* out) const;
 
  uint64_t bitmap_serial() const { return bitmap_serial_; }
 
  void UseCachedTileset(const std::vector<uint8_t>& cached_gfx) {
    current_gfx_ = cached_gfx;
    ApplyGraphicsPreview(graphics_preview_, current_gfx_);
    // Overworld::BuildMapWithTilesetCache only hands out an entry whose
    // recorded sheet revisions match the store, so these pixels are current.
    RecordSourceSheetRevisions();
  }
 
  void DrawAnimatedTiles();
 
  const std::vector<uint8_t>& current_tile16_blockset() const {
    return current_blockset_;
  }
  const std::vector<uint8_t>& current_graphics() const { return current_gfx_; }
  const gfx::SnesPalette& current_palette() const { return current_palette_; }
  const std::vector<uint8_t>& bitmap_data() const { return bitmap_data_; }
  auto is_large_map() const { return large_map_; }
  auto is_initialized() const { return initialized_; }
  auto is_built() const { return built_; }
  auto parent() const { return parent_; }
  int index() const { return index_; }
  auto mutable_mosaic() { return &mosaic_; }
  auto mutable_current_palette() {
    // A display/project override has not declared a writable model source.
    palette_addresses_ = {};
    return &current_palette_;
  }
  const PaletteAddressMap& palette_addresses() const {
    return palette_addresses_;
  }
 
  void SetNotBuilt() { built_ = false; }
 
  auto area_graphics() const { return area_graphics_; }
  OverworldRoomsetSource roomset_source() const;
  OverworldMainSlotProvenance MainSlotProvenance(int slot) const;
  auto area_palette() const { return area_palette_; }
  auto sprite_graphics(int i) const { return sprite_graphics_[i]; }
  auto sprite_palette(int i) const { return sprite_palette_[i]; }
  auto message_id() const { return message_id_; }
  auto area_music(int i) const { return area_music_[i]; }
  auto static_graphics(int i) const { return static_graphics_[i]; }
  auto large_index() const { return large_index_; }
  auto area_size() const { return area_size_; }
  auto main_gfx_id() const { return main_gfx_id_; }
 
  auto main_palette() const { return main_palette_; }
  void set_main_palette(uint8_t palette) { main_palette_ = palette; }
 
  auto area_specific_bg_color() const { return area_specific_bg_color_; }
  void set_area_specific_bg_color(uint16_t color) {
    area_specific_bg_color_ = color;
  }
 
  // Standard metadata is loaded through the area parent for editing/rendering.
  // Preserve the screen's original raw slot until that model value is edited.
  // Keeping both values also restores the original bytes after Save/Undo/Save.
  uint8_t area_graphics_for_save() const {
    return AreaInfoForSave(0, area_graphics_);
  }
  uint8_t area_palette_for_save() const {
    return AreaInfoForSave(1, area_palette_);
  }
  uint8_t sprite_graphics_for_save(int state) const {
    return AreaInfoForSave(2 + state, sprite_graphics_[state]);
  }
  uint8_t sprite_palette_for_save(int state) const {
    return AreaInfoForSave(5 + state, sprite_palette_[state]);
  }
 
  auto subscreen_overlay() const { return subscreen_overlay_; }
  void set_subscreen_overlay(uint16_t overlay) { subscreen_overlay_ = overlay; }
 
  auto animated_gfx() const { return animated_gfx_; }
  void set_animated_gfx(uint8_t gfx) { animated_gfx_ = gfx; }
 
  auto game_state() const { return game_state_; }
  void set_game_state(int state) { game_state_ = state; }
 
  auto custom_tileset(int index) const { return custom_gfx_ids_[index]; }
 
  AreaRenderProperties area_render_properties() const;
  void InheritAreaProperties(const OverworldMap& area_parent);
  void ClearInheritedAreaProperties() { inherited_area_.reset(); }
  bool has_inherited_area_properties() const {
    return inherited_area_.has_value();
  }
  uint8_t render_main_palette() const {
    return area_render_properties().main_palette;
  }
  uint16_t render_subscreen_overlay() const {
    return area_render_properties().subscreen_overlay;
  }
 
  uint8_t animated_sheet() const { return animated_sheet_; }
  OverworldTilesetKey tileset_key() const;
 
  // Overlay accessors (interactive overlays)
  auto overlay_id() const { return overlay_id_; }
  auto has_overlay() const { return has_overlay_; }
  const auto& overlay_data() const { return overlay_data_; }
 
  // Mosaic expanded accessors
  const std::array<bool, 4>& mosaic_expanded() const {
    return mosaic_expanded_;
  }
  void set_mosaic_expanded(int index, bool value) {
    mosaic_expanded_[index] = value;
  }
  void set_custom_tileset(int index, uint8_t value) {
    custom_gfx_ids_[index] = value;
  }
 
  auto mutable_current_graphics() { return &current_gfx_; }
  auto mutable_area_graphics() { return &area_graphics_; }
  auto mutable_area_palette() { return &area_palette_; }
  auto mutable_sprite_graphics(int i) { return &sprite_graphics_[i]; }
  auto mutable_sprite_palette(int i) { return &sprite_palette_[i]; }
  auto mutable_message_id() { return &message_id_; }
  auto mutable_main_palette() { return &main_palette_; }
  auto mutable_animated_gfx() { return &animated_gfx_; }
  auto mutable_subscreen_overlay() { return &subscreen_overlay_; }
  auto mutable_area_music(int i) { return &area_music_[i]; }
  auto mutable_static_graphics(int i) { return &static_graphics_[i]; }
 
  auto set_area_graphics(uint8_t value) { area_graphics_ = value; }
  auto set_area_palette(uint8_t value) { area_palette_ = value; }
  auto set_sprite_graphics(int i, uint8_t value) {
    sprite_graphics_[i] = value;
  }
  auto set_sprite_palette(int i, uint8_t value) { sprite_palette_[i] = value; }
  auto set_message_id(uint16_t value) { message_id_ = value; }
 
  uint8_t* mutable_custom_tileset(int index) { return &custom_gfx_ids_[index]; }
 
  void SetAsLargeMap(int parent_index, int quadrant) {
    parent_ = parent_index;
    large_index_ = quadrant;
    large_map_ = true;
    area_size_ = AreaSizeEnum::LargeArea;
  }
 
  void SetAsSmallMap(int index = -1) {
    if (index != -1)
      parent_ = index;
    else
      parent_ = index_;
    large_index_ = 0;
    large_map_ = false;
    area_size_ = AreaSizeEnum::SmallArea;
  }
 
  void SetAreaSize(AreaSizeEnum size) {
    area_size_ = size;
    large_map_ = (size == AreaSizeEnum::LargeArea);
  }
 
  void SetParent(int parent_index) { parent_ = parent_index; }
 
  void Destroy() {
    // Free memory-heavy data
    current_blockset_.clear();
    current_gfx_.clear();
    bitmap_data_.clear();
    map_tiles_.light_world.clear();
    map_tiles_.dark_world.clear();
    map_tiles_.special_world.clear();
 
    // Reset build state (allows rebuild)
    built_ = false;
    initialized_ = false;
 
    // Reset runtime state (will be recomputed on rebuild)
    world_ = 0;
    game_state_ = 0;
    main_gfx_id_ = 0;
 
    // NOTE: Do NOT reset these identity fields - they are needed for rebuild:
    // - index_: Map's position in overworld array (used for ROM lookups)
    // - parent_: Map's parent relationship (for large maps)
    // - rom_: ROM pointer (needed for data access)
    // - large_map_, large_index_, area_size_: Map structure info
    // - message_id_, area_graphics_, area_palette_, etc: Loaded from ROM on rebuild
  }
 
 private:
  OverworldMap(int index, Rom* rom, GameData* game_data, bool seed_area_parent,
               bool skip_legacy_data = false);
  absl::Status LoadLyraPreviewProperties();
  void CopyAnimatedSheetIntoSlot7();
  void LoadAreaInfo();
  void CaptureAreaInfoBaseline();
  uint8_t AreaInfoForSave(size_t field, uint8_t value) const {
    return area_info_baseline_valid_ && parent_ == loaded_area_info_parent_ &&
                   value == loaded_area_info_[field]
               ? raw_area_info_[field]
               : value;
  }
  void LoadCustomOverworldData();
  void SetupCustomTileset(uint8_t asm_version);
 
  void LoadMainBlocksetId();
  int ComputeMainBlocksetId() const;
  bool UsesSessionMainGraphicsGroup() const;
  bool UsesSessionAreaGraphicsGroup() const;
  bool UsesSessionSpriteGraphicsGroup() const;
  std::array<uint8_t, 8> ResolveMainGraphicsGroup() const;
  std::array<uint8_t, 4> ResolveAreaGraphicsGroup() const;
  std::array<uint8_t, 4> ResolveSpriteGraphicsGroup() const;
  std::array<uint8_t, 16> ResolveStaticGraphics() const;
  void LoadDeathMountainGFX();
  uint8_t ComputeWorldBasedMainPalette() const;
 
  void ProcessGraphicsBuffer(int index, int static_graphics_offset, int size,
                             const uint8_t* all_gfx);
  absl::StatusOr<gfx::SnesPalette> GetPalette(const gfx::PaletteGroup& group,
                                              int index, int previous_index,
                                              int limit,
                                              int* resolved_index = nullptr);
 
  // Helper to get version constants from game_data or default to US
  zelda3_version_pointers version_constants() const {
    return kVersionConstantsMap.at(game_data_ ? game_data_->version
                                              : zelda3_version::US);
  }
 
  Rom* rom_ = nullptr;
  GameData* game_data_ = nullptr;
  const rom::LyraLayoutInspection* descriptor_layout_ = nullptr;
 
  bool built_ = false;
  bool large_map_ = false;
  bool initialized_ = false;
  bool mosaic_ = false;
 
  int index_ = 0;                                     // Map index
  int parent_ = 0;                                    // Parent map index
  int large_index_ = 0;                               // Quadrant ID [0-3]
  int world_ = 0;                                     // World ID [0-2]
  int game_state_ = 0;                                // Game state [0-2]
  int main_gfx_id_ = 0;                               // Main Gfx ID
  AreaSizeEnum area_size_ = AreaSizeEnum::SmallArea;  // Area size for v3
 
  uint16_t message_id_ = 0;
  uint8_t area_graphics_ = 0;
  uint8_t area_palette_ = 0;
  uint8_t main_palette_ = 0;        // Custom Overworld Main Palette ID
  uint8_t animated_gfx_ = 0;        // Custom Overworld Animated ID
  uint16_t subscreen_overlay_ = 0;  // Custom Overworld Subscreen Overlay ID
  uint16_t area_specific_bg_color_ =
      0;  // Custom Overworld Area-Specific Background Color
  uint8_t animated_sheet_ = 0;  // Sheet for the top half of slot 7
  uint64_t bitmap_serial_ = 0;
  std::optional<AreaRenderProperties> inherited_area_;
  std::array<uint8_t, 8> loaded_area_info_{};
  std::array<uint8_t, 8> raw_area_info_{};
  int loaded_area_info_parent_ = -1;
  bool area_info_baseline_valid_ = false;
 
  std::array<uint8_t, 8> custom_gfx_ids_ = {};
  std::array<uint8_t, 3> sprite_graphics_;
  std::array<uint8_t, 3> sprite_palette_;
  std::array<uint8_t, 4> area_music_;
  std::array<uint8_t, 16> static_graphics_;
 
  std::array<bool, 4> mosaic_expanded_;
 
  // Overlay support (interactive overlays that reveal holes/change elements)
  uint16_t overlay_id_ = 0;
  bool has_overlay_ = false;
  std::vector<uint8_t> overlay_data_;
 
  std::vector<uint8_t> current_blockset_;
  std::vector<uint8_t> current_gfx_;
  std::vector<uint8_t> bitmap_data_;
 
  OverworldMapTiles map_tiles_;
  gfx::SnesPalette current_palette_;
  PaletteAddressMap palette_addresses_{};
  std::map<uint16_t, std::vector<uint8_t>> graphics_sheet_overrides_;
  AreaGraphicsPreview graphics_preview_;
  // Store revision of each static_graphics_ slot at the last BuildTileset();
  // 0 for slots not read from the store.
  static constexpr int kNumSourceSheets = 17;  // 16 slots + animated sheet
  std::array<uint64_t, kNumSourceSheets> source_sheet_revisions_{};
  bool source_assignments_recorded_ = false;
  uint16_t SourceSheetForRevision(int i) const;
  void RecordSourceSheetRevisions();
};
 
}  // namespace zelda3
}  // namespace yaze
 
#endif