object_tile_editor.h

Go to the documentation of this file.

#ifndef YAZE_ZELDA3_DUNGEON_OBJECT_TILE_EDITOR_H_
#define YAZE_ZELDA3_DUNGEON_OBJECT_TILE_EDITOR_H_
 
#include <cstddef>
#include <cstdint>
#include <filesystem>
#include <optional>
#include <string>
#include <utility>
#include <vector>
 
#include "absl/status/status.h"
#include "absl/status/statusor.h"
#include "app/gfx/core/bitmap.h"
#include "app/gfx/types/snes_palette.h"
#include "app/gfx/types/snes_tile.h"
#include "rom/rom.h"
#include "zelda3/dungeon/object_drawer.h"
#include "zelda3/dungeon/object_parser.h"
#include "zelda3/dungeon/room.h"
 
namespace yaze {
namespace zelda3 {
 
struct ObjectTileSourceSpan {
  uint32_t pc_address = 0;
  std::vector<uint16_t> expected_words;
};
 
struct ObjectTileSourceProvenance {
  int16_t object_id = -1;
  uint32_t descriptor_pc_address = 0;
  uint16_t expected_descriptor_word = 0;
  std::vector<ObjectTileSourceSpan> spans;
};
 
struct ObjectTileSourceRef {
  size_t span_index = 0;
  size_t word_index = 0;
};
 
struct ObjectTileSourceImpactEntry {
  int16_t object_id = -1;
  std::vector<ObjectTileReadRange> overlapping_ranges;
};
 
enum class ObjectTileRuntimeConsumer {
  // Synthesized room object 0x150 reads the unlit/lit torch blocks directly
  // during initial room drawing; it is not representable in the persisted
  // dungeon object stream.
  kLightableTorchDraw,
  // Underworld light/extinguish updates read the same literal blocks again
  // when replacing the torch tiles at runtime.
  kTorchLightingChange,
};
 
struct ObjectTileRuntimeConsumerImpactEntry {
  ObjectTileRuntimeConsumer consumer;
  std::vector<ObjectTileReadRange> overlapping_ranges;
};
 
struct ObjectTileSourceImpact {
  std::vector<ObjectTileSourceImpactEntry> affected_objects;
  std::vector<ObjectTileRuntimeConsumerImpactEntry> runtime_consumers;
 
  size_t consumer_count() const {
    return affected_objects.size() + runtime_consumers.size();
  }
};
 
struct ObjectTileLayout {
  int16_t object_id = 0;
  int origin_tile_x = 0;
  int origin_tile_y = 0;
 
  struct Cell {
    int rel_x = 0;            // 0-based tile X within bounding box
    int rel_y = 0;            // 0-based tile Y within bounding box
    gfx::TileInfo tile_info;  // Decomposed SNES tilemap word
    uint16_t original_word = 0;
    // Legacy name retained for preview/test compatibility. This is draw-trace
    // order only and never authorizes a ROM write; draw order is not generally
    // source order.
    int write_index = -1;
    std::optional<ObjectTileSourceRef> source_ref;
    bool modified = false;
  };
 
  std::vector<Cell> cells;
  int bounds_width = 0;   // Bounding box width in 8px tiles
  int bounds_height = 0;  // Bounding box height in 8px tiles
 
  // Legacy display/shared-data metadata. Standard writes are authorized only
  // by source_provenance + per-cell source_ref, never by this base address.
  int tile_data_address = -1;
  std::optional<ObjectTileSourceProvenance> source_provenance;
  bool is_custom = false;
  int custom_subtype = -1;
  std::string custom_filename;
  std::filesystem::path custom_resolved_path;
  std::vector<uint8_t> custom_source_bytes;
 
  static ObjectTileLayout FromTraces(
      const std::vector<ObjectDrawer::TileTrace>& traces);
 
  Cell* FindCell(int rel_x, int rel_y);
  const Cell* FindCell(int rel_x, int rel_y) const;
 
  bool HasModifications() const;
  void RevertAll();
};
 
class ObjectTileWritePlan {
 public:
  struct Write {
    int address = -1;
    uint16_t expected_word = 0;
    uint16_t word = 0;
  };
 
  struct WordPrecondition {
    int address = -1;
    uint16_t expected_word = 0;
  };
 
  ObjectTileWritePlan(const ObjectTileWritePlan&) = default;
  ObjectTileWritePlan(ObjectTileWritePlan&&) noexcept = default;
  ObjectTileWritePlan& operator=(const ObjectTileWritePlan&) = default;
  ObjectTileWritePlan& operator=(ObjectTileWritePlan&&) noexcept = default;
 
  const std::vector<Write>& writes() const { return writes_; }
  const std::vector<WordPrecondition>& preconditions() const {
    return preconditions_;
  }
  const std::vector<std::pair<uint32_t, uint32_t>>& write_ranges() const {
    return write_ranges_;
  }
 
 private:
  friend class ObjectTileEditor;
 
  ObjectTileWritePlan() = default;
 
  std::vector<Write> writes_;
  // Includes the pointer descriptor and every captured source word. Apply
  // rechecks these immediately before opening the transaction.
  std::vector<WordPrecondition> preconditions_;
  std::vector<std::pair<uint32_t, uint32_t>> write_ranges_;
};
 
class ObjectTileEditor {
 public:
  static constexpr int kAtlasTilesPerRow = 16;
  static constexpr int kAtlasTileRows = 64;
  static constexpr int kAtlasTileCount = kAtlasTilesPerRow * kAtlasTileRows;
  static constexpr int kAtlasWidthPx = kAtlasTilesPerRow * 8;
  static constexpr int kAtlasHeightPx = kAtlasTileRows * 8;
 
  explicit ObjectTileEditor(Rom* rom);
 
  // Capture: run object draw in trace_only mode, build editable layout
  absl::StatusOr<ObjectTileLayout> CaptureObjectLayout(
      int16_t object_id, const Room& room, const gfx::PaletteGroup& palette);
  absl::StatusOr<ObjectTileLayout> CaptureObjectLayout(
      int16_t object_id, const Room& room, const gfx::PaletteGroup& palette,
      uint8_t object_size);
 
  // Capture a standard object with exact ROM source provenance. The initial
  // fail-closed allowlist is intentionally limited to the two audited fixed
  // 2x2 subtype-2 objects (0x11F and 0x120).
  absl::StatusOr<ObjectTileLayout> CaptureEditableObjectLayout(
      int16_t object_id, const Room& room, const gfx::PaletteGroup& palette);
 
  // Load one existing fixed runtime custom-object asset directly from its
  // binary source, including no-op words and exact bytes for stale-write CAS.
  absl::StatusOr<ObjectTileLayout> LoadCustomObjectLayout(int16_t object_id,
                                                          int subtype);
 
  static bool IsEditableStandardObject(int16_t object_id);
 
  // Render: draw layout to preview bitmap using room's gfx buffer
  absl::Status RenderLayoutToBitmap(const ObjectTileLayout& layout,
                                    gfx::Bitmap& bitmap,
                                    const uint8_t* room_gfx_buffer,
                                    const gfx::PaletteGroup& palette);
 
  // Build a source-ID atlas from room graphics. Custom objects show the
  // runtime-effective tile at each raw source ID without changing saved words.
  // Retained H/V/priority attributes affect zero-word detection only; atlas
  // images remain unflipped so their orientation is consistent when browsing.
  absl::Status BuildTile8Atlas(
      gfx::Bitmap& atlas, const uint8_t* room_gfx_buffer,
      const gfx::PaletteGroup& palette, int display_palette = 2,
      std::optional<int16_t> custom_object_id = std::nullopt,
      uint16_t retained_attributes = 0);
 
  // Write-back: standard objects patch ROM, custom objects write .bin
  absl::Status WriteBack(ObjectTileLayout& layout);
 
  // Resolve and validate all standard-object writes before any ROM mutation.
  absl::StatusOr<ObjectTileWritePlan> BuildStandardWritePlan(
      const ObjectTileLayout& layout) const;
 
  // Atomically apply a previously validated standard-object write plan.
  absl::Status ApplyStandardWritePlan(const ObjectTileWritePlan& plan);
 
  // Enumerate every representable standard object whose parser-visible source
  // ranges overlap this editable layout, plus the explicit runtime consumers
  // modeled by this backend. Resolution errors are returned to the caller and
  // must block writes rather than being interpreted as no sharing. Other
  // runtime-only behavior remains a separate parity-audit concern.
  absl::StatusOr<ObjectTileSourceImpact> AnalyzeStandardTileSourceImpact(
      const ObjectTileLayout& layout) const;
 
 private:
  Rom* rom_;
};
 
}  // namespace zelda3
}  // namespace yaze
 
#endif  // YAZE_ZELDA3_DUNGEON_OBJECT_TILE_EDITOR_H_