# Mod Compatibility

This document covers `TODOS.phase-72.72.14.1.10`: game-version compatibility
checks, mismatch warnings, and migration helpers for `.mayamod` packages.

## Runtime Surface

- module: `V2Modding`
- policy: `FV2ModCompatibilityPolicy`
- migration step: `FV2ModMigrationStep`
- issue: `FV2ModCompatibilityIssue`
- result: `FV2ModCompatibilityResult`
- helper functions: `BuildDefaultModCompatibilityPolicy`,
  `BuildModMigrationStep`, `EvaluateModGameVersionCompatibility`, and
  `ApplyModCompatibilityMigration`
- subsystem forwarding:
  `UV2ModLoadingSubsystem::EvaluateGameVersionCompatibility`
- automation: `V2/ue/Source/V2Tests/Private/Modding/ModLoadingSystem.spec.cpp`
- contract: `V2/ue/Content/V2/Modding/ModCompatibility_V2_Contract.json`

## Compatibility Evaluation

`EvaluateModGameVersionCompatibility` compares the current game version from
`FV2ModCompatibilityPolicy` against the manifest `GameVersionRange` using the
same semantic range parser used for dependency checks. Manifests in range are
compatible and loadable.

When the current game version falls outside the manifest range, the default
policy emits a warning and keeps the mod loadable. Stricter builds can set
`bBlockIncompatibleMods` to make mismatched mods fail the compatibility gate.
Invalid current game versions always block because the compatibility result
cannot be trusted.

## Migration Helpers

`BuildModMigrationStep` declares an explicit helper from one manifest
`GameVersionRange` to a target game version. Matching helpers are returned on
the compatibility result and set `bMigrationAvailable`.

`ApplyModCompatibilityMigration` marks a result as migrated when migration steps
are available, sets the mod compatible/loadable, and clears the migration
warning from blocking consideration. Migration helpers are intentionally
explicit so teams can review release notes, rebuild assets, recompile scripts,
or review breaking changes before treating an old mod as updated.

## Verification

```bash
python3 V2/ue/Tools/check-v2-mod-compatibility.py
python3 V2/ue/Tools/check-v2-mod-loading-system.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 V2/tools/validate-v2-docs.py
python3 -m py_compile V2/ue/Tools/check-v2-mod-compatibility.py V2/ue/Tools/check-v2-mod-hot-reload.py V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Content/V2/Modding/ModCompatibility_V2_Contract.json
```