room.h

Go to the documentation of this file.

#ifndef YAZE_APP_ZELDA3_DUNGEON_ROOM_H
#define YAZE_APP_ZELDA3_DUNGEON_ROOM_H
 
#include <yaze.h>
#include "zelda3/dungeon/pot_item_position.h"
 
#include <array>
#include <cstdint>
#include <functional>
#include <map>
#include <memory>
#include <optional>
#include <string_view>
#include <tuple>
#include <utility>
#include <vector>
 
#include "absl/status/statusor.h"
#include "absl/types/span.h"
#include "zelda3/graphics/resolved_graphics_context.h"
 
#include "app/gfx/render/background_buffer.h"
#include "rom/rom.h"
#include "zelda3/dungeon/custom_collision.h"
#include "zelda3/dungeon/door_position.h"
#include "zelda3/dungeon/door_types.h"
#include "zelda3/dungeon/dungeon_limits.h"
#include "zelda3/dungeon/dungeon_rom_addresses.h"
#include "zelda3/dungeon/dungeon_stream_allocator.h"
#include "zelda3/dungeon/room_header_destination.h"
#include "zelda3/dungeon/room_layer_registers.h"
#include "zelda3/dungeon/room_layout.h"
#include "zelda3/dungeon/room_object.h"
#include "zelda3/game_data.h"
#include "zelda3/sprite/sprite.h"
 
namespace yaze {
namespace zelda3 {
 
class DungeonState;
class Room;
class RoomLayerManager;
struct DungeonStreamLayout;
 
std::vector<SDL_Color> BuildDungeonRenderPalette(
    const gfx::SnesPalette& dungeon_palette,
    const gfx::SnesPalette* hud_palette = nullptr,
    PaletteAddressMap* addresses = nullptr, int palette_id = 0);
 
// Builds the same eight CGRAM rows as BuildDungeonRenderPalette, but keeps
// them grouped for tools whose tile renderer indexes colors as
// pixel + (tile_palette * 16).
gfx::PaletteGroup BuildDungeonRenderPaletteGroup(
    const gfx::SnesPalette& dungeon_palette,
    const gfx::SnesPalette* hud_palette = nullptr);
 
// Builds the editor-facing dungeon render group and resolves its HUD rows from
// GameData. A null GameData, or one without HUD palettes, leaves those rows
// blank while preserving the canonical dungeon rows.
gfx::PaletteGroup BuildDungeonRenderPaletteGroupFromGameData(
    const gfx::SnesPalette& dungeon_palette, const GameData* game_data);
 
// Builds the sprite half of the underworld CGRAM palette for editor previews.
// Room palette-set slots select row 8 left and rows 13/14 left. The inherited
// Light World environment fallback occupies row 8 right, while the standard
// underworld environment palette occupies row 14 right. Missing or invalid
// palette selectors fall back to palette 0 in the corresponding ROM group.
std::array<SDL_Color, 256> BuildDungeonSpriteRenderPalette(
    const Room& room, const GameData* game_data);
 
void LoadDungeonRenderPaletteToCgram(
    std::span<uint16_t> cgram, const gfx::SnesPalette& dungeon_palette,
    const gfx::SnesPalette* hud_palette = nullptr);
 
// ROM addresses defined in dungeon_rom_addresses.h (use kPrefixed names)
 
struct LayerMergeType {
  uint8_t ID;
  std::string Name;
  bool Layer2OnTop;
  bool Layer2Translucent;
  bool Layer2Visible;
  LayerMergeType() = default;
  LayerMergeType(uint8_t id, std::string name, bool see, bool top, bool trans) {
    ID = id;
    Name = name;
    Layer2OnTop = top;
    Layer2Translucent = trans;
    Layer2Visible = see;
  }
  bool operator==(const LayerMergeType&) const = default;
};
 
// LayerMergeType(id, name, Layer2Visible, Layer2OnTop, Layer2Translucent)
//
// SNES Mode 1 Layer Priority: BG1 is ALWAYS rendered on top of BG2 by default.
// The flags control COLOR MATH effects, not Z-order:
// - Layer2Visible: Whether BG2 is enabled on main screen
// - Layer2OnTop: Whether BG2 participates in sub-screen color math effects
//   (transparency, additive blending) - does NOT change draw order
// - Layer2Translucent: Whether color math creates transparency effect
const static LayerMergeType LayerMerge00{0x00, "Off", true, false, false};
const static LayerMergeType LayerMerge01{0x01, "Parallax", true, false, false};
const static LayerMergeType LayerMerge02{0x02, "Dark", true, true, true};
const static LayerMergeType LayerMerge03{0x03, "On top", false, true, false};
const static LayerMergeType LayerMerge04{0x04, "Translucent", true, true, true};
const static LayerMergeType LayerMerge05{0x05, "Addition", true, true, true};
const static LayerMergeType LayerMerge06{0x06, "Normal", true, false, false};
const static LayerMergeType LayerMerge07{0x07, "Transparent", true, true, true};
const static LayerMergeType LayerMerge08{0x08, "Dark room", true, true, true};
 
const static LayerMergeType kLayerMergeTypeList[] = {
    LayerMerge00, LayerMerge01, LayerMerge02, LayerMerge03, LayerMerge04,
    LayerMerge05, LayerMerge06, LayerMerge07, LayerMerge08};
 
// Fixed byte storage keeps unnamed ROM values representable for lossless
// load/save and undo. Authoring controls validate their supported subset.
enum CollisionKey : uint8_t {
  One_Collision,
  Both,
  Both_With_Scroll,
  Moving_Floor_Collision,
  Moving_Water_Collision,
};
 
enum EffectKey : uint8_t {
  Effect_Nothing,
  One,
  Moving_Floor,
  Moving_Water,
  Four,
  Red_Flashes,
  Torch_Show_Floor,
  Ganon_Room,
};
 
// Pot item - items hidden under pots, rocks, skulls etc.
// Each item has its own position from ROM data
struct PotItem {
  uint16_t position = 0;  // Raw position word from ROM
  uint8_t item = 0;       // Item type (0 = nothing)
 
  // Coordinates occupy bits 1..12; layer/control bits do not affect pixels.
  int GetPixelX() const { return PotItemPixelX(position); }
  int GetPixelY() const { return PotItemPixelY(position); }
 
  // Get tile coordinates (8-pixel tiles)
  int GetTileX() const { return GetPixelX() / 8; }
  int GetTileY() const { return GetPixelY() / 8; }
};
 
enum TagKey : uint8_t {
  Nothing,
  NW_Kill_Enemy_to_Open,
  NE_Kill_Enemy_to_Open,
  SW_Kill_Enemy_to_Open,
  SE_Kill_Enemy_to_Open,
  W_Kill_Enemy_to_Open,
  E_Kill_Enemy_to_Open,
  N_Kill_Enemy_to_Open,
  S_Kill_Enemy_to_Open,
  Clear_Quadrant_to_Open,
  Clear_Room_to_Open,
  NW_Push_Block_to_Open,
  NE_Push_Block_to_Open,
  SW_Push_Block_to_Open,
  SE_Push_Block_to_Open,
  W_Push_Block_to_Open,
  E_Push_Block_to_Open,
  N_Push_Block_to_Open,
  S_Push_Block_to_Open,
  Push_Block_to_Open,
  Pull_Lever_to_Open,
  Clear_Level_to_Open,
  Switch_Open_Door_Hold,
  Switch_Open_Door_Toggle,
  Turn_off_Water,
  Turn_on_Water,
  Water_Gate,
  Water_Twin,
  Secret_Wall_Right,
  Secret_Wall_Left,
  Crash1,
  Crash2,
  Pull_Switch_to_bomb_Wall,
  Holes_0,
  Open_Chest_Activate_Holes_0,
  Holes_1,
  Holes_2,
  Kill_Enemy_to_clear_level,
  SE_Kill_Enemy_to_Move_Block,
  Trigger_activated_Chest,
  Pull_lever_to_Bomb_Wall,
  NW_Kill_Enemy_for_Chest,
  NE_Kill_Enemy_for_Chest,
  SW_Kill_Enemy_for_Chest,
  SE_Kill_Enemy_for_Chest,
  W_Kill_Enemy_for_Chest,
  E_Kill_Enemy_for_Chest,
  N_Kill_Enemy_for_Chest,
  S_Kill_Enemy_for_Chest,
  Clear_Quadrant_for_Chest,
  Clear_Room_for_Chest,
  Light_Torches_to_Open,
  Holes_3,
  Holes_4,
  Holes_5,
  Holes_6,
  Agahnim_Room,
  Holes_7,
  Holes_8,
  Open_Chest_for_Holes_8,
  Push_Block_for_Chest,
  Kill_to_open_Ganon_Door,
  Light_Torches_to_get_Chest,
  Kill_boss_Again
};
 
// Editor-authored water fill zones (Oracle of Secrets).
// Stored as a 64x64 boolean map (0/1 per 8x8 tile). At runtime, the hack
// consumes a compact offset list derived from these tiles.
struct WaterFillZoneMap {
  std::array<uint8_t, 64 * 64> tiles{};
  bool has_data = false;
  uint8_t sram_bit_mask = 0;  // Bit in $7EF411 (e.g. 0x01)
};
 
class Room {
 public:
  // Authoring state only: restoring metadata never replaces entity collections,
  // room load state, ROM bytes, or dirty flags for unrelated save domains.
  struct MetadataSnapshot {
    uint8_t palette = 0;
    uint8_t blockset = 0;
    uint8_t spriteset = 0;
    uint8_t layout = 0;
    uint8_t floor1 = 0;
    uint8_t floor2 = 0;
    uint16_t message = 0;
    background2 bg2{};
    uint8_t layer2_mode = 0;
    LayerMergeType layer_merging = LayerMerge00;
    bool is_dark = false;
    bool is_light = false;
    CollisionKey collision = One_Collision;
    EffectKey effect = Effect_Nothing;
    TagKey tag1 = Nothing;
    TagKey tag2 = Nothing;
    uint8_t holewarp = 0;
    uint8_t pit_target_layer = 0;
    std::array<uint8_t, 4> staircase_rooms{};
    std::array<uint8_t, 4> staircase_planes{};
 
    bool operator==(const MetadataSnapshot&) const = default;
  };
 
  MetadataSnapshot CaptureMetadataSnapshot() const;
  void RestoreMetadataSnapshot(const MetadataSnapshot& snapshot);
 
  struct SaveDirtySnapshot {
    struct BlockLoadOrder {
      size_t tile_object_index;
      int load_order;
    };
 
    bool header = false;
    bool object_stream = false;
    uint8_t object_stream_header = 0;
    bool sprites = false;
    bool chests = false;
    bool pot_items = false;
    bool torches = false;
    bool blocks = false;
    bool custom_collision = false;
    bool water_fill = false;
    uint8_t water_fill_sram_bit_mask = 0;
    std::vector<BlockLoadOrder> block_load_orders;
  };
 
  Room();
  Room(int room_id, Rom* rom, GameData* game_data = nullptr);
  ~Room();
 
  // Move-only type due to unique_ptr
  Room(Room&&);
  Room& operator=(Room&&);
  Room(const Room&) = delete;
  Room& operator=(const Room&) = delete;
 
  void LoadRoomGraphics(
      std::optional<uint8_t> entrance_blockset = std::nullopt);
  friend ResolvedGraphicsContext DescribeDungeonGraphicsContext(
      const Room& room, const GraphicsContextIdentity& identity);
  void CopyRoomGraphicsToBuffer();
  // LoadGraphicsSheetsIntoArena() removed - per-room graphics instead
  void RenderRoomGraphics();
  void RenderObjectsToBackground();
  void LoadAnimatedGraphics();
  void LoadObjects();
  void EnsureObjectsLoaded();
  void LoadSprites();
  void EnsureSpritesLoaded();
  void LoadChests();
  void LoadPotItems();
  void EnsurePotItemsLoaded();
  void LoadDoors();
  void LoadTorches();
  void LoadBlocks();
  void LoadPits();
  void LoadLayoutTilesToBuffer();
  void ReloadGraphics(std::optional<uint8_t> entrance_blockset = std::nullopt);
  void PrepareForRender(
      std::optional<uint8_t> entrance_blockset = std::nullopt);
 
  // Public getters and manipulators for sprites
  const std::vector<zelda3::Sprite>& GetSprites() const { return sprites_; }
  std::vector<zelda3::Sprite>& GetSprites() { return sprites_; }
  bool sprites_dirty() const { return save_dirty_state_.sprites; }
  void MarkSpritesDirty() { save_dirty_state_.sprites = true; }
  void ClearSpritesDirty() { save_dirty_state_.sprites = false; }
 
  // Public getters and manipulators for chests
  const std::vector<chest_data>& GetChests() const { return chests_in_room_; }
  std::vector<chest_data>& GetChests() { return chests_in_room_; }
  bool chests_dirty() const { return save_dirty_state_.chests; }
  void MarkChestsDirty() { save_dirty_state_.chests = true; }
  void ClearChestsDirty() { save_dirty_state_.chests = false; }
 
  // Public getters and manipulators for stairs
  const std::vector<staircase>& GetStairs() const { return z3_staircases_; }
  std::vector<staircase>& GetStairs() { return z3_staircases_; }
 
  struct Door {
    uint8_t position;         
    DoorType type;            
    DoorDirection direction;  
 
    uint8_t byte1;  
    uint8_t byte2;  
 
    std::pair<int, int> GetTileCoords() const {
      return DoorPositionManager::PositionToTileCoords(position, direction);
    }
 
    std::pair<int, int> GetPixelCoords() const {
      return DoorPositionManager::PositionToPixelCoords(position, direction);
    }
 
    DoorDimensions GetDimensions() const {
      return GetDoorDimensions(direction);
    }
 
    DoorDimensions GetEditorDimensions() const {
      return GetEditorDoorDimensions(direction, type);
    }
 
    std::tuple<int, int, int, int> GetBounds() const {
      return DoorPositionManager::GetDoorBounds(position, direction);
    }
 
    std::tuple<int, int, int, int> GetEditorBounds() const {
      return DoorPositionManager::GetDoorEditorBounds(position, direction,
                                                      type);
    }
 
    std::string_view GetTypeName() const {
      return zelda3::GetDoorTypeName(type);
    }
 
    std::string_view GetDirectionName() const {
      return zelda3::GetDoorDirectionName(direction);
    }
 
    std::pair<uint8_t, uint8_t> EncodeBytes() const {
      return DoorPositionManager::EncodeDoorBytes(position, type, direction);
    }
 
    static Door FromRomBytes(uint8_t b1, uint8_t b2) {
      Door door;
      door.byte1 = b1;
      door.byte2 = b2;
      // Position index is in bits 4-7 of b1
      // ASM does: (b1 & 0xF0) >> 3 which gives index * 2 for table lookup
      // We store the raw index (0-15, typically 0-5)
      door.position = (b1 >> 4) & 0x0F;
      // Direction is in bits 0-1 of b1
      door.direction = DoorDirectionFromRaw(b1 & 0x03);
      // Door type is the full second byte
      door.type = DoorTypeFromRaw(b2);
      return door;
    }
  };
 
  const std::vector<Door>& GetDoors() const { return doors_; }
  std::vector<Door>& GetDoors() { return doors_; }
  void AddDoor(const Door& door) {
    doors_.push_back(door);
    objects_loaded_ = true;
    MarkObjectStreamDirty();
  }
  void RemoveDoor(size_t index) {
    if (index < doors_.size()) {
      doors_.erase(doors_.begin() + index);
      objects_loaded_ = true;
      MarkObjectStreamDirty();
    }
  }
 
  // Public getters for pot items (items hidden under pots/bushes)
  const std::vector<PotItem>& GetPotItems() const { return pot_items_; }
  std::vector<PotItem>& GetPotItems() { return pot_items_; }
  bool pot_items_dirty() const { return save_dirty_state_.pot_items; }
  void MarkPotItemsDirty() { save_dirty_state_.pot_items = true; }
  void ClearPotItemsDirty() { save_dirty_state_.pot_items = false; }
 
  bool torches_dirty() const { return save_dirty_state_.torches; }
  void MarkTorchesDirty() { save_dirty_state_.torches = true; }
  void ClearTorchesDirty() { save_dirty_state_.torches = false; }
  bool blocks_dirty() const { return save_dirty_state_.blocks; }
  void MarkBlocksDirty() { save_dirty_state_.blocks = true; }
  void ClearBlocksDirty() { save_dirty_state_.blocks = false; }
 
  const RoomLayout& GetLayout() const { return layout_; }
 
  // Public getters and manipulators for tile objects
  const std::vector<RoomObject>& GetTileObjects() const {
    return tile_objects_;
  }
  std::vector<RoomObject>& GetTileObjects() { return tile_objects_; }
 
  // Methods for modifying tile objects
  void ClearTileObjects() {
    MarkTileObjectDomainsDirtyForSnapshot(tile_objects_);
    tile_objects_.clear();
    objects_loaded_ = true;
    MarkObjectsDirty();
  }
  void AddTileObject(const RoomObject& object) {
    tile_objects_.push_back(object);
    objects_loaded_ = true;
    MarkSaveDirtyForTileObject(object);
  }
 
  // Enhanced object manipulation (Phase 3)
  absl::Status AddObject(const RoomObject& object);
  absl::Status RemoveObject(size_t index);
  absl::Status UpdateObject(size_t index, const RoomObject& object);
  absl::StatusOr<size_t> FindObjectAt(int x, int y, int layer) const;
  bool ValidateObject(const RoomObject& object) const;
 
  // Performance optimization: Mark objects as dirty when modified
  void MarkObjectsDirty() {
    dirty_state_.objects = true;
    dirty_state_.textures = true;
    MarkCompositeDirty();
  }
  void MarkObjectStreamDirty() {
    save_dirty_state_.object_stream = true;
    MarkObjectsDirty();
  }
  void MarkSaveDirtyForTileObject(const RoomObject& object) {
    bool is_special_table_object = false;
    if ((object.options() & ObjectOption::Torch) != ObjectOption::Nothing) {
      save_dirty_state_.torches = true;
      is_special_table_object = true;
    }
    if ((object.options() & ObjectOption::Block) != ObjectOption::Nothing) {
      save_dirty_state_.blocks = true;
      is_special_table_object = true;
    }
    if (!is_special_table_object) {
      save_dirty_state_.object_stream = true;
    }
    MarkObjectsDirty();
  }
  void MarkTileObjectDomainsDirtyForSnapshot(
      const std::vector<RoomObject>& objects) {
    for (const auto& object : objects) {
      MarkSaveDirtyForTileObject(object);
    }
  }
  void MarkTileObjectCollectionDirty() {
    MarkTileObjectDomainsDirtyForSnapshot(tile_objects_);
  }
  bool object_stream_dirty() const { return save_dirty_state_.object_stream; }
  void ClearObjectStreamDirty() { save_dirty_state_.object_stream = false; }
  bool object_stream_header_dirty() const {
    return save_dirty_state_.object_stream_header != 0;
  }
  void ClearObjectStreamHeaderDirty() {
    save_dirty_state_.object_stream_header = 0;
  }
  void MarkGraphicsDirty() {
    dirty_state_.graphics = true;
    dirty_state_.textures = true;
    MarkCompositeDirty();
  }
  void MarkLayoutDirty() {
    dirty_state_.layout = true;
    dirty_state_.textures = true;
    MarkCompositeDirty();
  }
  void RemoveTileObject(size_t index) {
    if (index < tile_objects_.size()) {
      MarkSaveDirtyForTileObject(tile_objects_[index]);
      tile_objects_.erase(tile_objects_.begin() + index);
      objects_loaded_ = true;
      MarkObjectsDirty();
    }
  }
  size_t GetTileObjectCount() const { return tile_objects_.size(); }
  RoomObject& GetTileObject(size_t index) { return tile_objects_[index]; }
  const RoomObject& GetTileObject(size_t index) const {
    return tile_objects_[index];
  }
 
  // =========================================================================
  // Object Limit Tracking (ZScream Feature Parity)
  // =========================================================================
 
  std::map<DungeonLimit, int> GetLimitedObjectCounts() const;
 
  bool HasExceededLimits() const;
 
  std::vector<DungeonLimitInfo> GetExceededLimitDetails() const;
 
  // Custom Collision access
  const CustomCollisionMap& custom_collision() const {
    return custom_collision_;
  }
  CustomCollisionMap& custom_collision() { return custom_collision_; }
  bool has_custom_collision() const { return custom_collision_.has_data; }
  void set_has_custom_collision(bool has) {
    if (custom_collision_.has_data != has) {
      custom_collision_.has_data = has;
      custom_collision_dirty_ = true;
    }
  }
 
  uint8_t GetCollisionTile(int x, int y) const {
    if (x < 0 || x >= 64 || y < 0 || y >= 64)
      return 0;
    return custom_collision_.tiles[y * 64 + x];
  }
 
  bool HasCollisionOverride(int x, int y) const {
    return x >= 0 && x < 64 && y >= 0 && y < 64 &&
           custom_collision_.HasOverride(y * 64 + x);
  }
 
  void SetCollisionTile(int x, int y, uint8_t tile) {
    if (x < 0 || x >= 64 || y < 0 || y >= 64)
      return;
    custom_collision_.SetOverride(y * 64 + x, tile);
    custom_collision_dirty_ = true;
  }
 
  void ClearCollisionTile(int x, int y) {
    if (x < 0 || x >= 64 || y < 0 || y >= 64)
      return;
    custom_collision_.ClearOverride(y * 64 + x);
    custom_collision_dirty_ = true;
  }
 
  bool custom_collision_dirty() const { return custom_collision_dirty_; }
  void ClearCustomCollisionDirty() { custom_collision_dirty_ = false; }
  void MarkCustomCollisionDirty() { custom_collision_dirty_ = true; }
 
  // Water fill zones (Oracle of Secrets)
  const WaterFillZoneMap& water_fill_zone() const { return water_fill_zone_; }
  WaterFillZoneMap& water_fill_zone() { return water_fill_zone_; }
  bool has_water_fill_zone() const { return water_fill_zone_.has_data; }
 
  bool GetWaterFillTile(int x, int y) const {
    if (x < 0 || x >= 64 || y < 0 || y >= 64)
      return false;
    return water_fill_zone_.tiles[y * 64 + x] != 0;
  }
 
  void SetWaterFillTile(int x, int y, bool filled) {
    if (x < 0 || x >= 64 || y < 0 || y >= 64)
      return;
    const uint8_t val = filled ? 1 : 0;
    const size_t idx = static_cast<size_t>(y * 64 + x);
    const uint8_t prev = water_fill_zone_.tiles[idx];
    if (prev == val)
      return;
    water_fill_zone_.tiles[idx] = val;
    if (val) {
      ++water_fill_tile_count_;
      water_fill_zone_.has_data = true;
    } else {
      if (water_fill_tile_count_ > 0) {
        --water_fill_tile_count_;
      }
      if (water_fill_tile_count_ == 0) {
        water_fill_zone_.has_data = false;
      }
    }
    water_fill_dirty_ = true;
  }
 
  void ClearWaterFillZone() {
    water_fill_zone_.tiles.fill(0);
    water_fill_zone_.has_data = false;
    water_fill_zone_.sram_bit_mask = 0;
    water_fill_tile_count_ = 0;
    water_fill_dirty_ = true;
  }
 
  int WaterFillTileCount() const { return water_fill_tile_count_; }
 
  uint8_t water_fill_sram_bit_mask() const {
    return water_fill_zone_.sram_bit_mask;
  }
  void set_water_fill_sram_bit_mask(uint8_t mask) {
    if (water_fill_zone_.sram_bit_mask != mask) {
      water_fill_zone_.sram_bit_mask = mask;
      water_fill_dirty_ = true;
    }
  }
 
  bool water_fill_dirty() const { return water_fill_dirty_; }
  void ClearWaterFillDirty() { water_fill_dirty_ = false; }
  void MarkWaterFillDirty() { water_fill_dirty_ = true; }
 
  bool header_dirty() const { return save_dirty_state_.header; }
  void MarkHeaderDirty() { save_dirty_state_.header = true; }
  void ClearHeaderDirty() { save_dirty_state_.header = false; }
 
  bool HasUnsavedChanges() const {
    return save_dirty_state_.header || save_dirty_state_.object_stream ||
           save_dirty_state_.object_stream_header != 0 ||
           save_dirty_state_.sprites || save_dirty_state_.chests ||
           save_dirty_state_.pot_items || save_dirty_state_.torches ||
           save_dirty_state_.blocks || custom_collision_dirty_ ||
           water_fill_dirty_;
  }
 
  void ClearSaveDirtyState() { save_dirty_state_ = {}; }
 
  SaveDirtySnapshot CaptureSaveDirtySnapshot() const {
    SaveDirtySnapshot snapshot{
        .header = save_dirty_state_.header,
        .object_stream = save_dirty_state_.object_stream,
        .object_stream_header = save_dirty_state_.object_stream_header,
        .sprites = save_dirty_state_.sprites,
        .chests = save_dirty_state_.chests,
        .pot_items = save_dirty_state_.pot_items,
        .torches = save_dirty_state_.torches,
        .blocks = save_dirty_state_.blocks,
        .custom_collision = custom_collision_dirty_,
        .water_fill = water_fill_dirty_,
        .water_fill_sram_bit_mask = water_fill_zone_.sram_bit_mask,
    };
    for (size_t index = 0; index < tile_objects_.size(); ++index) {
      const auto& object = tile_objects_[index];
      if ((object.options() & ObjectOption::Block) != ObjectOption::Nothing) {
        snapshot.block_load_orders.push_back(
            {.tile_object_index = index,
             .load_order = object.block_load_order()});
      }
    }
    return snapshot;
  }
 
  void RestoreSaveDirtySnapshot(const SaveDirtySnapshot& snapshot) {
    save_dirty_state_.header = snapshot.header;
    save_dirty_state_.object_stream = snapshot.object_stream;
    save_dirty_state_.object_stream_header = snapshot.object_stream_header;
    save_dirty_state_.sprites = snapshot.sprites;
    save_dirty_state_.chests = snapshot.chests;
    save_dirty_state_.pot_items = snapshot.pot_items;
    save_dirty_state_.torches = snapshot.torches;
    save_dirty_state_.blocks = snapshot.blocks;
    custom_collision_dirty_ = snapshot.custom_collision;
    water_fill_dirty_ = snapshot.water_fill;
    water_fill_zone_.sram_bit_mask = snapshot.water_fill_sram_bit_mask;
    for (const auto& block : snapshot.block_load_orders) {
      if (block.tile_object_index >= tile_objects_.size())
        continue;
      auto& object = tile_objects_[block.tile_object_index];
      if ((object.options() & ObjectOption::Block) != ObjectOption::Nothing) {
        object.set_block_load_order(block.load_order);
      }
    }
  }
 
  // For undo/redo functionality
  void SetTileObjects(const std::vector<RoomObject>& objects) {
    MarkTileObjectDomainsDirtyForSnapshot(tile_objects_);
    tile_objects_ = objects;
    objects_loaded_ = true;
    MarkTileObjectDomainsDirtyForSnapshot(tile_objects_);
    MarkObjectsDirty();
  }
 
  // Public setters for LoadRoomFromRom function
  void SetBg2(background2 bg2) {
    const uint8_t raw_value = static_cast<uint8_t>(bg2);
    const uint8_t normalized_value = raw_value <= 8 ? raw_value : 0;
    const bool dark_room = normalized_value == 8;
    const uint8_t next_layer2_mode =
        dark_room ? static_cast<uint8_t>(layer2_mode_ & 0x07)
                  : normalized_value;
    const LayerMergeType& next_merge =
        kLayerMergeTypeList[dark_room ? 8 : next_layer2_mode];
    const background2 normalized_bg2 =
        static_cast<background2>(normalized_value);
 
    if (bg2_ != normalized_bg2 || layer2_mode_ != next_layer2_mode ||
        layer_merging_ != next_merge || is_dark_ != dark_room ||
        is_light_ != dark_room) {
      bg2_ = normalized_bg2;
      layer2_mode_ = next_layer2_mode;
      layer_merging_ = next_merge;
      is_dark_ = dark_room;
      is_light_ = dark_room;
      MarkHeaderDirty();
      MarkGraphicsDirty();
    }
  }
  void SetCollision(CollisionKey collision) {
    if (collision_ != collision) {
      collision_ = collision;
      MarkHeaderDirty();
    }
  }
  void SetIsLight(bool is_light) {
    if (is_light_ != is_light) {
      is_light_ = is_light;
      MarkHeaderDirty();
    }
  }
  void SetPalette(uint8_t pal) {
    if (palette_ != pal) {
      palette_ = pal;
      MarkHeaderDirty();
      MarkGraphicsDirty();
    }
  }
  void SetBlockset(uint8_t bs) {
    if (blockset_ != bs) {
      blockset_ = bs;
      resolved_main_blockset_ = 0xFF;
      MarkHeaderDirty();
      MarkGraphicsDirty();
    }
  }
  void SetSpriteset(uint8_t ss) {
    if (spriteset_ != ss) {
      spriteset_ = ss;
      MarkHeaderDirty();
      MarkGraphicsDirty();
    }
  }
  void SetRenderEntranceBlockset(uint8_t entrance_blockset) {
    if (render_entrance_blockset_ != entrance_blockset) {
      render_entrance_blockset_ = entrance_blockset;
      resolved_main_blockset_ = 0xFF;
      MarkGraphicsDirty();
    }
  }
  void SetEffect(EffectKey effect) {
    if (effect_ != effect) {
      effect_ = effect;
      MarkHeaderDirty();
      MarkObjectsDirty();
    }
  }
  void SetTag1(TagKey tag1) {
    if (tag1_ != tag1) {
      tag1_ = tag1;
      MarkHeaderDirty();
      MarkObjectsDirty();
    }
  }
  void SetTag2(TagKey tag2) {
    if (tag2_ != tag2) {
      tag2_ = tag2;
      MarkHeaderDirty();
      MarkObjectsDirty();
    }
  }
  void SetStaircasePlane(int index, uint8_t plane) {
    if (index >= 0 && index < 4 && staircase_plane_[index] != plane) {
      staircase_plane_[index] = plane;
      MarkHeaderDirty();
    }
  }
  void SetHolewarp(uint8_t hw) {
    if (holewarp_ != hw) {
      holewarp_ = hw;
      MarkHeaderDirty();
    }
  }
  void SetStaircaseRoom(int index, uint8_t room) {
    if (index >= 0 && index < 4 && staircase_rooms_[index] != room) {
      staircase_rooms_[index] = room;
      MarkHeaderDirty();
    }
  }
  // SetFloor1/SetFloor2 removed - use set_floor1()/set_floor2() instead
  // (defined above)
  void SetMessageId(uint16_t mid) {
    if (message_id_ != mid) {
      message_id_ = mid;
      MarkHeaderDirty();
    }
  }
 
  // Getters for LoadRoomFromRom function
  bool IsLight() const { return is_light_; }
 
  // Additional setters for LoadRoomFromRom function
  void SetMessageIdDirect(uint16_t mid) {
    if (message_id_ != mid) {
      message_id_ = mid;
      MarkHeaderDirty();
    }
  }
  void SetLayer2Mode(uint8_t mode) {
    const uint8_t normalized_mode = mode & 0x07;
    if (layer2_mode_ != normalized_mode) {
      layer2_mode_ = normalized_mode;
      if (bg2_ != background2::DarkRoom) {
        bg2_ = static_cast<background2>(normalized_mode);
        layer_merging_ = kLayerMergeTypeList[normalized_mode];
      }
      MarkHeaderDirty();
      MarkGraphicsDirty();
    }
  }
  void SetLayerMerging(LayerMergeType merging) {
    if (layer_merging_ != merging) {
      layer_merging_ = merging;
      MarkHeaderDirty();
      MarkGraphicsDirty();
    }
  }
  void SetIsDark(bool is_dark) {
    if (is_dark_ != is_dark) {
      is_dark_ = is_dark;
      MarkHeaderDirty();
    }
  }
  void SetBackgroundTileset(uint8_t tileset) {
    if (background_tileset_ != tileset) {
      background_tileset_ = tileset;
      MarkHeaderDirty();
    }
  }
  void SetSpriteTileset(uint8_t tileset) {
    if (sprite_tileset_ != tileset) {
      sprite_tileset_ = tileset;
      MarkHeaderDirty();
    }
  }
  void SetLayer2Behavior(uint8_t behavior) {
    if (layer2_behavior_ != behavior) {
      layer2_behavior_ = behavior;
      MarkHeaderDirty();
    }
  }
  void SetTag1Direct(TagKey tag1) {
    if (tag1_ != tag1) {
      tag1_ = tag1;
      MarkHeaderDirty();
    }
  }
  void SetTag2Direct(TagKey tag2) {
    if (tag2_ != tag2) {
      tag2_ = tag2;
      MarkHeaderDirty();
    }
  }
  void SetPitsTargetLayer(uint8_t layer) {
    if (pits_.target_layer != layer) {
      pits_.target_layer = layer;
      MarkHeaderDirty();
    }
  }
  void SetStair1TargetLayer(uint8_t layer) {
    if (stair1_.target_layer != layer) {
      stair1_.target_layer = layer;
      MarkHeaderDirty();
    }
  }
  void SetStair2TargetLayer(uint8_t layer) {
    if (stair2_.target_layer != layer) {
      stair2_.target_layer = layer;
      MarkHeaderDirty();
    }
  }
  void SetStair3TargetLayer(uint8_t layer) {
    if (stair3_.target_layer != layer) {
      stair3_.target_layer = layer;
      MarkHeaderDirty();
    }
  }
  void SetStair4TargetLayer(uint8_t layer) {
    if (stair4_.target_layer != layer) {
      stair4_.target_layer = layer;
      MarkHeaderDirty();
    }
  }
  void SetPitsTarget(uint8_t target) {
    if (pits_.target != target) {
      pits_.target = target;
      MarkHeaderDirty();
    }
  }
  void SetStair1Target(uint8_t target) {
    if (stair1_.target != target) {
      stair1_.target = target;
      MarkHeaderDirty();
    }
  }
  void SetStair2Target(uint8_t target) {
    if (stair2_.target != target) {
      stair2_.target = target;
      MarkHeaderDirty();
    }
  }
  void SetStair3Target(uint8_t target) {
    if (stair3_.target != target) {
      stair3_.target = target;
      MarkHeaderDirty();
    }
  }
  void SetStair4Target(uint8_t target) {
    if (stair4_.target != target) {
      stair4_.target = target;
      MarkHeaderDirty();
    }
  }
 
  // Loaded state
  bool IsLoaded() const { return is_loaded_; }
  void SetLoaded(bool loaded) { is_loaded_ = loaded; }
  bool AreObjectsLoaded() const { return objects_loaded_; }
  bool AreSpritesLoaded() const { return sprites_loaded_; }
  bool AreChestsLoaded() const { return chests_loaded_; }
  bool ArePotItemsLoaded() const { return pot_items_loaded_; }
  bool AreTorchesLoaded() const { return torches_loaded_; }
  // True once `LoadBlocks` has populated `tile_objects_` for this room.
  // The `SaveAllBlocks` encoder uses this to distinguish header-only
  // rooms (preserve their existing ROM block bytes) from rooms whose
  // blocks have been fully materialized (encode from in-memory state,
  // which may include edits/additions/deletions).
  bool AreBlocksLoaded() const { return blocks_loaded_; }
 
  // Read-only accessors for metadata
  background2 bg2() const { return bg2_; }
  EffectKey effect() const { return effect_; }
  TagKey tag1() const { return tag1_; }
  TagKey tag2() const { return tag2_; }
  CollisionKey collision() const { return collision_; }
  const LayerMergeType& layer_merging() const { return layer_merging_; }
  uint8_t layer2_mode() const { return layer2_mode_; }
  // The PPU layer settings the game uses for this room on entry, given the
  // room's persistent flags (0: as first entered). See room_layer_registers.h.
  RoomLayerRegisters GameLayerRegisters(uint16_t room_flags = 0) const;
  uint8_t staircase_plane(int index) const {
    return (index >= 0 && index < 4) ? staircase_plane_[index] : 0;
  }
  // Raw header byte. Use staircase_destination_room() for the room id.
  uint8_t staircase_room(int index) const {
    return (index >= 0 && index < 4) ? staircase_rooms_[index] : 0;
  }
  // Destination room id of stair slot `index`, including this room's high
  // byte (see room_header_destination.h).
  int staircase_destination_room(int index) const {
    return ResolveHeaderDestinationRoom(room_id_, staircase_room(index));
  }
  // Destination room id of this room's pits and warp tiles.
  int holewarp_destination_room() const {
    return ResolveHeaderDestinationRoom(room_id_, holewarp_);
  }
 
  int id() const { return room_id_; }
 
  // Room header property accessors
  uint8_t blockset() const { return blockset_; }
  uint8_t render_entrance_blockset() const { return render_entrance_blockset_; }
  uint8_t resolved_main_blockset() const { return resolved_main_blockset_; }
  uint8_t spriteset() const { return spriteset_; }
  uint8_t palette() const { return palette_; }
 
  // Resolves the room's palette-set ID to the concrete dungeon_main palette
  // index (0-19) via the two-level ROM lookup. Returns 0 when game data is
  // missing or the resolved index is out of range. See palette_structure.md
  // "Dungeon Main" section for the lookup algorithm.
  int ResolveDungeonPaletteId() const;
  uint8_t layout_id() const { return layout_id_; }
  // Raw header byte. Use holewarp_destination_room() for the room id.
  uint8_t holewarp() const { return holewarp_; }
  uint16_t message_id() const { return message_id_; }
 
  // Layout ID setter (marks dirty)
  void SetLayoutId(uint8_t id) {
    if (layout_id_ != id) {
      layout_id_ = id;
      save_dirty_state_.object_stream_header |= kObjectHeaderLayoutDirty;
      MarkLayoutDirty();
    }
  }
 
  // Floor graphics accessors
  uint8_t floor1() const { return floor1_graphics_; }
  uint8_t floor2() const { return floor2_graphics_; }
  void set_floor1(uint8_t value) {
    if (floor1_graphics_ != value) {
      floor1_graphics_ = value;
      save_dirty_state_.object_stream_header |= kObjectHeaderFloor1Dirty;
      MarkGraphicsDirty();
    }
  }
  void set_floor2(uint8_t value) {
    if (floor2_graphics_ != value) {
      floor2_graphics_ = value;
      save_dirty_state_.object_stream_header |= kObjectHeaderFloor2Dirty;
      MarkGraphicsDirty();
    }
  }
  // Enhanced object parsing methods
  void ParseObjectsFromLocation(int objects_location);
  void HandleSpecialObjects(short oid, uint8_t posX, uint8_t posY,
                            int& nbr_of_staircase);
 
  // Object saving (Phase 1, Task 1.3)
  absl::Status SaveObjects(const DungeonStreamLayout* layout = nullptr);
  // Read-only save plans expose half-open PC ranges for the same direct or
  // copy-on-write writes as the matching Save method. Clean streams return {}.
  absl::StatusOr<std::vector<std::pair<uint32_t, uint32_t>>>
  GetObjectSaveWriteRanges(const DungeonStreamLayout* layout = nullptr) const;
  absl::Status SaveObjectStreamHeader(
      const DungeonStreamLayout* layout = nullptr);
  absl::StatusOr<std::vector<std::pair<uint32_t, uint32_t>>>
  GetObjectStreamHeaderSaveWriteRanges(
      const DungeonStreamLayout* layout = nullptr) const;
  std::vector<uint8_t> EncodeObjects() const;
  absl::Status SaveSprites(const DungeonStreamLayout* layout = nullptr);
  absl::StatusOr<std::vector<std::pair<uint32_t, uint32_t>>>
  GetSpriteSaveWriteRanges(const DungeonStreamLayout* layout = nullptr) const;
  std::vector<uint8_t> EncodeSprites() const;
  absl::Status SaveRoomHeader();
 
  auto blocks() const { return blocks_; }
  auto& mutable_blocks() { return blocks_; }
  auto rom() const { return rom_; }
  auto rom() { return rom_; }
  auto mutable_rom() { return rom_; }
  void SetRom(Rom* rom) { rom_ = rom; }
  auto game_data() { return game_data_; }
  const GameData* game_data() const { return game_data_; }
  void SetGameData(GameData* data) {
    if (game_data_ != data)
      rendered_palette_addresses_ = {};
    game_data_ = data;
  }
 
  void SetGraphicsSheetOverrides(
      std::map<uint16_t, std::vector<uint8_t>> overrides) {
    graphics_sheet_overrides_ = std::move(overrides);
    MarkGraphicsDirty();
  }
  const std::map<uint16_t, std::vector<uint8_t>>& graphics_sheet_overrides()
      const {
    return graphics_sheet_overrides_;
  }
 
  bool SourceSheetsChanged() const;
 
  // 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);
  }
  const std::array<uint8_t, 0x10000>& get_gfx_buffer() const {
    return current_gfx16_;
  }
  // Identifies the assembled pixels, including animated frame reloads. The
  // token survives moves and cannot collide with another room's reload count.
  uint64_t graphics_revision() const { return graphics_revision_; }
  // Identifies every source change that can alter a composed room image.
  // Unlike graphics_revision(), this also advances for object-only, layout,
  // palette, and direct composite invalidations.
  uint64_t composite_source_revision() const {
    return composite_source_revision_;
  }
  const gfx::SnesPalette& rendered_dungeon_palette() const {
    return rendered_dungeon_palette_;
  }
  const PaletteAddressMap& rendered_palette_addresses() const {
    return rendered_palette_addresses_;
  }
  const std::vector<SDL_Color>& rendered_palette() const {
    return rendered_palette_;
  }
  // Palette-half expansion applied to nonzero raw 3bpp background pixels.
  int BackgroundPaletteOffset(int slot) const;
 
  // Per-room background buffers (not shared via arena!)
  auto& bg1_buffer() { return bg1_buffer_; }
  auto& bg2_buffer() { return bg2_buffer_; }
  const auto& bg1_buffer() const { return bg1_buffer_; }
  const auto& bg2_buffer() const { return bg2_buffer_; }
  auto& object_bg1_buffer() { return object_bg1_buffer_; }
  const auto& object_bg1_buffer() const { return object_bg1_buffer_; }
  auto& object_bg2_buffer() { return object_bg2_buffer_; }
  const auto& object_bg2_buffer() const { return object_bg2_buffer_; }
 
  gfx::Bitmap& GetCompositeBitmap(RoomLayerManager& layer_mgr);
  void RenderComposite(const RoomLayerManager& layer_mgr, gfx::Bitmap& output);
  const gfx::Bitmap& composite_bitmap() const { return composite_bitmap_; }
 
  void MarkCompositeDirty();
  bool IsCompositeDirty() const { return dirty_state_.composite; }
 
  DungeonState* GetDungeonState() { return dungeon_state_.get(); }
  const DungeonState* GetDungeonState() const { return dungeon_state_.get(); }
 
 private:
  struct StreamSavePlan {
    std::vector<std::pair<uint32_t, std::vector<uint8_t>>> direct_writes;
    std::optional<std::pair<uint32_t, uint32_t>> direct_long_write;
    std::optional<DungeonStreamWritePlan> relocation;
 
    std::vector<std::pair<uint32_t, uint32_t>> write_ranges() const;
  };
  absl::StatusOr<StreamSavePlan> PlanObjectSave(
      const DungeonStreamLayout* layout) const;
  absl::StatusOr<StreamSavePlan> PlanSpriteSave(
      const DungeonStreamLayout* layout) const;
  absl::StatusOr<StreamSavePlan> PlanObjectStreamHeaderSave(
      const DungeonStreamLayout* layout) const;
  absl::Status ApplyStreamSavePlan(const StreamSavePlan& plan);
  Rom* rom_;
  GameData* game_data_ = nullptr;
 
  // Returns the 4096-byte 8bpp source for a sheet: an override when one is
  // set, otherwise the GameData buffer. Null when neither covers the sheet.
  const uint8_t* GraphicsSheetSource(int sheet_id) const;
  // Notes the store revision of a sheet copied from GameData (not overrides).
  void RecordSourceSheet(int sheet_id);
 
  std::array<uint8_t, 0x10000> current_gfx16_;
  std::map<uint16_t, std::vector<uint8_t>> graphics_sheet_overrides_;
  // Sheet id and store revision of each store sheet in current_gfx16_.
  std::vector<std::pair<uint16_t, uint64_t>> source_sheet_revisions_;
  uint64_t graphics_revision_ = 0;
  uint64_t composite_source_revision_ = 0;
  gfx::SnesPalette rendered_dungeon_palette_;
  std::vector<SDL_Color> rendered_palette_;
  PaletteAddressMap rendered_palette_addresses_{};
 
  // Each room has its OWN background buffers and bitmaps
  // Each room has its OWN background buffers and bitmaps
  gfx::BackgroundBuffer bg1_buffer_{512, 512};
  gfx::BackgroundBuffer bg2_buffer_{512, 512};
  gfx::BackgroundBuffer object_bg1_buffer_{512, 512};
  gfx::BackgroundBuffer object_bg2_buffer_{512, 512};
 
  struct DirtyState {
    bool graphics = true;
    bool objects = true;
    bool layout = true;
    bool textures = true;
    bool composite = true;
  };
 
  struct SaveDirtyState {
    bool header = false;
    bool object_stream = false;
    uint8_t object_stream_header = 0;
    bool sprites = false;
    bool chests = false;
    bool pot_items = false;
    bool torches = false;
    bool blocks = false;
  };
 
  static constexpr uint8_t kObjectHeaderFloor1Dirty = 1u << 0;
  static constexpr uint8_t kObjectHeaderFloor2Dirty = 1u << 1;
  static constexpr uint8_t kObjectHeaderLayoutDirty = 1u << 2;
 
  // Composite bitmap for merged layer output
  mutable gfx::Bitmap composite_bitmap_;
  mutable uint64_t composite_signature_ = 0;
  mutable uint64_t composite_rendered_source_revision_ = 0;
  mutable bool has_composite_signature_ = false;
  DirtyState dirty_state_;
  SaveDirtyState save_dirty_state_;
 
  bool is_light_ = false;
  bool is_loaded_ = false;
  bool objects_loaded_ = false;
  bool sprites_loaded_ = false;
  bool chests_loaded_ = false;
  bool pot_items_loaded_ = false;
  bool torches_loaded_ = false;
  bool blocks_loaded_ = false;
  bool is_dark_ = false;
  bool is_floor_ = true;
 
  // Performance optimization: Cache room properties to avoid unnecessary
  // re-renders
  uint8_t cached_blockset_ = 0xFF;
  uint8_t cached_spriteset_ = 0xFF;
  uint8_t cached_palette_ = 0xFF;
  uint8_t cached_layout_ = 0xFF;
  uint8_t cached_floor1_graphics_ = 0xFF;
  uint8_t cached_floor2_graphics_ = 0xFF;
  uint8_t cached_effect_ = 0xFF;
  TagKey cached_tag1_ = TagKey::Nothing;
  TagKey cached_tag2_ = TagKey::Nothing;
 
  int room_id_ = 0;
  int animated_frame_ = 0;
 
  uint8_t staircase_plane_[4]{};
  uint8_t staircase_rooms_[4]{};
 
  // Room header properties (formerly public)
  uint8_t blockset_ = 0;
  uint8_t render_entrance_blockset_ = 0xFF;
  uint8_t resolved_main_blockset_ = 0xFF;
  uint8_t spriteset_ = 0;
  uint8_t palette_ = 0;
  uint8_t layout_id_ = 0;
  uint8_t holewarp_ = 0;
  uint16_t message_id_ = 0;
 
  uint8_t background_tileset_ = 0;
  uint8_t sprite_tileset_ = 0;
  uint8_t layer2_behavior_ = 0;
  uint8_t floor1_graphics_ = 0;
  uint8_t floor2_graphics_ = 0;
  uint8_t layer2_mode_ = 0;
 
  std::array<uint8_t, 16> blocks_;
  std::array<chest, 16> chest_list_;
 
  std::vector<RoomObject> tile_objects_;
  // TODO: add separate door objects list when door section (F0 FF) is parsed
  std::vector<zelda3::Sprite> sprites_;
  std::vector<staircase> z3_staircases_;
  std::vector<chest_data> chests_in_room_;
  std::vector<Door> doors_;
  std::vector<PotItem> pot_items_;
  RoomLayout layout_;
 
  LayerMergeType layer_merging_ = LayerMerge00;
  CollisionKey collision_ = One_Collision;
  EffectKey effect_ = Effect_Nothing;
  TagKey tag1_ = Nothing;
  TagKey tag2_ = Nothing;
 
  background2 bg2_{};
  destination pits_{};
  destination stair1_{};
  destination stair2_{};
  destination stair3_{};
  destination stair4_{};
 
  CustomCollisionMap custom_collision_;
  bool custom_collision_dirty_ = false;
 
  WaterFillZoneMap water_fill_zone_;
  bool water_fill_dirty_ = false;
  int water_fill_tile_count_ = 0;
  std::unique_ptr<DungeonState> dungeon_state_;
};
 
// Loads a room from the ROM.
Room LoadRoomFromRom(Rom* rom, int room_id);
 
// Loads only the room header (metadata) from the ROM.
Room LoadRoomHeaderFromRom(Rom* rom, int room_id);
 
struct RoomSize {
  int64_t room_size_pointer;
  int64_t room_size;
};
 
// Calculates the size of a room in the ROM.
RoomSize CalculateRoomSize(Rom* rom, int room_id);
 
// Dungeon-level save: aggregate torches from all rooms and write to ROM.
absl::Status SaveAllTorches(Rom* rom, absl::Span<const Room> rooms);
absl::Status SaveAllTorches(Rom* rom, int room_count,
                            const std::function<const Room*(int)>& room_lookup);
// Validate and describe the exact torch writes without changing ROM or rooms.
// Returns no ranges when the merged table already matches the source ROM.
absl::StatusOr<std::vector<std::pair<uint32_t, uint32_t>>>
GetTorchSaveWriteRanges(const Rom* rom, int room_count,
                        const std::function<const Room*(int)>& room_lookup);
 
// Preserve pit count/pointer and table bytes, or encode an explicitly supplied
// dirty RoomsWithPitDamage table through the overload below.
absl::Status SaveAllPits(Rom* rom);
absl::Status SaveAllPits(Rom* rom, PitDamageTable* pit_damage_table);
 
// Preserve blocks length and the four block regions (read from ROM,
// write back). No edit support; legacy callers without per-room state
// keep this path. New callers should use the room-aware overload below.
absl::Status SaveAllBlocks(Rom* rom);
 
// Encode pushable blocks from loaded rooms back into the four
// pointer-dereferenced data regions while preserving unmaterialized entries.
// Existing blocks retain their committed `block_load_order_`; user-added
// blocks tail the buffer in creation order. After every ROM write succeeds,
// loaded objects are rebased to their emitted slots and encoded rooms become
// clean. Returns FailedPrecondition before mutation if a dirty room's blocks
// are not loaded, the final buffer is empty (the vanilla do-while scan requires
// one entry), or it exceeds the 128-entry vanilla cap (4 regions × 0x80 bytes /
// 4 bytes per entry).
absl::Status SaveAllBlocks(Rom* rom, int room_count,
                           const std::function<const Room*(int)>& room_lookup);
// Validate and describe the room-aware block serializer's exact write spans
// without changing ROM bytes, dirty flags, or block load-order identities.
absl::StatusOr<std::vector<std::pair<uint32_t, uint32_t>>>
GetBlockSaveWriteRanges(const Rom* rom, int room_count,
                        const std::function<const Room*(int)>& room_lookup);
 
// Save custom collision maps for any rooms marked dirty.
//
// This writes into the ZScream expanded collision region and updates the room
// pointer table. Rooms not loaded (or not dirty) are preserved.
absl::Status SaveAllCollision(Rom* rom, absl::Span<Room> rooms);
absl::Status SaveAllCollision(Rom* rom, int room_count,
                              const std::function<Room*(int)>& room_lookup);
 
// Scan all room sprite pointers and return the highest used PC address end.
int FindMaxUsedSpriteAddress(Rom* rom);
 
// Legacy compatibility helper: relocate a room's sprite payload into free tail
// space and update its pointer. The old stream is deliberately preserved;
// manifest-backed saves should use DungeonStreamAllocator instead.
absl::Status RelocateSpriteData(Rom* rom, int room_id,
                                const std::vector<uint8_t>& encoded_bytes);
 
// Returns the complete set of PC ranges that the global chest serializer may
// write: the two-byte runtime length operand and the live pointer target's
// fixed-capacity data region. The three-byte pointer operand itself is read
// only and is deliberately excluded.
absl::StatusOr<std::vector<std::pair<uint32_t, uint32_t>>>
GetChestTableWriteRanges(const Rom* rom);
 
struct ChestWriteRun {
  uint32_t pc = 0;
  std::vector<uint8_t> expected_bytes;
  std::vector<uint8_t> replacement_bytes;
 
  bool operator==(const ChestWriteRun&) const = default;
 
  uint32_t end() const {
    return pc + static_cast<uint32_t>(replacement_bytes.size());
  }
};
 
struct ChestDirtyRoomState {
  int room_id = 0;
  std::vector<uint8_t> encoded_chests;
 
  bool operator==(const ChestDirtyRoomState&) const = default;
};
 
// Chest serialization snapshot. It captures both the exact byte runs presented
// to manifest preflight and the source state required to apply those runs
// safely after other save domains have run. ApplyChestSavePlan reconstructs
// and compares the canonical plan before permitting any write.
struct ChestSavePlan {
  bool any_dirty = false;
  int room_limit = 0;
  uint32_t data_pc = 0;
  std::array<uint8_t, 3> pointer_operand{};
  uint16_t original_byte_length = 0;
  std::vector<uint8_t> original_capacity_bytes;
  std::vector<ChestWriteRun> writes;
  std::vector<ChestDirtyRoomState> dirty_rooms;
 
  bool operator==(const ChestSavePlan&) const = default;
 
  std::vector<std::pair<uint32_t, uint32_t>> write_ranges() const {
    std::vector<std::pair<uint32_t, uint32_t>> ranges;
    ranges.reserve(writes.size());
    for (const ChestWriteRun& write : writes) {
      ranges.emplace_back(write.pc, write.end());
    }
    return ranges;
  }
};
 
absl::StatusOr<ChestSavePlan> BuildChestSavePlan(
    const Rom* rom, int room_count,
    const std::function<const Room*(int)>& room_lookup);
absl::Status ApplyChestSavePlan(
    Rom* rom, const ChestSavePlan& plan,
    const std::function<const Room*(int)>& room_lookup);
 
// Plan the exact PC ranges changed by the current dirty-room chest state.
// One-for-one edits return only the affected record bytes; growth/removal may
// return wider runs plus the two-byte runtime length operand. The same plan is
// used by manifest preflight and SaveAllChests so protected bytes that are not
// actually changing do not block an otherwise safe edit.
absl::StatusOr<std::vector<std::pair<uint32_t, uint32_t>>>
GetDirtyChestWriteRanges(const Rom* rom, int room_count,
                         const std::function<const Room*(int)>& room_lookup);
 
// Aggregate chests from all rooms and write to ROM. Dirty rooms replace their
// existing occurrences one-for-one in physical-table order. Untouched and
// unknown-room records retain their exact bytes and relative order; surplus
// occurrences are removed and additional records are appended by room ID.
absl::Status SaveAllChests(Rom* rom, absl::Span<const Room> rooms);
absl::Status SaveAllChests(Rom* rom, int room_count,
                           const std::function<const Room*(int)>& room_lookup);
 
// Save pot items for all rooms. Preserves ROM data for rooms not loaded.
absl::Status SaveAllPotItems(Rom* rom, absl::Span<const Room> rooms);
absl::Status SaveAllPotItems(Rom* rom, absl::Span<const Room> rooms,
                             const DungeonStreamLayout* repack_layout);
absl::Status SaveAllPotItems(
    Rom* rom, int room_count,
    const std::function<const Room*(int)>& room_lookup);
absl::Status SaveAllPotItems(Rom* rom, int room_count,
                             const std::function<const Room*(int)>& room_lookup,
                             const DungeonStreamLayout* repack_layout);
 
// RoomEffect names defined in room.cc to avoid static initialization order issues
extern const std::string RoomEffect[8];
 
constexpr std::array<std::string_view, 297> kRoomNames = {
    "Ganon",
    "Hyrule Castle (North Corridor)",
    "Behind Sanctuary (Switch)",
    "Houlihan",
    "Turtle Rock (Crysta-Roller)",
    "Empty",
    "Swamp Palace (Arrghus[Boss])",
    "Tower of Hera (Moldorm[Boss])",
    "Cave (Healing Fairy)",
    "Palace of Darkness",
    "Palace of Darkness (Stalfos Trap)",
    "Palace of Darkness (Turtle)",
    "Ganon's Tower (Entrance)",
    "Ganon's Tower (Agahnim2[Boss])",
    "Ice Palace (Entrance )",
    "Empty Clone ",
    "Ganon Evacuation Route",
    "Hyrule Castle (Bombable Stock )",
    "Sanctuary",
    "Turtle Rock (Hokku-Bokku Key 2)",
    "Turtle Rock (Big Key )",
    "Turtle Rock",
    "Swamp Palace (Swimming Treadmill)",
    "Tower of Hera (Moldorm Fall )",
    "Cave",
    "Palace of Darkness (Dark Maze)",
    "Palace of Darkness (Big Chest )",
    "Palace of Darkness (Mimics / Moving Wall )",
    "Ganon's Tower (Ice Armos)",
    "Ganon's Tower (Final Hallway)",
    "Ice Palace (Bomb Floor / Bari )",
    "Ice Palace (Pengator / Big Key )",
    "Agahnim's Tower (Agahnim[Boss])",
    "Hyrule Castle (Key-rat )",
    "Hyrule Castle (Sewer Text Trigger )",
    "Turtle Rock (West Exit to Balcony)",
    "Turtle Rock (Double Hokku-Bokku / Big chest )",
    "Empty Clone ",
    "Swamp Palace (Statue )",
    "Tower of Hera (Big Chest)",
    "Swamp Palace (Entrance )",
    "Skull Woods (Mothula[Boss])",
    "Palace of Darkness (Big Hub )",
    "Palace of Darkness (Map Chest / Fairy )",
    "Cave",
    "Empty Clone ",
    "Ice Palace (Compass )",
    "Cave (Kakariko Well HP)",
    "Agahnim's Tower (Maiden Sacrifice Chamber)",
    "Tower of Hera (Hardhat Beetles )",
    "Hyrule Castle (Sewer Key Chest )",
    "Desert Palace (Lanmolas[Boss])",
    "Swamp Palace (Push Block Puzzle / Pre-Big Key )",
    "Swamp Palace (Big Key / BS )",
    "Swamp Palace (Big Chest )",
    "Swamp Palace (Map Chest / Water Fill )",
    "Swamp Palace (Key Pot )",
    "Skull Woods (Gibdo Key / Mothula Hole )",
    "Palace of Darkness (Bombable Floor )",
    "Palace of Darkness (Spike Block / Conveyor )",
    "Cave",
    "Ganon's Tower (Torch 2)",
    "Ice Palace (Stalfos Knights / Conveyor Hellway)",
    "Ice Palace (Map Chest )",
    "Agahnim's Tower (Final Bridge )",
    "Hyrule Castle (First Dark )",
    "Hyrule Castle (6 Ropes )",
    "Desert Palace (Torch Puzzle / Moving Wall )",
    "Thieves Town (Big Chest )",
    "Thieves Town (Jail Cells )",
    "Swamp Palace (Compass Chest )",
    "Empty Clone ",
    "Empty Clone ",
    "Skull Woods (Gibdo Torch Puzzle )",
    "Palace of Darkness (Entrance )",
    "Palace of Darkness (Warps / South Mimics )",
    "Ganon's Tower (Mini-Helmasaur Conveyor )",
    "Ganon's Tower (Moldorm )",
    "Ice Palace (Bomb-Jump )",
    "Ice Palace Clone (Fairy )",
    "Hyrule Castle (West Corridor)",
    "Hyrule Castle (Throne )",
    "Hyrule Castle (East Corridor)",
    "Desert Palace (Popos 2 / Beamos Hellway )",
    "Swamp Palace (Upstairs Pits )",
    "Castle Secret Entrance / Uncle Death ",
    "Skull Woods (Key Pot / Trap )",
    "Skull Woods (Big Key )",
    "Skull Woods (Big Chest )",
    "Skull Woods (Final Section Entrance )",
    "Palace of Darkness (Helmasaur King[Boss])",
    "Ganon's Tower (Spike Pit )",
    "Ganon's Tower (Ganon-Ball Z)",
    "Ganon's Tower (Gauntlet 1/2/3)",
    "Ice Palace (Lonely Firebar)",
    "Ice Palace (Hidden Chest / Spike Floor )",
    "Hyrule Castle (West Entrance )",
    "Hyrule Castle (Main Entrance )",
    "Hyrule Castle (East Entrance )",
    "Desert Palace (Final Section Entrance )",
    "Thieves Town (West Attic )",
    "Thieves Town (East Attic )",
    "Swamp Palace (Hidden Chest / Hidden Door )",
    "Skull Woods (Compass Chest )",
    "Skull Woods (Key Chest / Trap )",
    "Empty Clone ",
    "Palace of Darkness (Rupee )",
    "Ganon's Tower (Mimics s)",
    "Ganon's Tower (Lanmolas )",
    "Ganon's Tower (Gauntlet 4/5)",
    "Ice Palace (Pengators )",
    "Empty Clone ",
    "Hyrule Castle (Small Corridor to Jail Cells)",
    "Hyrule Castle (Boomerang Chest )",
    "Hyrule Castle (Map Chest )",
    "Desert Palace (Big Chest )",
    "Desert Palace (Map Chest )",
    "Desert Palace (Big Key Chest )",
    "Swamp Palace (Water Drain )",
    "Tower of Hera (Entrance )",
    "Empty Clone ",
    "Empty Clone ",
    "Empty Clone ",
    "Ganon's Tower",
    "Ganon's Tower (East Side Collapsing Bridge / Exploding Wall )",
    "Ganon's Tower (Winder / Warp Maze )",
    "Ice Palace (Hidden Chest / Bombable Floor )",
    "Ice Palace ( Big Spike Traps )",
    "Hyrule Castle (Jail Cell )",
    "Hyrule Castle",
    "Hyrule Castle (Basement Chasm )",
    "Desert Palace (West Entrance )",
    "Desert Palace (Main Entrance )",
    "Desert Palace (East Entrance )",
    "Empty Clone ",
    "Tower of Hera (Tile )",
    "Empty Clone ",
    "Eastern Palace (Fairy )",
    "Empty Clone ",
    "Ganon's Tower (Block Puzzle / Spike Skip / Map Chest )",
    "Ganon's Tower (East and West Downstairs / Big Chest )",
    "Ganon's Tower (Tile / Torch Puzzle )",
    "Ice Palace",
    "Empty Clone ",
    "Misery Mire (Vitreous[Boss])",
    "Misery Mire (Final Switch )",
    "Misery Mire (Dark Bomb Wall / Switches )",
    "Misery Mire (Dark Cane Floor Switch Puzzle )",
    "Empty Clone ",
    "Ganon's Tower (Final Collapsing Bridge )",
    "Ganon's Tower (Torches 1 )",
    "Misery Mire (Torch Puzzle / Moving Wall )",
    "Misery Mire (Entrance )",
    "Eastern Palace (Eyegore Key )",
    "Empty Clone ",
    "Ganon's Tower (Many Spikes / Warp Maze )",
    "Ganon's Tower (Invisible Floor Maze )",
    "Ganon's Tower (Compass Chest / Invisible Floor )",
    "Ice Palace (Big Chest )",
    "Ice Palace",
    "Misery Mire (Pre-Vitreous )",
    "Misery Mire (Fish )",
    "Misery Mire (Bridge Key Chest )",
    "Misery Mire",
    "Turtle Rock (Trinexx[Boss])",
    "Ganon's Tower (Wizzrobes s)",
    "Ganon's Tower (Moldorm Fall )",
    "Tower of Hera (Fairy )",
    "Eastern Palace (Stalfos Spawn )",
    "Eastern Palace (Big Chest )",
    "Eastern Palace (Map Chest )",
    "Thieves Town (Moving Spikes / Key Pot )",
    "Thieves Town (Blind The Thief[Boss])",
    "Empty Clone ",
    "Ice Palace",
    "Ice Palace (Ice Bridge )",
    "Agahnim's Tower (Circle of Pots)",
    "Misery Mire (Hourglass )",
    "Misery Mire (Slug )",
    "Misery Mire (Spike Key Chest )",
    "Turtle Rock (Pre-Trinexx )",
    "Turtle Rock (Dark Maze)",
    "Turtle Rock (Chain Chomps )",
    "Turtle Rock (Map Chest / Key Chest / Roller )",
    "Eastern Palace (Big Key )",
    "Eastern Palace (Lobby Cannonballs )",
    "Eastern Palace (Dark Antifairy / Key Pot )",
    "Thieves Town (Hellway)",
    "Thieves Town (Conveyor Toilet)",
    "Empty Clone ",
    "Ice Palace (Block Puzzle )",
    "Ice Palace Clone (Switch )",
    "Agahnim's Tower (Dark Bridge )",
    "Misery Mire (Compass Chest / Tile )",
    "Misery Mire (Big Hub )",
    "Misery Mire (Big Chest )",
    "Turtle Rock (Final Crystal Switch Puzzle )",
    "Turtle Rock (Laser Bridge)",
    "Turtle Rock",
    "Turtle Rock (Torch Puzzle)",
    "Eastern Palace (Armos Knights[Boss])",
    "Eastern Palace (Entrance )",
    "??",
    "Thieves Town (North West Entrance )",
    "Thieves Town (North East Entrance )",
    "Empty Clone ",
    "Ice Palace (Hole to Kholdstare )",
    "Empty Clone ",
    "Agahnim's Tower (Dark Maze)",
    "Misery Mire (Conveyor Slug / Big Key )",
    "Misery Mire (Mire02 / Wizzrobes )",
    "Empty Clone ",
    "Empty Clone ",
    "Turtle Rock (Laser Key )",
    "Turtle Rock (Entrance )",
    "Empty Clone ",
    "Eastern Palace (Zeldagamer / Pre-Armos Knights )",
    "Eastern Palace (Canonball ",
    "Eastern Palace",
    "Thieves Town (Main (South West) Entrance )",
    "Thieves Town (South East Entrance )",
    "Empty Clone ",
    "Ice Palace (Kholdstare[Boss])",
    "Cave",
    "Agahnim's Tower (Entrance )",
    "Cave (Lost Woods HP)",
    "Cave (Lumberjack's Tree HP)",
    "Cave (1/2 Magic)",
    "Cave (Lost Old Man Final Cave)",
    "Cave (Lost Old Man Final Cave)",
    "Cave",
    "Cave",
    "Cave",
    "Empty Clone ",
    "Cave (Spectacle Rock HP)",
    "Cave",
    "Empty Clone ",
    "Cave",
    "Cave (Spiral Cave)",
    "Cave (Crystal Switch / 5 Chests )",
    "Cave (Lost Old Man Starting Cave)",
    "Cave (Lost Old Man Starting Cave)",
    "House",
    "House (Old Woman (Sahasrahla's Wife?))",
    "House (Angry Brothers)",
    "House (Angry Brothers)",
    "Empty Clone ",
    "Empty Clone ",
    "Cave",
    "Cave",
    "Cave",
    "Cave",
    "Empty Clone ",
    "Cave",
    "Cave",
    "Cave",
 
    "Chest Minigame",
    "Houses",
    "Sick Boy house",
    "Tavern",
    "Link's House",
    "Sarashrala Hut",
    "Chest Minigame",
    "Library",
    "Chicken House",
    "Witch Shop",
    "A Aginah's Cave",
    "Dam",
    "Mimic Cave",
    "Mire Shed",
    "Cave",
    "Shop",
    "Shop",
    "Archery Minigame",
    "DW Church/Shop",
    "Grave Cave",
    "Fairy Fountain",
    "Fairy Upgrade",
    "Pyramid Fairy",
    "Spike Cave",
    "Chest Minigame",
    "Blind Hut",
    "Bonzai Cave",
    "Circle of bush Cave",
    "Big Bomb Shop, C-House",
    "Blind Hut 2",
    "Hype Cave",
    "Shop",
    "Ice Cave",
    "Smith",
    "Fortune Teller",
    "MiniMoldorm Cave",
    "Under Rock Caves",
    "Smith",
    "Cave",
    "Mazeblock Cave",
    "Smith Peg Cave"};
 
// RoomTag names defined in room.cc to avoid static initialization order issues
extern const std::string RoomTag[65];
 
}  // namespace zelda3
}  // namespace yaze
 
#endif