Fighting Game · Guides & deep dives

.mayamod File Format

A .mayamod file is a deterministic ZIP archive.

5sections2 minread
Markdown source
On this page

This document covers TODOS.phase-72.72.14.1.1: the canonical .mayamod package format for V2 modding.

Package Shape#

A .mayamod file is a deterministic ZIP archive. The archive root contains manifest.json, assets/, scripts/, and preview/. Optional folders are docs/, licenses/, localization/, and signatures/.

Paths are UTF-8, use /, are case-sensitive, and must not contain absolute paths, parent-directory traversal, Windows drive prefixes, symlinks, or device files. The default package limit is 512 MiB.

Manifest#

The manifest schema lives at V2/ue/Content/V2/Modding/MayamodManifest_v1.schema.json. The contract lives at V2/ue/Content/V2/Modding/ModFileFormat_V2_Contract.json.

Every manifest declares:

  • format version, mod id, display name, semantic version, author, license, and description
  • category and user-facing metadata
  • version requirements for game, engine, mod API, package format, platforms, required DLC, and incompatible mods
  • optional dependencies with mod id, version range, and required/optional flag
  • asset entries with id, type, package path, SHA-256, byte size, and mount point for textures, meshes, levels, audio, and other supported engine assets
  • script entries with id, runtime, entrypoint, SHA-256, permissions, memory limit, and timeout
  • permission policy and package integrity hashes

Assets And Scripts#

Asset paths must live under assets/, localization/, or preview/. Level assets use Level entries under assets/ so the mod asset loader can mount them into the engine asset registry for match-load or on-demand use. Script entrypoints must live under scripts/ and use either Lua5.4 or WASI0.2. Script permissions are default-deny and must be enumerated per script.

The v1 permission set is intentionally narrow: reading public game state, registering event listeners, modifying cosmetic components, spawning cosmetic actors, creating UI screens, and reading or writing mod-scoped storage.

Versioning And Safety#

Version ranges use npm-style semver syntax. Public publishing requires the Themis Originality Shields gate, and mounted mods disable ranked eligibility by default. Filesystem access is mod-package read-only, network access is denied by default, native code is not allowed, and every package declares SHA-256 hashes.

The PC policy remains cosmetic/offline by default. Future loader, sandbox, dependency, and distribution tasks consume this file format instead of changing the v1 contract in place.

Verification#

bash
python3 V2/ue/Tools/check-v2-mod-file-format.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-file-format.py V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Content/V2/Modding/ModFileFormat_V2_Contract.json
python3 -m json.tool V2/ue/Content/V2/Modding/MayamodManifest_v1.schema.json
python3 -m json.tool V2/ue/Content/V2/Modding/Examples/CosmeticRecolor.mayamod/manifest.json