# Mod Scripting Integration

This document covers `TODOS.phase-72.72.14.1.5`: Lua/WASI script runtime binding
for `.mayamod` packages, script access to the curated mod API, and development
hot reload.

## Runtime Surface

- module: `V2Modding`
- policy: `FV2ModScriptRuntimePolicy`
- script binding: `FV2ModScriptRuntimeBinding`
- invocation: `FV2ModScriptInvocation`
- hot reload request: `FV2ModScriptHotReloadRequest`
- result: `FV2ModScriptResult`
- helper functions: `BuildDefaultModScriptRuntimePolicy`,
  `BuildModScriptBindingFromManifest`, `BuildModScriptInvocation`,
  `EvaluateModScriptBinding`, `ExecuteModScriptInvocation`, and
  `EvaluateModScriptHotReload`
- automation: `V2/ue/Source/V2Tests/Private/Modding/ModLoadingSystem.spec.cpp`
- contract: `V2/ue/Content/V2/Modding/ModScriptingIntegration_V2_Contract.json`

## Supported Runtimes

Manifest script entries may use `Lua5.4` with `.lua` entrypoints or `WASI0.2`
with `.wasm` entrypoints. Entrypoints must remain under `scripts/`, script
integrity hashes must be present, and runtime resource limits must fit within
the default policy caps of 64 MiB and 100 ms.

## Mod API Access

`BuildModScriptBindingFromManifest` converts manifest script permissions into
granted `EV2ModApiCapability` entries. `ExecuteModScriptInvocation` only routes
script-requested API calls when the capability was granted by the script
manifest and is still allowed by the current `FV2ModApiPolicy`. Each accepted
script API call is evaluated through `ExecuteModApiRequest`, preserving sandbox,
network, ranked-safety, event namespace, UI-root, and cosmetic-only world
mutation checks.

## Hot Reload

Development hot reload is enabled by `FV2ModScriptRuntimePolicy` and requires a
hot-reloadable binding, a development session, a 64-character replacement script
hash, and a strictly increasing script revision. Optional replacement
entrypoints must still stay under `scripts/` and match the existing runtime
extension.

## Verification

```bash
python3 V2/ue/Tools/check-v2-mod-scripting-integration.py
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-scripting-integration.py 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/ModScriptingIntegration_V2_Contract.json
```