overworld_version_helper.h

Go to the documentation of this file.

#ifndef YAZE_ZELDA3_OVERWORLD_VERSION_HELPER_H
#define YAZE_ZELDA3_OVERWORLD_VERSION_HELPER_H
 
#include <cstdint>
 
#include "rom/rom.h"
#include "zelda3/common.h"
 
namespace yaze::zelda3 {
 
// =============================================================================
// ZSCustomOverworld Version System
// =============================================================================
//
// OVERVIEW:
// ---------
// ZSCustomOverworld is an ASM patch system that extends the overworld
// capabilities of A Link to the Past ROMs. This header provides centralized
// version detection to enable feature gating throughout the editor.
//
// VERSION HISTORY:
// ----------------
// - Vanilla (0xFF/0x00): Original game, no patches applied
// - v1: Basic expanded pointers for map data overflow
// - v2: Custom BG colors per area, main palette selection
// - v3: Area enum system, wide/tall areas, mosaic, animated GFX, overlays
//
// ROM MARKER LOCATION:
// --------------------
// The version byte is stored at OverworldCustomASMHasBeenApplied (0x140145):
//   - 0xFF or 0x00: Vanilla ROM (no ZScream ASM applied)
//   - 0x01: ZSCustomOverworld v1
//   - 0x02: ZSCustomOverworld v2
//   - 0x03+: ZSCustomOverworld v3
//
// FEATURE TESTING:
// ----------------
// To test a specific version's features:
//   1. Load a ROM with that version applied
//   2. Use GetVersion() to confirm detection works
//   3. Check feature flags with SupportsXXX() methods
//   4. Enable/edit the feature in the editor
//   5. Save and verify in an emulator
//
// UPGRADE WORKFLOW:
// -----------------
// In OverworldEditor::ApplyZSCustomOverworldASM(int target_version):
//   1. Validate current ROM version (can only upgrade, not downgrade)
//   2. Load appropriate ASM file (yaze.asm for v3, ZSCustomOverworld.asm for v2)
//   3. Apply patch via AsarWrapper
//   4. Update version markers via UpdateROMVersionMarkers()
//   5. Enable feature flags in ROM
//   6. Reload overworld data to reflect changes
//
// See overworld/README.md for complete documentation.
// =============================================================================
 
enum class AreaSizeEnum {
  SmallArea = 0,
  LargeArea = 1,
  WideArea = 2,
  TallArea = 3,
};
 
enum class OverworldVersion {
  kVanilla = 0,     
  kZSCustomV1 = 1,  
  kZSCustomV2 = 2,  
  kZSCustomV3 = 3   
};
 
class OverworldVersionHelper {
 public:
  // ===========================================================================
  // Version Detection
  // ===========================================================================
  
  static OverworldVersion GetVersion(const Rom& rom) {
    if (rom.size() <= OverworldCustomASMHasBeenApplied) {
      return OverworldVersion::kVanilla;
    }
    uint8_t asm_version = rom.data()[OverworldCustomASMHasBeenApplied];
 
    // 0xFF = vanilla ROM (no ZScream ASM applied)
    if (asm_version == 0xFF || asm_version == 0x00) {
      return OverworldVersion::kVanilla;
    }
 
    if (asm_version == 1) {
      return OverworldVersion::kZSCustomV1;
    }
    if (asm_version == 2) {
      return OverworldVersion::kZSCustomV2;
    }
    if (asm_version >= 3) {
      return OverworldVersion::kZSCustomV3;
    }
 
    // Fallback for unknown values
    return OverworldVersion::kVanilla;
  }
 
  static uint8_t GetAsmVersion(const Rom& rom) {
    return rom.data()[OverworldCustomASMHasBeenApplied];
  }
  
  // ===========================================================================
  // Feature Checks
  // ===========================================================================
 
  static bool SupportsAreaEnum(OverworldVersion version) {
    return version == OverworldVersion::kZSCustomV3;
  }
 
  static bool SupportsExpandedSpace(OverworldVersion version) {
    return version != OverworldVersion::kVanilla;
  }
 
  static bool SupportsCustomBGColors(OverworldVersion version) {
    return version == OverworldVersion::kZSCustomV2 ||
           version == OverworldVersion::kZSCustomV3;
  }
 
  static bool SupportsCustomTileGFX(OverworldVersion version) {
    return version == OverworldVersion::kZSCustomV3;
  }
 
  static bool SupportsAnimatedGFX(OverworldVersion version) {
    return version == OverworldVersion::kZSCustomV3;
  }
 
  static bool SupportsSubscreenOverlay(OverworldVersion version) {
    return version == OverworldVersion::kZSCustomV3;
  }
 
  // ===========================================================================
  // Utility Methods
  // ===========================================================================
 
  static const char* GetVersionName(OverworldVersion version) {
    switch (version) {
      case OverworldVersion::kVanilla:
        return "Vanilla";
      case OverworldVersion::kZSCustomV1:
        return "ZSCustomOverworld v1";
      case OverworldVersion::kZSCustomV2:
        return "ZSCustomOverworld v2";
      case OverworldVersion::kZSCustomV3:
        return "ZSCustomOverworld v3";
      default:
        return "Unknown";
    }
  }
};
 
}  // namespace yaze::zelda3
 
#endif  // YAZE_ZELDA3_OVERWORLD_VERSION_HELPER_H