object_parser.cc

Go to the documentation of this file.

#include "object_parser.h"
 
#include <algorithm>
#include <cstring>
#include <tuple>
 
#include "absl/strings/str_format.h"
#include "util/log.h"
#include "zelda3/dungeon/draw_routines/draw_routine_registry.h"
#include "zelda3/dungeon/room_object.h"
 
// ROM addresses for object data are defined in room_object.h:
// - kRoomObjectSubtype1 = 0x8000 (SNES $01:8000)
// - kRoomObjectSubtype2 = 0x83F0 (SNES $01:83F0)
// - kRoomObjectSubtype3 = 0x84F0 (SNES $01:84F0)
// - kRoomObjectTileAddress = 0x1B52 (SNES $00:9B52)
 
// Subtype 1 tile count lookup table.
//
// Each entry specifies how many tiles the corresponding `RoomDraw_*`
// routine reads from the per-object tile stream. Index directly by
// `(object_id & 0xFF)` for subtype 1 objects.
//
// Audit history:
// - Initial table sourced from ZScream's `DungeonObjectData.cs`.
// - 2026-04-25 audit (zelda3-hacking-expert): IDs `0x47` and `0x48`
//   stored as 0 (fallback to 8) but routine bodies in
//   `special_routines.cc::DrawWaterfall47` and `DrawWaterfall48`
//   deterministically index tile slots 0..14 and 0..8 respectively
//   (three 1x5 / 1x3 columns). The under-fetched 8-tile vector is
//   not a bounds bug — `TileAtWrapped` wraps `index % tiles.size()`
//   — but the wrap quietly substitutes the wrong tile for the right
//   column (e.g. Waterfall47 column 3 indexes tile 12, which wraps
//   to tile 4 with size 8). Updated to the real counts so the wrap
//   never fires for vanilla data.
// - IDs `0xD3..0xD6` are routed to `DrawNothing` (logic-only;
//   `CheckIfWallIsMoved` flag tests). Their tile-count entry is `0`
//   because those routines have no tile payload. Other uncataloged zero
//   entries still use the conservative 8-tile fallback.
// - IDs `0xCD` and `0xCE` consume 24 words: top corner (9), vertical
//   pattern (6), and bottom corner (9). ZScream's count of 28 crosses into
//   the next object's data block, so yaze uses the routine-proven count.
// - IDs `0x3C` and `0x4C` consume 8 and 12 words respectively. Their
//   registry routines index the complete 4x2 and 4x3 payloads, while
//   ZScream's counts of 4 and 9 under-fetch the final stamp/column and make
//   ObjectDrawer fall back to a single tile.
// - 2026-04-25 ZScream parity diff: full byte-for-byte comparison
//   against ZScream's `subtype1Lengths` (`DungeonObjectData.cs:184`)
//   remains pinned, with routine-body-proven corrections allowlisted.
//   The pin lives in `object_parser_test.cc::Subtype1TileLengths`
//   `MatchesZScreamReferenceExceptAtKnownDivergences` and detects
//   future drift in either direction.
// clang-format off
static constexpr uint8_t kSubtype1TileLengths[0xF8] = {
     4,  8,  8,  8,  8,  8,  8,  4,  4,  5,  5,  5,  5,  5,  5,  5,  // 0x00-0x0F
     5,  5,  5,  5,  5,  5,  5,  5,  5,  5,  5,  5,  5,  5,  5,  5,  // 0x10-0x1F
     5,  9,  3,  3,  3,  3,  3,  3,  3,  3,  3,  3,  3,  3,  3,  6,  // 0x20-0x2F
     6,  1,  1, 16,  1,  1, 16, 16,  6,  8, 12, 12,  8,  8,  4,  3,  // 0x30-0x3F (0x3C=Doubled2x2:8)
     3,  3,  3,  3,  3,  3,  3, 15,  9,  8,  8,  4, 12, 16, 16, 16,  // 0x40-0x4F (0x47=Waterfall47:15, 0x48=Waterfall48:9, 0x4C=Bar4x3:12)
     1, 18, 18,  4,  1,  8,  8,  1,  1,  1,  1, 18, 18, 15,  4,  3,  // 0x50-0x5F
     4,  8,  8,  8,  8,  8,  8,  4,  4,  3,  1,  1,  6,  6,  1,  1,  // 0x60-0x6F
    16,  1,  1, 16, 16,  8, 16, 16,  4,  1,  1,  4,  1,  4,  1,  8,  // 0x70-0x7F
     8, 12, 12, 12, 12, 18, 18,  8, 12,  4,  3,  3,  3,  1,  1,  6,  // 0x80-0x8F
     8,  8,  4,  4, 16,  4,  4,  1,  1,  1,  1,  1,  1,  1,  1,  1,  // 0x90-0x9F
     1,  1,  1,  1, 24,  1,  1,  1,  1,  1,  1,  1,  1,  1,  1,  1,  // 0xA0-0xAF
     1,  1, 16,  3,  3,  8,  8,  8,  4,  4, 16,  4,  4,  4,  1,  1,  // 0xB0-0xBF
     1, 68,  1,  1,  8,  8,  8,  8,  8,  8,  8,  1,  1, 24, 24,  1,  // 0xC0-0xCF (0xCD/0xCE use 24-word platform payloads)
     1,  8,  8,  0,  0,  0,  0,  1,  8,  8,  8,  8, 21, 16,  4,  8,  // 0xD0-0xDF (0xD3..0xD6: DrawNothing logic; tiles unused)
     8,  8,  8,  8,  8,  8,  8,  8,  8,  1,  1,  1,  1,  1,  1,  1,  // 0xE0-0xEF
     1,  1,  1,  1,  1,  1,  1,  1                                   // 0xF0-0xF7
};
// clang-format on
 
static inline bool IsSubtype1LogicOnlyZeroTileObject(int object_id) {
  int index = object_id & 0xFF;
  return index >= 0xD3 && index <= 0xD6;
}
 
// Helper function to get tile count for Subtype 1 objects.
static inline int GetSubtype1TileCount(int object_id) {
  int index = object_id & 0xFF;
  if (index < 0xF8) {
    int count = kSubtype1TileLengths[index];
    if (count > 0) {
      return count;
    }
    if (IsSubtype1LogicOnlyZeroTileObject(index)) {
      return 0;
    }
    return 8;  // Default to 8 if an uncataloged table entry has 0.
  }
  return 8;  // Default for IDs >= 0xF8
}
 
namespace yaze {
namespace zelda3 {
 
absl::StatusOr<std::vector<gfx::TileInfo>> ObjectParser::ParseObject(
    int16_t object_id) {
  if (rom_ == nullptr) {
    return absl::InvalidArgumentError("ROM is null");
  }
 
  // Validate object ID is non-negative
  if (object_id < 0) {
    return absl::InvalidArgumentError(
        absl::StrFormat("Invalid object ID: %d", object_id));
  }
 
  int subtype = DetermineSubtype(object_id);
 
  switch (subtype) {
    case 1:
      return ParseSubtype1(object_id);
    case 2:
      return ParseSubtype2(object_id);
    case 3:
      return ParseSubtype3(object_id);
    default:
      return absl::InvalidArgumentError(
          absl::StrFormat("Invalid object subtype for ID: %#04x", object_id));
  }
}
 
absl::StatusOr<std::vector<ObjectTileReadRange>>
ObjectParser::ResolveTileReadRanges(int16_t object_id) {
  if (tile_read_range_collector_ != nullptr) {
    return absl::FailedPreconditionError(
        "Object tile source resolution is already active");
  }
 
  std::vector<ObjectTileReadRange> ranges;
  tile_read_range_collector_ = &ranges;
  const auto parsed_or = ParseObject(object_id);
  tile_read_range_collector_ = nullptr;
  if (!parsed_or.ok()) {
    return parsed_or.status();
  }
 
  std::sort(ranges.begin(), ranges.end(),
            [](const ObjectTileReadRange& lhs, const ObjectTileReadRange& rhs) {
              return std::tie(lhs.begin, lhs.end) <
                     std::tie(rhs.begin, rhs.end);
            });
  ranges.erase(std::unique(ranges.begin(), ranges.end()), ranges.end());
  return ranges;
}
 
absl::StatusOr<ObjectRoutineInfo> ObjectParser::ParseObjectRoutine(
    int16_t object_id) {
  if (rom_ == nullptr) {
    return absl::InvalidArgumentError("ROM is null");
  }
 
  auto subtype_info = GetObjectSubtype(object_id);
  if (!subtype_info.ok()) {
    return subtype_info.status();
  }
 
  ObjectRoutineInfo routine_info;
  routine_info.routine_ptr = subtype_info->routine_ptr;
  routine_info.tile_ptr = subtype_info->subtype_ptr;
  routine_info.tile_count = subtype_info->max_tile_count;
  routine_info.is_repeatable = true;
  routine_info.is_orientation_dependent = true;
 
  return routine_info;
}
 
absl::StatusOr<ObjectSubtypeInfo> ObjectParser::GetObjectSubtype(
    int16_t object_id) {
  ObjectSubtypeInfo info;
  info.subtype = DetermineSubtype(object_id);
 
  switch (info.subtype) {
    case 1: {
      int index = object_id & 0xFF;
      info.subtype_ptr = kRoomObjectSubtype1 + (index * 2);
      info.routine_ptr = kRoomObjectSubtype1 + 0x200 + (index * 2);
      break;
    }
    case 2: {
      // Type 2 objects: 0x100-0x13F (64 objects only)
      // Index mask 0x3F ensures we stay within 64-entry table bounds
      int index = (object_id - 0x100) & 0x3F;
      info.subtype_ptr = kRoomObjectSubtype2 + (index * 2);
      // Routine table starts 128 bytes (64 entries * 2 bytes) after data table
      info.routine_ptr = kRoomObjectSubtype2 + 0x80 + (index * 2);
      break;
    }
    case 3: {
      // Type 3 object IDs are 0xF80-0xFFF (128 objects)
      // Table index should be 0-127
      int index = (object_id - 0xF80) & 0x7F;
      info.subtype_ptr = kRoomObjectSubtype3 + (index * 2);
      info.routine_ptr = kRoomObjectSubtype3 + 0x100 + (index * 2);
      break;
    }
    default:
      return absl::InvalidArgumentError(
          absl::StrFormat("Invalid object subtype for ID: %#04x", object_id));
  }
 
  info.max_tile_count = ResolveTileCountForObject(object_id);
 
  return info;
}
 
absl::StatusOr<ObjectSizeInfo> ObjectParser::ParseObjectSize(
    int16_t object_id, uint8_t size_byte) {
  ObjectSizeInfo info;
 
  // Extract size bits (0-3 for X, 4-7 for Y)
  int size_x = size_byte & 0x03;
  int size_y = (size_byte >> 2) & 0x03;
 
  info.width_tiles = (size_x + 1) * 2;  // Convert to tile count
  info.height_tiles = (size_y + 1) * 2;
 
  // Determine orientation based on object ID and size
  // This is a heuristic based on the object naming patterns
  if (object_id >= 0x80 && object_id <= 0xFF) {
    // Objects 0x80-0xFF are typically vertical
    info.is_horizontal = false;
  } else {
    // Objects 0x00-0x7F are typically horizontal
    info.is_horizontal = true;
  }
 
  // Determine if object is repeatable
  info.is_repeatable = (size_byte != 0);
  info.repeat_count = size_byte == 0 ? 32 : size_byte;
 
  return info;
}
 
absl::StatusOr<std::vector<gfx::TileInfo>> ObjectParser::ParseSubtype1(
    int16_t object_id) {
  int index = object_id & 0xFF;
  int tile_ptr = kRoomObjectSubtype1 + (index * 2);
 
  if (tile_ptr + 1 >= (int)rom_->size()) {
    return absl::OutOfRangeError(
        absl::StrFormat("Tile pointer out of range: %#06x", tile_ptr));
  }
 
  // Read tile data pointer (16-bit little-endian offset)
  uint8_t low = rom_->data()[tile_ptr];
  uint8_t high = rom_->data()[tile_ptr + 1];
  int16_t offset = (int16_t)((high << 8) | low);  // Signed offset!
  int tile_data_ptr = kRoomObjectTileAddress + offset;
 
  // DEBUG: Log wall objects 0x61/0x62 and ceiling 0xC0 to verify tile data
  bool is_debug_object = (object_id == 0x61 || object_id == 0x62 ||
                          object_id == 0xC0 || object_id == 0xC2);
  static int debug_count = 0;
  if (debug_count < 10 || is_debug_object) {
    LOG_DEBUG("ObjectParser",
              "ParseSubtype1: obj=0x%02X%s tile_ptr=0x%04X (SNES $01:%04X)",
              object_id, is_debug_object ? " (DEBUG)" : "", tile_ptr, tile_ptr);
    LOG_DEBUG("ObjectParser",
              "  ROM[0x%04X..0x%04X]=0x%02X 0x%02X offset=%d (0x%04X)",
              tile_ptr, tile_ptr + 1, low, high, offset, (uint16_t)offset);
    LOG_DEBUG("ObjectParser",
              "  tile_data_ptr=0x%04X+0x%04X=0x%04X (SNES $00:%04X)",
              kRoomObjectTileAddress, (uint16_t)offset, tile_data_ptr,
              tile_data_ptr + 0x8000);
 
    // Fix: Check for negative tile_data_ptr to prevent SIGSEGV on corrupted ROMs
    if (tile_data_ptr >= 0 && tile_data_ptr + 8 < (int)rom_->size()) {
      uint16_t tw0 =
          rom_->data()[tile_data_ptr] | (rom_->data()[tile_data_ptr + 1] << 8);
      uint16_t tw1 = rom_->data()[tile_data_ptr + 2] |
                     (rom_->data()[tile_data_ptr + 3] << 8);
      LOG_DEBUG("ObjectParser", "  First 2 tiles: $%04X(id=%d) $%04X(id=%d)",
                tw0, tw0 & 0x3FF, tw1, tw1 & 0x3FF);
    } else {
      LOG_DEBUG("ObjectParser", "  Tile data at 0x%04X: <OUT OF BOUNDS>",
                tile_data_ptr);
    }
    if (!is_debug_object)
      debug_count++;
  }
 
  // Use lookup table for correct tile count per object ID
  int tile_count = GetSubtype1TileCount(object_id);
  return ReadTileData(tile_data_ptr, tile_count);
}
 
absl::StatusOr<std::vector<gfx::TileInfo>> ObjectParser::ParseSubtype2(
    int16_t object_id) {
  constexpr int kDamFloodGateOpenTileOffset = 0x13E8;
  constexpr int kDamFloodGateTileCount = 40;
 
  // Type 2 objects: 0x100-0x13F (64 objects only)
  int index = (object_id - 0x100) & 0x3F;
  int tile_ptr = kRoomObjectSubtype2 + (index * 2);
 
  if (tile_ptr + 1 >= (int)rom_->size()) {
    return absl::OutOfRangeError(
        absl::StrFormat("Tile pointer out of range: %#06x", tile_ptr));
  }
 
  // Read tile data pointer
  uint8_t low = rom_->data()[tile_ptr];
  uint8_t high = rom_->data()[tile_ptr + 1];
  int tile_data_ptr = kRoomObjectTileAddress + ((high << 8) | low);
 
  // Determine tile count based on object ID
  int tile_count = GetSubtype2TileCount(object_id);
 
  // DEBUG: Log corner tile loading (0x100-0x103)
  bool is_corner = (object_id >= 0x100 && object_id <= 0x103);
  if (is_corner) {
    LOG_DEBUG("ObjectParser",
              "ParseSubtype2: CORNER obj=0x%03X index=%d tile_ptr=0x%04X",
              object_id, index, tile_ptr);
    LOG_DEBUG("ObjectParser",
              "  ROM[0x%04X..0x%04X]=0x%02X 0x%02X offset=0x%04X", tile_ptr,
              tile_ptr + 1, low, high, (high << 8) | low);
    LOG_DEBUG(
        "ObjectParser", "  tile_data_ptr=0x%04X+0x%04X=0x%04X (tile_count=%d)",
        kRoomObjectTileAddress, (high << 8) | low, tile_data_ptr, tile_count);
 
    // Show first 2 tile words
    if (tile_data_ptr >= 0 && tile_data_ptr + 4 < (int)rom_->size()) {
      uint16_t tw0 =
          rom_->data()[tile_data_ptr] | (rom_->data()[tile_data_ptr + 1] << 8);
      uint16_t tw1 = rom_->data()[tile_data_ptr + 2] |
                     (rom_->data()[tile_data_ptr + 3] << 8);
      LOG_DEBUG("ObjectParser", "  First 2 tiles: $%04X(id=%d) $%04X(id=%d)",
                tw0, tw0 & 0x3FF, tw1, tw1 & 0x3FF);
    }
  }
 
  if (object_id == 0x137) {
    auto closed_tiles = ReadTileData(tile_data_ptr, kDamFloodGateTileCount);
    if (!closed_tiles.ok()) {
      return closed_tiles.status();
    }
    auto open_tiles =
        ReadTileData(kRoomObjectTileAddress + kDamFloodGateOpenTileOffset,
                     kDamFloodGateTileCount);
    if (!open_tiles.ok()) {
      return open_tiles.status();
    }
    closed_tiles->insert(closed_tiles->end(), open_tiles->begin(),
                         open_tiles->end());
    return closed_tiles;
  }
 
  return ReadTileData(tile_data_ptr, tile_count);
}
 
absl::StatusOr<std::vector<gfx::TileInfo>> ObjectParser::ParseSubtype3(
    int16_t object_id) {
  constexpr int kBombableFloorOpenTileOffset = 0x05BA;
  constexpr int kBombableFloorStateTileCount = 16;
  constexpr int kPrisonCellTileOffset = 0x1488;
  constexpr int kPrisonCellTileCount = 6;
  constexpr int kRupeeFloorTileOffset = 0x1DD6;
  constexpr int kRupeeFloorTileCount = 2;
  constexpr int kBigKeyLockTileOffset = 0x1494;
  constexpr int kClosedChestTileOffset = 0x149C;
  constexpr int kOpenChestTileOffset = 0x14A4;
  constexpr int kChestStateTileCount = 4;
  constexpr int kClosedBigChestTileOffset = 0x14AC;
  constexpr int kOpenBigChestTileOffset = 0x14C4;
  constexpr int kBigChestStateTileCount = 12;
  constexpr int kBigGrayRockTileOffset = 0x0E62;
  constexpr int kBigGrayRockTileCount = 16;
  constexpr int kAgahnimsAltarTileOffset = 0x1B4A;
  constexpr int kAgahnimsAltarTileCount = 84;
  constexpr int kFortuneTellerRoomTileOffset = 0x202E;
  constexpr int kFortuneTellerRoomTileCount = 26;
  constexpr int kSmithyFurnaceTileOffset = 0x1F92;
  constexpr int kSmithyFurnaceTileCount = 48;
 
  // Type 3 object IDs are 0xF80-0xFFF (128 objects)
  // Table index should be 0-127, calculated by subtracting base offset 0xF80
  int index = (object_id - 0xF80) & 0x7F;
  int tile_ptr = kRoomObjectSubtype3 + (index * 2);
 
  if (tile_ptr + 1 >= (int)rom_->size()) {
    return absl::OutOfRangeError(
        absl::StrFormat("Tile pointer out of range: %#06x", tile_ptr));
  }
 
  // Read tile data pointer
  uint8_t low = rom_->data()[tile_ptr];
  uint8_t high = rom_->data()[tile_ptr + 1];
  int tile_data_ptr = kRoomObjectTileAddress + ((high << 8) | low);
 
  // Determine tile count based on object ID
  int tile_count = GetSubtype3TileCount(object_id);
 
  // BombableFloor's intact 4x4 block starts at the object's pointer, while
  // USDASM's replacement 4x4 block lives separately at obj05BA. Keep the two
  // 16-word states adjacent in the parsed payload for stateful rendering.
  if (object_id == 0xFC7) {
    auto intact_tiles =
        ReadTileData(tile_data_ptr, kBombableFloorStateTileCount);
    if (!intact_tiles.ok()) {
      return intact_tiles.status();
    }
    auto open_tiles =
        ReadTileData(kRoomObjectTileAddress + kBombableFloorOpenTileOffset,
                     kBombableFloorStateTileCount);
    if (!open_tiles.ok()) {
      return open_tiles.status();
    }
    intact_tiles->insert(intact_tiles->end(), open_tiles->begin(),
                         open_tiles->end());
    return intact_tiles;
  }
 
  // Both PrisonCell IDs dispatch to RoomDraw_PrisonCell, which ignores the
  // subtype table pointer and loads literal obj1488. F8D's vanilla table entry
  // does not point there, so following the table would render the two aliases
  // differently even though the game does not.
  if (object_id == 0xF8D || object_id == 0xF97) {
    return ReadTileData(kRoomObjectTileAddress + kPrisonCellTileOffset,
                        kPrisonCellTileCount);
  }
 
  // RupeeFloor replaces the table-derived pointer with literal obj1DD6 and
  // repeats those two words across its fixed footprint. Following the table
  // here would hide a real shared-source overlap from both rendering and the
  // source-impact resolver.
  if (object_id == 0xF92) {
    return ReadTileData(kRoomObjectTileAddress + kRupeeFloorTileOffset,
                        kRupeeFloorTileCount);
  }
 
  // BigKeyLock overwrites the table-derived X register with obj1494 before
  // drawing. Follow the runtime literal so a relocated F98 table entry does
  // not change the editor while the game continues using obj1494.
  if (object_id == 0xF98) {
    return ReadTileData(kRoomObjectTileAddress + kBigKeyLockTileOffset,
                        kChestStateTileCount);
  }
 
  // Chest overwrites X with obj149C/obj14A4 for its closed/open branches.
  if (object_id == 0xF99) {
    auto closed_tiles = ReadTileData(
        kRoomObjectTileAddress + kClosedChestTileOffset, kChestStateTileCount);
    if (!closed_tiles.ok()) {
      return closed_tiles.status();
    }
    auto open_tiles = ReadTileData(
        kRoomObjectTileAddress + kOpenChestTileOffset, kChestStateTileCount);
    if (!open_tiles.ok()) {
      return open_tiles.status();
    }
    closed_tiles->insert(closed_tiles->end(), open_tiles->begin(),
                         open_tiles->end());
    return closed_tiles;
  }
 
  // BigChest likewise overwrites X with obj14AC/obj14C4. F9A/FB2 remain
  // direct-open routines and legitimately use their table-derived pointers.
  if (object_id == 0xFB1) {
    auto closed_tiles =
        ReadTileData(kRoomObjectTileAddress + kClosedBigChestTileOffset,
                     kBigChestStateTileCount);
    if (!closed_tiles.ok()) {
      return closed_tiles.status();
    }
    auto open_tiles =
        ReadTileData(kRoomObjectTileAddress + kOpenBigChestTileOffset,
                     kBigChestStateTileCount);
    if (!open_tiles.ok()) {
      return open_tiles.status();
    }
    closed_tiles->insert(closed_tiles->end(), open_tiles->begin(),
                         open_tiles->end());
    return closed_tiles;
  }
 
  // BigGrayRock replaces the table-derived data pointer with literal obj0E62,
  // then draws its four contiguous 2x2 quadrants. Follow the runtime literal
  // so a relocated FAC table entry cannot change only the editor rendering.
  if (object_id == 0xFAC) {
    return ReadTileData(kRoomObjectTileAddress + kBigGrayRockTileOffset,
                        kBigGrayRockTileCount);
  }
 
  // AgahnimsAltar replaces the table-derived pointer with literal obj1B4A,
  // then mirrors its six source columns into a fixed 14x14 destination.
  if (object_id == 0xFAD) {
    return ReadTileData(kRoomObjectTileAddress + kAgahnimsAltarTileOffset,
                        kAgahnimsAltarTileCount);
  }
 
  // FortuneTellerRoom ignores its table-derived pointer and loads literal
  // obj202E before writing a sparse, fixed 14x14 room facade.
  if (object_id == 0xFD4) {
    return ReadTileData(kRoomObjectTileAddress + kFortuneTellerRoomTileOffset,
                        kFortuneTellerRoomTileCount);
  }
 
  // SmithyFurnace replaces the table-derived data pointer with literal
  // obj1F92 before drawing. Mirror the runtime source rather than allowing a
  // relocated FCC table entry to change only the editor's rendering.
  if (object_id == 0xFCC) {
    return ReadTileData(kRoomObjectTileAddress + kSmithyFurnaceTileOffset,
                        kSmithyFurnaceTileCount);
  }
 
  return ReadTileData(tile_data_ptr, tile_count);
}
 
absl::StatusOr<std::vector<gfx::TileInfo>> ObjectParser::ReadTileData(
    int address, int tile_count) {
  // Each tile is stored as a 16-bit word (2 bytes), not 8 bytes!
  // ZScream: tiles.Add(new Tile(ROM.DATA[pos + ((i * 2))], ROM.DATA[pos + ((i *
  // 2)) + 1]));
  if (tile_count < 0) {
    return absl::InvalidArgumentError(
        absl::StrFormat("Invalid tile count: %d", tile_count));
  }
  if (tile_count == 0) {
    return std::vector<gfx::TileInfo>{};
  }
  if (address < 0 || address + (tile_count * 2) >= (int)rom_->size()) {
    return absl::OutOfRangeError(
        absl::StrFormat("Tile data address out of range: %#06x", address));
  }
 
  if (tile_read_range_collector_ != nullptr) {
    tile_read_range_collector_->push_back(
        {static_cast<uint32_t>(address),
         static_cast<uint32_t>(address + tile_count * 2)});
  }
 
  std::vector<gfx::TileInfo> tiles;
  tiles.reserve(tile_count);
 
  // DEBUG: Log first tile read
  static int debug_read_count = 0;
  bool should_log = (debug_read_count < 3);
 
  for (int i = 0; i < tile_count; i++) {
    int tile_offset = address + (i * 2);  // 2 bytes per tile word
 
    // Read 1 word (2 bytes) per tile - this is the SNES tile format
    uint16_t tile_word =
        rom_->data()[tile_offset] | (rom_->data()[tile_offset + 1] << 8);
 
    auto tile_info = gfx::WordToTileInfo(tile_word);
    tiles.push_back(tile_info);
 
    // DEBUG: Log first few tiles
    if (should_log && i < 4) {
      LOG_DEBUG("ObjectParser",
                "ReadTile[%d]: addr=0x%06X word=0x%04X id=0x%03X pal=%d "
                "mirror=(h:%d,v:%d)",
                i, tile_offset, tile_word, tile_info.id_, tile_info.palette_,
                tile_info.horizontal_mirror_, tile_info.vertical_mirror_);
    }
  }
 
  if (should_log) {
    LOG_DEBUG("ObjectParser",
              "ReadTileData: addr=0x%06X count=%d loaded %zu tiles", address,
              tile_count, tiles.size());
    debug_read_count++;
  }
 
  return tiles;
}
 
int ObjectParser::GetSubtype2TileCount(int16_t object_id) const {
  // 4x4 corners (0x100-0x10F): 16 tiles (32 bytes)
  // These are RoomDraw_4x4 and RoomDraw_4x4Corner_BothBG routines
  if (object_id >= 0x100 && object_id <= 0x10F) {
    return 16;
  }
  // Weird corners (0x110-0x117): 12 tiles (24 bytes)
  // These are RoomDraw_WeirdCornerBottom_BothBG and RoomDraw_WeirdCornerTop_BothBG
  if (object_id >= 0x110 && object_id <= 0x117) {
    return 12;
  }
  // Enabled star switch and lit torch are fixed 2x2 patterns.
  if (object_id == 0x11F || object_id == 0x120) {
    return 4;
  }
  // 4x4 fixed patterns (stairs/walls)
  if (object_id == 0x11C || object_id == 0x124 || object_id == 0x125 ||
      object_id == 0x129 || (object_id >= 0x12D && object_id <= 0x133) ||
      object_id == 0x13C) {
    return 16;
  }
  // Magic Bat altar is subtype-2 object 0x13F (table index 0x3F).
  // RoomDraw_MagicBatAltar consumes eight columns of seven words from obj2086.
  if (object_id == 0x13F) {
    return 56;
  }
  // Water hop stairs use a fixed 4x2 pattern.
  if (object_id == 0x135 || object_id == 0x136) {
    return 8;
  }
  // Dam floodgate preserves both closed and water-open 10x4 tile blocks.
  if (object_id == 0x137) {
    return 80;
  }
  // Beds (4x5)
  if (object_id == 0x122 || object_id == 0x128) {
    return 20;
  }
  // Tables (4x3)
  if (object_id == 0x123 || object_id == 0x13D) {
    return 12;
  }
  // 3x6 and 6x3 utility patterns
  if (object_id == 0x12C || object_id == 0x13E) {
    return 18;
  }
  // Spiral stairs (4x3)
  if (object_id >= 0x138 && object_id <= 0x13B) {
    return 12;
  }
  // Default: 8 tiles for other subtype 2 objects
  return 8;
}
 
int ObjectParser::GetSubtype3TileCount(int16_t object_id) const {
  // Water face variants:
  // - 0xF80 (Empty) may branch to the 0xF81 tile block at runtime, so we load
  //   both spans to preserve parity for state-dependent rendering.
  // - 0xF81 (Spitting): 4x5
  // - 0xF82 (Drenching): 4x7
  if (object_id == 0xF80) {
    return 32;
  }
  if (object_id == 0xF81) {
    return 20;
  }
  if (object_id == 0xF82) {
    return 28;
  }
 
  // RoomDraw_PrisonCell loads literal obj1488 and consumes its six words for
  // both object aliases.
  if (object_id == 0xF8D || object_id == 0xF97) {
    return 6;
  }
 
  // RupeeFloor (0xF92 = ASM 0x212) reads the two words at obj1DD6 and
  // repeats them at fixed positions.
  if (object_id == 0xF92) {
    return 2;
  }
 
  // HammerPegSingle (0xF96 = ASM 0x216) jumps to
  // RoomDraw_Rightwards2x2 and consumes one fixed 2x2 tile block.
  if (object_id == 0xF96) {
    return 4;
  }
 
  // BigKeyLock (0xF98 = ASM 0x218) loads literal obj1494 and consumes exactly
  // one fixed 2x2 block. The following four words belong to obj149C (Chest),
  // not to an alternate lock state.
  if (object_id == 0xF98) {
    return 4;
  }
 
  // Chest (F99) carries both closed/open 2x2 states. OpenChest (F9A) is
  // already the fixed open state and consumes one 2x2 payload.
  if (object_id == 0xF99) {
    return 8;
  }
  if (object_id == 0xF9A) {
    return 4;
  }
 
  // BombableFloor (0xFC7 = ASM 0x247) has two non-contiguous 4x4 states:
  // 16 intact words from the object pointer and 16 replacement words at
  // obj05BA. ParseSubtype3 loads and concatenates both spans.
  if (object_id == 0xFC7) {
    return 32;
  }
 
  // Somaria path pieces (ASM objects 0x203-0x20C, 0x20E, and 0x20F) each
  // point to one tile word. RoomDraw_SomariaLine writes that word once.
  if ((object_id >= 0xF83 && object_id <= 0xF8C) || object_id == 0xF8E ||
      object_id == 0xF8F) {
    return 1;
  }
 
  // BigChest (FB1) carries closed/open 4x3 states. OpenBigChest (FB2) is the
  // fixed open state. Both draw through RoomDraw_1x3N_rightwards with N=4.
  if (object_id == 0xFB1) {
    return 24;
  }
  if (object_id == 0xFB2) {
    return 12;
  }
  // TableRock4x3 variants (0xF94, 0xFCE, 0xFE7-0xFE8, 0xFEC-0xFED): 12 tiles
  if (object_id == 0xF94 || object_id == 0xFCE ||
      (object_id >= 0xFE7 && object_id <= 0xFE8) ||
      (object_id >= 0xFEC && object_id <= 0xFED)) {
    return 12;
  }
  // 4x4 pattern objects: 16 tiles
  // (0xFC8 = 0x248, 0xFE6 = 0x266, 0xFEB = 0x26B, 0xFFA = 0x27A)
  if (object_id == 0xFC8 || object_id == 0xFE6 || object_id == 0xFEB ||
      object_id == 0xFFA) {
    return 16;
  }
  // Boss shells (4x4)
  if (object_id == 0xF95 || object_id == 0xFF2) {
    return 16;
  }
  // Vitreous goo damage reuses one 8-word 4x2 source stamp across a fixed
  // 5x2 grid of 4x4 destinations.
  if (object_id == 0xFFB) {
    return 8;
  }
  // Auto stairs (4x4)
  if ((object_id >= 0xF9B && object_id <= 0xF9D) || object_id == 0xFB3) {
    return 16;
  }
  // Straight inter-room stairs (4x4)
  if ((object_id >= 0xF9E && object_id <= 0xFA1) ||
      (object_id >= 0xFA6 && object_id <= 0xFA9)) {
    return 16;
  }
  // BigGrayRock (0xFAC = ASM 0x22C) loads obj0E62 and draws four fixed
  // 2x2 quadrants, consuming 16 contiguous tile words.
  if (object_id == 0xFAC) {
    return 16;
  }
  // AgahnimsAltar (0xFAD = ASM 0x22D) consumes six 14-tile source columns
  // from obj1B4A before mirroring them into a 14x14 destination.
  if (object_id == 0xFAD) {
    return 84;
  }
  // FortuneTellerRoom (0xFD4 = ASM 0x254) consumes all 26 words from obj202E
  // while writing a sparse, fixed 14x14 BG1 footprint.
  if (object_id == 0xFD4) {
    return 26;
  }
  // SmithyFurnace (0xFCC = ASM 0x24C) loads obj1F92 and draws a fixed
  // 6-column x 8-row block through RoomDraw_SomeBigDecors.
  if (object_id == 0xFCC) {
    return 48;
  }
  // 4x4 single-pattern objects
  if (object_id == 0xFAA || object_id == 0xFAE ||
      (object_id >= 0xFB4 && object_id <= 0xFB9) || object_id == 0xFE2) {
    return 16;
  }
  // Big wall decor aliases: RoomDraw_BigWallDecor calls
  // RoomDraw_1x3N_rightwards with A=8, consuming 8 columns x 3 rows.
  if (object_id == 0xFCB || object_id == 0xFF6 || object_id == 0xFF7) {
    return 24;
  }
  // Turtle Rock pipes: 24 tiles (proven from routine bodies, not just
  // dimensions table). DrawVerticalTurtleRockPipe (0xFBA, 0xFBB) draws two
  // stacked 4x3 sections, reading tiles[0..11] then tiles[12..23].
  // DrawHorizontalTurtleRockPipe (0xFBC, 0xFBD, 0xFDC / ASM 0x25C) calls
  // DrawNx4 with columns=6, which reads a 6x4 column-major block
  // (tiles[0..23]).
  // Without this case the parser fell through to the default 8 and
  // TileAtWrapped substituted tiles[0..7] for indices 8..23 -- same
  // failure mode Waterfall47/48 had before e9938002.
  if ((object_id >= 0xFBA && object_id <= 0xFBD) || object_id == 0xFDC) {
    return 24;
  }
  // Utility 6x3 (18 tiles)
  if (object_id == 0xFCD || object_id == 0xFDD) {
    return 18;
  }
  // Utility 3x5 (15 tiles)
  if (object_id == 0xFD5 || object_id == 0xFDB) {
    return 15;
  }
  // Archery game target door (3x6, 18 tiles)
  if (object_id >= 0xFE0 && object_id <= 0xFE1) {
    return 18;
  }
  // Solid wall decor 3x4 (12 tiles)
  if (object_id == 0xFE9 || object_id == 0xFEA || object_id == 0xFEE ||
      object_id == 0xFEF) {
    return 12;
  }
  // LightBeamOnFloor (0xFF0 / ASM 0x270) reads two unique 4x4 blocks:
  // obj2376 is reused for the top and overlapping middle stamps, then
  // obj2396 supplies the bottom stamp.
  if (object_id == 0xFF0) {
    return 32;
  }
  // BigLightBeamOnFloor (0xFF1 / ASM 0x271) draws four unique 4x4 blocks.
  if (object_id == 0xFF1) {
    return 64;
  }
  // FloorLight (0xFF4 / ASM 0x274) unconditionally draws four unique 4x4
  // blocks in an 8x8 grid.
  if (object_id == 0xFF4) {
    return 64;
  }
  // Ganon Triforce floor decor (two 4x4 blocks -> 32 tiles)
  if (object_id == 0xFF8) {
    return 32;
  }
  // Table rock 4x3
  if (object_id == 0xFF9) {
    return 12;
  }
  // Default: 8 tiles for most subtype 3 objects
  return 8;
}
 
int ObjectParser::DetermineSubtype(int16_t object_id) const {
  // Type 3 IDs from decoding are 0xF80-0xFFF (b3 0xF8-0xFF shifted).
  if (object_id >= 0xF80) {
    return 3;
  } else if (object_id >= 0x100) {
    return 2;
  } else {
    return 1;
  }
}
 
int ObjectParser::ResolveTileCountForObject(int16_t object_id) const {
  if (object_id < 0) {
    return 1;
  }
 
  switch (DetermineSubtype(object_id)) {
    case 1:
      return GetSubtype1TileCount(object_id);
    case 2:
      return GetSubtype2TileCount(object_id);
    case 3:
      return GetSubtype3TileCount(object_id);
    default:
      return 1;
  }
}
 
ObjectDrawInfo ObjectParser::GetObjectDrawInfo(int16_t object_id) const {
  ObjectDrawInfo info;
 
  // Keep draw-info tile counts sourced from subtype tables (ROM-facing data),
  // while routine selection comes from DrawRoutineRegistry (renderer-facing
  // canonical mapping).
  info.tile_count = ResolveTileCountForObject(object_id);
  const bool is_vertical_band = (object_id >= 0x60 && object_id <= 0x6F);
  info.is_horizontal = !is_vertical_band;
  info.is_vertical = is_vertical_band;
 
  info.draw_routine_id = DrawRoutineIds::kRightwards1x1Solid_1to16_plus3;
  info.routine_name = "DefaultSolid";
  info.both_layers = false;
 
  auto& registry = DrawRoutineRegistry::Get();
  // Feature flags (custom objects) can be toggled at runtime by project
  // context, so keep parser metadata aligned with current registry mappings.
  registry.RefreshFeatureFlagMappings();
 
  int registry_routine = registry.GetRoutineIdForObject(object_id);
  if (registry_routine < 0) {
    return info;
  }
 
  info.draw_routine_id = registry_routine;
  if (const DrawRoutineInfo* routine_info =
          registry.GetRoutineInfo(registry_routine);
      routine_info != nullptr) {
    info.routine_name = routine_info->name;
    info.both_layers = routine_info->draws_to_both_bgs;
 
    switch (routine_info->category) {
      case DrawRoutineInfo::Category::Downwards:
        info.is_horizontal = false;
        info.is_vertical = true;
        break;
      case DrawRoutineInfo::Category::Diagonal:
        info.is_horizontal = false;
        info.is_vertical = false;
        break;
      default:
        info.is_horizontal = true;
        info.is_vertical = false;
        break;
    }
  }
 
  return info;
}
 
}  // namespace zelda3
}  // namespace yaze