object_drawer.cc

Go to the documentation of this file.

#include "object_drawer.h"
 
#include <algorithm>
#include <array>
#include <cstdio>
#include <cstring>
#include <filesystem>
 
#include "absl/strings/str_format.h"
#include "app/gfx/types/snes_tile.h"
#include "core/features.h"
#include "rom/rom.h"
#include "rom/snes.h"
#include "util/log.h"
#include "zelda3/dungeon/dimension_service.h"
#include "zelda3/dungeon/draw_routines/draw_routine_registry.h"
#include "zelda3/dungeon/draw_routines/draw_routine_types.h"
#include "zelda3/dungeon/draw_routines/special_routines.h"
#include "zelda3/dungeon/dungeon_rom_addresses.h"
#include "zelda3/dungeon/object_dimensions.h"
#include "zelda3/dungeon/object_layer_semantics.h"
#include "zelda3/dungeon/object_parser.h"
 
namespace yaze {
namespace zelda3 {
namespace {
 
bool LockSurface(SDL_Surface* surface) {
#if SDL_MAJOR_VERSION >= 3
  return SDL_LockSurface(surface);
#else
  return SDL_LockSurface(surface) == 0;
#endif
}
 
void SyncModifiedBitmapToSurface(gfx::Bitmap& bitmap, const char* layer_name) {
  SDL_Surface* surface = bitmap.surface();
  if (!bitmap.modified() || surface == nullptr || bitmap.size() == 0) {
    return;
  }
 
  if (bitmap.depth() != 8) {
    LOG_DEBUG("ObjectDrawer", "%s bitmap depth is not indexed 8bpp: %d",
              layer_name, bitmap.depth());
    return;
  }
 
  const int width = bitmap.width();
  const int height = bitmap.height();
  if (width <= 0 || height <= 0 || surface->w < width || surface->h < height ||
      surface->pitch < width) {
    LOG_DEBUG("ObjectDrawer",
              "%s surface dimensions cannot hold bitmap: surface=%dx%d "
              "pitch=%d bitmap=%dx%d",
              layer_name, surface->w, surface->h, surface->pitch, width,
              height);
    return;
  }
 
  const size_t row_bytes = static_cast<size_t>(width);
  const size_t required_bytes = row_bytes * static_cast<size_t>(height);
  if (bitmap.size() < required_bytes) {
    LOG_DEBUG("ObjectDrawer", "%s bitmap data too small: data=%zu needed=%zu",
              layer_name, bitmap.size(), required_bytes);
    return;
  }
 
  if (!LockSurface(surface)) {
    LOG_DEBUG("ObjectDrawer", "%s surface lock failed: %s", layer_name,
              SDL_GetError());
    return;
  }
  auto* destination = static_cast<uint8_t*>(surface->pixels);
  const uint8_t* source = bitmap.data();
  for (int y = 0; y < height; ++y) {
    std::memcpy(destination + static_cast<size_t>(y) *
                                  static_cast<size_t>(surface->pitch),
                source + static_cast<size_t>(y) * row_bytes, row_bytes);
  }
  SDL_UnlockSurface(surface);
}
 
// Sets the priority bit of the tile word already stored at (tile_x, tile_y),
// as USDASM's ORA #$2000 does. An empty word means this buffer did not draw
// the tile, so it is left empty; the other buffer's word is what shows there.
void PromoteTileWordPriority(gfx::BackgroundBuffer& target, int tile_x,
                             int tile_y) {
  constexpr uint16_t kPriorityBit = 0x2000;
  const uint16_t word = target.GetTileAt(tile_x, tile_y);
  if (word != 0) {
    target.SetTileAt(tile_x, tile_y, word | kPriorityBit);
  }
}
 
void PromoteTilePriorityOnly(gfx::BackgroundBuffer& target, int tile_x,
                             int tile_y) {
  PromoteTileWordPriority(target, tile_x, tile_y);
  for (int py = 0; py < 8; ++py) {
    for (int px = 0; px < 8; ++px) {
      target.SetPriorityAt(tile_x * 8 + px, tile_y * 8 + py, 1);
    }
  }
}
 
void PromoteTilePriorityOnOwners(gfx::BackgroundBuffer& object_owner,
                                 gfx::BackgroundBuffer* layout_owner,
                                 int tile_x, int tile_y) {
  // The SNES mutates one physical tilemap. Yaze temporarily splits that map
  // between layout and object buffers, so update both possible pixel owners
  // without writing bitmap pixels, coverage, or a new tile word.
  PromoteTilePriorityOnly(object_owner, tile_x, tile_y);
  if (layout_owner != nullptr && layout_owner != &object_owner) {
    PromoteTilePriorityOnly(*layout_owner, tile_x, tile_y);
  }
}
 
}  // namespace
 
ObjectDrawer::ObjectDrawer(Rom* rom, int room_id,
                           const uint8_t* room_gfx_buffer,
                           const CustomObjectRenderSnapshot* custom_objects)
    : custom_objects_(custom_objects),
      rom_(rom),
      room_id_(room_id),
      room_gfx_buffer_(room_gfx_buffer) {
  InitializeDrawRoutines();
}
 
void ObjectDrawer::SetTraceCollector(std::vector<TileTrace>* collector,
                                     bool trace_only) {
  trace_collector_ = collector;
  trace_only_ = trace_only;
}
 
void ObjectDrawer::ClearTraceCollector() {
  trace_collector_ = nullptr;
  trace_only_ = false;
}
 
void ObjectDrawer::SetTraceContext(const RoomObject& object,
                                   RoomObject::LayerType layer) {
  trace_context_.object_id = static_cast<uint16_t>(object.id_);
  trace_context_.size = object.size_;
  trace_context_.layer = static_cast<uint8_t>(layer);
}
 
void ObjectDrawer::PushTrace(int tile_x, int tile_y,
                             const gfx::TileInfo& tile_info) {
  if (!trace_collector_) {
    return;
  }
  uint8_t flags = 0;
  if (tile_info.horizontal_mirror_)
    flags |= 0x1;
  if (tile_info.vertical_mirror_)
    flags |= 0x2;
  if (tile_info.over_)
    flags |= 0x4;
  flags |= static_cast<uint8_t>((tile_info.palette_ & 0x7) << 3);
 
  TileTrace trace{};
  trace.object_id = trace_context_.object_id;
  trace.size = trace_context_.size;
  trace.layer = trace_context_.layer;
  trace.x_tile = static_cast<int16_t>(tile_x);
  trace.y_tile = static_cast<int16_t>(tile_y);
  trace.tile_id = tile_info.id_;
  trace.flags = flags;
  trace_collector_->push_back(trace);
}
 
void ObjectDrawer::TraceHookThunk(gfx::BackgroundBuffer* /*bg*/, int tile_x,
                                  int tile_y, const gfx::TileInfo& tile_info,
                                  void* user_data) {
  auto* drawer = static_cast<ObjectDrawer*>(user_data);
  if (!drawer || tile_y >= DrawContext::kMaxTilesY) {
    return;
  }
  drawer->PushTrace(tile_x, tile_y, tile_info);
}
 
void ObjectDrawer::DrawUsingRegistryRoutine(
    int routine_id, const RoomObject& obj, gfx::BackgroundBuffer& bg,
    std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
  // Many DrawRoutineRegistry routines are implemented as pure functions that
  // call DrawRoutineUtils::WriteTile8(), which only writes to BackgroundBuffer's
  // tile buffer (not the bitmap). Runtime rendering/compositing uses the
  // bitmap-backed buffers, so we capture tile writes from the pure routine and
  // replay them via ObjectDrawer::WriteTile8().
  const auto* info = DrawRoutineRegistry::Get().GetRoutineInfo(routine_id);
  if (info == nullptr) {
    LOG_DEBUG("ObjectDrawer", "DrawUsingRegistryRoutine: unknown routine %d",
              routine_id);
    return;
  }
 
  struct CapturedWrite {
    int x = 0;
    int y = 0;
    gfx::TileInfo tile{};
    bool secondary = false;
  };
 
  struct CaptureState {
    std::vector<CapturedWrite>* writes = nullptr;
    gfx::BackgroundBuffer* secondary_bg = nullptr;
  };
 
  std::vector<CapturedWrite> writes;
  writes.reserve(256);
  CaptureState capture_state{.writes = &writes,
                             .secondary_bg = registry_secondary_bg_};
 
  DrawRoutineUtils::SetTraceHook(
      [](gfx::BackgroundBuffer* target_bg, int tile_x, int tile_y,
         const gfx::TileInfo& tile_info, void* user_data) {
        auto* capture = static_cast<CaptureState*>(user_data);
        if (!capture || !capture->writes) {
          return;
        }
        capture->writes->push_back(CapturedWrite{
            .x = tile_x,
            .y = tile_y,
            .tile = tile_info,
            .secondary =
                target_bg != nullptr && target_bg == capture->secondary_bg,
        });
      },
      &capture_state,
      /*trace_only=*/true);
 
  DrawContext ctx{
      .target_bg = bg,
      .object = obj,
      .tiles = tiles,
      .state = state,
      .rom = rom_,
      .room_id = room_id_,
      .room_gfx_buffer = room_gfx_buffer_,
      .secondary_bg = registry_secondary_bg_,
      .target_layout_bg = registry_primary_layout_bg_,
      .room_tag2 = room_tag2_,
      .custom_objects = custom_objects_,
  };
  info->function(ctx);
 
  DrawRoutineUtils::ClearTraceHook();
 
  for (const auto& w : writes) {
    gfx::BackgroundBuffer* target = &bg;
    RoomObject::LayerType layer = registry_primary_layer_;
    if (w.secondary && registry_secondary_bg_ != nullptr) {
      target = registry_secondary_bg_;
      layer = registry_secondary_layer_;
    }
    int tile_y = w.y;
    if (tile_y >= DrawContext::kMaxTilesY) {
      // $7E2000 row 64+ is $7E4000 (BG2) row - 64, e.g. a size-0 0x60
      // column from row 4 in room 0x10C. BG2 rows past 63 leave the
      // tilemaps entirely.
      if (layer != RoomObject::LayerType::BG1 || registry_bg2_ == nullptr) {
        continue;
      }
      target = registry_bg2_;
      layer = RoomObject::LayerType::BG2;
      tile_y -= DrawContext::kMaxTilesY;
    }
    SetTraceContext(obj, layer);
    WriteTile8(*target, w.x, tile_y, w.tile);
  }
}
 
absl::Status ObjectDrawer::DrawObject(
    const RoomObject& object, gfx::BackgroundBuffer& bg1,
    gfx::BackgroundBuffer& bg2, const gfx::PaletteGroup& palette_group,
    [[maybe_unused]] const DungeonState* state,
    gfx::BackgroundBuffer* layout_bg1, gfx::BackgroundBuffer* layout_bg2) {
  if (!rom_ || !rom_->is_loaded()) {
    return absl::FailedPreconditionError("ROM not loaded");
  }
 
  if (!routines_initialized_) {
    return absl::FailedPreconditionError("Draw routines not initialized");
  }
 
  // Ensure object has tiles loaded
  auto mutable_obj = const_cast<RoomObject&>(object);
  mutable_obj.SetRom(rom_);
  mutable_obj.EnsureTilesLoaded();
 
  // Select buffer based on layer
  // Layer 0 (BG1): Main objects - drawn to BG1_Objects (on top of layout)
  // Layer 1 (BG2): Overlay objects - drawn to BG2_Objects (behind layout)
  // Layer 2 (BG3): Priority objects (torches) - drawn to BG1_Objects (on top)
  bool use_bg2 = (object.layer_ == RoomObject::LayerType::BG2);
  auto& target_bg = use_bg2 ? bg2 : bg1;
  auto& other_bg = use_bg2 ? bg1 : bg2;
 
  // Log buffer selection for debugging layer routing
  LOG_DEBUG("ObjectDrawer", "Object 0x%03X layer=%d -> drawing to %s buffer",
            object.id_, static_cast<int>(object.layer_),
            use_bg2 ? "BG2 (behind layout)" : "BG1 (on top of layout)");
 
  // Check for custom object override first (guarded by feature flag).
  // We check this BEFORE routine lookup to allow overriding vanilla objects.
  const bool custom_override =
      custom_objects_ != nullptr
          ? custom_objects_->enabled() &&
                custom_objects_->GetObject(object.id_, object.size_ & 0x1F).ok()
          : HasActiveCustomObjectOverride(object);
  if (custom_override) {
    // Custom objects default to drawing on the target layer only, unless all_bgs_ is set
    // Mask propagation is difficult without dimensions, so we rely on explicit transparency in the custom object tiles if needed
 
    // Draw to target layer
    SetTraceContext(object, use_bg2 ? RoomObject::LayerType::BG2
                                    : RoomObject::LayerType::BG1);
    DrawCustomObject(object, target_bg, mutable_obj.tiles(), state);
 
    // If marked for both BGs, draw to the other layer too
    if (object.all_bgs_) {
      SetTraceContext(object, (&other_bg == &bg1) ? RoomObject::LayerType::BG1
                                                  : RoomObject::LayerType::BG2);
      DrawCustomObject(object, other_bg, mutable_obj.tiles(), state);
    }
    return absl::OkStatus();
  }
 
  // Type-3 routines that write fixed tilemap data regardless of the object's
  // position and size. Checked against tilemaps captured from the game.
  if (object.id_ == 0xFF3) {
    return DrawLayerMaskFull(
        object, target_bg,
        use_bg2 ? RoomObject::LayerType::BG2 : RoomObject::LayerType::BG1);
  }
  if (object.id_ == 0xFAA) {
    return DrawLampCones(object, bg2);
  }
  if (object.id_ == 0xFAE) {
    return DrawAgahnimsWindows(object, bg1, bg2, layout_bg1, layout_bg2);
  }
  if (object.id_ == 0xFE2) {
    return DrawVitreousGoo(object, bg2);
  }
  if ((object.id_ == 0xF95 || object.id_ == 0xFF2) && state != nullptr &&
      state->IsBossShellCleared(room_id_)) {
    return absl::OkStatus();  // $0402 bit 15: shell already gone.
  }
  if (object.id_ == 0xF95 || object.id_ == 0xFF2) {
    // Kholdstare's shell reads fixed data (obj1DFA); Trinexx's shell reads
    // its own payload (TXY). Both skip drawing once $0402 bit 15 is set in
    // the game; the editor shows the room as first entered.
    int data_pc = kRoomObjectTileAddress + 0x1DFA;
    if (object.id_ == 0xFF2) {
      // The object's own data: .type1_subtype_3_data_offset[id - 0xF80].
      const auto& rom_data = rom_->vector();
      const int entry = kRoomObjectSubtype3 + (object.id_ - 0xF80) * 2;
      if (entry < 0 || entry + 1 >= static_cast<int>(rom_data.size())) {
        return absl::OutOfRangeError("Trinexx shell data offset out of range");
      }
      data_pc =
          kRoomObjectTileAddress +
          static_cast<int16_t>(rom_data[entry] | (rom_data[entry + 1] << 8));
    }
    return DrawBigDecor10x8(
        object, target_bg,
        use_bg2 ? RoomObject::LayerType::BG2 : RoomObject::LayerType::BG1,
        data_pc);
  }
 
  std::array<gfx::TileInfo, 8> room_floor_tiles;
  std::span<const gfx::TileInfo> render_tiles = mutable_obj.tiles();
  // Keep source patterns out of the RoomObject cache and ROM save path. Worker
  // draws use their immutable snapshot rather than the active session.
  auto patterns = custom_objects_ != nullptr
                      ? custom_objects_->tile_patterns()
                      : CustomObjectManager::Get().GetTilePatterns();
  if (!patterns.ok())
    return patterns.status();
  std::vector<gfx::TileInfo> source_tiles;
  if (*patterns) {
    ObjectParser parser(rom_, patterns->get());
    auto parsed = parser.ParseObject(object.id_);
    if (!parsed.ok())
      return parsed.status();
    source_tiles = std::move(*parsed);
    render_tiles = source_tiles;
  }
  if (has_room_floor_graphics_ &&
      (object.id_ == 0x00C4 || object.id_ == 0x00DB)) {
    const uint8_t floor_graphics =
        object.id_ == 0x00C4 ? floor1_graphics_ : floor2_graphics_;
    const auto decoded = gfx::DecodeDungeonFloorTilePattern(
        rom_->vector(), kRoomObjectTileAddress, kRoomObjectTileAddressFloor,
        floor_graphics);
    if (!decoded.has_value()) {
      return absl::DataLossError(
          absl::StrFormat("Object 0x%03X cannot read room floor pattern %d",
                          object.id_, static_cast<int>(floor_graphics)));
    }
    room_floor_tiles = *decoded;
    render_tiles = room_floor_tiles;
  }
 
  // Skip objects that don't have tiles loaded
  if (render_tiles.empty()) {
    LOG_DEBUG("ObjectDrawer",
              "Object 0x%03X at (%d,%d) has NO TILES - skipping", object.id_,
              object.x_, object.y_);
    return absl::OkStatus();
  }
 
  // Look up draw routine for this object
  int routine_id = GetDrawRoutineId(object.id_);
 
  // Log draw routine lookup with tile info
  LOG_DEBUG("ObjectDrawer",
            "Object 0x%03X at (%d,%d) size=%d -> routine=%d tiles=%zu",
            object.id_, object.x_, object.y_, object.size_, routine_id,
            render_tiles.size());
 
  if (routine_id < 0 || routine_id >= static_cast<int>(draw_routines_.size())) {
    LOG_DEBUG("ObjectDrawer",
              "Object 0x%03X: NO ROUTINE (id=%d, max=%zu) - using fallback 1x1",
              object.id_, routine_id, draw_routines_.size());
    // Fallback to simple 1x1 drawing using first 8x8 tile
    if (!render_tiles.empty()) {
      const auto& tile_info = render_tiles[0];
      SetTraceContext(object, use_bg2 ? RoomObject::LayerType::BG2
                                      : RoomObject::LayerType::BG1);
      WriteTile8(target_bg, object.x_, object.y_, tile_info);
    }
    return absl::OkStatus();
  }
 
  // Null-tile guard: skip routines whose tile payload is too small.
  // Hack ROMs with abbreviated tile tables would otherwise cause
  // out-of-bounds access in fixed-size draw patterns.
  const DrawRoutineInfo* routine_info =
      DrawRoutineRegistry::Get().GetRoutineInfo(routine_id);
  if (routine_info && routine_info->min_tiles > 0 &&
      static_cast<int>(render_tiles.size()) < routine_info->min_tiles) {
    LOG_WARN("ObjectDrawer",
             "Object 0x%03X at (%d,%d): tile payload too small "
             "(%zu < %d required by routine '%s') - skipping",
             object.id_, object.x_, object.y_, render_tiles.size(),
             routine_info->min_tiles, routine_info->name.c_str());
    // Fall through to 1x1 fallback if any tiles are present
    if (!render_tiles.empty()) {
      const auto& tile_info = render_tiles[0];
      SetTraceContext(object, use_bg2 ? RoomObject::LayerType::BG2
                                      : RoomObject::LayerType::BG1);
      WriteTile8(target_bg, object.x_, object.y_, tile_info);
    }
    return absl::OkStatus();
  }
 
  bool trace_hook_active = false;
  if (trace_collector_) {
    DrawRoutineUtils::SetTraceHook(&ObjectDrawer::TraceHookThunk, this,
                                   trace_only_);
    trace_hook_active = true;
  }
 
  // Check if this should draw to both BG layers.
  // In the original engine, BothBG routines explicitly write to both tilemaps
  // regardless of which object list or pass they are executed from.
  bool is_both_bg = (object.all_bgs_ || RoutineDrawsToBothBGs(routine_id));
  const bool use_rectangular_bg1_mask =
      !trace_only_ && object.layer_ == RoomObject::LayerType::BG2 &&
      !is_both_bg && RequiresRectangularBg1Mask(object);
  const bool use_pixel_bg1_mask = !trace_only_ &&
                                  object.layer_ == RoomObject::LayerType::BG2 &&
                                  !is_both_bg && !use_rectangular_bg1_mask;
 
  registry_secondary_bg_ = nullptr;
  registry_bg2_ = &bg2;
  registry_primary_layout_bg_ =
      use_bg2 ? static_cast<const gfx::BackgroundBuffer*>(layout_bg2)
              : static_cast<const gfx::BackgroundBuffer*>(layout_bg1);
  registry_primary_layer_ =
      use_bg2 ? RoomObject::LayerType::BG2 : RoomObject::LayerType::BG1;
  registry_secondary_layer_ =
      use_bg2 ? RoomObject::LayerType::BG1 : RoomObject::LayerType::BG2;
  gfx::BackgroundBuffer* dispatch_bg = &target_bg;
 
  // Special routines may need a second buffer for mixed-layer draws or fixed
  // BG1/BG2 routing regardless of the parsed object-layer flag.
  if (!is_both_bg && (routine_id == DrawRoutineIds::kAgahnimsAltar ||
                      routine_id == DrawRoutineIds::kFortuneTellerRoom)) {
    // USDASM writes these fixed room facades directly to the upper tilemap at
    // $7E2000.
    dispatch_bg = &bg1;
    registry_primary_layer_ = RoomObject::LayerType::BG1;
  } else if (!is_both_bg && (routine_id == DrawRoutineIds::kAutoStairs ||
                             routine_id == DrawRoutineIds::kSanctuaryWall)) {
    registry_secondary_bg_ = &other_bg;
  } else if (!is_both_bg && routine_id == DrawRoutineIds::kDamFloodGate) {
    // The open gate's water flooring goes to $7E4000.
    registry_secondary_bg_ = &bg2;
  } else if (!is_both_bg &&
             routine_id == DrawRoutineIds::kWaterOverlay8x8_1to16) {
    // The water-on stamp goes to $7E2000.
    registry_secondary_bg_ = &bg1;
  } else if (!is_both_bg &&
             routine_id == DrawRoutineIds::kStraightInterRoomStairs) {
    dispatch_bg = &bg1;
    registry_secondary_bg_ = &bg2;
    registry_primary_layer_ = RoomObject::LayerType::BG1;
    registry_secondary_layer_ = RoomObject::LayerType::BG2;
  }
 
  if (use_pixel_bg1_mask) {
    active_object_bg1_mask_ = &bg1;
    active_layout_bg1_mask_ = layout_bg1;
    active_mask_source_bg_ = &bg2;
  }
 
  if (is_both_bg) {
    // Draw to both background layers
    registry_secondary_bg_ = nullptr;
    registry_primary_layer_ = RoomObject::LayerType::BG1;
    registry_primary_layout_bg_ = layout_bg1;
    SetTraceContext(object, RoomObject::LayerType::BG1);
    draw_routines_[routine_id](this, object, bg1, render_tiles, state);
    registry_primary_layer_ = RoomObject::LayerType::BG2;
    registry_primary_layout_bg_ = layout_bg2;
    SetTraceContext(object, RoomObject::LayerType::BG2);
    draw_routines_[routine_id](this, object, bg2, render_tiles, state);
  } else {
    // Execute the appropriate draw routine on target buffer only
    registry_primary_layout_bg_ =
        dispatch_bg == &bg2
            ? static_cast<const gfx::BackgroundBuffer*>(layout_bg2)
            : static_cast<const gfx::BackgroundBuffer*>(layout_bg1);
    SetTraceContext(object, registry_primary_layer_);
    draw_routines_[routine_id](this, object, *dispatch_bg, render_tiles, state);
  }
 
  const bool is_upper_spiral =
      routine_id == DrawRoutineIds::kSpiralStairsGoingUpUpper ||
      routine_id == DrawRoutineIds::kSpiralStairsGoingDownUpper;
  const bool is_lower_spiral =
      routine_id == DrawRoutineIds::kSpiralStairsGoingUpLower ||
      routine_id == DrawRoutineIds::kSpiralStairsGoingDownLower;
  if (!trace_only_ && (is_upper_spiral || is_lower_spiral)) {
    auto& priority_object_owner = is_upper_spiral ? bg1 : bg2;
    auto* priority_layout_owner = is_upper_spiral ? layout_bg1 : layout_bg2;
    // USDASM ORs $2000 into the tile immediately left of the 4x3 raster and
    // the tile immediately right of it.
    for (const int tile_x : {object.x_ - 1, object.x_ + 4}) {
      PromoteTilePriorityOnOwners(priority_object_owner, priority_layout_owner,
                                  tile_x, object.y_);
    }
  }
 
  if (!trace_only_ &&
      object_render_routing::IsMixedStraightInterroomObject(object.id_)) {
    // USDASM promotes a fixed BG1 column outside the lower staircase raster.
    // North variants touch y-4..y-1; south variants touch y+4..y+7.
    const int priority_y =
        object_render_routing::IsNorthMixedStraightInterroomObject(object.id_)
            ? object.y_ - 4
            : object.y_ + 4;
    for (int row = 0; row < 4; ++row) {
      PromoteTilePriorityOnOwners(bg1, layout_bg1, object.x_, priority_y + row);
    }
  }
 
  if (trace_hook_active) {
    DrawRoutineUtils::ClearTraceHook();
  }
 
  active_object_bg1_mask_ = nullptr;
  active_layout_bg1_mask_ = nullptr;
  active_mask_source_bg_ = nullptr;
  registry_secondary_bg_ = nullptr;
  registry_bg2_ = nullptr;
  registry_primary_layout_bg_ = nullptr;
 
  // BG2 mask propagation is deferred to compositing so raw BG1 stays intact.
  //
  // Ordinary BG2 overlay objects mask per-pixel as they draw, which keeps
  // transparent cutouts intact for platforms/statues/stairs. Full-rect masking
  // remains only for true pit/ceiling mask families that intentionally clear an
  // area larger than their opaque tile pixels. Layer mode 6 ignores these legacy
  // cross-BG masks because its upper-main/lower-sub PPU setup is resolved by
  // transparency instead.
  if (use_rectangular_bg1_mask) {
    // Route through DimensionService so the mask rect comes from the same
    // source as selection bounds (ObjectGeometry if available, then
    // ObjectDimensionTable, then the size-nibble fallback). Keeps the
    // transparent cutout aligned with what the user sees in the editor.
    ObjectDimensionTable::Get().LoadFromRom(rom_).IgnoreError();
    const auto [mask_px_x, mask_px_y, pixel_width, pixel_height] =
        DimensionService::Get().GetSelectionBoundsPixels(object);
 
    LOG_DEBUG("ObjectDrawer",
              "Pit mask 0x%03X at (%d,%d) -> recording %dx%d BG1 reveal pixels",
              object.id_, mask_px_x / 8, mask_px_y / 8, pixel_width,
              pixel_height);
 
    MarkBg1RectRevealed(bg1, mask_px_x, mask_px_y, pixel_width, pixel_height);
    if (layout_bg1 != nullptr) {
      MarkBg1RectRevealed(*layout_bg1, mask_px_x, mask_px_y, pixel_width,
                          pixel_height);
    }
  }
 
  return absl::OkStatus();
}
 
bool ObjectDrawer::RequiresRectangularBg1Mask(const RoomObject& object) {
  return (object.id_ == 0xA4) ||                        // Pit
         (object.id_ >= 0xA5 && object.id_ <= 0xA8) ||  // Diagonal masks A
         (object.id_ == 0xC0) ||                        // Large ceiling overlay
         (object.id_ == 0xC2) ||                        // Layer 2 pit mask
         (object.id_ == 0xC3) ||                        // Layer 2 pit mask
         (object.id_ == 0xC6) ||                        // Layer 2 mask
         (object.id_ == 0xC8) ||                        // Water floor overlay
         (object.id_ == 0xD7) ||                        // Layer 2 mask
         (object.id_ == 0xD8) ||                        // Flood water overlay
         (object.id_ == 0xD9) ||                        // Layer 2 swim mask
         (object.id_ == 0xDA) ||                        // Flood water overlay B
         (object.id_ == 0xFE6) ||                       // Type 3 pit
         (object.id_ == 0xFF3);                         // Type 3 full mask
}
 
absl::Status ObjectDrawer::DrawObjectList(
    const std::vector<RoomObject>& objects, gfx::BackgroundBuffer& bg1,
    gfx::BackgroundBuffer& bg2, const gfx::PaletteGroup& palette_group,
    [[maybe_unused]] const DungeonState* state,
    gfx::BackgroundBuffer* layout_bg1, bool reset_room_event_indices,
    gfx::BackgroundBuffer* layout_bg2) {
  if (reset_room_event_indices) {
    ResetChestIndex();
  }
  absl::Status status = absl::OkStatus();
 
  // DEBUG: Count objects routed to each buffer
  int to_bg1 = 0, to_bg2 = 0, both_bgs = 0;
 
  for (const auto& object : objects) {
    const auto semantics = GetEffectiveObjectLayerSemantics(object);
    switch (semantics.effective_bg_layer) {
      case EffectiveBgLayer::kBg1:
        ++to_bg1;
        break;
      case EffectiveBgLayer::kBg2:
        ++to_bg2;
        break;
      case EffectiveBgLayer::kBothBg1Bg2:
        ++both_bgs;
        break;
    }
 
    auto s = DrawObject(object, bg1, bg2, palette_group, state, layout_bg1,
                        layout_bg2);
    if (!s.ok() && status.ok()) {
      status = s;
    }
  }
 
  LOG_DEBUG("ObjectDrawer", "Buffer routing: to_BG1=%d, to_BG2=%d, BothBGs=%d",
            to_bg1, to_bg2, both_bgs);
 
  // The palette is already applied by Room::RenderRoomGraphics(). SDL can pad
  // indexed surface rows, so synchronize each row using the surface pitch.
  SyncModifiedBitmapToSurface(bg1.bitmap(), "BG1");
  SyncModifiedBitmapToSurface(bg2.bitmap(), "BG2");
 
  return status;
}
 
// ============================================================================
// Metadata-based BothBG Detection
// ============================================================================
 
bool ObjectDrawer::RoutineDrawsToBothBGs(int routine_id) {
  // Use DrawRoutineRegistry as the single source of truth for BothBG metadata.
  return DrawRoutineRegistry::Get().RoutineDrawsToBothBGs(routine_id);
}
 
// ============================================================================
// Draw Routine Registry Initialization
// ============================================================================
 
void ObjectDrawer::InitializeDrawRoutines() {
  // This function maps object IDs to their corresponding draw routines.
  // The mapping is based on ZScream's DungeonObjectData.cs and the game's
  // assembly code. The order of functions in draw_routines_ MUST match the
  // indices used here.
  //
  // ASM Reference (Bank 01):
  // Subtype 1 Data Offset: $018000 (DrawObjects.type1_subtype_1_data_offset)
  // Subtype 1 Routine Ptr: $018200 (DrawObjects.type1_subtype_1_routine)
  // Subtype 2 Data Offset: $0183F0 (DrawObjects.type1_subtype_2_data_offset)
  // Subtype 2 Routine Ptr: $018470 (DrawObjects.type1_subtype_2_routine)
  // Subtype 3 Data Offset: $0184F0 (DrawObjects.type1_subtype_3_data_offset)
  // Subtype 3 Routine Ptr: $0185F0 (DrawObjects.type1_subtype_3_routine)
 
  draw_routines_.clear();
 
  // Object-to-routine mapping now lives in DrawRoutineRegistry::BuildObjectMapping().
  // ObjectDrawer::GetDrawRoutineId() delegates to the registry singleton.
  // Initialize draw routine function array in the correct order
  // Routines 0-82 (existing), 80-98 (new special routines for stairs, locks, etc.)
  draw_routines_.reserve(100);
 
  // Routine 0
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(0, obj, bg, tiles, state);
      });
  // Routine 1
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(1, obj, bg, tiles, state);
      });
  // Routine 2 - 2x4 tiles with adjacent spacing (s * 2), count = size + 1
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(2, obj, bg, tiles, state);
      });
  // Routine 3 - Same as routine 2 but draws to both BG1 and BG2
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(3, obj, bg, tiles, state);
      });
  // Routine 4
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(4, obj, bg, tiles, state);
      });
  // Routine 5
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(5, obj, bg, tiles, state);
      });
  // Routine 6
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(6, obj, bg, tiles, state);
      });
  // Routine 7
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(7, obj, bg, tiles, state);
      });
  // Routine 8
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(8, obj, bg, tiles, state);
      });
  // Routine 9
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(9, obj, bg, tiles, state);
      });
  // Routine 10
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(10, obj, bg, tiles, state);
      });
  // Routine 11
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(11, obj, bg, tiles, state);
      });
  // Routine 12
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(12, obj, bg, tiles, state);
      });
  // Routine 13
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(13, obj, bg, tiles, state);
      });
  // Routine 14
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(14, obj, bg, tiles, state);
      });
  // Routine 15
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(15, obj, bg, tiles, state);
      });
  // Routine 16
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(16, obj, bg, tiles, state);
      });
  // Routine 17 - Diagonal Acute BothBG
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(17, obj, bg, tiles, state);
      });
  // Routine 18 - Diagonal Grave BothBG
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(18, obj, bg, tiles, state);
      });
  // Routine 19 - 4x4 Corner (Type 2 corners)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(19, obj, bg, tiles, state);
      });
 
  // Routine 20 - Edge objects 1x2 +2
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(20, obj, bg, tiles, state);
      });
  // Routine 21 - Edge with perimeter 1x1 +3
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(21, obj, bg, tiles, state);
      });
  // Routine 22 - Edge variant 1x1 +2
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(22, obj, bg, tiles, state);
      });
  // Routine 23 - Top corners 1x2 +13
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(23, obj, bg, tiles, state);
      });
  // Routine 24 - Bottom corners 1x2 +13
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(24, obj, bg, tiles, state);
      });
  // Routine 25 - Solid fill 1x1 +3 (floor patterns)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(25, obj, bg, tiles, state);
      });
  // Routine 26 - Door switcherer
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(26, obj, bg, tiles, state);
      });
  // Routine 27 - Decorations 4x4 spaced 2
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(27, obj, bg, tiles, state);
      });
  // Routine 28 - Statues 2x3 spaced 2
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(28, obj, bg, tiles, state);
      });
  // Routine 29 - Pillars 2x4 spaced 4
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(29, obj, bg, tiles, state);
      });
  // Routine 30 - Decorations 4x3 spaced 4
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(30, obj, bg, tiles, state);
      });
  // Routine 31 - Doubled 2x2 spaced 2
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(31, obj, bg, tiles, state);
      });
  // Routine 32 - Decorations 2x2 spaced 12
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(32, obj, bg, tiles, state);
      });
  // Routine 33 - Somaria Line
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(33, obj, bg, tiles, state);
      });
  // Routine 34 - Water Face
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(34, obj, bg, tiles, state);
      });
  // Routine 35 - 4x4 Corner BothBG
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(35, obj, bg, tiles, state);
      });
  // Routine 36 - Weird Corner Bottom BothBG
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(36, obj, bg, tiles, state);
      });
  // Routine 37 - Weird Corner Top BothBG
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(37, obj, bg, tiles, state);
      });
  // Routine 38 - Nothing
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(38, obj, bg, tiles, state);
      });
  // Routine 39 - Small chest rendering (stateful F99 / fixed-open F9A)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawChest(obj, bg, tiles, state);
      });
  // Routine 40 - Rightwards 4x2 (Floor Tile)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(40, obj, bg, tiles, state);
      });
  // Routine 41 - Rightwards Decor 4x2 spaced 8 (12-column spacing)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(41, obj, bg, tiles, state);
      });
  // Routine 42 - Rightwards Cannon Hole 4x3
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(42, obj, bg, tiles, state);
      });
  // Routine 43 - Downwards Floor 4x4 (object 0x70)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(43, obj, bg, tiles, state);
      });
  // Routine 44 - Downwards 1x1 Solid +3 (object 0x71)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(44, obj, bg, tiles, state);
      });
  // Routine 45 - Downwards Decor 4x4 spaced 2 (objects 0x73-0x74)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(45, obj, bg, tiles, state);
      });
  // Routine 46 - Downwards Pillar 2x4 spaced 2 (objects 0x75, 0x87)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(46, obj, bg, tiles, state);
      });
  // Routine 47 - Downwards Decor 3x4 spaced 4 (objects 0x76-0x77)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(47, obj, bg, tiles, state);
      });
  // Routine 48 - Downwards Decor 2x2 spaced 12 (objects 0x78, 0x7B)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(48, obj, bg, tiles, state);
      });
  // Routine 49 - Downwards Line 1x1 +1 (object 0x7C)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(49, obj, bg, tiles, state);
      });
  // Routine 50 - Downwards Decor 2x4 spaced 8 (objects 0x7F, 0x80)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(50, obj, bg, tiles, state);
      });
  // Routine 51 - Rightwards Line 1x1 +1 (object 0x50)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(51, obj, bg, tiles, state);
      });
  // Routine 52 - Rightwards Bar 4x3 (object 0x4C)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(52, obj, bg, tiles, state);
      });
  // Routine 53 - Rightwards Shelf 4x4 (objects 0x4D-0x4F)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(53, obj, bg, tiles, state);
      });
  // Routine 54 - Rightwards Big Rail 1x3 +5 (object 0x5D)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(54, obj, bg, tiles, state);
      });
  // Routine 55 - Rightwards Block 2x2 spaced 2 (object 0x5E)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(55, obj, bg, tiles, state);
      });
 
  // ============================================================================
  // Phase 4: SuperSquare Routines (routines 56-64)
  // ============================================================================
 
  // Routine 56 - 4x4 Blocks in 4x4 SuperSquare (objects 0xC0, 0xC2)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(56, obj, bg, tiles, state);
      });
 
  // Routine 57 - 3x3 Floor in 4x4 SuperSquare (objects 0xC3, 0xD7)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(57, obj, bg, tiles, state);
      });
 
  // Routine 58 - 4x4 Floor in 4x4 SuperSquare (objects 0xC5-0xCA, 0xD1-0xD2,
  // 0xD9, 0xDF-0xE8)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(58, obj, bg, tiles, state);
      });
 
  // Routine 59 - 4x4 Floor One in 4x4 SuperSquare (object 0xC4)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(59, obj, bg, tiles, state);
      });
 
  // Routine 60 - 4x4 Floor Two in 4x4 SuperSquare (object 0xDB)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(60, obj, bg, tiles, state);
      });
 
  // Routine 61 - Big Hole 4x4 (object 0xA4)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(61, obj, bg, tiles, state);
      });
 
  // Routine 62 - Spike 2x2 in 4x4 SuperSquare (object 0xDE)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(62, obj, bg, tiles, state);
      });
 
  // Routine 63 - Table Rock 4x4 (object 0xDD)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(63, obj, bg, tiles, state);
      });
 
  // Routine 64 - Water Overlay 8x8 (objects 0xD8, 0xDA)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(64, obj, bg, tiles, state);
      });
 
  // ============================================================================
  // Phase 4 Step 2: Simple Variant Routines (routines 65-74)
  // ============================================================================
 
  // Routine 65 - Downwards Decor 3x4 spaced 2 (objects 0x81-0x84)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(65, obj, bg, tiles, state);
      });
 
  // Routine 66 - Downwards Big Rail 3x1 plus 5 (object 0x88)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(66, obj, bg, tiles, state);
      });
 
  // Routine 67 - Downwards Block 2x2 spaced 2 (object 0x89)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(67, obj, bg, tiles, state);
      });
 
  // Routine 68 - Downwards Cannon Hole 3x6 (objects 0x85-0x86)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(68, obj, bg, tiles, state);
      });
 
  // Routine 69 - Downwards Bar 2x3 (object 0x8F)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(69, obj, bg, tiles, state);
      });
 
  // Routine 70 - Downwards Pots 2x2 (object 0x95)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(70, obj, bg, tiles, state);
      });
 
  // Routine 71 - Downwards Hammer Pegs 2x2 (object 0x96)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(71, obj, bg, tiles, state);
      });
 
  // Routine 72 - Rightwards Edge 1x1 plus 7 (objects 0xB0-0xB1)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(72, obj, bg, tiles, state);
      });
 
  // Routine 73 - Rightwards Pots 2x2 (object 0xBC)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(73, obj, bg, tiles, state);
      });
 
  // Routine 74 - Rightwards Hammer Pegs 2x2 (object 0xBD)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(74, obj, bg, tiles, state);
      });
 
  // ============================================================================
  // Phase 4 Step 3: Diagonal Ceiling Routines (routines 75-78)
  // ============================================================================
 
  // Routine 75 - Diagonal Ceiling Top Left (objects 0xA0, 0xA5, 0xA9)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(75, obj, bg, tiles, state);
      });
 
  // Routine 76 - Diagonal Ceiling Bottom Left (objects 0xA1, 0xA6, 0xAA)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(76, obj, bg, tiles, state);
      });
 
  // Routine 77 - Diagonal Ceiling Top Right (objects 0xA2, 0xA7, 0xAB)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(77, obj, bg, tiles, state);
      });
 
  // Routine 78 - Diagonal Ceiling Bottom Right (objects 0xA3, 0xA8, 0xAC)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(78, obj, bg, tiles, state);
      });
 
  // ============================================================================
  // Phase 4 Step 5: Special Routines (routines 79-82)
  // ============================================================================
 
  // Routine 79 - Closed Chest Platform (object 0xC1, 68 tiles)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(79, obj, bg, tiles, state);
      });
 
  // Routine 80 - Moving Wall West (object 0xCD, 24 tiles)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(80, obj, bg, tiles, state);
      });
 
  // Routine 81 - Moving Wall East (object 0xCE, 24 tiles)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(81, obj, bg, tiles, state);
      });
 
  // Routine 82 - Open Chest Platform (object 0xDC, 21 tiles)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(82, obj, bg, tiles, state);
      });
 
  // ============================================================================
  // New Special Routines (Phase 5) - Stairs, Locks, Interactive Objects
  // ============================================================================
 
  // Routine 83 - InterRoom Fat Stairs Up (object 0x12D)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(83, obj, bg, tiles, state);
      });
 
  // Routine 84 - InterRoom Fat Stairs Down A (object 0x12E)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(84, obj, bg, tiles, state);
      });
 
  // Routine 85 - InterRoom Fat Stairs Down B (object 0x12F)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(85, obj, bg, tiles, state);
      });
 
  // Routine 86 - Auto Stairs (objects 0x130-0x133)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(86, obj, bg, tiles, state);
      });
 
  // Routine 87 - Straight InterRoom Stairs (Type 3 objects 0x21E-0x229)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(87, obj, bg, tiles, state);
      });
 
  // Routine 88 - Spiral Stairs Going Up Upper (object 0x138)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(88, obj, bg, tiles, state);
      });
 
  // Routine 89 - Spiral Stairs Going Down Upper (object 0x139)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(89, obj, bg, tiles, state);
      });
 
  // Routine 90 - Spiral Stairs Going Up Lower (object 0x13A)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(90, obj, bg, tiles, state);
      });
 
  // Routine 91 - Spiral Stairs Going Down Lower (object 0x13B)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(91, obj, bg, tiles, state);
      });
 
  // Routine 92 - Big Key Lock (Yaze 0xF98 / ASM object 0x218)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawBigKeyLock(obj, bg, tiles, state);
      });
 
  // Routine 93 - Bombable Floor (Type 3 object 0x247)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(93, obj, bg, tiles, state);
      });
 
  // Routine 94 - Empty Water Face (Type 3 object 0x200)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(94, obj, bg, tiles, state);
      });
 
  // Routine 95 - Spitting Water Face (Type 3 object 0x201)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(95, obj, bg, tiles, state);
      });
 
  // Routine 96 - Drenching Water Face (Type 3 object 0x202)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(96, obj, bg, tiles, state);
      });
 
  // Routine 97 - Prison Cell (Type 3 objects 0x20D, 0x217)
  // USDASM selects one tilemap through $BF and draws a sparse 16x4 pattern.
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(97, obj, bg, tiles, state);
      });
 
  // Routine 98 - Bed 4x5 (Type 2 objects 0x122, 0x128)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kBed4x5, obj, bg, tiles,
                                       state);
      });
 
  // Routine 99 - Rightwards 3x6 (Type 2 object 0x12C, Type 3 0x236-0x237)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kRightwards3x6, obj, bg,
                                       tiles, state);
      });
 
  // Routine 100 - Utility 6x3 (Type 2 object 0x13E, Type 3 0x24D, 0x25D)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kUtility6x3, obj, bg,
                                       tiles, state);
      });
 
  // Routine 101 - Utility 3x5 (Type 3 objects 0x255, 0x25B)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kUtility3x5, obj, bg,
                                       tiles, state);
      });
 
  // Routine 102 - Vertical Turtle Rock Pipe (Type 3 objects 0x23A, 0x23B)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kVerticalTurtleRockPipe,
                                       obj, bg, tiles, state);
      });
 
  // Routine 103 - Horizontal Turtle Rock Pipe (Type 3 objects 0x23C, 0x23D,
  // 0x25C)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(
            DrawRoutineIds::kHorizontalTurtleRockPipe, obj, bg, tiles, state);
      });
 
  // Routine 104 - Light Beam on Floor (Type 3 object 0x270)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kLightBeam, obj, bg,
                                       tiles, state);
      });
 
  // Routine 105 - Big Light Beam on Floor (Type 3 object 0x271)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kBigLightBeam, obj, bg,
                                       tiles, state);
      });
 
  // Routine 106 - Boss Shell 4x4 (Yaze 0xF95/0xFF2; ASM 0x215/0x272)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kBossShell4x4, obj, bg,
                                       tiles, state);
      });
 
  // Routine 107 - Solid Wall Decor 3x4 (Type 3 objects 0x269-0x26A, 0x26E-0x26F)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kSolidWallDecor3x4, obj,
                                       bg, tiles, state);
      });
 
  // Routine 108 - Archery Game Target Door (Type 3 objects 0x260-0x261)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kArcheryGameTargetDoor,
                                       obj, bg, tiles, state);
      });
 
  // Routine 109 - Ganon Triforce Floor Decor (Type 3 object 0x278)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kGanonTriforceFloorDecor,
                                       obj, bg, tiles, state);
      });
 
  // Routine 110 - Single 2x2 (pots, statues, single-instance 2x2 objects)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kSingle2x2, obj, bg,
                                       tiles, state);
      });
 
  // Routine 111 - Waterfall47 (object 0x47)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kWaterfall47, obj, bg,
                                       tiles, state);
      });
 
  // Routine 112 - Waterfall48 (object 0x48)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kWaterfall48, obj, bg,
                                       tiles, state);
      });
 
  // Routine 113 - Single 4x4 (NO repetition)
  // ASM: RoomDraw_4x4 - draws a single 4x4 pattern (16 tiles)
  // Used for: 0xFEB (large decor), and other single 4x4 objects
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kSingle4x4, obj, bg,
                                       tiles, state);
      });
 
  // Routine 114 - Single 4x3 (NO repetition)
  // ASM: RoomDraw_TableRock4x3 - draws a single 4x3 pattern (12 tiles)
  // Used for: 0xFED (water grate), 0xFB1 (big chest), etc.
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        if (obj.id_ == 0xFB1) {
          self->DrawBigChest(obj, bg, tiles, state);
          return;
        }
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kSingle4x3, obj, bg,
                                       tiles, state);
      });
 
  // Routine 115 - RupeeFloor (special pattern for 0xF92)
  // ASM: RoomDraw_RupeeFloor - draws 3 one-tile columns two tiles apart.
  // Pattern: 5 tiles wide, 8 rows tall with gaps (rows 2 and 5 are empty).
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kRupeeFloor, obj, bg,
                                       tiles, state);
      });
 
  // Routine 116 - Actual 4x4 tile8 pattern (32x32 pixels, NO repetition)
  // ASM: RoomDraw_4x4 - draws exactly 4 columns x 4 rows = 16 tiles
  // Used for: 0xFE6 (pit)
  draw_routines_.push_back(
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kActual4x4, obj, bg,
                                       tiles, state);
      });
 
  auto ensure_index = [this](size_t index) {
    while (draw_routines_.size() <= index) {
      draw_routines_.push_back([](ObjectDrawer* self, const RoomObject& obj,
                                  gfx::BackgroundBuffer& bg,
                                  std::span<const gfx::TileInfo> tiles,
                                  [[maybe_unused]] const DungeonState* state) {
        self->DrawNothing(obj, bg, tiles, state);
      });
    }
  };
 
  // Routine 117 - Long vertical rail with CORNER+MIDDLE+END pattern (0x8A)
  // ASM: RoomDraw_DownwardsHasEdge1x1_1to16_plus23 - matches horizontal 0x22
  ensure_index(117);
  draw_routines_[117] =
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(117, obj, bg, tiles, state);
      };
 
  // Routine 118 - Horizontal long rails with CORNER+MIDDLE+END pattern (0x5F)
  ensure_index(118);
  draw_routines_[118] =
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(118, obj, bg, tiles, state);
      };
 
  ensure_index(DrawRoutineIds::kWaterHopStairsA);
  draw_routines_[DrawRoutineIds::kWaterHopStairsA] =
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kWaterHopStairsA, obj,
                                       bg, tiles, state);
      };
 
  ensure_index(DrawRoutineIds::kWaterHopStairsB);
  draw_routines_[DrawRoutineIds::kWaterHopStairsB] =
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kWaterHopStairsB, obj,
                                       bg, tiles, state);
      };
 
  ensure_index(DrawRoutineIds::kDamFloodGate);
  draw_routines_[DrawRoutineIds::kDamFloodGate] =
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kDamFloodGate, obj, bg,
                                       tiles, state);
      };
 
  ensure_index(DrawRoutineIds::kDownwardsEdge1x1_1to16plus7);
  draw_routines_[DrawRoutineIds::kDownwardsEdge1x1_1to16plus7] =
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(
            DrawRoutineIds::kDownwardsEdge1x1_1to16plus7, obj, bg, tiles,
            state);
      };
 
  ensure_index(DrawRoutineIds::kFloorLight);
  draw_routines_[DrawRoutineIds::kFloorLight] =
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kFloorLight, obj, bg,
                                       tiles, state);
      };
 
  ensure_index(DrawRoutineIds::kWeird2x4_1to16);
  draw_routines_[DrawRoutineIds::kWeird2x4_1to16] =
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kWeird2x4_1to16, obj, bg,
                                       tiles, state);
      };
 
  ensure_index(DrawRoutineIds::kBigWallDecor);
  draw_routines_[DrawRoutineIds::kBigWallDecor] =
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kBigWallDecor, obj, bg,
                                       tiles, state);
      };
 
  ensure_index(DrawRoutineIds::kTableBowl);
  draw_routines_[DrawRoutineIds::kTableBowl] =
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kTableBowl, obj, bg,
                                       tiles, state);
      };
 
  ensure_index(DrawRoutineIds::kSmithyFurnace);
  draw_routines_[DrawRoutineIds::kSmithyFurnace] =
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kSmithyFurnace, obj, bg,
                                       tiles, state);
      };
 
  ensure_index(DrawRoutineIds::kBigGrayRock);
  draw_routines_[DrawRoutineIds::kBigGrayRock] =
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kBigGrayRock, obj, bg,
                                       tiles, state);
      };
 
  ensure_index(DrawRoutineIds::kAgahnimsAltar);
  draw_routines_[DrawRoutineIds::kAgahnimsAltar] =
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kAgahnimsAltar, obj, bg,
                                       tiles, state);
      };
 
  ensure_index(DrawRoutineIds::kFortuneTellerRoom);
  draw_routines_[DrawRoutineIds::kFortuneTellerRoom] =
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kFortuneTellerRoom, obj,
                                       bg, tiles, state);
      };
 
  ensure_index(DrawRoutineIds::kMagicBatAltar);
  draw_routines_[DrawRoutineIds::kMagicBatAltar] =
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kMagicBatAltar, obj, bg,
                                       tiles, state);
      };
 
  ensure_index(DrawRoutineIds::kVitreousGooDamage);
  draw_routines_[DrawRoutineIds::kVitreousGooDamage] =
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kVitreousGooDamage, obj,
                                       bg, tiles, state);
      };
 
  ensure_index(DrawRoutineIds::kSanctuaryWall);
  draw_routines_[DrawRoutineIds::kSanctuaryWall] =
      [](ObjectDrawer* self, const RoomObject& obj, gfx::BackgroundBuffer& bg,
         std::span<const gfx::TileInfo> tiles, const DungeonState* state) {
        self->DrawUsingRegistryRoutine(DrawRoutineIds::kSanctuaryWall, obj, bg,
                                       tiles, state);
      };
 
  // Routine 130 - Custom Object (Oracle of Secrets 0x31, 0x32)
  // Uses external binary files instead of ROM tile data.
  // Requires CustomObjectManager initialization and enable_custom_objects flag.
  ensure_index(130);
  draw_routines_[130] = [](ObjectDrawer* self, const RoomObject& obj,
                           gfx::BackgroundBuffer& bg,
                           std::span<const gfx::TileInfo> tiles,
                           [[maybe_unused]] const DungeonState* state) {
    self->DrawCustomObject(obj, bg, tiles, state);
  };
 
  routines_initialized_ = true;
}
 
int ObjectDrawer::GetDrawRoutineId(int16_t object_id) const {
  // Delegate to the unified registry for the canonical mapping
  const auto& registry = DrawRoutineRegistry::Get();
  return custom_objects_ != nullptr ? registry.GetRoutineIdForObject(
                                          object_id, custom_objects_->enabled())
                                    : registry.GetRoutineIdForObject(object_id);
}
 
// ============================================================================
// Draw Routine Implementations (Based on ZScream patterns)
// ============================================================================
 
void ObjectDrawer::DrawDoor(const DoorDef& door, int door_index,
                            gfx::BackgroundBuffer& bg1,
                            gfx::BackgroundBuffer& bg2,
                            const DungeonState* state,
                            gfx::BackgroundBuffer* layout_bg1,
                            gfx::BackgroundBuffer* layout_bg2) {
  // Door rendering based on ZELDA3_DUNGEON_SPEC.md Section 5 and disassembly
  // Uses DoorType and DoorDirection enums for type safety
  // Position calculations via DoorPositionManager
 
  LOG_DEBUG("ObjectDrawer", "DrawDoor: idx=%d type=%d dir=%d pos=%d",
            door_index, static_cast<int>(door.type),
            static_cast<int>(door.direction), door.position);
 
  if (!rom_ || !rom_->is_loaded() || !room_gfx_buffer_) {
    LOG_DEBUG("ObjectDrawer", "DrawDoor: SKIPPED - rom=%p loaded=%d gfx=%p",
              (void*)rom_, rom_ ? rom_->is_loaded() : 0,
              (void*)room_gfx_buffer_);
    return;
  }
 
  auto& bitmap = bg1.bitmap();
  if (!bitmap.is_active() || bitmap.width() == 0) {
    LOG_DEBUG("ObjectDrawer",
              "DrawDoor: SKIPPED - bitmap not active or zero width");
    return;
  }
 
  // DungeonState intentionally exposes the editor's logical door index. The
  // runtime derives a separate marker-aware physical slot from $0460 before it
  // probes $068C; reproducing that slot aliasing belongs in the state adapter,
  // not in this renderer's vector-index contract.
  const bool is_door_open = state && state->IsDoorOpen(room_id_, door_index);
 
  // Get door position from DoorPositionManager
  auto [tile_x, tile_y] = door.GetTileCoords();
  auto dims = door.GetDimensions();
  int door_width = dims.width_tiles;
  int door_height = dims.height_tiles;
 
  LOG_DEBUG("ObjectDrawer", "DrawDoor: tile_pos=(%d,%d) dims=%dx%d", tile_x,
            tile_y, door_width, door_height);
 
  constexpr int kRoomDrawObjectDataBase = 0x1B52;
  constexpr int kDoorwayReplacementDoorGfxBase = 0x1A02;
  constexpr int kExplodingWallTilemapPositionBase = 0x19DE;
  constexpr int kExplodingWallOpenReplacementType = 0x54;
  constexpr int kNorthCurtainClosedOffset = 0x078A;
  constexpr int kFancyDungeonExitObjectOffset = 0x2656;
  constexpr int kCaveExitLightObjectOffset = 0x26F6;
  const auto& rom_data = rom_->data();
 
  // RoomDraw_FlagDoorsAndGetFinalType ($01B152): an eye-watch door sets its
  // own $068C bit at room load unless it is the door the player just came
  // through, so it draws as a plain doorway. The editor has no player.
  const bool always_open = door.type == DoorType::EyeWatchDoor;
 
  auto resolve_effective_door_type = [&]() -> uint16_t {
    const auto stored_type = static_cast<uint16_t>(door.type);
    if (!is_door_open && !always_open) {
      return stored_type;
    }
 
    // RoomDraw_FlagDoorsAndGetFinalType leaves shutter graphics closed while
    // the room's shutter controller ($0468) is active, even when the persistent
    // door-open bit is set.
    const bool is_controlled_shutter =
        door.type == DoorType::DoubleSidedShutter ||
        door.type == DoorType::DoubleSidedShutterLower;
    if (is_controlled_shutter && state != nullptr &&
        state->IsDoorSwitchActive(room_id_)) {
      return stored_type;
    }
 
    // USDASM performs a 16-bit read from DoorwayReplacementDoorGFX using the
    // original even-valued door type as a byte offset. Keep the bounds check on
    // both bytes so malformed or undersized ROMs fall back to the stored type.
    const int replacement_addr =
        kDoorwayReplacementDoorGfxBase + static_cast<int>(door.type);
    if (replacement_addr < 0 ||
        replacement_addr + 1 >= static_cast<int>(rom_->size())) {
      return stored_type;
    }
 
    return static_cast<uint16_t>(rom_data[replacement_addr] |
                                 (rom_data[replacement_addr + 1] << 8));
  };
 
  const uint16_t effective_door_type = resolve_effective_door_type();
 
  auto draw_tile_word = [&](gfx::BackgroundBuffer& target, int tile_x,
                            int tile_y, uint16_t tile_word) {
    auto& bitmap = target.bitmap();
    auto& priority_buffer = target.mutable_priority_data();
    auto& coverage_buffer = target.mutable_coverage_data();
    const int bitmap_width = bitmap.width();
    const auto tile_info = gfx::WordToTileInfo(tile_word);
    const int pixel_x = tile_x * 8;
    const int pixel_y = tile_y * 8;
 
    target.SetTileAt(tile_x, tile_y, tile_word);
    target.ClearBG1RevealMaskRect(bg1_reveal_mask_source_, pixel_x, pixel_y, 8,
                                  8);
    DrawTileToBitmap(bitmap, tile_info, pixel_x, pixel_y, room_gfx_buffer_);
 
    const uint8_t priority = tile_info.over_ ? 1 : 0;
    const auto& bitmap_data = bitmap.vector();
    for (int py = 0; py < 8; py++) {
      const int dest_y = pixel_y + py;
      if (dest_y < 0 || dest_y >= bitmap.height()) {
        continue;
      }
      for (int px = 0; px < 8; px++) {
        const int dest_x = pixel_x + px;
        if (dest_x < 0 || dest_x >= bitmap_width) {
          continue;
        }
        const int dest_index = dest_y * bitmap_width + dest_x;
        if (dest_index >= 0 &&
            dest_index < static_cast<int>(coverage_buffer.size())) {
          coverage_buffer[dest_index] = 1;
        }
        if (dest_index < static_cast<int>(bitmap_data.size()) &&
            bitmap_data[dest_index] != 255) {
          priority_buffer[dest_index] = priority;
        }
      }
    }
  };
 
  auto draw_object_data_tile = [&](gfx::BackgroundBuffer& target, int tile_x,
                                   int tile_y, int tile_data_addr, int tile_idx,
                                   uint16_t word_mask = 0) -> bool {
    const int addr = tile_data_addr + (tile_idx * 2);
    if (addr < 0 || addr + 1 >= static_cast<int>(rom_->size())) {
      return false;
    }
 
    const uint16_t tile_word = static_cast<uint16_t>(
        (rom_data[addr] | (rom_data[addr + 1] << 8)) | word_mask);
    draw_tile_word(target, tile_x, tile_y, tile_word);
    return true;
  };
 
  auto draw_from_object_data = [&](gfx::BackgroundBuffer& target,
                                   int start_tile_x, int start_tile_y,
                                   int width, int height, int tile_data_addr) {
    int tile_idx = 0;
 
    for (int dx = 0; dx < width; dx++) {
      for (int dy = 0; dy < height; dy++) {
        (void)draw_object_data_tile(target, start_tile_x + dx,
                                    start_tile_y + dy, tile_data_addr,
                                    tile_idx++);
      }
    }
  };
 
  auto draw_from_object_data_row_major =
      [&](gfx::BackgroundBuffer& target, int start_tile_x, int start_tile_y,
          int width, int height, int tile_data_addr) {
        int tile_idx = 0;
        for (int dy = 0; dy < height; ++dy) {
          for (int dx = 0; dx < width; ++dx) {
            (void)draw_object_data_tile(target, start_tile_x + dx,
                                        start_tile_y + dy, tile_data_addr,
                                        tile_idx++);
          }
        }
      };
 
  auto draw_repeated_tile = [&](gfx::BackgroundBuffer& target, int start_tile_x,
                                int start_tile_y, int width, int height,
                                uint16_t tile_word) {
    auto& bitmap = target.bitmap();
    auto& priority_buffer = target.mutable_priority_data();
    auto& coverage_buffer = target.mutable_coverage_data();
    const int bitmap_width = bitmap.width();
    const auto tile_info = gfx::WordToTileInfo(tile_word);
 
    for (int dx = 0; dx < width; dx++) {
      for (int dy = 0; dy < height; dy++) {
        const int pixel_x = (start_tile_x + dx) * 8;
        const int pixel_y = (start_tile_y + dy) * 8;
 
        target.ClearBG1RevealMaskRect(bg1_reveal_mask_source_, pixel_x, pixel_y,
                                      8, 8);
        DrawTileToBitmap(bitmap, tile_info, pixel_x, pixel_y, room_gfx_buffer_);
        target.SetTileAt(start_tile_x + dx, start_tile_y + dy, tile_word);
 
        const uint8_t priority = tile_info.over_ ? 1 : 0;
        const auto& bitmap_data = bitmap.vector();
        for (int py = 0; py < 8; py++) {
          const int dest_y = pixel_y + py;
          if (dest_y < 0 || dest_y >= bitmap.height()) {
            continue;
          }
          for (int px = 0; px < 8; px++) {
            const int dest_x = pixel_x + px;
            if (dest_x < 0 || dest_x >= bitmap_width) {
              continue;
            }
            const int dest_index = dest_y * bitmap_width + dest_x;
            if (dest_index >= 0 &&
                dest_index < static_cast<int>(coverage_buffer.size())) {
              coverage_buffer[dest_index] = 1;
            }
            if (dest_index < static_cast<int>(bitmap_data.size()) &&
                bitmap_data[dest_index] != 255) {
              priority_buffer[dest_index] = priority;
            }
          }
        }
      }
    }
  };
 
  auto tilemap_offset_to_tile_coords = [](uint16_t offset) {
    return std::pair<int, int>{static_cast<int>((offset % 0x80) / 2),
                               static_cast<int>(offset / 0x80)};
  };
  const int position_index = std::min<int>(door.position & 0x0F, 11);
 
  enum class DoorPrioritySpan {
    // RoomDraw_MakeDoorPartsHighPriority_{Vertical,Horizontal}.
    kNormalLower,
    // RoomDraw_MakeDoorHighPriorityLowerLayer_* (type $06).
    kLowerLayerOnly,
    // RoomDraw_MakeDoorHighPriority_* after a type $40-$66 raster.
    kHighRange,
  };
 
  auto promote_priority_rect_on_layer =
      [&](gfx::BackgroundBuffer& object_buffer,
          gfx::BackgroundBuffer* layout_buffer, int start_tile_x,
          int start_tile_y, int width_tiles, int height_tiles) {
        auto promote_target = [&](gfx::BackgroundBuffer& target) {
          for (int tile_y = start_tile_y; tile_y < start_tile_y + height_tiles;
               ++tile_y) {
            for (int tile_x = start_tile_x; tile_x < start_tile_x + width_tiles;
                 ++tile_x) {
              PromoteTileWordPriority(target, tile_x, tile_y);
            }
          }
          for (int y = start_tile_y * 8; y < (start_tile_y + height_tiles) * 8;
               ++y) {
            for (int x = start_tile_x * 8; x < (start_tile_x + width_tiles) * 8;
                 ++x) {
              target.SetPriorityAt(x, y, 1);
            }
          }
        };
 
        // USDASM has one tilemap per background. Yaze splits each into layout and
        // object buffers, so promote both potential pixel owners without changing
        // either bitmap or coverage mask.
        promote_target(object_buffer);
        if (layout_buffer != nullptr && layout_buffer != &object_buffer) {
          promote_target(*layout_buffer);
        }
      };
 
  auto promote_upper_priority_rect = [&](int start_tile_x, int start_tile_y,
                                         int width_tiles, int height_tiles) {
    // USDASM writes these through $7E2000,X. BG2's map ($7E4000) directly
    // follows BG1's, so rows past 63 continue on BG2 at row-64 (for example
    // the exit-light span under a south door at row 55).
    constexpr int kRows = 64;
    const int bg1_rows =
        std::max(0, std::min(height_tiles, kRows - start_tile_y));
    promote_priority_rect_on_layer(bg1, layout_bg1, start_tile_x, start_tile_y,
                                   width_tiles, bg1_rows);
    if (bg1_rows < height_tiles) {
      const int bg2_start = std::max(0, start_tile_y - kRows);
      promote_priority_rect_on_layer(
          bg2, layout_bg2, start_tile_x, bg2_start, width_tiles,
          start_tile_y + height_tiles - kRows - bg2_start);
    }
  };
 
  auto promote_lower_priority_rect = [&](int start_tile_x, int start_tile_y,
                                         int width_tiles, int height_tiles) {
    promote_priority_rect_on_layer(bg2, layout_bg2, start_tile_x, start_tile_y,
                                   width_tiles, height_tiles);
  };
 
  auto promote_door_priority = [&](DoorDirection render_direction,
                                   int render_tile_x, int render_tile_y,
                                   DoorPrioritySpan span) {
    constexpr int kSectionSize = 32;
    const auto section_start = [](int coordinate) {
      return (coordinate / kSectionSize) * kSectionSize;
    };
    const auto section_end = [&](int coordinate) {
      return section_start(coordinate) + kSectionSize;
    };
 
    int start_x = render_tile_x;
    int start_y = render_tile_y;
    int width = 0;
    int height = 0;
 
    switch (span) {
      case DoorPrioritySpan::kNormalLower:
        switch (render_direction) {
          case DoorDirection::North:
            start_y = section_start(render_tile_y);
            width = 4;
            height = 7;
            break;
          case DoorDirection::South:
            // South raster coordinates are one row below the USDASM table
            // anchor; the fixed priority span starts four rows below it.
            start_y = render_tile_y + 3;
            width = 4;
            height = 7;
            break;
          case DoorDirection::West:
            start_x = section_start(render_tile_x);
            width = 5;
            height = 4;
            break;
          case DoorDirection::East:
            // East raster coordinates are one column right of the table
            // anchor; the fixed priority span starts four columns right.
            start_x = render_tile_x + 3;
            width = 5;
            height = 4;
            break;
        }
        break;
 
      case DoorPrioritySpan::kLowerLayerOnly:
        switch (render_direction) {
          case DoorDirection::North:
            start_y = section_start(render_tile_y);
            width = 4;
            height = render_tile_y - start_y + 1;
            break;
          case DoorDirection::South:
            start_y = render_tile_y + 1;
            width = 4;
            height = section_end(render_tile_y) - start_y;
            break;
          case DoorDirection::West:
            start_x = section_start(render_tile_x);
            width = render_tile_x - start_x + 1;
            height = 4;
            break;
          case DoorDirection::East:
            start_x = render_tile_x + 1;
            width = section_end(render_tile_x) - start_x;
            height = 4;
            break;
        }
        break;
 
      case DoorPrioritySpan::kHighRange:
        switch (render_direction) {
          case DoorDirection::North:
            start_y = section_start(render_tile_y);
            width = 4;
            height = render_tile_y - start_y;
            break;
          case DoorDirection::South:
            start_y = render_tile_y + 3;
            width = 4;
            height = section_end(render_tile_y) - start_y;
            break;
          case DoorDirection::West:
            start_x = section_start(render_tile_x);
            width = render_tile_x - start_x;
            height = 4;
            break;
          case DoorDirection::East:
            // The visible raster starts one column right of the USDASM table
            // anchor and spans three columns. Priority begins at anchor+4.
            start_x = render_tile_x + 3;
            width = section_end(render_tile_x) - start_x;
            height = 4;
            break;
        }
        break;
    }
 
    if (width > 0 && height > 0) {
      promote_upper_priority_rect(start_x, start_y, width, height);
    }
  };
 
  // Door markers update room-transition metadata in USDASM; they do not
  // stamp tiles. In real room streams they commonly follow a physical door
  // at the same position, so treating them as art overwrites that door with
  // the marker table's mirrored shutter tiles.
  const bool is_nonvisual_marker = door.type == DoorType::DungeonSwapMarker ||
                                   door.type == DoorType::LayerSwapMarker ||
                                   (door.type == DoorType::ExitMarker &&
                                    (door.direction == DoorDirection::North ||
                                     door.direction == DoorDirection::South));
  if (is_nonvisual_marker) {
    return;
  }
 
  // Type $06 only promotes existing upper-layer wall tiles in USDASM. It
  // neither looks up nor stamps door graphics.
  if (door.type == DoorType::UnusedCaveExit) {
    promote_door_priority(door.direction, tile_x, tile_y,
                          DoorPrioritySpan::kLowerLayerOnly);
    return;
  }
 
  // South has several dedicated routines that bypass the ordinary 4x3 door
  // tables. Their coordinates begin at the raw USDASM tilemap anchor rather
  // than the generic South render anchor one row below it.
  if (door.direction == DoorDirection::South) {
    const auto [raw_tile_x, raw_tile_y] =
        DoorPositionManager::PositionToTileCoords(door.position,
                                                  door.direction);
    const int fancy_data_addr =
        kRoomDrawObjectDataBase + kFancyDungeonExitObjectOffset;
    const int cave_light_data_addr =
        kRoomDrawObjectDataBase + kCaveExitLightObjectOffset;
    const auto has_object_words = [&](int address, int word_count) {
      return address >= 0 &&
             address + word_count * 2 <= static_cast<int>(rom_->size());
    };
 
    switch (door.type) {
      case DoorType::FancyDungeonExit:
        if (!has_object_words(fancy_data_addr, 80)) {
          DrawDoorIndicator(bg1, raw_tile_x - 3, raw_tile_y - 4,
                            /*width=*/10, /*height=*/8, door.type,
                            door.direction);
          return;
        }
        draw_from_object_data_row_major(bg1, raw_tile_x - 3, raw_tile_y - 4,
                                        /*width=*/10, /*height=*/8,
                                        fancy_data_addr);
        return;
 
      case DoorType::FancyDungeonExitLower:
        if (!has_object_words(fancy_data_addr, 80)) {
          DrawDoorIndicator(bg2, raw_tile_x - 3, raw_tile_y - 4,
                            /*width=*/10, /*height=*/8, door.type,
                            door.direction);
          return;
        }
        draw_from_object_data_row_major(bg2, raw_tile_x - 3, raw_tile_y - 4,
                                        /*width=*/10, /*height=*/8,
                                        fancy_data_addr);
        // RoomDraw_NormalRangedDoors_South copies the final lower-layer row
        // back to the upper tilemap and forces high priority.
        for (int dx = 0; dx < 10; ++dx) {
          (void)draw_object_data_tile(
              bg1, raw_tile_x - 3 + dx, raw_tile_y + 3, fancy_data_addr,
              /*tile_idx=*/70 + dx, /*word_mask=*/0x2000);
        }
        return;
 
      case DoorType::ExitLower:
        if (!has_object_words(cave_light_data_addr, 16)) {
          DrawDoorIndicator(bg2, raw_tile_x, raw_tile_y, /*width=*/4,
                            /*height=*/4, door.type, door.direction);
          return;
        }
        promote_lower_priority_rect(raw_tile_x, raw_tile_y + 4,
                                    /*width_tiles=*/4, /*height_tiles=*/7);
        draw_from_object_data(bg2, raw_tile_x, raw_tile_y, /*width=*/4,
                              /*height=*/4, cave_light_data_addr);
        for (int dx = 0; dx < 4; ++dx) {
          (void)draw_object_data_tile(
              bg1, raw_tile_x + dx, raw_tile_y + 3, cave_light_data_addr,
              /*tile_idx=*/dx * 4 + 3, /*word_mask=*/0x2000);
        }
        return;
 
      case DoorType::CaveExit:
        if (!has_object_words(cave_light_data_addr, 16)) {
          DrawDoorIndicator(bg1, raw_tile_x, raw_tile_y, /*width=*/4,
                            /*height=*/4, door.type, door.direction);
          return;
        }
        draw_from_object_data(bg1, raw_tile_x, raw_tile_y, /*width=*/4,
                              /*height=*/4, cave_light_data_addr);
        return;
 
      case DoorType::LitCaveExitLower:
        if (!has_object_words(cave_light_data_addr, 16)) {
          DrawDoorIndicator(bg1, raw_tile_x, raw_tile_y, /*width=*/4,
                            /*height=*/4, door.type, door.direction);
          return;
        }
        promote_upper_priority_rect(raw_tile_x, raw_tile_y + 4,
                                    /*width_tiles=*/4, /*height_tiles=*/7);
        draw_from_object_data(bg1, raw_tile_x, raw_tile_y, /*width=*/4,
                              /*height=*/4, cave_light_data_addr);
        return;
 
      default:
        break;
    }
  }
 
  auto resolve_render_type = [](DoorDirection render_direction,
                                uint16_t render_type) -> uint16_t {
    switch (render_type) {
      case static_cast<uint16_t>(DoorType::BigKeyDoor):
        // South's closed big-key door is coerced to the normal-door table
        // entry by RoomDraw_OneSidedShutters_South.
        return render_direction == DoorDirection::South
                   ? static_cast<uint16_t>(DoorType::NormalDoor)
                   : render_type;
      case static_cast<uint16_t>(DoorType::BottomSidedShutter):
        return (render_direction == DoorDirection::North ||
                render_direction == DoorDirection::West)
                   ? static_cast<uint16_t>(DoorType::DoubleSidedShutter)
                   : static_cast<uint16_t>(DoorType::NormalDoor);
      case static_cast<uint16_t>(DoorType::TopSidedShutter):
        return (render_direction == DoorDirection::North ||
                render_direction == DoorDirection::West)
                   ? static_cast<uint16_t>(DoorType::NormalDoor)
                   : static_cast<uint16_t>(DoorType::DoubleSidedShutter);
      case static_cast<uint16_t>(DoorType::BottomShutterLower):
        return (render_direction == DoorDirection::North ||
                render_direction == DoorDirection::West)
                   ? static_cast<uint16_t>(DoorType::DoubleSidedShutterLower)
                   : static_cast<uint16_t>(DoorType::NormalDoorOneSidedShutter);
      case static_cast<uint16_t>(DoorType::TopShutterLower):
        return (render_direction == DoorDirection::North ||
                render_direction == DoorDirection::West)
                   ? static_cast<uint16_t>(DoorType::NormalDoorOneSidedShutter)
                   : static_cast<uint16_t>(DoorType::DoubleSidedShutterLower);
      default:
        return render_type;
    }
  };
 
  auto resolve_table_door_data = [&](DoorDirection render_direction,
                                     uint16_t render_type,
                                     int* tile_data_addr) -> bool {
    int offset_table_addr = 0;
    switch (render_direction) {
      case DoorDirection::North:
        offset_table_addr = kDoorGfxUp;
        break;
      case DoorDirection::South:
        offset_table_addr = kDoorGfxDown;
        break;
      case DoorDirection::West:
        offset_table_addr = kDoorGfxLeft;
        break;
      case DoorDirection::East:
        offset_table_addr = kDoorGfxRight;
        break;
    }
 
    const uint16_t resolved_type =
        resolve_render_type(render_direction, render_type);
    // DoorGFXDataOffset_* is an absolute-indexed word table and Y is already
    // the byte offset. Do not divide/re-multiply: hacked replacement tables may
    // intentionally supply an odd or wider offset.
    const int table_entry_addr = offset_table_addr + resolved_type;
    if (table_entry_addr + 1 >= static_cast<int>(rom_->size())) {
      return false;
    }
 
    const uint16_t tile_offset =
        rom_data[table_entry_addr] | (rom_data[table_entry_addr + 1] << 8);
    *tile_data_addr = kRoomDrawObjectDataBase + tile_offset;
    const auto dims = GetDoorDimensions(render_direction);
    const int data_size = dims.width_tiles * dims.height_tiles * 2;
    if (*tile_data_addr < 0 ||
        *tile_data_addr + data_size > static_cast<int>(rom_->size())) {
      return false;
    }
 
    return true;
  };
 
  auto draw_table_door = [&](gfx::BackgroundBuffer& target,
                             DoorDirection render_direction, int start_tile_x,
                             int start_tile_y, uint16_t render_type) -> bool {
    int tile_data_addr = 0;
    if (!resolve_table_door_data(render_direction, render_type,
                                 &tile_data_addr)) {
      return false;
    }
 
    const auto render_dims = GetDoorDimensions(render_direction);
    draw_from_object_data(target, start_tile_x, start_tile_y,
                          render_dims.width_tiles, render_dims.height_tiles,
                          tile_data_addr);
    return true;
  };
 
  auto draw_high_range_table_door = [&](DoorDirection render_direction,
                                        int start_tile_x, int start_tile_y,
                                        uint16_t render_type) -> bool {
    int tile_data_addr = 0;
    if (!resolve_table_door_data(render_direction, render_type,
                                 &tile_data_addr)) {
      return false;
    }
 
    const auto dims = GetDoorDimensions(render_direction);
    int tile_idx = 0;
    for (int dx = 0; dx < dims.width_tiles; ++dx) {
      for (int dy = 0; dy < dims.height_tiles; ++dy) {
        // RoomDraw_OneSidedLowerShutters_* splits one logical door across
        // the upper ($7E2000/BG1) and lower ($7E4000/BG2) tilemaps.
        bool writes_upper = false;
        switch (render_direction) {
          case DoorDirection::North:
            writes_upper = dy == 0;
            break;
          case DoorDirection::South:
            writes_upper = dy == dims.height_tiles - 1;
            break;
          case DoorDirection::West:
            writes_upper = dx == 0;
            break;
          case DoorDirection::East:
            writes_upper = dx == dims.width_tiles - 1;
            break;
        }
        gfx::BackgroundBuffer& target = writes_upper ? bg1 : bg2;
        if (!draw_object_data_tile(target, start_tile_x + dx, start_tile_y + dy,
                                   tile_data_addr, tile_idx++)) {
          return false;
        }
      }
    }
    return true;
  };
 
  auto draw_ranged_door = [&](DoorDirection render_direction, int start_tile_x,
                              int start_tile_y, DoorType original_type,
                              uint16_t table_type) -> bool {
    if (original_type == DoorType::NormalDoorLower) {
      // Type $02 stamps the ordinary door art after promoting the fixed wall
      // rectangle selected by RoomDraw_MakeDoorPartsHighPriority_*.
      promote_door_priority(render_direction, start_tile_x, start_tile_y,
                            DoorPrioritySpan::kNormalLower);
    }
 
    // The dispatcher selects the normal/high-range writer before
    // RoomDraw_FlagDoorsAndGetFinalType substitutes open-door graphics. Keep
    // that choice tied to the stored type while looking up art by final type.
    const int render_type_value = static_cast<int>(original_type);
    const bool is_high_range =
        render_type_value >= 0x40 && render_type_value <= 0x66;
    if (is_high_range) {
      const bool drew = draw_high_range_table_door(
          render_direction, start_tile_x, start_tile_y, table_type);
      // North type $46 deliberately skips RoomDraw_MakeDoorHighPriority_North;
      // every other high-range direction/type promotes the adjacent upper wall.
      if (drew && !(render_direction == DoorDirection::North &&
                    original_type == DoorType::ExplicitRoomDoor)) {
        promote_door_priority(render_direction, start_tile_x, start_tile_y,
                              DoorPrioritySpan::kHighRange);
      }
      return drew;
    }
    return draw_table_door(bg1, render_direction, start_tile_x, start_tile_y,
                           table_type);
  };
 
  // USDASM has special north-door branches that do not follow the generic 4x3
  // ranged-door path.
  if (door.direction == DoorDirection::North &&
      door.type == DoorType::ExplodingWall && !is_door_open) {
    LOG_DEBUG("ObjectDrawer",
              "DrawDoor: closed exploding wall intentionally draws nothing");
    (void)bg2;
    return;
  }
 
  if (door.direction == DoorDirection::North &&
      door.type == DoorType::CurtainDoor && !is_door_open) {
    const int tile_data_addr =
        kRoomDrawObjectDataBase + kNorthCurtainClosedOffset;
    const int data_size = 16 * 2;  // RoomDraw_4x4 closed curtain path.
    if (tile_data_addr < 0 ||
        tile_data_addr + data_size > static_cast<int>(rom_->size())) {
      DrawDoorIndicator(bg1, tile_x, tile_y, /*width=*/4, /*height=*/4,
                        door.type, door.direction);
      return;
    }
    draw_from_object_data(bg1, tile_x, tile_y, /*width=*/4, /*height=*/4,
                          tile_data_addr);
    return;
  }
 
  if (door.direction == DoorDirection::North &&
      door.type == DoorType::CurtainDoor && is_door_open) {
    const int table_entry_addr =
        kDoorGfxUp + static_cast<int>(effective_door_type);
    if (table_entry_addr < 0 ||
        table_entry_addr + 1 >= static_cast<int>(rom_->size())) {
      DrawDoorIndicator(bg1, tile_x, tile_y, /*width=*/4, /*height=*/4,
                        door.type, door.direction);
      return;
    }
 
    const uint16_t tile_offset =
        rom_data[table_entry_addr] | (rom_data[table_entry_addr + 1] << 8);
    const int tile_data_addr = kRoomDrawObjectDataBase + tile_offset;
    const int data_size = 16 * 2;  // RoomDraw_4x4 open curtain path.
    if (tile_data_addr < 0 ||
        tile_data_addr + data_size > static_cast<int>(rom_->size())) {
      DrawDoorIndicator(bg1, tile_x, tile_y, /*width=*/4, /*height=*/4,
                        door.type, door.direction);
      return;
    }
 
    draw_from_object_data(bg1, tile_x, tile_y, /*width=*/4, /*height=*/4,
                          tile_data_addr);
    return;
  }
 
  if (door.direction == DoorDirection::North &&
      door.type == DoorType::ExplodingWall && is_door_open) {
    const int position_index = std::min<int>(door.position & 0x0F, 5);
    const int tilemap_entry_addr =
        kExplodingWallTilemapPositionBase + (position_index * 2);
    if (tilemap_entry_addr < 0 ||
        tilemap_entry_addr + 1 >= static_cast<int>(rom_->size())) {
      DrawDoorIndicator(bg1, tile_x, tile_y, /*width=*/4, /*height=*/4,
                        door.type, door.direction);
      return;
    }
 
    const uint16_t tilemap_offset =
        rom_data[tilemap_entry_addr] | (rom_data[tilemap_entry_addr + 1] << 8);
    const auto explosion_tile_coords =
        tilemap_offset_to_tile_coords(tilemap_offset);
    const int explosion_tile_x = explosion_tile_coords.first;
    const int explosion_tile_y = explosion_tile_coords.second;
 
    auto draw_exploding_wall_segment = [&](int table_entry_addr,
                                           int segment_tile_y) -> bool {
      if (table_entry_addr < 0 ||
          table_entry_addr + 1 >= static_cast<int>(rom_->size())) {
        return false;
      }
 
      const uint16_t tile_offset =
          rom_data[table_entry_addr] | (rom_data[table_entry_addr + 1] << 8);
      const int tile_data_addr = kRoomDrawObjectDataBase + tile_offset;
      // RoomDraw_ExplodingWallSegment: a 2x6 column (words 0-11), an 18x6
      // fill of word 12, then a 2x6 column (words 13-24) at x+20.
      constexpr int kFillWordIndex = 12;
      constexpr int kRightColumnWordIndex = 13;
      const int min_data_size = (kRightColumnWordIndex + 12) * 2;
      if (tile_data_addr < 0 ||
          tile_data_addr + min_data_size > static_cast<int>(rom_->size())) {
        return false;
      }
 
      draw_from_object_data(bg1, explosion_tile_x, segment_tile_y,
                            /*width=*/2, /*height=*/6, tile_data_addr);
      const uint16_t fill_word =
          rom_data[tile_data_addr + (kFillWordIndex * 2)] |
          (rom_data[tile_data_addr + (kFillWordIndex * 2) + 1] << 8);
      draw_repeated_tile(bg1, explosion_tile_x + 2, segment_tile_y,
                         /*width=*/18, /*height=*/6, fill_word);
      draw_from_object_data(bg1, explosion_tile_x + 20, segment_tile_y,
                            /*width=*/2, /*height=*/6,
                            tile_data_addr + (kRightColumnWordIndex * 2));
      return true;
    };
 
    const int south_table_entry_addr =
        kDoorGfxDown + kExplodingWallOpenReplacementType;
    const int north_table_entry_addr =
        kDoorGfxUp + kExplodingWallOpenReplacementType;
    if (!draw_exploding_wall_segment(south_table_entry_addr,
                                     explosion_tile_y) ||
        !draw_exploding_wall_segment(north_table_entry_addr,
                                     explosion_tile_y + 6)) {
      DrawDoorIndicator(bg1, explosion_tile_x, explosion_tile_y, /*width=*/20,
                        /*height=*/12, door.type, door.direction);
    }
    return;
  }
 
  // RoomDraw_North treats all four key-stair types ($20/$22/$24/$26) as
  // stateful stair records. Once their persistent bit is open, USDASM returns
  // without drawing replacement art.
  const bool is_north_key_stairs =
      door.direction == DoorDirection::North &&
      (door.type == DoorType::SmallKeyStairsUp ||
       door.type == DoorType::SmallKeyStairsDown ||
       door.type == DoorType::SmallKeyStairsUpLower ||
       door.type == DoorType::SmallKeyStairsDownLower);
  if (is_north_key_stairs && is_door_open) {
    return;
  }
 
  // Closed North lower-layer key stairs ($24/$26) use the ordinary 4x3 table
  // layout, but every tile is written to $7E4000/BG2 and no middle-door
  // counterpart is emitted.
  const bool is_north_lower_key_stairs =
      door.direction == DoorDirection::North &&
      (door.type == DoorType::SmallKeyStairsUpLower ||
       door.type == DoorType::SmallKeyStairsDownLower);
  if (is_north_lower_key_stairs) {
    if (!draw_table_door(bg2, door.direction, tile_x, tile_y,
                         static_cast<uint16_t>(door.type))) {
      DrawDoorIndicator(bg2, tile_x, tile_y, door_width, door_height, door.type,
                        door.direction);
    }
    return;
  }
 
  // The normal ranged-door callers treat curtain and waterfall final types as
  // metadata-only results (carry clear from FlagDoorsAndGetFinalType). North
  // curtain and lower key stairs have already taken their dedicated branches.
  const bool uses_normal_ranged_writer =
      static_cast<int>(door.type) <
      static_cast<int>(DoorType::NormalDoorOneSidedShutter);
  if (uses_normal_ranged_writer &&
      (effective_door_type == static_cast<uint16_t>(DoorType::CurtainDoor) ||
       effective_door_type == static_cast<uint16_t>(DoorType::WaterfallDoor))) {
    return;
  }
 
  // Door graphics use an indirect addressing scheme:
  // 1. kDoorGfxUp/Down/Left/Right point to offset tables (DoorGFXDataOffset_*)
  // 2. Each table entry is a 16-bit offset into RoomDrawObjectData
  // 3. RoomDrawObjectData base is at PC 0x1B52 (SNES $00:9B52)
  // 4. Actual tile data = 0x1B52 + offset_from_table
  const bool north_explicit_door = door.direction == DoorDirection::North &&
                                   door.type == DoorType::ExplicitRoomDoor;
  // Closed north key stairs take .not_open's `CMP #$0024 / BCC
  // RoomDraw_OneSidedShutters_North` and never reach the ranged-door writer
  // that mirrors a counterpart south door (rooms 0x00E, 0x099, 0x0AB).
  const bool north_key_stairs = door.direction == DoorDirection::North &&
                                (door.type == DoorType::SmallKeyStairsUp ||
                                 door.type == DoorType::SmallKeyStairsDown);
  if ((door.direction == DoorDirection::North ||
       door.direction == DoorDirection::West) &&
      position_index >= 6 && !north_explicit_door && !north_key_stairs) {
    const DoorDirection counterpart_direction =
        door.direction == DoorDirection::North ? DoorDirection::South
                                               : DoorDirection::East;
    // USDASM indexes the table immediately following NorthMiddle/WestMiddle
    // with the original 6..11 position offset. That lands on counterpart
    // positions 0..5; the two rasters are separated by the middle wall rather
    // than overlapping at the current anchor.
    const auto [counterpart_tile_x, counterpart_tile_y] =
        DoorPositionManager::PositionToRenderTileCoords(
            static_cast<uint8_t>(position_index - 6), counterpart_direction);
    (void)draw_ranged_door(counterpart_direction, counterpart_tile_x,
                           counterpart_tile_y, door.type, effective_door_type);
  }
 
  const bool drew_current = draw_ranged_door(door.direction, tile_x, tile_y,
                                             door.type, effective_door_type);
  if (!drew_current) {
    LOG_DEBUG("ObjectDrawer",
              "DrawDoor: INVALID ADDRESS - falling back to indicator");
    DrawDoorIndicator(bg1, tile_x, tile_y, door_width, door_height, door.type,
                      door.direction);
    return;
  }
 
  LOG_DEBUG("ObjectDrawer",
            "DrawDoor: type=%s effective=0x%04X dir=%s pos=%d at tile(%d,%d) "
            "size=%dx%d",
            std::string(GetDoorTypeName(door.type)).c_str(),
            static_cast<unsigned int>(effective_door_type),
            std::string(GetDoorDirectionName(door.direction)).c_str(),
            door.position, tile_x, tile_y, door_width, door_height);
}
 
void ObjectDrawer::DrawDoorIndicator(gfx::BackgroundBuffer& bg, int tile_x,
                                     int tile_y, int width, int height,
                                     DoorType type, DoorDirection direction) {
  // Draw a simple colored rectangle as door indicator when graphics unavailable
  // Different colors for different door types using DoorType enum
 
  auto& bitmap = bg.bitmap();
  auto& coverage_buffer = bg.mutable_coverage_data();
 
  uint8_t color_idx;
  switch (type) {
    case DoorType::NormalDoor:
    case DoorType::NormalDoorLower:
      color_idx = 45;  // Standard door color (brown)
      break;
 
    case DoorType::SmallKeyDoor:
    case DoorType::SmallKeyStairsUp:
    case DoorType::SmallKeyStairsDown:
    case DoorType::SmallKeyStairsUpLower:
    case DoorType::SmallKeyStairsDownLower:
      color_idx = 60;  // Key door - yellowish
      break;
 
    case DoorType::BigKeyDoor:
    case DoorType::UnopenableBigKeyDoor:
      color_idx = 58;  // Big key - golden
      break;
 
    case DoorType::BombableDoor:
    case DoorType::BombableCaveExit:
    case DoorType::ExplodingWall:
    case DoorType::DashWall:
      color_idx = 15;  // Bombable/destructible - brownish/cracked
      break;
 
    case DoorType::DoubleSidedShutter:
    case DoorType::DoubleSidedShutterLower:
    case DoorType::BottomSidedShutter:
    case DoorType::TopSidedShutter:
    case DoorType::BottomShutterLower:
    case DoorType::TopShutterLower:
      color_idx = 30;  // Shutter - greenish
      break;
 
    case DoorType::EyeWatchDoor:
      color_idx = 42;  // Eye watch - lighter brown
      break;
 
    case DoorType::CurtainDoor:
      color_idx = 35;  // Curtain - special
      break;
 
    case DoorType::CaveExit:
    case DoorType::FancyDungeonExit:
    case DoorType::FancyDungeonExitLower:
    case DoorType::WaterfallDoor:
    case DoorType::LitCaveExitLower:
      color_idx = 25;  // Cave/dungeon exit - dark
      break;
 
    case DoorType::ExitMarker:
    case DoorType::DungeonSwapMarker:
    case DoorType::LayerSwapMarker:
      color_idx = 5;  // Markers - very faint
      break;
 
    default:
      color_idx = 50;  // Default door color
      break;
  }
 
  int pixel_x = tile_x * 8;
  int pixel_y = tile_y * 8;
  int pixel_width = width * 8;
  int pixel_height = height * 8;
 
  int bitmap_width = bitmap.width();
  int bitmap_height = bitmap.height();
 
  bg.ClearBG1RevealMaskRect(bg1_reveal_mask_source_, pixel_x, pixel_y,
                            pixel_width, pixel_height);
 
  // Draw filled rectangle with border
  for (int py = 0; py < pixel_height; py++) {
    for (int px = 0; px < pixel_width; px++) {
      int dest_x = pixel_x + px;
      int dest_y = pixel_y + py;
 
      if (dest_x >= 0 && dest_x < bitmap_width && dest_y >= 0 &&
          dest_y < bitmap_height) {
        // Draw border (2 pixel thick) or fill
        bool is_border = (px < 2 || px >= pixel_width - 2 || py < 2 ||
                          py >= pixel_height - 2);
        uint8_t final_color = is_border ? (color_idx + 5) : color_idx;
 
        int offset = (dest_y * bitmap_width) + dest_x;
        bitmap.WriteToPixel(offset, final_color);
 
        if (offset >= 0 && offset < static_cast<int>(coverage_buffer.size())) {
          coverage_buffer[offset] = 1;
        }
      }
    }
  }
}
 
void ObjectDrawer::DrawChest(const RoomObject& obj, gfx::BackgroundBuffer& bg,
                             std::span<const gfx::TileInfo> tiles,
                             [[maybe_unused]] const DungeonState* state) {
  // USDASM RoomDraw_OpenChest draws F9A's fixed open graphic directly and
  // does not read or advance either chest/event counter.
  if (obj.id_ == 0xF9A) {
    DrawUsingRegistryRoutine(DrawRoutineIds::kSingle2x2, obj, bg, tiles, state);
    return;
  }
 
  // USDASM RoomDraw_Chest draws F99 as a single stateful 2x2 chest. The size
  // byte is not used for repetition.
 
  // Determine if chest is open
  bool is_open = false;
  if (state) {
    is_open = state->IsChestOpen(room_id_, current_chest_index_);
  }
 
  // RoomDraw_Chest advances the chest-only $0496 counter, then copies its next
  // value into the shared chest/lock $0498 counter.
  current_chest_index_++;
  current_room_event_index_ = current_chest_index_;
 
  // Draw SINGLE chest - no repetition based on size
  // Standard chests are 2x2 (4 tiles)
  // If we have extra tiles loaded, the second 4 are for open state
 
  if (is_open && tiles.size() >= 8) {
    // Small chest open tiles (indices 4-7) - SINGLE 2x2 draw
    if (tiles.size() >= 8) {
      WriteTile8(bg, obj.x_, obj.y_, tiles[4]);          // top-left
      WriteTile8(bg, obj.x_, obj.y_ + 1, tiles[5]);      // bottom-left
      WriteTile8(bg, obj.x_ + 1, obj.y_, tiles[6]);      // top-right
      WriteTile8(bg, obj.x_ + 1, obj.y_ + 1, tiles[7]);  // bottom-right
    }
    return;
  }
 
  // Draw closed chest - SINGLE 2x2 pattern (column-major order)
  if (tiles.size() >= 4) {
    WriteTile8(bg, obj.x_, obj.y_, tiles[0]);          // top-left
    WriteTile8(bg, obj.x_, obj.y_ + 1, tiles[1]);      // bottom-left
    WriteTile8(bg, obj.x_ + 1, obj.y_, tiles[2]);      // top-right
    WriteTile8(bg, obj.x_ + 1, obj.y_ + 1, tiles[3]);  // bottom-right
  }
}
 
void ObjectDrawer::DrawBigChest(const RoomObject& obj,
                                gfx::BackgroundBuffer& bg,
                                std::span<const gfx::TileInfo> tiles,
                                const DungeonState* state) {
  // USDASM RoomDraw_BigChest uses the chest-only $0496 slot for its room flag,
  // advances it once, then copies the next value into shared $0498. FB2 uses
  // RoomDraw_OpenBigChest directly and never reaches this stateful wrapper.
  bool is_open = false;
  if (state) {
    is_open = state->IsBigChestOpen(room_id_, current_chest_index_);
  }
 
  current_chest_index_++;
  current_room_event_index_ = current_chest_index_;
 
  constexpr size_t kBigChestStateTileCount = 12;
  if (is_open && tiles.size() >= kBigChestStateTileCount * 2) {
    tiles = tiles.subspan(kBigChestStateTileCount, kBigChestStateTileCount);
  }
  DrawUsingRegistryRoutine(DrawRoutineIds::kSingle4x3, obj, bg, tiles, state);
}
 
void ObjectDrawer::DrawBigKeyLock(const RoomObject& obj,
                                  gfx::BackgroundBuffer& bg,
                                  std::span<const gfx::TileInfo> tiles,
                                  const DungeonState* state) {
  // USDASM RoomDraw_BigKeyLock indexes $0402 through the shared $0498
  // chest/lock slot. An opened lock advances the slot but writes no tiles.
  const int room_event_index = current_room_event_index_++;
  if (state && state->IsBigKeyLockOpen(room_id_, room_event_index)) {
    return;
  }
 
  DrawUsingRegistryRoutine(DrawRoutineIds::kBigKeyLock, obj, bg, tiles, state);
}
 
void ObjectDrawer::DrawNothing(const RoomObject& obj, gfx::BackgroundBuffer& bg,
                               std::span<const gfx::TileInfo> tiles,
                               [[maybe_unused]] const DungeonState* state) {
  // Intentionally empty - represents invisible logic objects or placeholders
  // ASM: RoomDraw_Nothing_A ($0190F2), RoomDraw_Nothing_B ($01932E), etc.
  // These routines typically just RTS.
  LOG_DEBUG("ObjectDrawer", "DrawNothing for object 0x%02X (logic/invisible)",
            obj.id_);
}
 
void ObjectDrawer::CustomDraw(const RoomObject& obj, gfx::BackgroundBuffer& bg,
                              std::span<const gfx::TileInfo> tiles,
                              [[maybe_unused]] const DungeonState* state) {
  // Pattern: Custom draw routine (objects 0x31-0x32)
  // For now, fall back to simple 1x1
  if (tiles.size() >= 1) {
    // Use first 8x8 tile from span
    WriteTile8(bg, obj.x_, obj.y_, tiles[0]);
  }
}
 
void ObjectDrawer::DrawRightwards4x4_1to16(
    const RoomObject& obj, gfx::BackgroundBuffer& bg,
    std::span<const gfx::TileInfo> tiles,
    [[maybe_unused]] const DungeonState* state) {
  // Pattern: 4x4 block rightward (objects 0x33, 0xBA = large ceiling, etc.)
  int size = obj.size_ & 0x0F;
 
  // Assembly: GetSize_1to16, so count = size + 1
  int count = size + 1;
 
  // Debug: Log large ceiling objects (0xBA)
  if (obj.id_ == 0xBA && tiles.size() >= 16) {
    LOG_DEBUG("ObjectDrawer",
              "Large Ceiling Draw: obj=0x%02X pos=(%d,%d) size=%d tiles=%zu",
              obj.id_, obj.x_, obj.y_, size, tiles.size());
    LOG_DEBUG("ObjectDrawer", "  First 4 Tile IDs: [%d, %d, %d, %d]",
              tiles[0].id_, tiles[1].id_, tiles[2].id_, tiles[3].id_);
    LOG_DEBUG("ObjectDrawer", "  First 4 Palettes: [%d, %d, %d, %d]",
              tiles[0].palette_, tiles[1].palette_, tiles[2].palette_,
              tiles[3].palette_);
  }
 
  for (int s = 0; s < count; s++) {
    if (tiles.size() >= 16) {
      // Draw 4x4 pattern in COLUMN-MAJOR order (matching assembly)
      // Iterate columns (x) first, then rows (y) within each column
      for (int x = 0; x < 4; ++x) {
        for (int y = 0; y < 4; ++y) {
          WriteTile8(bg, obj.x_ + (s * 4) + x, obj.y_ + y, tiles[x * 4 + y]);
        }
      }
    }
  }
}
 
void ObjectDrawer::DrawRightwardsDecor4x3spaced4_1to16(
    const RoomObject& obj, gfx::BackgroundBuffer& bg,
    std::span<const gfx::TileInfo> tiles,
    [[maybe_unused]] const DungeonState* state) {
  // Pattern: 4x3 decoration with spacing (objects 0x3A-0x3B)
  // 4 columns × 3 rows = 12 tiles in COLUMN-MAJOR order
  // ASM: ADC #$0008 to Y = 8-byte advance = 4 tiles per iteration
  // Total spacing: 4 (object width) + 4 (gap) = 8 tiles between starts
  int size = obj.size_ & 0x0F;
 
  // Assembly: GetSize_1to16, so count = size + 1
  int count = size + 1;
 
  for (int s = 0; s < count; s++) {
    if (tiles.size() >= 12) {
      // Draw 4x3 pattern in COLUMN-MAJOR order (matching assembly)
      // Spacing: 8 tiles (4 object + 4 gap) per ASM ADC #$0008
      for (int x = 0; x < 4; ++x) {
        for (int y = 0; y < 3; ++y) {
          WriteTile8(bg, obj.x_ + (s * 8) + x, obj.y_ + y, tiles[x * 3 + y]);
        }
      }
    }
  }
}
 
// ============================================================================
// Utility Methods
// ============================================================================
 
void ObjectDrawer::MarkBg1RectRevealed(gfx::BackgroundBuffer& bg1, int start_px,
                                       int start_py, int pixel_width,
                                       int pixel_height) {
  bg1.SetBG1RevealMaskRect(bg1_reveal_mask_source_, start_px, start_py,
                           pixel_width, pixel_height);
}
 
void ObjectDrawer::MarkBg1OpaqueTilePixelsRevealed(
    gfx::BackgroundBuffer& bg1, const gfx::TileInfo& tile_info, int pixel_x,
    int pixel_y, const uint8_t* tiledata) {
  auto& bitmap = bg1.bitmap();
  if (!bitmap.is_active() || bitmap.width() == 0 || bitmap.height() == 0 ||
      tiledata == nullptr) {
    return;
  }
 
  constexpr int kMaxTileRow = 63;
  const int tile_col = tile_info.id_ % 16;
  const int tile_row = tile_info.id_ / 16;
  if (tile_row > kMaxTileRow) {
    return;
  }
 
  const int tile_base_x = tile_col * 8;
  const int tile_base_y = tile_row * 1024;
  auto& reveal_mask = bg1.mutable_bg1_reveal_mask_data();
  const uint8_t source_mask = static_cast<uint8_t>(bg1_reveal_mask_source_);
 
  for (int py = 0; py < 8; ++py) {
    const int src_row = tile_info.vertical_mirror_ ? (7 - py) : py;
    const int dest_y = pixel_y + py;
    if (dest_y < 0 || dest_y >= bitmap.height()) {
      continue;
    }
 
    for (int px = 0; px < 8; ++px) {
      const int src_col = tile_info.horizontal_mirror_ ? (7 - px) : px;
      const int src_index =
          (src_row * 128) + src_col + tile_base_x + tile_base_y;
      if (tiledata[src_index] == 0) {
        continue;
      }
 
      const int dest_x = pixel_x + px;
      if (dest_x < 0 || dest_x >= bitmap.width()) {
        continue;
      }
 
      const int dest_index = dest_y * bitmap.width() + dest_x;
      reveal_mask[dest_index] |= source_mask;
    }
  }
}
 
void ObjectDrawer::WriteTile8(gfx::BackgroundBuffer& bg, int tile_x, int tile_y,
                              const gfx::TileInfo& tile_info) {
  if (!IsValidTilePosition(tile_x, tile_y)) {
    return;
  }
  PushTrace(tile_x, tile_y, tile_info);
  if (trace_only_) {
    return;
  }
  // Keep the logical tilemap synchronized with the bitmap/coverage owner.
  // Conditional edge routines query this word after coverage selects whether
  // the object or layout half owns the effective physical BG entry.
  bg.SetTileAt(tile_x, tile_y, gfx::TileInfoToWord(tile_info));
  // Draw directly to bitmap instead of tile buffer to avoid being overwritten
  auto& bitmap = bg.bitmap();
  if (!bitmap.is_active() || bitmap.width() == 0) {
    return;  // Bitmap not ready
  }
 
  // The room-specific graphics buffer (current_gfx16_) contains the assembled
  // tile graphics for the current room. Object tile IDs are relative to this
  // buffer.
  const uint8_t* gfx_data = room_gfx_buffer_;
 
  if (!gfx_data) {
    LOG_DEBUG("ObjectDrawer", "ERROR: No graphics data available");
    return;
  }
 
  // A later BG1 tilemap write supersedes an earlier reveal request from the
  // same logical stream, including transparent pixels in the 8x8 footprint.
  bg.ClearBG1RevealMaskRect(bg1_reveal_mask_source_, tile_x * 8, tile_y * 8, 8,
                            8);
 
  const bool should_mark_bg1_mask =
      active_mask_source_bg_ != nullptr && (&bg == active_mask_source_bg_);
  // Draw single 8x8 tile directly to bitmap.
  DrawTileToBitmap(bitmap, tile_info, tile_x * 8, tile_y * 8, gfx_data);
  if (should_mark_bg1_mask && active_object_bg1_mask_ != nullptr) {
    MarkBg1OpaqueTilePixelsRevealed(*active_object_bg1_mask_, tile_info,
                                    tile_x * 8, tile_y * 8, gfx_data);
  }
  if (should_mark_bg1_mask && active_layout_bg1_mask_ != nullptr) {
    MarkBg1OpaqueTilePixelsRevealed(*active_layout_bg1_mask_, tile_info,
                                    tile_x * 8, tile_y * 8, gfx_data);
  }
 
  // Mark coverage for the full 8x8 tile region (even if pixels are transparent).
  //
  // This distinguishes "tilemap entry written but transparent" from "no write",
  // which is required to emulate SNES behavior where a transparent tile still
  // overwrites the previous tilemap entry (clearing BG1 and revealing BG2/backdrop).
  auto& coverage_buffer = bg.mutable_coverage_data();
 
  // Also update priority buffer with tile's priority bit.
  // Priority (over_) affects Z-ordering in SNES Mode 1 compositing.
  uint8_t priority = tile_info.over_ ? 1 : 0;
  int pixel_x = tile_x * 8;
  int pixel_y = tile_y * 8;
  auto& priority_buffer = bg.mutable_priority_data();
  int width = bitmap.width();
 
  // Update priority for each pixel in the 8x8 tile
  const auto& bitmap_data = bitmap.vector();
  for (int py = 0; py < 8; py++) {
    int dest_y = pixel_y + py;
    if (dest_y < 0 || dest_y >= bitmap.height())
      continue;
 
    for (int px = 0; px < 8; px++) {
      int dest_x = pixel_x + px;
      if (dest_x < 0 || dest_x >= width)
        continue;
 
      int dest_index = dest_y * width + dest_x;
 
      // Coverage is set for all pixels in the tile footprint.
      if (dest_index >= 0 &&
          dest_index < static_cast<int>(coverage_buffer.size())) {
        coverage_buffer[dest_index] = 1;
      }
 
      // Store priority only for opaque pixels; transparent writes clear stale
      // priority at this location.
      if (dest_index < static_cast<int>(bitmap_data.size()) &&
          bitmap_data[dest_index] != 255) {
        priority_buffer[dest_index] = priority;
      } else {
        priority_buffer[dest_index] = 0xFF;
      }
    }
  }
}
 
bool ObjectDrawer::IsValidTilePosition(int tile_x, int tile_y) const {
  return tile_x >= 0 && tile_x < kMaxTilesX && tile_y >= 0 &&
         tile_y < kMaxTilesY;
}
 
void ObjectDrawer::DrawTileToBitmap(gfx::Bitmap& bitmap,
                                    const gfx::TileInfo& tile_info, int pixel_x,
                                    int pixel_y, const uint8_t* tiledata) {
  // Draw an 8x8 tile directly to bitmap at pixel coordinates
  // Graphics data is in 8BPP linear format (1 pixel per byte)
  if (!tiledata)
    return;
 
  // DEBUG: Check if bitmap is valid
  if (!bitmap.is_active() || bitmap.width() == 0 || bitmap.height() == 0) {
    LOG_DEBUG("ObjectDrawer", "ERROR: Invalid bitmap - active=%d, size=%dx%d",
              bitmap.is_active(), bitmap.width(), bitmap.height());
    return;
  }
 
  // Calculate tile position in 8BPP graphics buffer
  // Layout: 16 tiles per row, each tile is 8 pixels wide (8 bytes)
  // Row stride: 128 bytes (16 tiles * 8 bytes)
  // Buffer size: 0x10000 (65536 bytes) = 64 tile rows max
  constexpr int kGfxBufferSize = 0x10000;
  constexpr int kMaxTileRow = 63;  // 64 rows (0-63), each 1024 bytes
 
  int tile_col = tile_info.id_ % 16;
  int tile_row = tile_info.id_ / 16;
 
  // CRITICAL: Validate tile_row to prevent index out of bounds
  if (tile_row > kMaxTileRow) {
    LOG_DEBUG("ObjectDrawer", "Tile ID 0x%03X out of bounds (row %d > %d)",
              tile_info.id_, tile_row, kMaxTileRow);
    return;
  }
 
  int tile_base_x = tile_col * 8;  // 8 bytes per tile horizontally
  int tile_base_y =
      tile_row * 1024;  // 1024 bytes per tile row (8 rows * 128 bytes)
 
  // DEBUG: Log first few tiles being drawn with their graphics data
  static int draw_debug_count = 0;
  if (draw_debug_count < 5) {
    int sample_index = tile_base_y + tile_base_x;
    LOG_DEBUG("ObjectDrawer",
              "DrawTile: id=%d (col=%d,row=%d) gfx_offset=%d (0x%04X)",
              tile_info.id_, tile_col, tile_row, sample_index, sample_index);
    draw_debug_count++;
  }
 
  // Palette offset calculation using direct CGRAM row mirroring.
  //
  // Room::RenderRoomGraphics loads dungeon main palettes into SDL bank rows 2-7,
  // leaving rows 0-1 as transparent HUD placeholders. The tile palette bits are
  // therefore already the correct SDL bank row index.
  //
  // Drawing formula: final_color = pixel + (pal * 16)
  // Where pixel 0 = transparent (not written), pixel 1-15 = colors within bank.
  uint8_t pal = tile_info.palette_ & 0x07;
  const uint8_t palette_offset = static_cast<uint8_t>(pal * 16);
 
  // Draw 8x8 pixels with overwrite semantics.
  //
  // Important SNES behavior: writing a tilemap entry replaces the previous
  // contents for the full 8x8 footprint. Source pixel 0 is transparent, but it
  // still clears what was there before. We model that by writing 255
  // (transparent key) for zero pixels.
  bool any_pixels_changed = false;
 
  for (int py = 0; py < 8; py++) {
    // Source row with vertical mirroring
    int src_row = tile_info.vertical_mirror_ ? (7 - py) : py;
 
    for (int px = 0; px < 8; px++) {
      // Source column with horizontal mirroring
      int src_col = tile_info.horizontal_mirror_ ? (7 - px) : px;
 
      // Calculate source index in 8BPP buffer
      // Stride is 128 bytes (sheet width)
      int src_index = (src_row * 128) + src_col + tile_base_x + tile_base_y;
      uint8_t pixel = tiledata[src_index];
      uint8_t out_pixel = 255;  // transparent/clear
      if (pixel != 0) {
        // Pixels 1-15 map into a 16-color bank chunk.
        out_pixel = static_cast<uint8_t>(pixel + palette_offset);
      }
 
      int dest_x = pixel_x + px;
      int dest_y = pixel_y + py;
      if (dest_x < 0 || dest_x >= bitmap.width() || dest_y < 0 ||
          dest_y >= bitmap.height()) {
        continue;
      }
 
      int dest_index = dest_y * bitmap.width() + dest_x;
      if (dest_index < 0 ||
          dest_index >= static_cast<int>(bitmap.mutable_data().size())) {
        continue;
      }
 
      auto& dst = bitmap.mutable_data()[dest_index];
      if (dst != out_pixel) {
        dst = out_pixel;
        any_pixels_changed = true;
      }
    }
  }
 
  if (any_pixels_changed) {
    bitmap.set_modified(true);
  }
}
 
absl::Status ObjectDrawer::DrawLayerMaskFull(const RoomObject& object,
                                             gfx::BackgroundBuffer& target_bg,
                                             RoomObject::LayerType layer) {
  // USDASM RoomDraw_BG2MaskFull (bank_01 table entry 0x273) runs
  // RoomDraw_FloorChunks with obj00E0, eight words of $01EC, over the whole
  // map of the current list's layer. $01EC is the game's tilemap erase value
  // (EraseTilemaps). Vanilla places it only in the BG2 object list, where it
  // erases the floor and the BothBG walls drawn before it. The transparent
  // erase tile also marks object coverage, so compositing hides the layout.
  constexpr uint16_t kTilemapEraseWord = 0x01EC;
  const gfx::TileInfo erase = gfx::WordToTileInfo(kTilemapEraseWord);
  SetTraceContext(object, layer);
  for (int y = 0; y < DrawContext::kMaxTilesY; ++y) {
    for (int x = 0; x < DrawContext::kMaxTilesX; ++x) {
      WriteTile8(target_bg, x, y, erase);
    }
  }
  return absl::OkStatus();
}
 
absl::Status ObjectDrawer::DrawLampCones(const RoomObject& object,
                                         gfx::BackgroundBuffer& bg2) {
  // USDASM RoomDraw_LampCones / RoomDraw_SingleLampCone (bank_01 table entry
  // 0x22A): four 12x12 row-major blocks from RoomDrawObjectData stored with
  // STA.l $7E4000,X, i.e. always BG2, at fixed tilemap offsets.
  struct Cone {
    int data_offset;     // relative to RoomDrawObjectData
    int tilemap_offset;  // byte offset into the 64x64 tilemap
  };
  constexpr Cone kCones[] = {
      {0x16DC, 0x0514}, {0x17F6, 0x0554}, {0x1914, 0x1514}, {0x1A2A, 0x1554}};
  constexpr int kConeSize = 12;
  const auto& rom_data = rom_->vector();
  SetTraceContext(object, RoomObject::LayerType::BG2);
  for (const Cone& cone : kCones) {
    const int base = kRoomObjectTileAddress + cone.data_offset;
    if (base < 0 ||
        base + kConeSize * kConeSize * 2 > static_cast<int>(rom_data.size())) {
      return absl::OutOfRangeError(
          absl::StrFormat("Lamp cone data out of range: 0x%X", base));
    }
    const int origin = cone.tilemap_offset / 2;
    for (int row = 0; row < kConeSize; ++row) {
      for (int column = 0; column < kConeSize; ++column) {
        const int word_address = base + (row * kConeSize + column) * 2;
        const uint16_t word = static_cast<uint16_t>(
            rom_data[word_address] | (rom_data[word_address + 1] << 8));
        WriteTile8(bg2, origin % 64 + column, origin / 64 + row,
                   gfx::WordToTileInfo(word));
      }
    }
  }
  return absl::OkStatus();
}
 
absl::Status ObjectDrawer::DrawAgahnimsWindows(
    const RoomObject& object, gfx::BackgroundBuffer& bg1,
    gfx::BackgroundBuffer& bg2, gfx::BackgroundBuffer* layout_bg1,
    gfx::BackgroundBuffer* layout_bg2) {
  // Literal port of USDASM RoomDraw_AgahnimsWindows (bank_01 table entry
  // 0x22E). X starts at $08, the object's tilemap byte offset; each
  // `STA.l $7E2xxx,X` stores to byte (xxx + X) of the upper tilemap. Offsets
  // past $2000 bytes continue into the lower tilemap at $7E4000, as in WRAM.
  const auto& rom_data = rom_->vector();
  const int anchor = object.y_ * 0x80 + object.x_ * 2;
  auto read_word = [&](int data_offset) -> uint16_t {
    const int address = kRoomObjectTileAddress + data_offset;
    if (address < 0 || address + 1 >= static_cast<int>(rom_data.size())) {
      return 0;
    }
    return static_cast<uint16_t>(rom_data[address] |
                                 (rom_data[address + 1] << 8));
  };
  auto tile_at = [&](int store, int x) -> std::pair<int, int> {
    return {((store - 0x2000 + x) / 2) % 64, ((store - 0x2000 + x) / 2) / 64};
  };
  auto store = [&](int address, int x, uint16_t word) {
    auto [tile_x, tile_y] = tile_at(address, x);
    if (tile_y < 64) {
      SetTraceContext(object, RoomObject::LayerType::BG1);
      WriteTile8(bg1, tile_x, tile_y, gfx::WordToTileInfo(word));
    } else if (tile_y < 128) {
      SetTraceContext(object, RoomObject::LayerType::BG2);
      WriteTile8(bg2, tile_x, tile_y - 64, gfx::WordToTileInfo(word));
    }
  };
  constexpr uint16_t kHFlip = 0x4000;
 
  // .next_a: 6 columns x 4 rows from obj1BF2, three copies.
  for (int i = 0, x = anchor, y = 0x1BF2; i < 6; ++i, x += 2, y += 8) {
    for (int row = 0; row < 4; ++row) {
      const uint16_t word = read_word(y + row * 2);
      for (int base : {0x220E, 0x221A, 0x2226}) {
        store(base + row * 0x80, x, word);
      }
    }
  }
  // .next_b: 5 rows from obj1C22, two mirrored diagonals.
  for (int i = 0, x = anchor, y = 0x1C22; i < 5; ++i, x += 0x80, y += 2) {
    const uint16_t word = read_word(y);
    for (int base : {0x2504, 0x2486, 0x2408, 0x238A, 0x230C, 0x228E, 0x2210}) {
      store(base, x, word);
    }
    for (int base : {0x222E, 0x22B0, 0x2332, 0x23B4, 0x2436, 0x24B8, 0x253A}) {
      store(base, x, word | kHFlip);
    }
  }
  // .next_c: 6 rows from obj1C2C, left edge and mirrored right edge, three
  // copies 6 rows apart.
  for (int i = 0, x = anchor, y = 0x1C2C; i < 6; ++i, x += 0x80, y += 8) {
    for (int k = 0; k < 4; ++k) {
      const uint16_t word = read_word(y + k * 2);
      for (int base : {0x2584, 0x2884, 0x2B84}) {
        store(base + k * 2, x, word);
      }
      for (int base : {0x25BA, 0x28BA, 0x2BBA}) {
        store(base - k * 2, x, word | kHFlip);
      }
    }
  }
  // .next_d: 6 columns from obj1C5C, two rows, two copies.
  for (int i = 0, x = anchor, y = 0x1C5C; i < 6; ++i, x += 2, y += 2) {
    const uint16_t top = read_word(y);
    const uint16_t bottom = read_word(y + 12);
    store(0x2498, x, top);
    store(0x24A4, x, top);
    store(0x2518, x, bottom);
    store(0x2524, x, bottom);
  }
  // .next_e: 6 rows from obj1C74, two columns, two copies.
  for (int i = 0, x = anchor, y = 0x1C74; i < 6; ++i, x += 0x80, y += 4) {
    store(0x270E, x, read_word(y));
    store(0x2A0E, x, read_word(y));
    store(0x2710, x, read_word(y + 2));
    store(0x2A10, x, read_word(y + 2));
  }
  // .next_f: 5 columns x 5 rows from obj1C8C, column-major.
  for (int i = 0, x = anchor, y = 0x1C8C; i < 5; ++i, x += 2, y += 10) {
    for (int row = 0; row < 5; ++row) {
      store(0x248E + row * 0x80, x, read_word(y + row * 2));
    }
  }
  // .next_g: ORA #$2000 into four tiles of two rows.
  if (!trace_only_) {
    for (int i = 0, x = anchor; i < 4; ++i, x += 2) {
      for (int base : {0x2E1C, 0x2E9C}) {
        auto [tile_x, tile_y] = tile_at(base, x);
        if (tile_y < 64) {
          PromoteTilePriorityOnOwners(bg1, layout_bg1, tile_x, tile_y);
        } else if (tile_y < 128) {
          PromoteTilePriorityOnOwners(bg2, layout_bg2, tile_x, tile_y - 64);
        }
      }
    }
  }
  return absl::OkStatus();
}
 
absl::Status ObjectDrawer::DrawBigDecor10x8(const RoomObject& object,
                                            gfx::BackgroundBuffer& target_bg,
                                            RoomObject::LayerType layer,
                                            int data_pc) {
  // USDASM RoomDraw_SomeBigDecors ($01:9D9B area): 8 rows of 10 words,
  // row-major, stored at the object's position on the current list's layer.
  constexpr int kColumns = 10;
  constexpr int kRows = 8;
  const auto& rom_data = rom_->vector();
  if (data_pc < 0 ||
      data_pc + kColumns * kRows * 2 > static_cast<int>(rom_data.size())) {
    return absl::OutOfRangeError(
        absl::StrFormat("Big decor data out of range: 0x%X", data_pc));
  }
  SetTraceContext(object, layer);
  for (int row = 0; row < kRows; ++row) {
    for (int column = 0; column < kColumns; ++column) {
      const int address = data_pc + (row * kColumns + column) * 2;
      const uint16_t word = static_cast<uint16_t>(rom_data[address] |
                                                  (rom_data[address + 1] << 8));
      WriteTile8(target_bg, object.x_ + column, object.y_ + row,
                 gfx::WordToTileInfo(word));
    }
  }
  return absl::OkStatus();
}
 
absl::Status ObjectDrawer::DrawVitreousGoo(const RoomObject& object,
                                           gfx::BackgroundBuffer& bg2) {
  // USDASM RoomDraw_VitreousGooGraphics (bank_01 table entry 0x262): 22
  // columns of 11 rows from obj20F6 (11 words per column) stored with
  // STA.l $7E4000,X, i.e. always BG2, then a 3x2 block from obj22DA at
  // $4592/$4612 (column +9, rows +11 and +12).
  const auto& rom_data = rom_->vector();
  auto read_word = [&](int data_offset) -> uint16_t {
    const int address = kRoomObjectTileAddress + data_offset;
    if (address < 0 || address + 1 >= static_cast<int>(rom_data.size())) {
      return 0;
    }
    return static_cast<uint16_t>(rom_data[address] |
                                 (rom_data[address + 1] << 8));
  };
  SetTraceContext(object, RoomObject::LayerType::BG2);
  for (int column = 0; column < 22; ++column) {
    for (int row = 0; row < 11; ++row) {
      WriteTile8(
          bg2, object.x_ + column, object.y_ + row,
          gfx::WordToTileInfo(read_word(0x20F6 + column * 22 + row * 2)));
    }
  }
  for (int column = 0; column < 3; ++column) {
    WriteTile8(bg2, object.x_ + 9 + column, object.y_ + 11,
               gfx::WordToTileInfo(read_word(0x22DA + column * 2)));
    WriteTile8(bg2, object.x_ + 9 + column, object.y_ + 12,
               gfx::WordToTileInfo(read_word(0x22DA + 6 + column * 2)));
  }
  return absl::OkStatus();
}
 
void ObjectDrawer::DrawChestHoleOverlay(int tag1, int tag2,
                                        const DungeonState* state,
                                        gfx::BackgroundBuffer& bg1) {
  constexpr int kChestHoles0Tag = 0x22;
  constexpr int kChestHoles8Tag = 0x3B;
  constexpr int kOverlayDataPointers = 0x026CC0;  // $04:ECC0, 3-byte pointers
  constexpr uint8_t kPitObjectId = 0xA4;
  if (state == nullptr || rom_ == nullptr || !state->IsChestOpen(room_id_, 0)) {
    return;
  }
  int overlay = -1;
  if (tag1 == kChestHoles0Tag || tag2 == kChestHoles0Tag) {
    overlay = 0x00;
  } else if (tag1 == kChestHoles8Tag || tag2 == kChestHoles8Tag) {
    overlay = 0x12;
  } else {
    return;
  }
 
  const auto& rom_data = rom_->vector();
  auto read_byte = [&](int address) -> int {
    return address >= 0 && address < static_cast<int>(rom_data.size())
               ? rom_data[address]
               : -1;
  };
  auto read_word = [&](int data_offset) -> uint16_t {
    const int address = kRoomObjectTileAddress + data_offset;
    const int lo = read_byte(address);
    const int hi = read_byte(address + 1);
    return lo < 0 || hi < 0 ? 0 : static_cast<uint16_t>(lo | (hi << 8));
  };
  const int pointer = kOverlayDataPointers + (overlay * 3);
  const int b0 = read_byte(pointer);
  const int b1 = read_byte(pointer + 1);
  const int b2 = read_byte(pointer + 2);
  if (b0 < 0 || b1 < 0 || b2 < 0) {
    return;
  }
  int entry = static_cast<int>(SnesToPc((b2 << 16) | (b1 << 8) | b0));
 
  // Underworld_DrawRoomOverlay .draw_hole: row 0 obj063C+2, rows 1-2
  // obj05AA+0, row 3 obj0642+2, each four tiles wide.
  const gfx::TileInfo row_tiles[4] = {
      gfx::WordToTileInfo(read_word(0x063C + 2)),
      gfx::WordToTileInfo(read_word(0x05AA)),
      gfx::WordToTileInfo(read_word(0x05AA)),
      gfx::WordToTileInfo(read_word(0x0642 + 2)),
  };
  for (;; entry += 3) {
    const int x_byte = read_byte(entry);
    const int y_byte = read_byte(entry + 1);
    const int id = read_byte(entry + 2);
    if (x_byte < 0 || y_byte < 0 || (x_byte == 0xFF && y_byte == 0xFF)) {
      return;
    }
    if (id != kPitObjectId) {
      continue;  // .draw_solid_floor needs the runtime $046A floor pointer.
    }
    for (int row = 0; row < 4; ++row) {
      for (int col = 0; col < 4; ++col) {
        WriteTile8(bg1, (x_byte >> 2) + col, (y_byte >> 2) + row,
                   row_tiles[row]);
      }
    }
  }
}
 
absl::Status ObjectDrawer::DrawRoomDrawObjectData2x2(
    uint16_t object_id, int tile_x, int tile_y, RoomObject::LayerType layer,
    uint16_t room_draw_object_data_offset, gfx::BackgroundBuffer& bg1,
    gfx::BackgroundBuffer& bg2) {
  if (!rom_ || !rom_->is_loaded()) {
    return absl::FailedPreconditionError("ROM not loaded");
  }
 
  const auto& rom_data = rom_->vector();
  const int base =
      kRoomObjectTileAddress + static_cast<int>(room_draw_object_data_offset);
  if (base < 0 || base + 7 >= static_cast<int>(rom_data.size())) {
    return absl::OutOfRangeError(absl::StrFormat(
        "RoomDrawObjectData 2x2 out of range: base=0x%X", base));
  }
 
  auto read_word = [&](int off) -> uint16_t {
    return static_cast<uint16_t>(rom_data[off]) |
           (static_cast<uint16_t>(rom_data[off + 1]) << 8);
  };
 
  const uint16_t w0 = read_word(base + 0);
  const uint16_t w1 = read_word(base + 2);
  const uint16_t w2 = read_word(base + 4);
  const uint16_t w3 = read_word(base + 6);
 
  const gfx::TileInfo t0 = gfx::WordToTileInfo(w0);
  const gfx::TileInfo t1 = gfx::WordToTileInfo(w1);
  const gfx::TileInfo t2 = gfx::WordToTileInfo(w2);
  const gfx::TileInfo t3 = gfx::WordToTileInfo(w3);
 
  // Set trace context once; WriteTile8 will emit per-tile traces.
  RoomObject trace_obj(
      static_cast<int16_t>(object_id), static_cast<uint8_t>(tile_x),
      static_cast<uint8_t>(tile_y), 0, static_cast<uint8_t>(layer));
  SetTraceContext(trace_obj, layer);
 
  gfx::BackgroundBuffer& target_bg =
      (layer == RoomObject::LayerType::BG2) ? bg2 : bg1;
 
  // Column-major order (matches USDASM $BF/$CB/$C2/$CE writes).
  WriteTile8(target_bg, tile_x + 0, tile_y + 0, t0);  // top-left
  WriteTile8(target_bg, tile_x + 0, tile_y + 1, t1);  // bottom-left
  WriteTile8(target_bg, tile_x + 1, tile_y + 0, t2);  // top-right
  WriteTile8(target_bg, tile_x + 1, tile_y + 1, t3);  // bottom-right
 
  return absl::OkStatus();
}
 
// ============================================================================
// Type 3 / Special Routine Implementations
// ============================================================================
 
void ObjectDrawer::DrawLargeCanvasObject(const RoomObject& obj,
                                         gfx::BackgroundBuffer& bg,
                                         std::span<const gfx::TileInfo> tiles,
                                         int width, int height) {
  // Generic large object drawer
  if (tiles.size() >= static_cast<size_t>(width * height)) {
    for (int y = 0; y < height; ++y) {
      for (int x = 0; x < width; ++x) {
        WriteTile8(bg, obj.x_ + x, obj.y_ + y, tiles[y * width + x]);
      }
    }
  }
}
 
}  // namespace zelda3
}  // namespace yaze
 
std::pair<int, int> yaze::zelda3::ObjectDrawer::CalculateObjectDimensions(
    const RoomObject& object) {
  return DimensionService::Get().GetPixelDimensions(object);
}
 
void yaze::zelda3::ObjectDrawer::DrawCustomObject(
    const RoomObject& obj, gfx::BackgroundBuffer& bg,
    [[maybe_unused]] std::span<const gfx::TileInfo> tiles,
    [[maybe_unused]] const DungeonState* state) {
  const int subtype = obj.size_ & 0x1F;
  absl::StatusOr<std::shared_ptr<const CustomObject>> result =
      custom_objects_ != nullptr
          ? custom_objects_->GetObject(obj.id_, subtype)
          : absl::StatusOr<std::shared_ptr<const CustomObject>>(
                CustomObjectManager::Get().GetObjectInternal(obj.id_, subtype));
  if (!result.ok()) {
    DrawMissingCustomObjectPlaceholder(bg, obj.x_, obj.y_);
    LOG_DEBUG("ObjectDrawer", "Custom object 0x%03X subtype %d not found: %s",
              obj.id_, subtype, result.status().message().data());
    return;
  }
 
  auto custom_obj = result.value();
  if (!custom_obj || custom_obj->IsEmpty())
    return;
 
  int tile_x = obj.x_;
  int tile_y = obj.y_;
 
  for (const auto& entry : custom_obj->tiles) {
    // Oracle's custom-object handlers advance past a zero payload word without
    // storing it. Preserve the tile already underneath this object.
    if (entry.tile_data == 0) {
      continue;
    }
    // entry.tile_data is the raw vhopppcc cccccccc source word. Resolve the
    // effective runtime word here so source editing remains lossless.
    const uint16_t runtime_word =
        CustomObjectRuntimeTileWord(obj.id_, entry.tile_data);
    // Convert to TileInfo and render using WriteTile8 (not SetTileAt which
    // only stores to buffer without rendering)
    gfx::TileInfo tile_info = gfx::WordToTileInfo(runtime_word);
    WriteTile8(bg, tile_x + entry.rel_x, tile_y + entry.rel_y, tile_info);
  }
}
 
void yaze::zelda3::ObjectDrawer::DrawMissingCustomObjectPlaceholder(
    gfx::BackgroundBuffer& bg, int tile_x, int tile_y) {
  if (trace_only_) {
    return;
  }
 
  auto& bitmap = bg.bitmap();
  if (!bitmap.is_active() || bitmap.width() <= 0 || bitmap.height() <= 0) {
    return;
  }
 
  auto& pixels = bitmap.mutable_data();
  auto& coverage = bg.mutable_coverage_data();
  auto& priority = bg.mutable_priority_data();
 
  constexpr int kPlaceholderSizePx = 16;
  constexpr uint8_t kFillColor = 33;
  constexpr uint8_t kAccentColor = 47;
 
  const int start_x = tile_x * 8;
  const int start_y = tile_y * 8;
  const int width = bitmap.width();
  const int height = bitmap.height();
 
  bg.ClearBG1RevealMaskRect(bg1_reveal_mask_source_, start_x, start_y,
                            kPlaceholderSizePx, kPlaceholderSizePx);
 
  for (int py = 0; py < kPlaceholderSizePx; ++py) {
    const int dest_y = start_y + py;
    if (dest_y < 0 || dest_y >= height)
      continue;
    for (int px = 0; px < kPlaceholderSizePx; ++px) {
      const int dest_x = start_x + px;
      if (dest_x < 0 || dest_x >= width)
        continue;
      const bool border = (px == 0 || py == 0 || px == kPlaceholderSizePx - 1 ||
                           py == kPlaceholderSizePx - 1);
      const bool diagonal = (px == py) || (px + py == kPlaceholderSizePx - 1);
      const int dest_index = dest_y * width + dest_x;
      pixels[dest_index] = (border || diagonal) ? kAccentColor : kFillColor;
      if (dest_index < static_cast<int>(coverage.size()))
        coverage[dest_index] = 1;
      if (dest_index < static_cast<int>(priority.size()))
        priority[dest_index] = 0;
    }
  }
  bitmap.set_modified(true);
}
 
void yaze::zelda3::ObjectDrawer::DrawPotItem(uint8_t item_id, int x, int y,
                                             gfx::BackgroundBuffer& bg) {
  // Draw a small colored indicator for pot items
  // Item types from ZELDA3_DUNGEON_SPEC.md Section 7.2
  // Uses palette indices that map to recognizable colors
 
  if (item_id == 0)
    return;  // Nothing - skip
 
  auto& bitmap = bg.bitmap();
  auto& coverage_buffer = bg.mutable_coverage_data();
  if (!bitmap.is_active() || bitmap.width() == 0)
    return;
 
  // Convert tile coordinates to pixel coordinates
  // Items are drawn offset from pot position (centered on pot)
  int pixel_x = (x * 8) + 2;  // Offset 2 pixels into the pot tile
  int pixel_y = (y * 8) + 2;
 
  // Choose color based on item category
  // Using palette indices that should be visible in dungeon palettes
  uint8_t color_idx;
  switch (item_id) {
    // Rupees (green/blue/red tones)
    case 1:            // Green rupee
    case 7:            // Blue rupee
    case 12:           // Blue rupee variant
      color_idx = 30;  // Greenish (palette 2, index 0)
      break;
 
    // Hearts (red tones)
    case 6:   // Heart
    case 11:  // Heart
    case 13:  // Heart variant
      // NOTE: Avoid palette indices 0/16/32/.. which are transparent in SNES
      // CGRAM rows. Using 5 gives a consistently visible indicator.
      color_idx = 5;
      break;
 
    // Keys (yellow/gold)
    case 8:            // Key*8
    case 19:           // Key
      color_idx = 45;  // Yellowish (palette 3)
      break;
 
    // Bombs (dark/black)
    case 5:            // Bomb
    case 10:           // 1 bomb
    case 16:           // Bomb refill
      color_idx = 60;  // Darker color (palette 4)
      break;
 
    // Arrows (brown/wood)
    case 9:            // Arrow
    case 17:           // Arrow refill
      color_idx = 15;  // Brownish (palette 1)
      break;
 
    // Magic (blue/purple)
    case 14:           // Small magic
    case 15:           // Big magic
      color_idx = 75;  // Bluish (palette 5)
      break;
 
    // Fairy (pink/light)
    case 18:          // Fairy
    case 20:          // Fairy*8
      color_idx = 5;  // Pinkish
      break;
 
    // Special/Traps (distinct colors)
    case 2:            // Rock crab
    case 3:            // Bee
      color_idx = 20;  // Enemy indicator
      break;
 
    case 23:           // Hole
    case 24:           // Warp
    case 25:           // Staircase
      color_idx = 10;  // Transport indicator
      break;
 
    case 26:           // Bombable
    case 27:           // Switch
      color_idx = 35;  // Interactive indicator
      break;
 
    case 4:  // Random
    default:
      color_idx = 50;  // Default/random indicator
      break;
  }
 
  // Safety: never use CGRAM transparent slots (0,16,32,...) for the indicator.
  // In the editor these would appear invisible or "missing" depending on
  // compositing.
  if (color_idx != 255 && (color_idx % 16) == 0) {
    color_idx++;
  }
 
  // Draw a 4x4 colored square as item indicator
  int bitmap_width = bitmap.width();
  int bitmap_height = bitmap.height();
 
  bg.ClearBG1RevealMaskRect(bg1_reveal_mask_source_, pixel_x, pixel_y, 4, 4);
 
  for (int py = 0; py < 4; py++) {
    for (int px = 0; px < 4; px++) {
      int dest_x = pixel_x + px;
      int dest_y = pixel_y + py;
 
      // Bounds check
      if (dest_x >= 0 && dest_x < bitmap_width && dest_y >= 0 &&
          dest_y < bitmap_height) {
        int offset = (dest_y * bitmap_width) + dest_x;
        bitmap.WriteToPixel(offset, color_idx);
        if (offset >= 0 && offset < static_cast<int>(coverage_buffer.size())) {
          coverage_buffer[offset] = 1;
        }
      }
    }
  }
}