Fighting Game · Guides & deep dives

Mod API Surface

The v1 API surface exposes only these capabilities:

4sections1 minread
Markdown source
On this page

This document covers TODOS.phase-72.72.14.1.4: the curated engine API exposed to .mayamod packages.

Runtime Surface#

  • module: V2Modding
  • policy: FV2ModApiPolicy
  • catalog entry: FV2ModApiCapabilityDescriptor
  • request/result: FV2ModApiRequest and FV2ModApiResult
  • helper functions: BuildDefaultModApiPolicy, BuildDefaultModApiCatalog, BuildSpawnCosmeticActorRequest, BuildModifyCosmeticComponentRequest, BuildRegisterEventListenerRequest, BuildCreateUIScreenRequest, EvaluateModApiRequest, and ExecuteModApiRequest
  • automation: V2/ue/Source/V2Tests/Private/Modding/ModLoadingSystem.spec.cpp
  • contract: V2/ue/Content/V2/Modding/ModApiSurface_V2_Contract.json

Capabilities#

The v1 API surface exposes only these capabilities:

  • ReadPublicGameState
  • SpawnCosmeticActor
  • ModifyCosmeticComponent
  • RegisterEventListener
  • CreateUIScreen
  • ReadModStorage
  • WriteModStorage

World mutation is cosmetic-only. Entity spawning is limited to approved cosmetic actor templates, and component mutation is limited to approved cosmetic components on mod-owned targets. Event listeners must live under Mod., Gameplay.Public., or UI.Public. namespaces. UI creation must target HUD.ModOverlay, Menu.ModPanel, or Settings.ModPanel roots so mods cannot replace core HUD, ranked, commerce, or account surfaces.

Policy Enforcement#

Every API request is evaluated against FV2ModApiPolicy and an approved FV2ModSandboxDecision. The default policy requires sandbox approval, denies networked API calls, denies ranked-unsafe API calls, enforces cosmetic-only world mutation, and caps accepted calls at 64 requests per tick.

Rejected requests return explicit issue types for capability denial, missing sandbox approval, missing targets, ranked-unsafe requests, event namespace denial, UI surface denial, non-cosmetic world mutation, and network denial.

Verification#

bash
python3 V2/ue/Tools/check-v2-mod-api-surface.py
python3 V2/ue/Tools/check-v2-mod-sandboxing.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-api-surface.py V2/ue/Tools/check-v2-mod-sandboxing.py V2/ue/Tools/check-v2-mod-loading-system.py V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Content/V2/Modding/ModApiSurface_V2_Contract.json