object_tile_editor.cc

Go to the documentation of this file.

#include "zelda3/dungeon/object_tile_editor.h"
 
#include <algorithm>
#include <array>
#include <cstring>
#include <limits>
#include <unordered_map>
#include <unordered_set>
 
#include "absl/strings/str_format.h"
#include "app/gfx/types/snes_tile.h"
#include "core/features.h"
#include "rom/transaction.h"
#include "util/log.h"
#include "util/macro.h"
#include "zelda3/dungeon/custom_object.h"
#include "zelda3/dungeon/geometry/object_geometry.h"
#include "zelda3/dungeon/object_drawer.h"
#include "zelda3/dungeon/room_object.h"
 
namespace yaze {
namespace zelda3 {
 
namespace {
 
absl::Status CheckPatternSourceReadOnly(int64_t begin, int64_t end) {
  const auto patterns = CustomObjectManager::Get().GetTilePatterns();
  if (!patterns.ok())
    return patterns.status();
  if (*patterns && begin >= 0) {
    const auto it =
        (*patterns)->words.lower_bound(static_cast<uint32_t>(begin));
    if (it != (*patterns)->words.end() && it->first < end) {
      return absl::FailedPreconditionError(
          "Object tile words are supplied by a pattern source; reopen the "
          "object tile editor to edit the source file");
    }
  }
  return absl::OkStatus();
}
 
constexpr int kPaletteBankSize = 16;
 
gfx::SnesPalette BuildPaddedPaletteBank(const gfx::SnesPalette& source) {
  gfx::SnesPalette padded;
  for (size_t i = 0; i < static_cast<size_t>(kPaletteBankSize); ++i) {
    if (i < source.size()) {
      padded.AddColor(source[i]);
    } else {
      padded.AddColor(gfx::SnesColor());
    }
  }
  return padded;
}
 
gfx::SnesPalette BuildCombinedPaletteBanks(const gfx::PaletteGroup& palette) {
  gfx::SnesPalette combined;
  for (int i = 0; i < palette.size(); ++i) {
    const auto padded = BuildPaddedPaletteBank(palette.palette_ref(i));
    for (size_t color = 0; color < padded.size(); ++color) {
      combined.AddColor(padded[color]);
    }
  }
  return combined;
}
 
int ResolvePaletteIndex(const gfx::PaletteGroup& palette, int requested) {
  if (palette.empty()) {
    return 0;
  }
  if (requested >= 0 && requested < static_cast<int>(palette.size())) {
    return requested;
  }
  return 0;
}
 
struct EditableShape {
  int width;
  int height;
  bool row_major;
  uint8_t capture_size;
  size_t word_count() const { return static_cast<size_t>(width * height); }
};
 
std::optional<EditableShape> ShapeForObject(int16_t id) {
  // Bank 01: Nx4 consumes columns; 4xN consumes rows. Size 1 gives
  // exactly one repeating wall unit (size 0 means 26 units).
  if (id == 0x01 || id == 0x02)
    return EditableShape{2, 4, false, 1};
  if (id == 0x61 || id == 0x62)
    return EditableShape{4, 2, true, 1};
  if (id == 0x03 || id == 0x04)
    return EditableShape{2, 4, false, 0};
  if (id == 0x63 || id == 0x64)
    return EditableShape{4, 2, true, 0};
  if (id >= 0x100 && id <= 0x107)
    return EditableShape{4, 4, false, 0};
  if (id == 0x11F || id == 0x120)
    return EditableShape{2, 2, false, 0};
  return std::nullopt;
}
 
uint32_t DescriptorForObject(int16_t id) {
  return id < 0x100 ? kRoomObjectSubtype1 + id * 2
                    : kRoomObjectSubtype2 + (id - 0x100) * 2;
}
 
absl::Status ValidatePatternContext(const DungeonTilePatterns& expected) {
  const auto active = CustomObjectManager::Get().GetTilePatterns();
  if (!active.ok())
    return active.status();
  if (!*active || (*active)->source_path != expected.source_path) {
    return absl::AbortedError("Object pattern source changed with the project");
  }
  auto current = LoadDungeonTilePatterns(expected.source_path);
  if (!current.ok())
    return current.status();
  if (current->source_text != expected.source_text) {
    return absl::AbortedError("Object pattern source changed after capture");
  }
  return absl::OkStatus();
}
 
// The subtype tile-descriptor and routine-pointer tables are contiguous from
// the first Type-1 descriptor through the two 128-word Type-3 tables. None of
// this metadata is tile data, so an audited object source must never alias it.
constexpr int64_t kObjectMetadataStart = kRoomObjectSubtype1;
constexpr int64_t kObjectMetadataEnd = kRoomObjectSubtype3 + 0x200;
 
bool RangesOverlap(int64_t lhs_start, int64_t lhs_end, int64_t rhs_start,
                   int64_t rhs_end) {
  return lhs_start < rhs_end && rhs_start < lhs_end;
}
 
bool WordRangesOverlap(int64_t lhs_address, int64_t rhs_address) {
  return RangesOverlap(lhs_address, lhs_address + 2, rhs_address,
                       rhs_address + 2);
}
 
absl::StatusOr<size_t> ResolveSourceWordIndex(
    const ObjectTileLayout::Cell& cell, const EditableShape& shape) {
  if (cell.rel_x < 0 || cell.rel_x >= shape.width || cell.rel_y < 0 ||
      cell.rel_y >= shape.height) {
    return absl::FailedPreconditionError(
        "Editable object cell is outside the audited layout");
  }
  return static_cast<size_t>(shape.row_major
                                 ? cell.rel_y * shape.width + cell.rel_x
                                 : cell.rel_x * shape.height + cell.rel_y);
}
 
}  // namespace
 
// =============================================================================
// ObjectTileLayout
// =============================================================================
 
ObjectTileLayout ObjectTileLayout::FromTraces(
    const std::vector<ObjectDrawer::TileTrace>& traces) {
  ObjectTileLayout layout;
  if (traces.empty()) {
    return layout;
  }
 
  layout.object_id = static_cast<int16_t>(traces[0].object_id);
 
  // Find bounding box
  int min_x = traces[0].x_tile;
  int min_y = traces[0].y_tile;
  int max_x = min_x;
  int max_y = min_y;
  for (const auto& t : traces) {
    min_x = std::min(min_x, static_cast<int>(t.x_tile));
    min_y = std::min(min_y, static_cast<int>(t.y_tile));
    max_x = std::max(max_x, static_cast<int>(t.x_tile));
    max_y = std::max(max_y, static_cast<int>(t.y_tile));
  }
 
  layout.origin_tile_x = min_x;
  layout.origin_tile_y = min_y;
  layout.bounds_width = max_x - min_x + 1;
  layout.bounds_height = max_y - min_y + 1;
 
  std::unordered_map<uint32_t, size_t> last_trace_by_cell;
  last_trace_by_cell.reserve(traces.size());
  for (size_t i = 0; i < traces.size(); ++i) {
    const auto& t = traces[i];
    const uint32_t cell_key =
        (static_cast<uint32_t>(static_cast<uint16_t>(t.x_tile)) << 16) |
        static_cast<uint16_t>(t.y_tile);
    last_trace_by_cell[cell_key] = i;
  }
 
  std::vector<size_t> surviving_trace_indices;
  surviving_trace_indices.reserve(last_trace_by_cell.size());
  for (const auto& [_, trace_index] : last_trace_by_cell) {
    surviving_trace_indices.push_back(trace_index);
  }
  std::sort(surviving_trace_indices.begin(), surviving_trace_indices.end());
 
  layout.cells.reserve(surviving_trace_indices.size());
  for (size_t trace_index : surviving_trace_indices) {
    const auto& t = traces[trace_index];
    Cell cell;
    cell.rel_x = t.x_tile - min_x;
    cell.rel_y = t.y_tile - min_y;
 
    // Reconstruct TileInfo from trace fields
    bool h_mirror = (t.flags & 0x1) != 0;
    bool v_mirror = (t.flags & 0x2) != 0;
    bool priority = (t.flags & 0x4) != 0;
    uint8_t palette = (t.flags >> 3) & 0x7;
    cell.tile_info =
        gfx::TileInfo(t.tile_id, palette, v_mirror, h_mirror, priority);
    cell.original_word = gfx::TileInfoToWord(cell.tile_info);
    cell.write_index = static_cast<int>(trace_index);
    cell.modified = false;
 
    layout.cells.push_back(cell);
  }
 
  return layout;
}
 
ObjectTileLayout::Cell* ObjectTileLayout::FindCell(int rel_x, int rel_y) {
  for (auto& cell : cells) {
    if (cell.rel_x == rel_x && cell.rel_y == rel_y)
      return &cell;
  }
  return nullptr;
}
 
const ObjectTileLayout::Cell* ObjectTileLayout::FindCell(int rel_x,
                                                         int rel_y) const {
  for (const auto& cell : cells) {
    if (cell.rel_x == rel_x && cell.rel_y == rel_y)
      return &cell;
  }
  return nullptr;
}
 
bool ObjectTileLayout::HasModifications() const {
  for (const auto& cell : cells) {
    if (cell.modified)
      return true;
  }
  return false;
}
 
void ObjectTileLayout::RevertAll() {
  for (auto& cell : cells) {
    if (cell.modified) {
      cell.tile_info = gfx::WordToTileInfo(cell.original_word);
      cell.modified = false;
    }
  }
}
 
// =============================================================================
// ObjectTileEditor
// =============================================================================
 
ObjectTileEditor::ObjectTileEditor(Rom* rom) : rom_(rom) {}
 
absl::StatusOr<ObjectTileLayout> ObjectTileEditor::LoadCustomObjectLayout(
    int16_t object_id, int subtype) {
  const int runtime_count =
      CustomObjectManager::RuntimeSubtypeCountForObject(object_id);
  if (runtime_count == 0) {
    return absl::UnimplementedError(
        "Custom tile editing supports only registered fixed runtime objects");
  }
  if (subtype < 0 || subtype >= runtime_count) {
    return absl::OutOfRangeError(
        "Custom object subtype is outside the runtime dispatch table");
  }
 
  auto& manager = CustomObjectManager::Get();
  const std::string filename = manager.ResolveFilename(object_id, subtype);
  if (filename.empty()) {
    return absl::NotFoundError(
        "Custom object runtime slot has no mapped asset filename");
  }
  CustomObjectAsset asset;
  ASSIGN_OR_RETURN(asset,
                   LoadCustomObjectAsset(manager.GetBasePath(), filename));
 
  ObjectTileLayout layout;
  layout.object_id = object_id;
  layout.origin_tile_x = 0;
  layout.origin_tile_y = 0;
  layout.tile_data_address = -1;
  layout.is_custom = true;
  layout.custom_subtype = subtype;
  layout.custom_filename = filename;
  layout.custom_resolved_path = std::move(asset.resolved_path);
  layout.custom_source_bytes = std::move(asset.source_bytes);
 
  const auto bounds = asset.object.GetBoundingBox();
  layout.bounds_width = bounds.max_x + 1;
  layout.bounds_height = bounds.max_y + 1;
  layout.cells.reserve(asset.object.tiles.size());
  for (const auto& tile : asset.object.tiles) {
    ObjectTileLayout::Cell cell;
    cell.rel_x = tile.rel_x;
    cell.rel_y = tile.rel_y;
    cell.tile_info = gfx::WordToTileInfo(tile.tile_data);
    cell.original_word = tile.tile_data;
    cell.write_index = static_cast<int>(layout.cells.size());
    layout.cells.push_back(cell);
  }
  return layout;
}
 
absl::StatusOr<ObjectTileLayout> ObjectTileEditor::CaptureObjectLayout(
    int16_t object_id, const Room& room, const gfx::PaletteGroup& palette) {
  return CaptureObjectLayout(object_id, room, palette,
                             DefaultRoomObjectSizeForPlacement(object_id));
}
 
absl::StatusOr<ObjectTileLayout> ObjectTileEditor::CaptureObjectLayout(
    int16_t object_id, const Room& room, const gfx::PaletteGroup& palette,
    uint8_t object_size) {
  if (!rom_ || !rom_->is_loaded()) {
    return absl::FailedPreconditionError("ROM not loaded");
  }
 
  // Resolve the canvas anchor through ObjectGeometry so routines that
  // draw upward or leftward (acute diagonals 0x09-0x14 / 0x15-0x20,
  // diagonal ceilings 0xA0-0xAC) replay their full extent without
  // clipping. Hardcoded (2, 2) previously
  // dropped tile writes at negative tile coordinates because
  // DrawRoutineUtils::WriteTile8 short-circuits via IsValidTilePosition
  // before invoking the trace hook.
  const uint8_t preview_size = CanonicalRoomObjectSize(object_id, object_size);
  auto [anchor_x, anchor_y] =
      ObjectGeometry::Get().ResolveAnchor(object_id, preview_size);
  RoomObject obj(object_id, anchor_x, anchor_y, preview_size, 0);
  obj.SetRom(rom_);
  obj.EnsureTilesLoaded();
 
  // Check if this is a custom object
  bool is_custom = false;
  std::string custom_filename;
  int subtype = obj.size_ & 0x1F;
  if (core::FeatureFlags::get().kEnableCustomObjects) {
    auto custom_result =
        CustomObjectManager::Get().GetObjectInternal(object_id, subtype);
    if (custom_result.ok()) {
      is_custom = true;
      custom_filename =
          CustomObjectManager::Get().ResolveFilename(object_id, subtype);
    }
  }
 
  // Create drawer and set up trace collection
  ObjectDrawer drawer(rom_, room.id(), room.get_gfx_buffer().data());
  drawer.SetRoomFloorGraphics(room.floor1(), room.floor2());
 
  std::vector<ObjectDrawer::TileTrace> traces;
  traces.reserve(256);
  drawer.SetTraceCollector(&traces, /*trace_only=*/true);
 
  // Draw the object to collect traces
  gfx::BackgroundBuffer dummy_bg1(512, 512);
  gfx::BackgroundBuffer dummy_bg2(512, 512);
  auto status = drawer.DrawObject(obj, dummy_bg1, dummy_bg2, palette);
  drawer.ClearTraceCollector();
 
  if (!status.ok()) {
    return status;
  }
 
  if (traces.empty()) {
    return absl::NotFoundError("Object produced no tile traces");
  }
 
  // Build layout from traces
  ObjectTileLayout layout = ObjectTileLayout::FromTraces(traces);
  // A draw trace proves visual placement, not ROM source ownership. Keep
  // generic captures preview-only even when RoomObject happens to expose a
  // legacy tile-data pointer.
  layout.tile_data_address = -1;
  layout.source_provenance.reset();
  layout.is_custom = is_custom;
  layout.custom_subtype = is_custom ? subtype : -1;
  layout.custom_filename = custom_filename;
 
  return layout;
}
 
bool ObjectTileEditor::IsEditableStandardObject(int16_t object_id) {
  return ShapeForObject(object_id).has_value();
}
 
absl::StatusOr<ObjectTileLayout> ObjectTileEditor::CaptureEditableObjectLayout(
    int16_t object_id, const Room& room, const gfx::PaletteGroup& palette) {
  if (!IsEditableStandardObject(object_id)) {
    return absl::UnimplementedError(
        "Standard object tile editing is not supported for this object");
  }
  if (rom_ == nullptr || !rom_->is_loaded()) {
    return absl::FailedPreconditionError("ROM not loaded");
  }
 
  const auto shape = *ShapeForObject(object_id);
  const uint32_t descriptor_pc_address = DescriptorForObject(object_id);
  auto descriptor_or = rom_->ReadWord(static_cast<int>(descriptor_pc_address));
  if (!descriptor_or.ok()) {
    return descriptor_or.status();
  }
  const uint16_t descriptor_word = *descriptor_or;
  const int64_t source_address =
      static_cast<int64_t>(kRoomObjectTileAddress) + descriptor_word;
  if (source_address < 0 ||
      source_address + static_cast<int64_t>(shape.word_count() * 2) >
          static_cast<int64_t>(rom_->size()) ||
      source_address > std::numeric_limits<int>::max()) {
    return absl::OutOfRangeError(
        "Editable object tile source is outside the loaded ROM");
  }
  const int64_t source_end =
      source_address + static_cast<int64_t>(shape.word_count() * 2);
  if (RangesOverlap(source_address, source_end, kObjectMetadataStart,
                    kObjectMetadataEnd)) {
    return absl::FailedPreconditionError(
        "Editable object tile source overlaps object descriptor or routine "
        "metadata");
  }
 
  auto patterns = CustomObjectManager::Get().GetTilePatterns();
  if (!patterns.ok())
    return patterns.status();
  std::shared_ptr<const DungeonTilePatterns> pattern_source;
  if (*patterns) {
    size_t covered = 0;
    for (int64_t pc = source_address; pc < source_end; pc += 2) {
      covered += (*patterns)->words.count(static_cast<uint32_t>(pc));
    }
    if (covered != 0 && covered != shape.word_count()) {
      return absl::FailedPreconditionError(
          "Object mixes ROM and source-file tiles; edit its complete source "
          "pattern first");
    }
    if (covered)
      pattern_source = *patterns;
  }
  auto layout_or =
      CaptureObjectLayout(object_id, room, palette, shape.capture_size);
  if (!layout_or.ok()) {
    return layout_or.status();
  }
  ObjectTileLayout layout = std::move(*layout_or);
  if (layout.is_custom) {
    return absl::FailedPreconditionError(
        "Custom objects do not use standard ROM source provenance");
  }
  if (layout.object_id != object_id ||
      layout.cells.size() != shape.word_count() ||
      layout.bounds_width != shape.width ||
      layout.bounds_height != shape.height) {
    return absl::FailedPreconditionError(
        "Object draw does not match the audited source layout");
  }
 
  ObjectTileSourceSpan span;
  span.pc_address = static_cast<uint32_t>(source_address);
  span.expected_words.reserve(shape.word_count());
  for (size_t word_index = 0; word_index < shape.word_count(); ++word_index) {
    auto word_or =
        rom_->ReadWord(static_cast<int>(span.pc_address + word_index * 2));
    if (!word_or.ok()) {
      return word_or.status();
    }
    span.expected_words.push_back(
        pattern_source
            ? pattern_source->words.at(span.pc_address + word_index * 2)
            : *word_or);
  }
 
  std::vector<bool> mapped_words(shape.word_count(), false);
  for (auto& cell : layout.cells) {
    auto source_word_index_or = ResolveSourceWordIndex(cell, shape);
    if (!source_word_index_or.ok()) {
      return source_word_index_or.status();
    }
    const size_t source_word_index = *source_word_index_or;
    if (mapped_words[source_word_index]) {
      return absl::FailedPreconditionError(
          "Editable object layout maps multiple cells to one source word");
    }
    if (cell.original_word != span.expected_words[source_word_index]) {
      return absl::FailedPreconditionError(
          "Draw trace does not match the resolved ROM source word");
    }
    mapped_words[source_word_index] = true;
    cell.source_ref = ObjectTileSourceRef{/*span_index=*/0, source_word_index};
  }
  if (std::find(mapped_words.begin(), mapped_words.end(), false) !=
      mapped_words.end()) {
    return absl::FailedPreconditionError(
        "Editable object layout does not cover every source word");
  }
 
  ObjectTileSourceProvenance provenance;
  provenance.object_id = object_id;
  provenance.descriptor_pc_address = descriptor_pc_address;
  provenance.expected_descriptor_word = descriptor_word;
  provenance.spans.push_back(std::move(span));
  layout.pattern_source = std::move(pattern_source);
  layout.tile_data_address = static_cast<int>(source_address);
  layout.source_provenance = std::move(provenance);
  return layout;
}
 
absl::Status ObjectTileEditor::RenderLayoutToBitmap(
    const ObjectTileLayout& layout, gfx::Bitmap& bitmap,
    const uint8_t* room_gfx_buffer, const gfx::PaletteGroup& palette) {
  if (!room_gfx_buffer) {
    return absl::FailedPreconditionError("No room graphics buffer");
  }
  if (layout.cells.empty()) {
    return absl::OkStatus();
  }
 
  int bmp_w = layout.bounds_width * 8;
  int bmp_h = layout.bounds_height * 8;
 
  // Create or resize bitmap
  std::vector<uint8_t> pixel_data(bmp_w * bmp_h, 255);
  bitmap.Create(bmp_w, bmp_h, 8, pixel_data);
 
  // Preview rendering uses tile palette bank offsets (pal * 16), so the bitmap
  // needs a combined banked palette rather than a single sub-palette.
  if (!palette.empty()) {
    bitmap.SetPalette(BuildCombinedPaletteBanks(palette));
  }
  if (bitmap.surface()) {
    SDL_SetColorKey(bitmap.surface(), SDL_TRUE, 255);
    SDL_SetSurfaceBlendMode(bitmap.surface(), SDL_BLENDMODE_BLEND);
  }
 
  // Use a temporary ObjectDrawer just for its DrawTileToBitmap utility
  ObjectDrawer drawer(rom_, 0, room_gfx_buffer);
 
  for (const auto& cell : layout.cells) {
    gfx::TileInfo preview_tile = cell.tile_info;
    if (layout.is_custom) {
      const uint16_t runtime_word = CustomObjectRuntimeTileWord(
          layout.object_id, gfx::TileInfoToWord(cell.tile_info));
      if (runtime_word == 0) {
        continue;
      }
      preview_tile = gfx::WordToTileInfo(runtime_word);
    }
    int px = cell.rel_x * 8;
    int py = cell.rel_y * 8;
    drawer.DrawTileToBitmap(bitmap, preview_tile, px, py, room_gfx_buffer);
  }
 
  // DrawTileToBitmap writes the CPU vector; texture uploads read the surface.
  bitmap.UpdateSurfacePixels();
  return absl::OkStatus();
}
 
absl::Status ObjectTileEditor::BuildTile8Atlas(
    gfx::Bitmap& atlas, const uint8_t* room_gfx_buffer,
    const gfx::PaletteGroup& palette, int display_palette,
    std::optional<int16_t> custom_object_id, uint16_t retained_attributes) {
  if (!room_gfx_buffer) {
    return absl::FailedPreconditionError("No room graphics buffer");
  }
 
  std::vector<uint8_t> pixel_data(kAtlasWidthPx * kAtlasHeightPx,
                                  custom_object_id.has_value() ? 255 : 0);
  atlas.Create(kAtlasWidthPx, kAtlasHeightPx, 8, pixel_data);
 
  const int resolved_palette = ResolvePaletteIndex(palette, display_palette);
  if (!palette.empty()) {
    atlas.SetPalette(
        BuildPaddedPaletteBank(palette.palette_ref(resolved_palette)));
  }
  if (atlas.surface()) {
    SDL_SetColorKey(atlas.surface(), SDL_TRUE, 255);
    SDL_SetSurfaceBlendMode(atlas.surface(), SDL_BLENDMODE_BLEND);
  }
 
  ObjectDrawer drawer(rom_, 0, room_gfx_buffer);
 
  for (int tile_id = 0; tile_id < kAtlasTileCount; ++tile_id) {
    int col = tile_id % kAtlasTilesPerRow;
    int row = tile_id / kAtlasTilesPerRow;
    int px = col * 8;
    int py = row * 8;
 
    // The atlas bitmap already contains the selected palette bank, so tiles
    // should draw into palette row 0 inside that local 16-color palette.
    gfx::TileInfo info(static_cast<uint16_t>(tile_id), /*palette=*/0, false,
                       false, false);
    if (custom_object_id.has_value()) {
      // Atlas selection retains the selected cell's H/V/priority bits. Include
      // them and the source palette in no-op detection, but do not flip the
      // atlas image or apply its priority as a display effect.
      const uint16_t source_word =
          static_cast<uint16_t>(tile_id | ((display_palette & 7) << 10) |
                                (retained_attributes & 0xE000));
      const uint16_t runtime_word =
          CustomObjectRuntimeTileWord(*custom_object_id, source_word);
      if (runtime_word == 0) {
        continue;
      }
      info.id_ = runtime_word & 0x03FF;
    }
    drawer.DrawTileToBitmap(atlas, info, px, py, room_gfx_buffer);
  }
 
  atlas.UpdateSurfacePixels();
  return absl::OkStatus();
}
 
absl::Status ObjectTileEditor::WriteBack(ObjectTileLayout& layout) {
  if (!layout.HasModifications()) {
    return absl::OkStatus();
  }
 
  if (layout.is_custom) {
    if (layout.custom_filename.empty()) {
      return absl::FailedPreconditionError(
          "Custom object has no filename for write-back");
    }
    if (layout.custom_source_bytes.empty()) {
      return absl::FailedPreconditionError(
          "Custom object has no source snapshot for safe write-back");
    }
    const int runtime_count =
        CustomObjectManager::RuntimeSubtypeCountForObject(layout.object_id);
    if (layout.custom_subtype < 0 || layout.custom_subtype >= runtime_count) {
      return absl::FailedPreconditionError(
          "Custom object layout no longer identifies a fixed runtime slot");
    }
 
    CustomObject object;
    object.tiles.reserve(layout.cells.size());
    for (const auto& cell : layout.cells) {
      object.tiles.push_back(
          {cell.rel_x, cell.rel_y, gfx::TileInfoToWord(cell.tile_info)});
    }
 
    auto& mgr = CustomObjectManager::Get();
    if (mgr.ResolveFilename(layout.object_id, layout.custom_subtype) !=
        layout.custom_filename) {
      return absl::AbortedError(
          "Custom object slot mapping changed after it was opened; edits were "
          "kept");
    }
    auto published_or = PublishCustomObjectBinary(
        mgr.GetBasePath(), layout.custom_filename, object,
        layout.custom_source_bytes, layout.custom_resolved_path);
    if (!published_or.ok()) {
      return published_or.status();
    }
 
    layout.custom_source_bytes = std::move(*published_or);
    mgr.ReloadAll();
    return absl::OkStatus();
  }
 
  auto plan_or = BuildStandardWritePlan(layout);
  if (!plan_or.ok()) {
    return plan_or.status();
  }
  return ApplyStandardWritePlan(*plan_or);
}
 
absl::StatusOr<ObjectTileWritePlan> ObjectTileEditor::BuildStandardWritePlan(
    const ObjectTileLayout& layout) const {
  if (layout.is_custom) {
    return absl::InvalidArgumentError(
        "Cannot build a standard ROM write plan for a custom object");
  }
 
  ObjectTileWritePlan plan;
  if (rom_ == nullptr || !rom_->is_loaded()) {
    return absl::FailedPreconditionError("ROM not loaded");
  }
  if (!layout.source_provenance.has_value()) {
    return absl::FailedPreconditionError(
        "Standard object layout has no editable source provenance");
  }
  if (!IsEditableStandardObject(layout.object_id)) {
    return absl::UnimplementedError(
        "Standard object tile editing is not supported for this object");
  }
 
  const auto shape = *ShapeForObject(layout.object_id);
  const auto& provenance = *layout.source_provenance;
  if (provenance.object_id != layout.object_id) {
    return absl::FailedPreconditionError(
        "Object tile source provenance does not match the layout object");
  }
  const uint32_t expected_descriptor_address =
      DescriptorForObject(layout.object_id);
  if (provenance.descriptor_pc_address != expected_descriptor_address) {
    return absl::FailedPreconditionError(
        "Object tile source descriptor address does not match the object");
  }
  if (provenance.spans.size() != 1 ||
      provenance.spans.front().expected_words.size() != shape.word_count()) {
    return absl::FailedPreconditionError(
        "Object tile source provenance does not match the audited source map");
  }
 
  const int64_t rom_size = static_cast<int64_t>(rom_->size());
  if (provenance.descriptor_pc_address >
          static_cast<uint32_t>(std::numeric_limits<int>::max()) ||
      static_cast<int64_t>(provenance.descriptor_pc_address) + 2 > rom_size) {
    return absl::OutOfRangeError(
        "Object tile source descriptor is outside the loaded ROM");
  }
  auto current_descriptor_or =
      rom_->ReadWord(static_cast<int>(provenance.descriptor_pc_address));
  if (!current_descriptor_or.ok()) {
    return current_descriptor_or.status();
  }
  if (*current_descriptor_or != provenance.expected_descriptor_word) {
    return absl::FailedPreconditionError(
        "Object tile source descriptor changed after capture");
  }
 
  const auto& span = provenance.spans.front();
  const int64_t expected_span_address =
      static_cast<int64_t>(kRoomObjectTileAddress) +
      provenance.expected_descriptor_word;
  if (span.pc_address != expected_span_address) {
    return absl::FailedPreconditionError(
        "Object tile source span does not match its descriptor");
  }
  if (span.pc_address >
          static_cast<uint32_t>(std::numeric_limits<int>::max()) ||
      static_cast<int64_t>(span.pc_address) +
              static_cast<int64_t>(span.expected_words.size() * 2) >
          rom_size) {
    return absl::OutOfRangeError(
        "Object tile source span is outside the loaded ROM");
  }
 
  const int64_t span_start = static_cast<int64_t>(span.pc_address);
  const int64_t span_end =
      span_start + static_cast<int64_t>(span.expected_words.size() * 2);
  if (RangesOverlap(span_start, span_end, kObjectMetadataStart,
                    kObjectMetadataEnd)) {
    return absl::FailedPreconditionError(
        "Object tile source span overlaps object descriptor or routine "
        "metadata");
  }
 
  if (layout.pattern_source) {
    RETURN_IF_ERROR(ValidatePatternContext(*layout.pattern_source));
    plan.pattern_source_ = layout.pattern_source;
  } else {
    RETURN_IF_ERROR(CheckPatternSourceReadOnly(span_start, span_end));
  }
  std::vector<int> precondition_addresses;
  const int descriptor_address =
      static_cast<int>(provenance.descriptor_pc_address);
  precondition_addresses.push_back(descriptor_address);
  plan.preconditions_.push_back(
      {descriptor_address, provenance.expected_descriptor_word});
  for (size_t word_index = 0; word_index < span.expected_words.size();
       ++word_index) {
    const int address = static_cast<int>(span.pc_address + word_index * 2);
    if (std::any_of(precondition_addresses.begin(),
                    precondition_addresses.end(), [&](int existing_address) {
                      return WordRangesOverlap(existing_address, address);
                    })) {
      return absl::FailedPreconditionError(
          "Object tile descriptor and source preconditions overlap");
    }
    precondition_addresses.push_back(address);
    auto current_word_or = rom_->ReadWord(address);
    if (plan.pattern_source_) {
      const auto source_word = plan.pattern_source_->words.find(address);
      if (source_word == plan.pattern_source_->words.end()) {
        return absl::FailedPreconditionError(
            "Object source pattern is incomplete");
      }
      current_word_or = source_word->second;
    }
    if (!current_word_or.ok()) {
      return current_word_or.status();
    }
    if (*current_word_or != span.expected_words[word_index]) {
      return absl::FailedPreconditionError(
          "Object tile source word changed after capture");
    }
    plan.preconditions_.push_back({address, span.expected_words[word_index]});
  }
 
  if (layout.cells.size() != shape.word_count() ||
      layout.bounds_width != shape.width ||
      layout.bounds_height != shape.height) {
    return absl::FailedPreconditionError(
        "Object tile layout does not match the audited shape");
  }
 
  std::unordered_set<int> resolved_addresses;
  for (const auto& cell : layout.cells) {
    if (!cell.source_ref.has_value()) {
      return absl::FailedPreconditionError(
          "Object tile cell has no editable source reference");
    }
    const auto& source_ref = *cell.source_ref;
    if (source_ref.span_index >= provenance.spans.size()) {
      return absl::FailedPreconditionError(
          "Object tile source span reference is out of bounds");
    }
    const auto& referenced_span = provenance.spans[source_ref.span_index];
    if (source_ref.word_index >= referenced_span.expected_words.size()) {
      return absl::FailedPreconditionError(
          "Object tile source word reference is out of bounds");
    }
 
    auto expected_source_index_or = ResolveSourceWordIndex(cell, shape);
    if (!expected_source_index_or.ok()) {
      return expected_source_index_or.status();
    }
    if (source_ref.span_index != 0 ||
        source_ref.word_index != *expected_source_index_or) {
      return absl::FailedPreconditionError(
          "Object tile cell source reference does not match the audited map");
    }
 
    const int64_t address64 = static_cast<int64_t>(referenced_span.pc_address) +
                              static_cast<int64_t>(source_ref.word_index) * 2;
    if (address64 < 0 || address64 + 2 > rom_size ||
        address64 > std::numeric_limits<int>::max()) {
      return absl::OutOfRangeError(
          "Object tile write range is outside the loaded ROM");
    }
    const int address = static_cast<int>(address64);
    if (!resolved_addresses.insert(address).second) {
      return absl::FailedPreconditionError(
          "Object tile cells resolve to a duplicate ROM address");
    }
 
    const uint16_t expected_word =
        referenced_span.expected_words[source_ref.word_index];
    if (cell.original_word != expected_word) {
      return absl::FailedPreconditionError(
          "Object tile cell original word does not match its source");
    }
    const uint16_t current_layout_word = gfx::TileInfoToWord(cell.tile_info);
    if (!cell.modified && current_layout_word != cell.original_word) {
      return absl::FailedPreconditionError(
          "Object tile cell changed without being marked modified");
    }
    if (!cell.modified) {
      continue;
    }
 
    plan.writes_.push_back({address, expected_word, current_layout_word});
    plan.write_ranges_.emplace_back(static_cast<uint32_t>(address),
                                    static_cast<uint32_t>(address + 2));
  }
 
  return plan;
}
 
absl::Status ObjectTileEditor::ApplyStandardWritePlan(
    const ObjectTileWritePlan& plan) {
  if (plan.writes_.empty()) {
    return absl::OkStatus();
  }
  if (plan.write_ranges_.size() != plan.writes_.size()) {
    return absl::FailedPreconditionError(
        "Object tile write plan ranges do not match its writes");
  }
  if (plan.preconditions_.empty()) {
    return absl::FailedPreconditionError(
        "Object tile write plan has no source provenance preconditions");
  }
  if (rom_ == nullptr || !rom_->is_loaded()) {
    return absl::FailedPreconditionError("ROM not loaded");
  }
 
  const int64_t rom_size = static_cast<int64_t>(rom_->size());
  std::unordered_map<int, uint16_t> precondition_words;
  if (plan.pattern_source_) {
    RETURN_IF_ERROR(ValidatePatternContext(*plan.pattern_source_));
    for (const auto& precondition : plan.preconditions_) {
      const auto source_word =
          plan.pattern_source_->words.find(precondition.address);
      if (source_word != plan.pattern_source_->words.end()) {
        if (source_word->second != precondition.expected_word) {
          return absl::AbortedError("Pattern source precondition changed");
        }
      } else {
        const auto word = rom_->ReadWord(precondition.address);
        if (!word.ok())
          return word.status();
        if (*word != precondition.expected_word) {
          return absl::AbortedError("Object descriptor changed after capture");
        }
      }
    }
    std::map<uint32_t, uint16_t> replacements;
    for (const auto& write : plan.writes_)
      replacements.emplace(write.address, write.word);
    RETURN_IF_ERROR(
        PublishDungeonTilePatterns(*plan.pattern_source_, replacements));
    CustomObjectManager::Get().ReloadAll();
    return absl::OkStatus();
  }
  std::vector<int> precondition_addresses;
  for (const auto& precondition : plan.preconditions_) {
    const int64_t address = static_cast<int64_t>(precondition.address);
    if (address < 0 || address + 2 > rom_size) {
      return absl::OutOfRangeError(
          "Object tile precondition is outside the loaded ROM");
    }
    RETURN_IF_ERROR(CheckPatternSourceReadOnly(address, address + 2));
    if (std::any_of(precondition_addresses.begin(),
                    precondition_addresses.end(), [&](int existing_address) {
                      return WordRangesOverlap(existing_address,
                                               precondition.address);
                    })) {
      return absl::FailedPreconditionError(
          "Object tile plan has overlapping CAS preconditions");
    }
    precondition_addresses.push_back(precondition.address);
    if (!precondition_words
             .emplace(precondition.address, precondition.expected_word)
             .second) {
      return absl::FailedPreconditionError(
          "Object tile plan has duplicate CAS preconditions");
    }
  }
 
  std::unordered_set<int> write_addresses;
  std::vector<int> validated_write_addresses;
  for (size_t write_index = 0; write_index < plan.writes_.size();
       ++write_index) {
    const auto& write = plan.writes_[write_index];
    const int64_t address = static_cast<int64_t>(write.address);
    if (address < 0 || address + 2 > rom_size) {
      return absl::OutOfRangeError(
          "Object tile write range is outside the loaded ROM");
    }
    if (std::any_of(validated_write_addresses.begin(),
                    validated_write_addresses.end(), [&](int existing_address) {
                      return WordRangesOverlap(existing_address, write.address);
                    })) {
      return absl::FailedPreconditionError(
          "Object tile plan has overlapping write ranges");
    }
    validated_write_addresses.push_back(write.address);
    if (!write_addresses.insert(write.address).second) {
      return absl::FailedPreconditionError(
          "Object tile plan has duplicate write addresses");
    }
    const std::pair<uint32_t, uint32_t> expected_range = {
        static_cast<uint32_t>(write.address),
        static_cast<uint32_t>(write.address + 2)};
    if (plan.write_ranges_[write_index] != expected_range) {
      return absl::FailedPreconditionError(
          "Object tile write plan range does not match its write address");
    }
    const auto precondition = precondition_words.find(write.address);
    if (precondition == precondition_words.end() ||
        precondition->second != write.expected_word) {
      return absl::FailedPreconditionError(
          "Object tile write has no matching source precondition");
    }
  }
 
  // Recheck every captured descriptor/source word immediately before the
  // transaction. This is the compare-and-swap boundary for a prepared plan.
  for (const auto& precondition : plan.preconditions_) {
    auto current_word_or = rom_->ReadWord(precondition.address);
    if (!current_word_or.ok()) {
      return current_word_or.status();
    }
    if (*current_word_or != precondition.expected_word) {
      return absl::FailedPreconditionError(
          "Object tile source changed after the write plan was built");
    }
  }
  for (const auto& write : plan.writes_) {
    auto current_word_or = rom_->ReadWord(write.address);
    if (!current_word_or.ok()) {
      return current_word_or.status();
    }
    if (*current_word_or != write.expected_word) {
      return absl::FailedPreconditionError(
          "Object tile write target changed after the plan was built");
    }
  }
 
  const bool was_dirty = rom_->dirty();
  Transaction transaction(*rom_);
  for (const auto& write : plan.writes_) {
    transaction.WriteWord(write.address, write.word);
  }
  const absl::Status status = transaction.Commit();
  if (!status.ok()) {
    rom_->set_dirty(was_dirty);
    return status;
  }
  rom_->AdvanceObjectTileRevision();
  return absl::OkStatus();
}
 
absl::StatusOr<ObjectTileSourceImpact>
ObjectTileEditor::AnalyzeStandardTileSourceImpact(
    const ObjectTileLayout& layout) const {
  if (rom_ == nullptr || !rom_->is_loaded()) {
    return absl::FailedPreconditionError("ROM not loaded");
  }
  if (layout.is_custom) {
    return absl::InvalidArgumentError(
        "Custom objects do not use standard ROM tile sources");
  }
  if (!layout.source_provenance.has_value()) {
    return absl::FailedPreconditionError(
        "Standard object layout has no editable source provenance");
  }
 
  // Reuse the write-plan validator as the provenance/CAS gate. This validates
  // the audited object ID, descriptor, complete source snapshot, and cell map
  // without mutating the ROM, regardless of whether the layout has edits.
  const auto plan_or = BuildStandardWritePlan(layout);
  if (!plan_or.ok()) {
    return plan_or.status();
  }
 
  std::vector<ObjectTileReadRange> target_ranges;
  for (const auto& span : layout.source_provenance->spans) {
    if (span.expected_words.empty()) {
      return absl::FailedPreconditionError(
          "Editable object tile source span is empty");
    }
    const uint64_t end = static_cast<uint64_t>(span.pc_address) +
                         static_cast<uint64_t>(span.expected_words.size()) * 2;
    if (end > rom_->size() || end > std::numeric_limits<uint32_t>::max()) {
      return absl::OutOfRangeError(
          "Editable object tile source span is outside the loaded ROM");
    }
    target_ranges.push_back({span.pc_address, static_cast<uint32_t>(end)});
  }
 
  const auto overlaps_target =
      [&target_ranges](const ObjectTileReadRange& candidate) {
        return std::any_of(target_ranges.begin(), target_ranges.end(),
                           [&candidate](const ObjectTileReadRange& target) {
                             return candidate.begin < target.end &&
                                    target.begin < candidate.end;
                           });
      };
 
  ObjectParser parser(rom_);
  ObjectTileSourceImpact impact;
  const auto inspect_object = [&](int object_id) -> absl::Status {
    auto ranges_or =
        parser.ResolveTileReadRanges(static_cast<int16_t>(object_id));
    if (!ranges_or.ok()) {
      return absl::FailedPreconditionError(absl::StrFormat(
          "Unable to resolve tile sources for object 0x%03X: %s", object_id,
          ranges_or.status().message()));
    }
 
    ObjectTileSourceImpactEntry entry;
    entry.object_id = static_cast<int16_t>(object_id);
    for (const auto& range : *ranges_or) {
      if (overlaps_target(range)) {
        entry.overlapping_ranges.push_back(range);
      }
    }
    if (!entry.overlapping_ranges.empty()) {
      impact.affected_objects.push_back(std::move(entry));
    }
    return absl::OkStatus();
  };
 
  // Only IDs representable in the dungeon object stream are relevant. Keep the
  // three families explicit so invalid aliases (Type 1 0xF8..0xFF and Type 2
  // 0x140..0x1FF) cannot silently inflate or hide the impact set.
  for (int object_id = 0x000; object_id <= 0x0F7; ++object_id) {
    const absl::Status status = inspect_object(object_id);
    if (!status.ok()) {
      return status;
    }
  }
  for (int object_id = 0x100; object_id <= 0x13F; ++object_id) {
    const absl::Status status = inspect_object(object_id);
    if (!status.ok()) {
      return status;
    }
  }
  for (int object_id = 0xF80; object_id <= 0xFFF; ++object_id) {
    const absl::Status status = inspect_object(object_id);
    if (!status.ok()) {
      return status;
    }
  }
 
  // Room::RenderObjectsToBackground synthesizes lightable torches as global
  // object 0x150, outside the persisted stream-ID families above. Both room
  // rendering and the in-game lighting-change path read these literal blocks.
  // In particular, the lit block aliases editable object 0x120 exactly.
  constexpr int kLightableTorchTileCount = 4;
  constexpr ObjectTileReadRange kLightableTorchSources[] = {
      {kRoomObjectTileAddress + 0x0EC2,
       kRoomObjectTileAddress + 0x0EC2 + kLightableTorchTileCount * 2},
      {kRoomObjectTileAddress + 0x0ECA,
       kRoomObjectTileAddress + 0x0ECA + kLightableTorchTileCount * 2},
  };
  for (const auto consumer :
       {ObjectTileRuntimeConsumer::kLightableTorchDraw,
        ObjectTileRuntimeConsumer::kTorchLightingChange}) {
    ObjectTileRuntimeConsumerImpactEntry torch_impact{consumer, {}};
    for (const auto& range : kLightableTorchSources) {
      if (overlaps_target(range)) {
        torch_impact.overlapping_ranges.push_back(range);
      }
    }
    if (!torch_impact.overlapping_ranges.empty()) {
      impact.runtime_consumers.push_back(std::move(torch_impact));
    }
  }
 
  const bool includes_edited_object = std::any_of(
      impact.affected_objects.begin(), impact.affected_objects.end(),
      [&](const auto& entry) { return entry.object_id == layout.object_id; });
  if (!includes_edited_object) {
    return absl::FailedPreconditionError(
        "Edited object is missing from its tile source impact inventory");
  }
 
  return impact;
}
 
}  // namespace zelda3
}  // namespace yaze