Fighting Game · Guides & deep dives

Mod Compatibility

same semantic range parser used for dependency checks.

4sections1 minread
Markdown source
On this page

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