dungeon_commands.cc

Go to the documentation of this file.

#include "cli/handlers/game/dungeon_commands.h"
 
#include <algorithm>
#include <fstream>
#include <limits>
#include <memory>
#include <optional>
#include <sstream>
#include <vector>
 
#include "absl/strings/ascii.h"
#include "absl/strings/str_cat.h"
#include "absl/strings/str_format.h"
#include "absl/strings/str_split.h"
#include "cli/util/hex_util.h"
#include "cli/util/sprite_label_fields.h"
#include "core/dungeon_stream_layout_adapter.h"
#include "core/hack_manifest.h"
#include "rom/rom.h"
#include "rom/snes.h"
#include "rom/transaction.h"
#include "util/macro.h"
#include "zelda3/dungeon/custom_collision.h"
#include "zelda3/dungeon/dungeon_editor_system.h"
#include "zelda3/dungeon/dungeon_rom_addresses.h"
#include "zelda3/dungeon/dungeon_spawn_point.h"
#include "zelda3/dungeon/room.h"
#include "zelda3/dungeon/room_collision.h"
#include "zelda3/dungeon/room_entrance.h"
#include "zelda3/dungeon/room_layout.h"
#include "zelda3/dungeon/track_collision_generator.h"
#include "zelda3/resource_labels.h"
#include "zelda3/sprite/sprite.h"
 
namespace yaze {
namespace cli {
namespace handlers {
 
using util::ParseHexString;
 
namespace {
 
constexpr uint8_t kStopTileMin = 0xB7;
constexpr uint8_t kStopTileMax = 0xBA;
 
bool IsStopTile(uint8_t v) {
  return v >= kStopTileMin && v <= kStopTileMax;
}
 
bool IsEncodedRoomStreamObject(const zelda3::RoomObject& object) {
  // Lightable torches and pushable blocks are synthesized from separate
  // global tables after the encoded room object stream has been parsed.
  return (object.options() & zelda3::ObjectOption::Torch) ==
             zelda3::ObjectOption::Nothing &&
         (object.options() & zelda3::ObjectOption::Block) ==
             zelda3::ObjectOption::Nothing;
}
 
struct RoomPropertyManifestContext {
  core::HackManifest manifest;
  std::optional<zelda3::DungeonStreamLayout> allocator_layout;
};
 
absl::StatusOr<std::optional<RoomPropertyManifestContext>>
LoadRoomPropertyManifestContext(const resources::ArgumentParser& parser,
                                bool require_object_allocator) {
  const auto manifest_path = parser.GetString("manifest");
  if (!manifest_path.has_value()) {
    return std::nullopt;
  }
 
  RoomPropertyManifestContext context;
  RETURN_IF_ERROR(context.manifest.LoadFromFile(*manifest_path));
  if (!require_object_allocator) {
    return std::optional<RoomPropertyManifestContext>(std::move(context));
  }
 
  const auto* manifest_layout = context.manifest.GetDungeonStreamLayout(
      core::DungeonStreamType::kObjects);
  if (manifest_layout == nullptr) {
    return absl::FailedPreconditionError(
        "Manifest does not define dungeon_stream_regions.objects");
  }
  if (manifest_layout->strategy != core::DungeonWriteStrategy::kCopyOnWrite) {
    return absl::FailedPreconditionError(
        "dungeon_stream_regions.objects must use copy_on_write");
  }
  zelda3::DungeonStreamLayout allocator_layout;
  ASSIGN_OR_RETURN(allocator_layout,
                   core::ToDungeonStreamAllocatorLayout(
                       core::DungeonStreamType::kObjects, *manifest_layout));
  context.allocator_layout = std::move(allocator_layout);
  return std::optional<RoomPropertyManifestContext>(std::move(context));
}
 
absl::Status ValidateManifestWriteRanges(
    const core::HackManifest& manifest,
    const std::vector<std::pair<uint32_t, uint32_t>>& ranges) {
  if (!manifest.AnalyzePcWriteRanges(ranges).empty()) {
    return absl::PermissionDeniedError("Write conflict with Hack Manifest");
  }
  return absl::OkStatus();
}
 
absl::Status ValidateObjectStreamHeaderManifestConflicts(
    const Rom& rom, int room_id, const RoomPropertyManifestContext& context) {
  if (!context.allocator_layout.has_value()) {
    return absl::FailedPreconditionError(
        "Object-stream header manifest is missing allocator capability");
  }
 
  std::vector<std::pair<uint32_t, uint32_t>> ranges;
 
  uint32_t pointer_table_snes = 0;
  ASSIGN_OR_RETURN(pointer_table_snes,
                   rom.ReadLong(zelda3::kRoomObjectPointer));
  const uint32_t pointer_table_pc = SnesToPc(pointer_table_snes);
  const uint64_t pointer_slot = static_cast<uint64_t>(pointer_table_pc) +
                                static_cast<uint64_t>(room_id) * 3u;
  if (pointer_slot + 3u > rom.size()) {
    return absl::OutOfRangeError(
        "Selected object pointer slot is outside the ROM");
  }
 
  uint32_t stream_snes = 0;
  ASSIGN_OR_RETURN(stream_snes, rom.ReadLong(static_cast<int>(pointer_slot)));
  const uint32_t stream_pc = SnesToPc(stream_snes);
  if (static_cast<uint64_t>(stream_pc) + 2u > rom.size()) {
    return absl::OutOfRangeError(
        "Selected object stream header is outside the ROM");
  }
  ranges.emplace_back(stream_pc, stream_pc + 2u);
 
  for (const auto& range : context.allocator_layout->allocation_ranges) {
    ranges.emplace_back(range.begin, range.end);
  }
  const uint64_t cow_pointer_slot =
      static_cast<uint64_t>(context.allocator_layout->pointer_table_pc) +
      static_cast<uint64_t>(room_id) * 3u;
  if (cow_pointer_slot + 3u > std::numeric_limits<uint32_t>::max()) {
    return absl::OutOfRangeError("Selected COW pointer range overflows");
  }
  ranges.emplace_back(static_cast<uint32_t>(cow_pointer_slot),
                      static_cast<uint32_t>(cow_pointer_slot + 3u));
 
  const uint64_t door_pointer_slot =
      static_cast<uint64_t>(zelda3::kDoorPointers) +
      static_cast<uint64_t>(room_id) * 3u;
  if (door_pointer_slot + 3u > std::numeric_limits<uint32_t>::max()) {
    return absl::OutOfRangeError("Selected door pointer range overflows");
  }
  ranges.emplace_back(static_cast<uint32_t>(door_pointer_slot),
                      static_cast<uint32_t>(door_pointer_slot + 3u));
 
  return ValidateManifestWriteRanges(context.manifest, ranges);
}
 
absl::StatusOr<std::vector<std::pair<uint32_t, uint32_t>>>
CollectRoomHeaderWriteRanges(const Rom& rom, int room_id) {
  uint32_t header_pointer_snes = 0;
  ASSIGN_OR_RETURN(header_pointer_snes,
                   rom.ReadLong(zelda3::kRoomHeaderPointer));
  const uint32_t header_pointer_pc = SnesToPc(header_pointer_snes);
  const uint64_t table_offset = static_cast<uint64_t>(header_pointer_pc) +
                                static_cast<uint64_t>(room_id) * 2u;
  if (table_offset + 2u > rom.size()) {
    return absl::OutOfRangeError(
        "Selected room header pointer slot is outside the ROM");
  }
 
  uint16_t header_offset = 0;
  ASSIGN_OR_RETURN(header_offset, rom.ReadWord(static_cast<int>(table_offset)));
  uint8_t header_bank = 0;
  ASSIGN_OR_RETURN(header_bank, rom.ReadByte(zelda3::kRoomHeaderPointerBank));
  const uint32_t header_pc =
      SnesToPc((static_cast<uint32_t>(header_bank) << 16) | header_offset);
  if (static_cast<uint64_t>(header_pc) + 14u > rom.size()) {
    return absl::OutOfRangeError("Selected room header is outside the ROM");
  }
 
  const uint64_t message_pc =
      static_cast<uint64_t>(zelda3::kMessagesIdDungeon) +
      static_cast<uint64_t>(room_id) * 2u;
  if (message_pc + 2u > rom.size()) {
    return absl::OutOfRangeError("Selected room message ID is outside the ROM");
  }
 
  return std::vector<std::pair<uint32_t, uint32_t>>{
      {header_pc, header_pc + 14u},
      {static_cast<uint32_t>(message_pc),
       static_cast<uint32_t>(message_pc + 2u)}};
}
 
absl::Status ValidateRoomHeaderManifestConflicts(
    const Rom& rom, int room_id, const core::HackManifest& manifest) {
  std::vector<std::pair<uint32_t, uint32_t>> ranges;
  ASSIGN_OR_RETURN(ranges, CollectRoomHeaderWriteRanges(rom, room_id));
  return ValidateManifestWriteRanges(manifest, ranges);
}
 
// Merge stop tiles from |existing| into |generated| without overwriting
// track tiles that were just produced. Stop tiles in |existing| that sit on
// cells that are zero in |generated| are copied across unchanged.
void MergeStopTiles(const zelda3::CustomCollisionMap& existing,
                    zelda3::CustomCollisionMap& generated) {
  for (int i = 0; i < static_cast<int>(existing.tiles.size()); ++i) {
    if (IsStopTile(existing.tiles[i]) && generated.tiles[i] == 0) {
      generated.tiles[i] = existing.tiles[i];
    }
  }
}
 
absl::Status SaveTrackCollisionRom(Rom* rom,
                                   const resources::ArgumentParser& parser,
                                   resources::OutputFormatter& formatter) {
  if (parser.HasFlag("mock-rom")) {
    formatter.AddField("save_status", "mock-rom-skipped");
    return absl::OkStatus();
  }
 
  Rom::SaveSettings save_settings;
  save_settings.require_backup = true;
  auto save_status = rom->SaveToFile(save_settings);
  if (!save_status.ok()) {
    formatter.AddField("save_error", std::string(save_status.message()));
    return save_status;
  }
 
  formatter.AddField("save_status", "saved");
  return absl::OkStatus();
}
 
// Helper to load sprite registry from file if --sprite-registry flag is provided
absl::Status MaybeLoadSpriteRegistry(const resources::ArgumentParser& parser) {
  auto registry_path = parser.GetString("sprite-registry");
  if (!registry_path.has_value()) {
    return absl::OkStatus();  // Flag not provided, nothing to load
  }
 
  std::ifstream file(registry_path.value());
  if (!file.is_open()) {
    return absl::NotFoundError(absl::StrFormat(
        "Could not open sprite registry: %s", registry_path.value()));
  }
 
  std::stringstream buffer;
  buffer << file.rdbuf();
  return zelda3::GetResourceLabels().ImportOracleSpriteRegistry(buffer.str());
}
 
}  // namespace
 
absl::Status WriteDungeonSpawnPointReport(Rom* rom, int spawn_id,
                                          resources::OutputFormatter& formatter,
                                          std::string_view object_title) {
  if (spawn_id < 0 || spawn_id >= zelda3::kNumDungeonSpawnPoints) {
    return absl::InvalidArgumentError(absl::StrFormat(
        "Dungeon spawn point ID %d out of range (0x00-0x06).", spawn_id));
  }
 
  auto spawn_or = zelda3::DungeonSpawnPoint::Load(*rom, spawn_id);
  if (!spawn_or.ok()) {
    return spawn_or.status();
  }
  const auto& spawn = spawn_or.value();
 
  if (!object_title.empty()) {
    formatter.BeginObject(std::string(object_title));
  }
 
  formatter.AddHexField("spawn_id", spawn_id, 2);
  formatter.AddField("is_spawn_point", true);
  formatter.AddHexField("room_id", spawn.room_id, 4);
  formatter.AddHexField("dungeon_id", spawn.dungeon_id, 2);
  formatter.AddHexField("quadrant", spawn.quadrant, 2);
  formatter.AddHexField("overworld_door_tilemap", spawn.overworld_door_tilemap,
                        4);
  formatter.AddHexField("entrance_id", spawn.entrance_id, 4);
 
  formatter.BeginObject("position");
  formatter.AddField("x", static_cast<int>(spawn.x_coordinate));
  formatter.AddField("y", static_cast<int>(spawn.y_coordinate));
  formatter.EndObject();
 
  formatter.BeginObject("camera");
  formatter.AddField("horizontal_scroll",
                     static_cast<int>(spawn.horizontal_scroll));
  formatter.AddField("vertical_scroll",
                     static_cast<int>(spawn.vertical_scroll));
  formatter.AddField("trigger_x", static_cast<int>(spawn.camera_trigger_x));
  formatter.AddField("trigger_y", static_cast<int>(spawn.camera_trigger_y));
  formatter.EndObject();
 
  formatter.BeginObject("properties");
  formatter.AddHexField("main_gfx", spawn.main_gfx, 2);
  formatter.AddHexField("floor", spawn.floor, 2);
  formatter.AddHexField("layer", spawn.layer, 2);
  formatter.AddHexField("camera_scroll_controller",
                        spawn.camera_scroll_controller, 2);
  formatter.AddHexField("song", spawn.song, 2);
  formatter.EndObject();
 
  formatter.BeginObject("camera_boundaries");
  formatter.AddHexField("qn", spawn.camera_scroll_boundaries[0], 2);
  formatter.AddHexField("fn", spawn.camera_scroll_boundaries[1], 2);
  formatter.AddHexField("qs", spawn.camera_scroll_boundaries[2], 2);
  formatter.AddHexField("fs", spawn.camera_scroll_boundaries[3], 2);
  formatter.AddHexField("qw", spawn.camera_scroll_boundaries[4], 2);
  formatter.AddHexField("fw", spawn.camera_scroll_boundaries[5], 2);
  formatter.AddHexField("qe", spawn.camera_scroll_boundaries[6], 2);
  formatter.AddHexField("fe", spawn.camera_scroll_boundaries[7], 2);
  formatter.EndObject();
 
  if (!object_title.empty()) {
    formatter.EndObject();
  }
  return absl::OkStatus();
}
 
absl::Status DungeonListSpritesCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  // Load custom sprite registry if provided (e.g., Oracle of Secrets)
  auto registry_status = MaybeLoadSpriteRegistry(parser);
  if (!registry_status.ok()) {
    return registry_status;
  }
 
  auto room_id_str = parser.GetString("room").value();
 
  int room_id;
  if (!ParseHexString(room_id_str, &room_id)) {
    return absl::InvalidArgumentError("Invalid room ID format. Must be hex.");
  }
 
  formatter.BeginObject("Dungeon Room Sprites");
  formatter.AddField("room_id", room_id);
 
  zelda3::Room room = zelda3::LoadRoomHeaderFromRom(rom, room_id);
  room.LoadSprites();
  const auto& sprites = room.GetSprites();
 
  formatter.AddField("total_sprites", static_cast<int>(sprites.size()));
  formatter.AddField("status", "success");
 
  formatter.BeginArray("sprites");
  for (const auto& sprite : sprites) {
    formatter.BeginObject();
    formatter.AddHexField("sprite_id", sprite.id(), 2);
    util::AddSpriteNameFields(formatter, sprite.id());
    formatter.AddField("x", sprite.x());
    formatter.AddField("y", sprite.y());
    formatter.AddField("subtype", sprite.subtype());
    formatter.AddField("layer", sprite.layer());
    if (sprite.key_drop() > 0) {
      formatter.AddField("key_drop", sprite.key_drop());
    }
    formatter.EndObject();
  }
  formatter.EndArray();
  formatter.EndObject();
 
  return absl::OkStatus();
}
 
absl::Status DungeonDescribeRoomCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  // Load custom sprite registry if provided (e.g., Oracle of Secrets)
  auto registry_status = MaybeLoadSpriteRegistry(parser);
  if (!registry_status.ok()) {
    return registry_status;
  }
 
  auto room_id_str = parser.GetString("room").value();
 
  int room_id;
  if (!ParseHexString(room_id_str, &room_id)) {
    return absl::InvalidArgumentError("Invalid room ID format. Must be hex.");
  }
 
  formatter.AddField("room_id", room_id);
 
  // Load full room to get objects, doors, and stairs
  zelda3::Room room = zelda3::LoadRoomFromRom(rom, room_id);
  const bool include_objects = parser.HasFlag("include-objects");
  const auto& tile_objects = room.GetTileObjects();
 
  formatter.AddField("status", "success");
  formatter.AddField("name", absl::StrFormat("Room %d", room.id()));
  formatter.AddField("room_name", zelda3::GetRoomLabel(room.id()));
  formatter.AddField("room_id", room.id());
  formatter.AddField("room_type", "Dungeon Room");
 
  // Room properties from Room data
  formatter.BeginObject("properties");
  formatter.AddField("blockset", room.blockset());
  formatter.AddField("spriteset", room.spriteset());
  formatter.AddField("palette", room.palette());
  formatter.AddField("layout", room.layout_id());
  formatter.AddField("floor1", room.floor1());
  formatter.AddField("floor2", room.floor2());
  formatter.AddField("effect", static_cast<int>(room.effect()));
  formatter.AddField("tag1", static_cast<int>(room.tag1()));
  formatter.AddField("tag2", static_cast<int>(room.tag2()));
 
  // Check object counts for simple heuristics
  const int object_count = include_objects
                               ? static_cast<int>(std::count_if(
                                     tile_objects.begin(), tile_objects.end(),
                                     IsEncodedRoomStreamObject))
                               : static_cast<int>(tile_objects.size());
  formatter.AddField("object_count", object_count);
 
  formatter.EndObject();
 
  if (include_objects) {
    formatter.BeginArray("objects");
    int stream_index = 0;
    for (const auto& object : tile_objects) {
      if (!IsEncodedRoomStreamObject(object)) {
        continue;
      }
 
      const auto encoded = object.EncodeObjectToBytes();
      formatter.BeginObject();
      formatter.AddHexField("object_id", static_cast<uint16_t>(object.id_), 3);
      formatter.AddField("entity_kind", "room_object");
      formatter.AddField("name", zelda3::GetObjectName(object.id_));
      formatter.AddField("name_source", "vanilla_object_catalog");
      formatter.AddField("coordinate_space", "room_tile8");
      formatter.AddField("subtype", zelda3::RoomObject::DetermineObjectType(
                                        encoded.b1, encoded.b3));
      formatter.AddField("x", static_cast<int>(object.x()));
      formatter.AddField("y", static_cast<int>(object.y()));
      formatter.AddField("size", static_cast<int>(object.size()));
      formatter.AddField("stream_index", stream_index++);
      formatter.EndObject();
    }
    formatter.EndArray();
  }
 
  // Export Sprites (project names when --project-context renames the slot)
  room.LoadSprites();
  formatter.BeginArray("sprites");
  for (const auto& sprite : room.GetSprites()) {
    formatter.BeginObject();
    formatter.AddHexField("sprite_id", sprite.id(), 2);
    util::AddSpriteNameFields(formatter, sprite.id());
    formatter.AddField("x", sprite.x());
    formatter.AddField("y", sprite.y());
    formatter.AddField("subtype", sprite.subtype());
    formatter.AddField("layer", sprite.layer());
    formatter.EndObject();
  }
  formatter.EndArray();
 
  // Export Doors
  formatter.BeginArray("doors");
  const auto& doors = room.GetDoors();
  for (size_t index = 0; index < doors.size(); ++index) {
    const auto& door = doors[index];
    formatter.BeginObject();
    formatter.AddField("index", static_cast<int>(index));
    formatter.AddField("entity_kind", "door");
    formatter.AddField("position", door.position);
    formatter.AddField("direction", std::string(door.GetDirectionName()));
    formatter.AddField("type", std::string(door.GetTypeName()));
    formatter.AddHexField("type_id", static_cast<uint8_t>(door.type), 2);
    auto [tx, ty] = door.GetTileCoords();
    formatter.AddField("tile_x", tx);
    formatter.AddField("tile_y", ty);
    const auto [px, py, width, height] = door.GetBounds();
    formatter.BeginObject("bounds_px");
    formatter.AddField("x", px);
    formatter.AddField("y", py);
    formatter.AddField("width", width);
    formatter.AddField("height", height);
    formatter.AddField("coordinate_space", "room_pixels");
    formatter.EndObject();
    formatter.EndObject();
  }
  formatter.EndArray();
 
  // Export Staircases
  formatter.BeginArray("staircases");
  for (const auto& stair : room.GetStairs()) {
    formatter.BeginObject();
    formatter.AddField("tile_x",
                       stair.id);  // 'id' field stores X in struct staircase
    formatter.AddField(
        "tile_y", stair.room);  // 'room' field stores Y in struct staircase
    formatter.AddField("label", stair.label);
    formatter.EndObject();
  }
  formatter.EndArray();
 
  if (parser.HasFlag("include-staircase-resolution")) {
    zelda3::RoomLayout layout(rom);
    const auto layout_status = layout.LoadLayout(room.layout_id());
    auto input = zelda3::MakeRoomCollisionInput(room);
    const auto& prefix = layout.GetObjects();
    input.objects.insert(input.objects.begin(), prefix.begin(), prefix.end());
    const auto resolutions = zelda3::ResolveVanillaStaircaseSlots(*rom, input);
    formatter.BeginObject("staircase_resolution");
    formatter.AddField("model", "vanilla_collision_preview");
    formatter.AddField("runtime_qualified", false);
    formatter.AddField("layout_loaded", layout_status.ok());
    formatter.AddField("custom_collision", room.has_custom_collision());
    formatter.BeginArray("objects");
    for (const auto& resolution : resolutions) {
      if (resolution.object_index < prefix.size())
        continue;
      const auto index = resolution.object_index - prefix.size();
      const auto& object = tile_objects[index];
      formatter.BeginObject();
      formatter.AddField("object_index", static_cast<int>(index));
      formatter.AddHexField("object_id", object.id_, 3);
      formatter.AddField("x", object.x());
      formatter.AddField("y", object.y());
      formatter.AddField("stream_index", object.GetLayerValue());
      const char* status = "trigger_unavailable";
      switch (resolution.status) {
        case zelda3::StaircaseSlotStatus::kResolved:
          status = "resolved";
          break;
        case zelda3::StaircaseSlotStatus::kTriggerUnavailable:
          break;
        case zelda3::StaircaseSlotStatus::kOverlappingStairs:
          status = "overlapping_stairs";
          break;
        case zelda3::StaircaseSlotStatus::kOutsideRoom:
          status = "outside_room";
          break;
        case zelda3::StaircaseSlotStatus::kTooManyStairs:
          status = "too_many_stairs";
          break;
      }
      formatter.AddField("vanilla_status", status);
      if (resolution.slot && layout_status.ok()) {
        formatter.AddField("vanilla_slot", *resolution.slot);
        formatter.AddHexField("vanilla_destination_room",
                              room.staircase_destination_room(*resolution.slot),
                              3);
        formatter.AddField("vanilla_arrival_plane",
                           room.staircase_plane(*resolution.slot));
      }
      if (!layout_status.ok())
        status = "layout_unavailable";
      if (room.has_custom_collision())
        status = "custom_collision";
      formatter.AddField("status", status);
      if (resolution.slot && layout_status.ok() &&
          !room.has_custom_collision()) {
        formatter.AddField("slot", *resolution.slot);
        formatter.AddHexField("destination_room",
                              room.staircase_destination_room(*resolution.slot),
                              3);
        formatter.AddField("arrival_plane",
                           room.staircase_plane(*resolution.slot));
      }
      formatter.EndObject();
    }
    formatter.EndArray();
    formatter.EndObject();
  }
 
  // Export Chests
  formatter.BeginArray("chests");
  for (const auto& chest : room.GetChests()) {
    formatter.BeginObject();
    formatter.AddHexField("item_id", chest.id, 2);
    formatter.AddField("item_name", zelda3::GetItemReceiptLabel(chest.id));
    formatter.AddField("item_name_source",
                       zelda3::GetItemReceiptLabelSource(chest.id));
    formatter.AddField("is_big_chest", chest.size);
    formatter.EndObject();
  }
  formatter.EndArray();
 
  return absl::OkStatus();
}
 
absl::Status DungeonListChestsCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  auto room_id_opt = parser.GetString("room");
 
  bool has_room_filter = room_id_opt.has_value();
  int room_filter = -1;
  if (has_room_filter) {
    if (!ParseHexString(room_id_opt.value(), &room_filter)) {
      return absl::InvalidArgumentError("Invalid room ID format. Must be hex.");
    }
  }
 
  int total_rooms = 0;
  int rooms_with_chests = 0;
  int total_chests = 0;
  std::map<int, int> item_counts;
 
  formatter.BeginObject("Dungeon Chests");
  formatter.AddField("room_filter", has_room_filter
                                        ? absl::StrFormat("0x%02X", room_filter)
                                        : "all");
 
  formatter.BeginArray("rooms");
  int start_room = has_room_filter ? room_filter : 0;
  int end_room = has_room_filter ? room_filter : zelda3::kNumberOfRooms - 1;
 
  for (int room_id = start_room; room_id <= end_room; ++room_id) {
    total_rooms++;
    zelda3::Room room = zelda3::LoadRoomHeaderFromRom(rom, room_id);
    room.LoadChests();
 
    const auto& chests = room.GetChests();
    if (chests.empty()) {
      continue;
    }
 
    rooms_with_chests++;
    total_chests += static_cast<int>(chests.size());
 
    formatter.BeginObject();
    formatter.AddField("room_id", absl::StrFormat("0x%02X", room_id));
    formatter.AddField("room_name", zelda3::GetRoomLabel(room_id));
    formatter.AddField("chest_count", static_cast<int>(chests.size()));
 
    formatter.BeginArray("chests");
    int chest_index = 0;
    for (const auto& chest : chests) {
      formatter.BeginObject();
      formatter.AddField("index", chest_index++);
      formatter.AddHexField("item_id", chest.id, 2);
      formatter.AddField("item_name", zelda3::GetItemReceiptLabel(chest.id));
      formatter.AddField("item_name_source",
                         zelda3::GetItemReceiptLabelSource(chest.id));
      formatter.AddField("is_big_chest", chest.size);
      formatter.EndObject();
 
      item_counts[chest.id]++;
    }
    formatter.EndArray();
    formatter.EndObject();
  }
  formatter.EndArray();
 
  formatter.BeginObject("summary");
  formatter.AddField("total_rooms", total_rooms);
  formatter.AddField("rooms_with_chests", rooms_with_chests);
  formatter.AddField("total_chests", total_chests);
  formatter.AddField("unique_items", static_cast<int>(item_counts.size()));
 
  formatter.BeginArray("duplicate_items");
  for (const auto& [item_id, count] : item_counts) {
    if (count < 2) {
      continue;
    }
    formatter.BeginObject();
    formatter.AddHexField("item_id", item_id, 2);
    formatter.AddField("item_name", zelda3::GetItemReceiptLabel(item_id));
    formatter.AddField("item_name_source",
                       zelda3::GetItemReceiptLabelSource(item_id));
    formatter.AddField("count", count);
    formatter.EndObject();
  }
  formatter.EndArray();
  formatter.EndObject();
 
  formatter.EndObject();
  return absl::OkStatus();
}
 
absl::Status DungeonGetEntranceCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  auto entrance_id_str = parser.GetString("entrance").value();
  bool is_spawn_point = parser.HasFlag("spawn");
 
  int entrance_id;
  if (!ParseHexString(entrance_id_str, &entrance_id)) {
    return absl::InvalidArgumentError(
        "Invalid entrance ID format. Must be hex.");
  }
 
  if (is_spawn_point) {
    return WriteDungeonSpawnPointReport(rom, entrance_id, formatter, "");
  }
 
  if (entrance_id < 0 || entrance_id >= zelda3::kNumRegularDungeonEntrances) {
    return absl::OutOfRangeError("Regular dungeon entrance ID is out of range");
  }
  zelda3::RoomEntrance entrance(rom, static_cast<uint8_t>(entrance_id), false);
  RETURN_IF_ERROR(entrance.load_status());
 
  formatter.AddField("entrance_id", absl::StrFormat("0x%02X", entrance_id));
  formatter.AddField("is_spawn_point", is_spawn_point);
  formatter.AddField("room_id", absl::StrFormat("0x%04X", entrance.room_));
  formatter.AddField("exit_id", absl::StrFormat("0x%04X", entrance.exit_));
 
  formatter.BeginObject("position");
  formatter.AddField("x", entrance.x_position_);
  formatter.AddField("y", entrance.y_position_);
  formatter.EndObject();
 
  formatter.BeginObject("camera");
  formatter.AddField("x", entrance.camera_x_);
  formatter.AddField("y", entrance.camera_y_);
  formatter.AddField("trigger_x", entrance.camera_trigger_x_);
  formatter.AddField("trigger_y", entrance.camera_trigger_y_);
  formatter.EndObject();
 
  formatter.BeginObject("properties");
  formatter.AddField("blockset", absl::StrFormat("0x%02X", entrance.blockset_));
  formatter.AddField("floor", absl::StrFormat("0x%02X", entrance.floor_));
  formatter.AddField("dungeon_id",
                     absl::StrFormat("0x%02X", entrance.dungeon_id_));
  formatter.AddField("door", absl::StrFormat("0x%02X", entrance.door_));
  formatter.AddField("ladder_bg",
                     absl::StrFormat("0x%02X", entrance.ladder_bg_));
  formatter.AddField("scrolling",
                     absl::StrFormat("0x%02X", entrance.scrolling_));
  formatter.AddField("scroll_quadrant",
                     absl::StrFormat("0x%02X", entrance.scroll_quadrant_));
  formatter.AddField("music", absl::StrFormat("0x%02X", entrance.music_));
  formatter.EndObject();
 
  formatter.BeginObject("camera_boundaries");
  formatter.AddField("qn",
                     absl::StrFormat("0x%02X", entrance.camera_boundary_qn_));
  formatter.AddField("fn",
                     absl::StrFormat("0x%02X", entrance.camera_boundary_fn_));
  formatter.AddField("qs",
                     absl::StrFormat("0x%02X", entrance.camera_boundary_qs_));
  formatter.AddField("fs",
                     absl::StrFormat("0x%02X", entrance.camera_boundary_fs_));
  formatter.AddField("qw",
                     absl::StrFormat("0x%02X", entrance.camera_boundary_qw_));
  formatter.AddField("fw",
                     absl::StrFormat("0x%02X", entrance.camera_boundary_fw_));
  formatter.AddField("qe",
                     absl::StrFormat("0x%02X", entrance.camera_boundary_qe_));
  formatter.AddField("fe",
                     absl::StrFormat("0x%02X", entrance.camera_boundary_fe_));
  formatter.EndObject();
 
  return absl::OkStatus();
}
 
absl::Status DungeonExportRoomCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  auto room_id_str = parser.GetString("room").value();
 
  int room_id;
  if (!ParseHexString(room_id_str, &room_id)) {
    return absl::InvalidArgumentError("Invalid room ID format. Must be hex.");
  }
 
  formatter.BeginObject("Dungeon Export");
  formatter.AddField("room_id", room_id);
 
  // Use existing dungeon system
  zelda3::DungeonEditorSystem dungeon_editor(rom);
  auto room_or = dungeon_editor.GetRoom(room_id);
  if (!room_or.ok()) {
    formatter.AddField("status", "error");
    formatter.AddField("error", room_or.status().ToString());
    formatter.EndObject();
    return room_or.status();
  }
 
  auto& room = room_or.value();
 
  // Export room data
  formatter.AddField("status", "success");
  formatter.AddField("room_width", "Unknown");
  formatter.AddField("room_height", "Unknown");
  formatter.AddField("room_name", absl::StrFormat("Room %d", room.id()));
 
  // Add room data as JSON
  formatter.BeginObject("room_data");
  formatter.AddField("tiles", "Room tile data would be exported here");
  formatter.AddField("sprites", "Room sprite data would be exported here");
  formatter.AddField("doors", "Room door data would be exported here");
  formatter.EndObject();
 
  formatter.EndObject();
 
  return absl::OkStatus();
}
 
absl::Status DungeonListObjectsCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  auto room_id_str = parser.GetString("room").value();
 
  int room_id;
  if (!ParseHexString(room_id_str, &room_id)) {
    return absl::InvalidArgumentError("Invalid room ID format. Must be hex.");
  }
 
  formatter.BeginObject("Dungeon Room Objects");
  formatter.AddField("room_id", room_id);
 
  // Use existing dungeon system
  zelda3::DungeonEditorSystem dungeon_editor(rom);
  auto room_or = dungeon_editor.GetRoom(room_id);
  if (!room_or.ok()) {
    formatter.AddField("status", "error");
    formatter.AddField("error", room_or.status().ToString());
    formatter.EndObject();
    return room_or.status();
  }
 
  auto& room = room_or.value();
 
  // Load objects if not already loaded (GetTileObjects might be empty otherwise)
  room.LoadObjects();
 
  const auto& objects = room.GetTileObjects();
  formatter.AddField("total_objects", static_cast<int>(objects.size()));
  formatter.AddField("status", "success");
 
  formatter.BeginArray("objects");
  for (const auto& obj : objects) {
    formatter.BeginObject("");
    formatter.AddField("id", obj.id_);
    formatter.AddField("id_hex", absl::StrFormat("0x%04X", obj.id_));
    formatter.AddField("x", obj.x_);
    formatter.AddField("y", obj.y_);
    formatter.AddField("size", obj.size_);
    formatter.AddField("layer", static_cast<int>(obj.layer_));
    // Add decoded type info if available
    int type = zelda3::RoomObject::DetermineObjectType((obj.id_ & 0xFF),
                                                       (obj.id_ >> 8));
    formatter.AddField("type", type);
    formatter.EndObject();
  }
  formatter.EndArray();
  formatter.EndObject();
 
  return absl::OkStatus();
}
 
absl::Status DungeonGetRoomTilesCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  auto room_id_str = parser.GetString("room").value();
 
  int room_id;
  if (!ParseHexString(room_id_str, &room_id)) {
    return absl::InvalidArgumentError("Invalid room ID format. Must be hex.");
  }
 
  formatter.BeginObject("Dungeon Room Tiles");
  formatter.AddField("room_id", room_id);
 
  // Use existing dungeon system
  zelda3::DungeonEditorSystem dungeon_editor(rom);
  auto room_or = dungeon_editor.GetRoom(room_id);
  if (!room_or.ok()) {
    formatter.AddField("status", "error");
    formatter.AddField("error", room_or.status().ToString());
    formatter.EndObject();
    return room_or.status();
  }
 
  auto& room = room_or.value();
 
  room.LoadObjects();
 
  formatter.AddField("room_width", 64);
  formatter.AddField("room_height", 64);
  formatter.AddField("total_tiles", 64 * 64);
  formatter.AddField("has_custom_collision", room.has_custom_collision());
  formatter.AddField("object_count",
                     static_cast<int>(room.GetTileObjects().size()));
  formatter.AddField("status", "success");
 
  // Emit tile rows as compact hex strings to keep output manageable while still
  // returning deterministic room-tile data.
  formatter.BeginArray("collision_rows");
  const auto& collision = room.custom_collision().tiles;
  for (int y = 0; y < 64; ++y) {
    std::string row;
    row.reserve(64 * 3);
    for (int x = 0; x < 64; ++x) {
      if (!row.empty()) {
        row.push_back(' ');
      }
      absl::StrAppend(&row, absl::StrFormat("%02X", collision[y * 64 + x]));
    }
    formatter.AddArrayItem(row);
  }
  formatter.EndArray();
  formatter.EndObject();
 
  return absl::OkStatus();
}
 
absl::Status DungeonSetRoomPropertyCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  auto room_id_str = parser.GetString("room").value();
  auto property = parser.GetString("property").value();
  auto value = parser.GetString("value").value();
 
  int room_id;
  if (!ParseHexString(room_id_str, &room_id)) {
    return absl::InvalidArgumentError("Invalid room ID format. Must be hex.");
  }
 
  formatter.BeginObject("Dungeon Room Property Set");
  formatter.AddField("room_id", room_id);
  formatter.AddField("property", property);
  formatter.AddField("value", value);
 
  if (room_id < 0 || room_id >= zelda3::kNumberOfRooms) {
    const absl::Status room_status =
        absl::InvalidArgumentError("Invalid room ID");
    formatter.AddField("status", "error");
    formatter.AddField("error", room_status.ToString());
    formatter.EndObject();
    return room_status;
  }
 
  int parsed_value = 0;
  if (!ParseHexString(value, &parsed_value)) {
    const absl::Status value_status =
        absl::InvalidArgumentError(absl::StrFormat(
            "Invalid value format: %s (expected integer/hex)", value));
    formatter.AddField("status", "error");
    formatter.AddField("error", std::string(value_status.message()));
    formatter.EndObject();
    return value_status;
  }
 
  const std::string prop = absl::AsciiStrToLower(property);
  const bool is_layout = prop == "layout" || prop == "layout_id";
  const bool is_floor = prop == "floor1" || prop == "floor2";
  const bool is_object_stream_header = is_layout || is_floor;
  const bool is_room_header = prop == "palette" || prop == "blockset" ||
                              prop == "spriteset" || prop == "effect" ||
                              prop == "tag1" || prop == "tag2" ||
                              prop == "holewarp";
  const int property_max = is_layout ? 0x07 : (is_floor ? 0x0F : 0xFF);
  if (is_object_stream_header &&
      (parsed_value < 0 || parsed_value > property_max)) {
    const absl::Status property_status =
        absl::InvalidArgumentError(absl::StrFormat(
            "Property %s must be in range 0..%d", property, property_max));
    formatter.AddField("status", "error");
    formatter.AddField("error", std::string(property_status.message()));
    formatter.EndObject();
    return property_status;
  }
 
  std::optional<RoomPropertyManifestContext> manifest_context;
  if (is_object_stream_header || is_room_header) {
    auto context_or =
        LoadRoomPropertyManifestContext(parser, is_object_stream_header);
    if (!context_or.ok()) {
      formatter.AddField("status", "error");
      formatter.AddField("error", std::string(context_or.status().message()));
      formatter.EndObject();
      return context_or.status();
    }
    manifest_context = std::move(context_or).value();
    if (manifest_context.has_value()) {
      const absl::Status manifest_status =
          is_object_stream_header
              ? ValidateObjectStreamHeaderManifestConflicts(*rom, room_id,
                                                            *manifest_context)
              : ValidateRoomHeaderManifestConflicts(*rom, room_id,
                                                    manifest_context->manifest);
      if (!manifest_status.ok()) {
        formatter.AddField("status", "error");
        formatter.AddField("error", std::string(manifest_status.message()));
        formatter.EndObject();
        return manifest_status;
      }
      formatter.AddField("manifest", *parser.GetString("manifest"));
      if (is_object_stream_header) {
        formatter.AddField("allocator_capability", "copy_on_write");
      }
    }
  }
 
  zelda3::Room room = zelda3::LoadRoomFromRom(rom, room_id);
  ScopedRomTransaction transaction(*rom);
  if (prop == "palette") {
    room.SetPalette(static_cast<uint8_t>(parsed_value & 0xFF));
  } else if (prop == "blockset") {
    room.SetBlockset(static_cast<uint8_t>(parsed_value & 0xFF));
  } else if (prop == "spriteset") {
    room.SetSpriteset(static_cast<uint8_t>(parsed_value & 0xFF));
  } else if (is_layout) {
    room.SetLayoutId(static_cast<uint8_t>(parsed_value));
  } else if (prop == "floor1") {
    room.set_floor1(static_cast<uint8_t>(parsed_value));
  } else if (prop == "floor2") {
    room.set_floor2(static_cast<uint8_t>(parsed_value));
  } else if (prop == "effect") {
    room.SetEffect(static_cast<zelda3::EffectKey>(parsed_value & 0xFF));
  } else if (prop == "tag1") {
    room.SetTag1(static_cast<zelda3::TagKey>(parsed_value & 0xFF));
  } else if (prop == "tag2") {
    room.SetTag2(static_cast<zelda3::TagKey>(parsed_value & 0xFF));
  } else if (prop == "holewarp") {
    room.SetHolewarp(static_cast<uint8_t>(parsed_value & 0xFF));
  } else {
    const absl::Status property_status = absl::InvalidArgumentError(
        absl::StrFormat("Unsupported property: %s", property));
    formatter.AddField("status", "error");
    formatter.AddField("error", std::string(property_status.message()));
    formatter.EndObject();
    return property_status;
  }
 
  const absl::Status write_status =
      is_object_stream_header
          ? room.SaveObjectStreamHeader(
                manifest_context.has_value() &&
                        manifest_context->allocator_layout.has_value()
                    ? &*manifest_context->allocator_layout
                    : nullptr)
          : room.SaveRoomHeader();
  if (!write_status.ok()) {
    formatter.AddField("status", "error");
    formatter.AddField("write_error", std::string(write_status.message()));
    formatter.EndObject();
    return write_status;
  }
 
  if (parser.HasFlag("mock-rom")) {
    transaction.Commit();
    formatter.AddField("save_status", "mock-rom-skipped");
  } else {
    Rom::SaveSettings save_settings;
    save_settings.require_backup = true;
    const absl::Status save_status = rom->SaveToFile(save_settings);
    if (!save_status.ok()) {
      formatter.AddField("status", "error");
      formatter.AddField("save_error", std::string(save_status.message()));
      formatter.EndObject();
      return save_status;
    }
    transaction.Commit();
    formatter.AddField("save_status", "saved");
  }
  formatter.AddField("status", "success");
  formatter.EndObject();
 
  return absl::OkStatus();
}
 
absl::Status DungeonRoomHeaderCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  auto room_id_str = parser.GetString("room").value();
 
  int room_id;
  if (!ParseHexString(room_id_str, &room_id)) {
    return absl::InvalidArgumentError("Invalid room ID format. Must be hex.");
  }
 
  formatter.BeginObject("Room Header Debug");
  formatter.AddField("room_id", room_id);
  formatter.AddHexField("room_id_hex", room_id, 2);
 
  // Show ROM address constants
  formatter.BeginObject("rom_addresses");
  formatter.AddHexField("kRoomHeaderPointer", zelda3::kRoomHeaderPointer, 4);
  formatter.AddHexField("kRoomHeaderPointerBank",
                        zelda3::kRoomHeaderPointerBank, 4);
  formatter.EndObject();
 
  // Read the pointer table address
  int header_pointer = (rom->data()[zelda3::kRoomHeaderPointer + 2] << 16) +
                       (rom->data()[zelda3::kRoomHeaderPointer + 1] << 8) +
                       (rom->data()[zelda3::kRoomHeaderPointer]);
  int header_pointer_pc = SnesToPc(header_pointer);
 
  formatter.BeginObject("pointer_table");
  formatter.AddHexField("snes_address", header_pointer, 6);
  formatter.AddHexField("pc_address", header_pointer_pc, 6);
  formatter.EndObject();
 
  // Read the room's specific header address from the table
  int table_offset = header_pointer_pc + (room_id * 2);
  int room_header_addr = (rom->data()[zelda3::kRoomHeaderPointerBank] << 16) +
                         (rom->data()[table_offset + 1] << 8) +
                         rom->data()[table_offset];
  int room_header_pc = SnesToPc(room_header_addr);
 
  formatter.BeginObject("room_header_address");
  formatter.AddHexField("table_offset_pc", table_offset, 6);
  formatter.AddHexField("snes_address", room_header_addr, 6);
  formatter.AddHexField("pc_address", room_header_pc, 6);
  formatter.EndObject();
 
  // Read and display raw header bytes (14 bytes)
  formatter.BeginArray("raw_bytes");
  for (int i = 0; i < 14; ++i) {
    if (room_header_pc + i < static_cast<int>(rom->size())) {
      formatter.AddArrayItem(
          absl::StrFormat("0x%02X", rom->data()[room_header_pc + i]));
    }
  }
  formatter.EndArray();
 
  // Decode the header bytes
  if (room_header_pc >= 0 &&
      room_header_pc + 13 < static_cast<int>(rom->size())) {
    uint8_t byte0 = rom->data()[room_header_pc];
    uint8_t byte1 = rom->data()[room_header_pc + 1];
    uint8_t byte2 = rom->data()[room_header_pc + 2];
    uint8_t byte3 = rom->data()[room_header_pc + 3];
 
    formatter.BeginObject("decoded");
    formatter.AddField("bg2", (byte0 >> 5) & 0x07);
    formatter.AddField("collision", (byte0 >> 2) & 0x07);
    formatter.AddField("is_light", (byte0 & 0x01) == 1);
    // This is the full 8-bit palette-set ID. Values 0x40-0x47 are valid;
    // masking to six bits silently aliases them to the wrong palette set.
    formatter.AddField("palette", byte1);
    formatter.AddField("blockset", byte2);
    formatter.AddField("spriteset", byte3);
    formatter.AddField("effect", rom->data()[room_header_pc + 4]);
    formatter.AddField("tag1", rom->data()[room_header_pc + 5]);
    formatter.AddField("tag2", rom->data()[room_header_pc + 6]);
    formatter.AddField("holewarp", rom->data()[room_header_pc + 9]);
    formatter.AddField("stair1_room", rom->data()[room_header_pc + 10]);
    formatter.AddField("stair2_room", rom->data()[room_header_pc + 11]);
    formatter.AddField("stair3_room", rom->data()[room_header_pc + 12]);
    formatter.AddField("stair4_room", rom->data()[room_header_pc + 13]);
    // The fields above are raw header bytes. The game keeps the current
    // room's high byte ($A1), so report the room each byte leads to.
    formatter.AddHexField("holewarp_destination_room",
                          zelda3::ResolveHeaderDestinationRoom(
                              room_id, rom->data()[room_header_pc + 9]),
                          3);
    for (int slot = 0; slot < 4; ++slot) {
      formatter.AddHexField(
          absl::StrFormat("stair%d_destination_room", slot + 1),
          zelda3::ResolveHeaderDestinationRoom(
              room_id, rom->data()[room_header_pc + 10 + slot]),
          3);
    }
    formatter.EndObject();
  } else {
    formatter.AddField("error", "Room header address out of range");
  }
 
  formatter.EndObject();
  return absl::OkStatus();
}
 
absl::Status DungeonGenerateTrackCollisionCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  // Build generator options (shared by single and batch modes)
  zelda3::GeneratorOptions options;
 
  // Parse --promote-switch X,Y pairs
  auto switch_str = parser.GetString("promote-switch");
  if (switch_str.has_value()) {
    for (absl::string_view pair :
         absl::StrSplit(switch_str.value(), ' ', absl::SkipEmpty())) {
      std::vector<std::string> coords =
          absl::StrSplit(pair, ',', absl::SkipEmpty());
      if (coords.size() == 2) {
        int sx, sy;
        if (ParseHexString(coords[0], &sx) && ParseHexString(coords[1], &sy)) {
          options.switch_promotions.emplace_back(sx, sy);
        }
      }
    }
  }
 
  bool do_write = parser.HasFlag("write");
  bool do_preserve_stops = parser.HasFlag("preserve-stops");
  bool do_visualize = parser.HasFlag("visualize");
 
  // Determine room list: --rooms (batch) or --room (single)
  std::vector<int> room_ids;
  auto rooms_arg = parser.GetString("rooms");
  auto room_arg = parser.GetString("room");
 
  if (rooms_arg.has_value()) {
    // Batch mode: parse comma-separated hex room IDs
    for (absl::string_view token :
         absl::StrSplit(rooms_arg.value(), ',', absl::SkipEmpty())) {
      int rid;
      std::string token_str(token);
      if (!ParseHexString(token_str, &rid)) {
        return absl::InvalidArgumentError(absl::StrFormat(
            "Invalid room ID '%s' in --rooms list. Must be hex.", token_str));
      }
      room_ids.push_back(rid);
    }
    if (room_ids.empty()) {
      return absl::InvalidArgumentError("--rooms list is empty.");
    }
  } else if (room_arg.has_value()) {
    // Single room mode (backwards compatible)
    int rid;
    if (!ParseHexString(room_arg.value(), &rid)) {
      return absl::InvalidArgumentError("Invalid room ID format. Must be hex.");
    }
    room_ids.push_back(rid);
  } else {
    return absl::InvalidArgumentError("Either --room or --rooms is required.");
  }
 
  bool is_batch = room_ids.size() > 1;
  std::unique_ptr<ScopedRomTransaction> transaction;
  if (do_write) {
    transaction = std::make_unique<ScopedRomTransaction>(*rom);
  }
 
  if (is_batch) {
    // Batch mode: aggregate results with per-room detail
    formatter.BeginObject("Batch Track Collision Generation");
    formatter.AddField("mode", do_write ? "write" : "dry-run");
    formatter.AddField("room_count", static_cast<int>(room_ids.size()));
 
    int total_tiles = 0;
    int total_stops = 0;
    int total_corners = 0;
    int total_switches = 0;
    int rooms_succeeded = 0;
 
    formatter.BeginArray("rooms");
    for (int room_id : room_ids) {
      zelda3::Room room = zelda3::LoadRoomHeaderFromRom(rom, room_id);
      room.LoadObjects();
 
      auto result = zelda3::GenerateTrackCollision(&room, options);
      if (!result.ok()) {
        // Stop on first error and report which room failed
        formatter.EndArray();
        formatter.AddHexField("failed_room", room_id, 3);
        formatter.AddField("error", std::string(result.status().message()));
        formatter.EndObject();
        return absl::InternalError(
            absl::StrFormat("Generation failed for room 0x%03X: %s", room_id,
                            result.status().message()));
      }
 
      if (do_preserve_stops && do_write) {
        auto existing = zelda3::LoadCustomCollisionMap(rom, room_id);
        if (existing.ok() && existing->has_data) {
          MergeStopTiles(*existing, result->collision_map);
        }
      }
 
      formatter.BeginObject();
      formatter.AddHexField("room_id", room_id, 3);
      formatter.AddField("tiles_generated", result->tiles_generated);
      formatter.AddField("stop_count", result->stop_count);
      formatter.AddField("corner_count", result->corner_count);
      formatter.AddField("switch_count", result->switch_count);
      if (do_preserve_stops) {
        formatter.AddField("stops_preserved", true);
      }
 
      if (do_visualize) {
        formatter.AddField("visualization", result->ascii_visualization);
      }
 
      if (do_write) {
        auto write_status =
            zelda3::WriteTrackCollision(rom, room_id, result->collision_map);
        if (!write_status.ok()) {
          // Stop on first write error
          formatter.AddField("write_error",
                             std::string(write_status.message()));
          formatter.EndObject();
          formatter.EndArray();
          formatter.EndObject();
          return absl::Status(
              write_status.code(),
              absl::StrFormat("Write failed for room 0x%03X: %s", room_id,
                              write_status.message()));
        }
        formatter.AddField("write_status", "success");
      }
 
      total_tiles += result->tiles_generated;
      total_stops += result->stop_count;
      total_corners += result->corner_count;
      total_switches += result->switch_count;
      rooms_succeeded++;
 
      formatter.EndObject();
    }
    formatter.EndArray();
 
    // Save ROM once after all rooms are written
    if (do_write) {
      auto save_status = SaveTrackCollisionRom(rom, parser, formatter);
      if (!save_status.ok()) {
        formatter.EndObject();
        return save_status;
      }
      transaction->Commit();
    }
 
    // Aggregated totals
    formatter.BeginObject("totals");
    formatter.AddField("rooms_succeeded", rooms_succeeded);
    formatter.AddField("tiles_generated", total_tiles);
    formatter.AddField("stop_count", total_stops);
    formatter.AddField("corner_count", total_corners);
    formatter.AddField("switch_count", total_switches);
    formatter.EndObject();
 
    formatter.EndObject();
  } else {
    // Single room mode (original behavior, backwards compatible)
    int room_id = room_ids[0];
 
    zelda3::Room room = zelda3::LoadRoomHeaderFromRom(rom, room_id);
    room.LoadObjects();
 
    auto result = zelda3::GenerateTrackCollision(&room, options);
    if (!result.ok()) {
      return result.status();
    }
 
    if (do_preserve_stops && do_write) {
      auto existing = zelda3::LoadCustomCollisionMap(rom, room_id);
      if (existing.ok() && existing->has_data) {
        MergeStopTiles(*existing, result->collision_map);
      }
    }
 
    formatter.BeginObject("Track Collision Generation");
    formatter.AddHexField("room_id", room_id, 3);
    formatter.AddField("tiles_generated", result->tiles_generated);
    formatter.AddField("stop_count", result->stop_count);
    formatter.AddField("corner_count", result->corner_count);
    formatter.AddField("switch_count", result->switch_count);
    formatter.AddField("mode", do_write ? "write" : "dry-run");
    if (do_preserve_stops) {
      formatter.AddField("stops_preserved", true);
    }
 
    if (do_visualize || !do_write) {
      formatter.AddField("visualization", result->ascii_visualization);
    }
 
    if (do_write) {
      auto write_status =
          zelda3::WriteTrackCollision(rom, room_id, result->collision_map);
      if (!write_status.ok()) {
        formatter.AddField("write_error", std::string(write_status.message()));
        formatter.EndObject();
        return write_status;
      } else {
        formatter.AddField("write_status", "success");
        auto save_status = SaveTrackCollisionRom(rom, parser, formatter);
        if (!save_status.ok()) {
          formatter.EndObject();
          return save_status;
        }
        transaction->Commit();
      }
    }
 
    formatter.EndObject();
  }
 
  return absl::OkStatus();
}
 
}  // namespace handlers
}  // namespace cli
}  // namespace yaze