# .mayamod File Format

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
```