hack_manifest.h

Go to the documentation of this file.

#ifndef YAZE_CORE_HACK_MANIFEST_H
#define YAZE_CORE_HACK_MANIFEST_H
 
#include <array>
#include <cstdint>
#include <optional>
#include <string>
#include <unordered_map>
#include <utility>
#include <vector>
 
#include "absl/status/status.h"
#include "core/oracle_progression.h"
#include "core/story_event_graph.h"
 
namespace yaze::core {
 
// Private, exact-save producer transfer. Every PC range is half-open.
// This is deliberately one fixed source contract, not an allocator capability.
struct LyraPrivateReservation {
  struct Preimage {
    std::array<uint32_t, 2> pc{};
    std::string sha256;
    bool operator==(const Preimage&) const = default;
  };
  std::string source_rom_sha256;
  std::array<uint32_t, 2> tile32_id_range{};
  std::array<uint32_t, 2> stream_pc_range{};
  std::array<uint32_t, 4> dictionary_bases_pc{};
  std::array<Preimage, 4> packed_preimages{};
  Preimage stream_preimage;
  bool operator==(const LyraPrivateReservation&) const = default;
};
 
LyraPrivateReservation PrivateLyraExactSaveReservation();
 
enum class AddressOwnership : uint8_t {
  kVanillaSafe,   // Yaze can edit; asar doesn't touch
  kHookPatched,   // Asar patches this; yaze edits are overwritten on build
  kAsmOwned,      // Entire bank owned by ASM hack
  kShared,        // Both yaze and ASM write (e.g., ZSCustomOverworld)
  kAsmExpansion,  // ROM expansion bank — only exists in patched ROM
  kRam,           // WRAM definition (not ROM data)
  kMirror,        // HiROM mirror of vanilla bank
};
 
std::string AddressOwnershipToString(AddressOwnership ownership);
 
struct ProtectedRegion {
  uint32_t start;
  uint32_t end;
  int hook_count;
  std::string module;
};
 
struct OwnedBank {
  uint8_t bank;
  uint32_t bank_start;
  uint32_t bank_end;
  AddressOwnership ownership;
  std::string ownership_note;
};
 
struct RoomTagEntry {
  uint8_t tag_id;
  uint32_t address;
  std::string name;
  std::string purpose;
  std::string source;
  std::string feature_flag;  // Empty if always enabled
  bool enabled = true;
};
 
struct FeatureFlag {
  std::string name;
  int value;
  bool enabled;
  std::string source;
};
 
struct SramVariable {
  std::string name;
  uint32_t address;
  std::string purpose;
};
 
struct MessageLayout {
  struct Source {
    std::string format;
    int version = 0;
    std::string canonical_bundle_path;
    std::string generated_asm_include_path;
  };
 
  uint32_t hook_address;       // $0ED436
  uint32_t data_start;         // $2F8000
  uint32_t data_end;           // $2FFFFF
  uint16_t first_expanded_id;  // $18D
  uint16_t last_expanded_id;   // $1D1
  int expanded_count;
  int vanilla_count;  // 397
  std::optional<Source> source;
};
 
struct MinecartTrackLayout {
  struct Source {
    std::string format;
    int version = 0;
    std::string path;
 
    bool operator==(const Source&) const = default;
  };
 
  std::optional<Source> source;
};
 
struct BuildPipeline {
  std::string dev_rom;
  std::string patched_rom;
  std::string assembler;
  std::string entry_point;
  std::string build_script;
};
 
enum class DungeonStreamType : uint8_t {
  kObjects,
  kSprites,
  kPotItems,
};
 
enum class DungeonPointerEncoding : uint8_t {
  kLong24,
  kBank16,
};
 
enum class DungeonWriteStrategy : uint8_t {
  kCopyOnWrite,
  kRepackAll,
};
 
struct SnesAddressRange {
  uint32_t start = 0;
  uint32_t end = 0;
};
 
struct DungeonStreamLayout {
  uint32_t pointer_table = 0;
  uint32_t pointer_count = 0;
  DungeonPointerEncoding pointer_encoding = DungeonPointerEncoding::kLong24;
  std::optional<uint8_t> pointer_bank;
  DungeonWriteStrategy strategy = DungeonWriteStrategy::kCopyOnWrite;
  std::vector<SnesAddressRange> data_regions;
  std::vector<SnesAddressRange> allocation_regions;
};
 
struct GraphicsSheetLayout {
  std::vector<SnesAddressRange> allocation_regions;
  std::vector<uint16_t> reserved_sheets;
};
 
struct WriteConflict {
  uint32_t address;
  AddressOwnership ownership;
  std::string module;  // From protected region, if applicable
};
 
// ─── Project Registry (Dungeon + Overworld data) ─────────────────────────
 
struct DungeonRoom {
  int id;
  std::string name;
  std::string floor;  // "F1", "B1", etc. Optional project-map label.
  int grid_row, grid_col;
  bool has_grid_position = false;
  std::string type;  // "entrance", "boss", "mini_boss", "connector", "normal"
  int palette, blockset, spriteset;
  uint8_t tag1, tag2;
};
 
struct DungeonConnection {
  int from_room, to_room;
  std::string label;
  std::string direction;  // For doors: "north"/"south"/"east"/"west"
};
 
struct DungeonEntry {
  std::string id;            // "D4"
  std::string name;          // "Zora Temple"
  std::string vanilla_name;  // "Thieves' Town"
  std::vector<DungeonRoom> rooms;
  std::vector<DungeonConnection> stairs;
  std::vector<DungeonConnection> holewarps;
  std::vector<DungeonConnection> doors;
};
 
struct OverworldArea {
  int area_id;
  std::string name;
  std::string world;  // "LW", "DW", "SW"
  int grid_row, grid_col;
};
 
struct ProjectRegistry {
  std::vector<DungeonEntry> dungeons;
  std::vector<OverworldArea> overworld_areas;
  StoryEventGraph story_events;
 
  // Universal resource labels: type -> {id_str -> label}
  //
  // Notes:
  // - Keys are normalized to decimal strings for project::YazeProject::resource_labels.
  // - Input JSON may use either decimal ("57") or hex ("0x39") IDs.
  //
  // Types: "room", "sprite", "item", "entrance", "overworld_map", "music".
  // Oracle `dungeons.json` room names are mirrored into "room" labels so the
  // opened project file can serialize the current registry names.
  std::unordered_map<std::string, std::unordered_map<std::string, std::string>>
      all_resource_labels;
 
  // Backward-compat accessor for room labels only
  const std::unordered_map<std::string, std::string>& room_labels() const {
    static const std::unordered_map<std::string, std::string> empty;
    auto it = all_resource_labels.find("room");
    return it != all_resource_labels.end() ? it->second : empty;
  }
};
 
class HackManifest {
 public:
  HackManifest() = default;
 
  absl::Status LoadFromFile(const std::string& filepath);
 
  absl::Status LoadFromString(const std::string& json_content);
 
  [[nodiscard]] bool loaded() const { return loaded_; }
 
  void Clear() { Reset(); }
 
  // ─── Address Classification ───────────────────────────────
 
  [[nodiscard]] AddressOwnership ClassifyAddress(uint32_t address) const;
 
  [[nodiscard]] bool IsWriteOverwritten(uint32_t address) const;
 
  [[nodiscard]] bool IsProtected(uint32_t address) const;
 
  [[nodiscard]] bool IsEditorManaged(uint32_t address) const;
 
  [[nodiscard]] std::optional<AddressOwnership> GetBankOwnership(
      uint8_t bank) const;
 
  // ─── Room Tags ────────────────────────────────────────────
 
  [[nodiscard]] std::string GetRoomTagLabel(uint8_t tag_id) const;
 
  [[nodiscard]] std::optional<RoomTagEntry> GetRoomTag(uint8_t tag_id) const;
 
  [[nodiscard]] const std::vector<RoomTagEntry>& room_tags() const {
    return room_tags_;
  }
 
  // ─── Feature Flags ────────────────────────────────────────
 
  [[nodiscard]] bool IsFeatureEnabled(const std::string& flag_name) const;
 
  [[nodiscard]] const std::vector<FeatureFlag>& feature_flags() const {
    return feature_flags_;
  }
 
  // ─── SRAM ─────────────────────────────────────────────────
 
  [[nodiscard]] std::string GetSramVariableName(uint32_t address) const;
 
  [[nodiscard]] const std::vector<SramVariable>& sram_variables() const {
    return sram_variables_;
  }
 
  // ─── Messages ─────────────────────────────────────────────
 
  [[nodiscard]] const MessageLayout& message_layout() const {
    return message_layout_;
  }
 
  [[nodiscard]] bool IsExpandedMessage(uint16_t message_id) const;
 
  // ─── Minecart Tracks ──────────────────────────────────────
 
  [[nodiscard]] const MinecartTrackLayout& minecart_track_layout() const {
    return minecart_track_layout_;
  }
 
  // ─── Dungeon Stream Allocation Layouts ────────────────────────────
 
  [[nodiscard]] const DungeonStreamLayout* GetDungeonStreamLayout(
      DungeonStreamType stream) const;
 
  [[nodiscard]] bool HasDungeonStreamLayouts() const {
    return !dungeon_stream_layouts_.empty();
  }
 
  // ─── Graphics Sheet Layout ────────────────────────────────
 
  [[nodiscard]] const GraphicsSheetLayout& graphics_sheet_layout() const {
    return graphics_sheet_layout_;
  }
 
  // ─── Protected Regions ──────────────────────────────────
 
  [[nodiscard]] const std::vector<ProtectedRegion>& protected_regions() const {
    return protected_regions_;
  }
 
  [[nodiscard]] const std::vector<SnesAddressRange>& editor_managed_regions()
      const {
    return editor_managed_regions_;
  }
 
  [[nodiscard]] const std::unordered_map<uint8_t, OwnedBank>& owned_banks()
      const {
    return owned_banks_;
  }
 
  // ─── Write Conflict Analysis ─────────────────────────────
 
  [[nodiscard]] std::vector<WriteConflict> AnalyzeWriteRanges(
      const std::vector<std::pair<uint32_t, uint32_t>>& ranges) const;
 
  [[nodiscard]] std::vector<WriteConflict> AnalyzePcWriteRanges(
      const std::vector<std::pair<uint32_t, uint32_t>>& pc_ranges) const;
 
  // ─── Project Registry ────────────────────────────────────
 
  absl::Status LoadProjectRegistry(const std::string& code_folder);
 
  [[nodiscard]] const ProjectRegistry& project_registry() const {
    return project_registry_;
  }
 
  [[nodiscard]] bool HasProjectRegistry() const {
    return !project_registry_.dungeons.empty() ||
           !project_registry_.all_resource_labels.empty() ||
           project_registry_.story_events.loaded();
  }
 
  // ─── Oracle Progression (SRAM) ─────────────────────────────
 
  // Updates story event completion coloring based on progression state parsed
  // from an emulator SRAM file (.srm).
  void SetOracleProgressionState(const OracleProgressionState& state);
 
  // Clears any loaded progression state and resets story graph status to
  // default (no progress).
  void ClearOracleProgressionState();
 
  [[nodiscard]] std::optional<OracleProgressionState> oracle_progression_state()
      const {
    return oracle_progression_state_;
  }
 
  // ─── Build Pipeline ───────────────────────────────────────
 
  [[nodiscard]] const BuildPipeline& build_pipeline() const {
    return build_pipeline_;
  }
 
  // ─── Metadata ─────────────────────────────────────────────
 
  [[nodiscard]] const std::string& hack_name() const { return hack_name_; }
  [[nodiscard]] int manifest_version() const { return manifest_version_; }
  [[nodiscard]] int total_hooks() const { return total_hooks_; }
 
  const std::optional<LyraPrivateReservation>& lyra_private_reservation()
      const {
    return lyra_private_reservation_;
  }
 
 private:
  void Reset();
  [[nodiscard]] const ProtectedRegion* FindProtectedRegion(
      uint32_t address) const;
 
  std::optional<LyraPrivateReservation> lyra_private_reservation_;
  bool loaded_ = false;
  int manifest_version_ = 0;
  std::string hack_name_;
  int total_hooks_ = 0;
 
  // Protected regions (vanilla bank hooks) — sorted by start address
  std::vector<ProtectedRegion> protected_regions_;
 
  // Exact manifest-v3 regions that remain yaze-owned inside otherwise owned
  // banks. Sorted, disjoint, and stored as canonical LoROM addresses.
  std::vector<SnesAddressRange> editor_managed_regions_;
 
  // Bank ownership lookup
  std::unordered_map<uint8_t, OwnedBank> owned_banks_;
 
  // Room tag lookup by tag ID
  std::unordered_map<uint8_t, RoomTagEntry> room_tag_map_;
  std::vector<RoomTagEntry> room_tags_;
 
  // Feature flags by name
  std::unordered_map<std::string, FeatureFlag> feature_flag_map_;
  std::vector<FeatureFlag> feature_flags_;
 
  // SRAM variable lookup by address
  std::unordered_map<uint32_t, SramVariable> sram_map_;
  std::vector<SramVariable> sram_variables_;
 
  // Message layout
  MessageLayout message_layout_{};
 
  // Optional canonical source contract for the minecart track table.
  MinecartTrackLayout minecart_track_layout_{};
 
  // Explicit dungeon stream layouts, indexed by stream kind.
  std::unordered_map<DungeonStreamType, DungeonStreamLayout>
      dungeon_stream_layouts_;
 
  // Optional graphics-sheet free space and reserved sheets.
  GraphicsSheetLayout graphics_sheet_layout_{};
 
  // Build pipeline
  BuildPipeline build_pipeline_;
 
  // Project registry (loaded from code_folder JSON files)
  ProjectRegistry project_registry_;
 
  // Optional: live progression state derived from SRAM/.srm. This is used to
  // color story event nodes and can be updated at runtime by editor panels.
  std::optional<OracleProgressionState> oracle_progression_state_;
};
 
}  // namespace yaze::core
 
#endif  // YAZE_CORE_HACK_MANIFEST_H