# Generated Mod API Reference

Generated from `V2/ue/Content/V2/Modding/ModApiSurface_V2_Contract.json`
and `V2/ue/Source/V2Modding/Private/V2ModLoading.cpp`.

Do not edit this file by hand. Run:

```bash
python3 V2/ue/Tools/generate-v2-mod-api-docs.py
```

## Policy

- Sandbox approval required: `true`
- Networked API requests denied: `true`
- Ranked-unsafe requests denied: `true`
- Cosmetic-only world mutation: `true`
- Max requests per tick: `64`
- Allowed event prefixes: `Mod.`, `Gameplay.Public.`, `UI.Public.`
- Allowed UI roots: `HUD.ModOverlay`, `Menu.ModPanel`, `Settings.ModPanel`

## Capabilities

### `ReadPublicGameState`

- Enum: `EV2ModApiCapability::ReadPublicGameState`
- Description: Read public, non-authoritative game state.
- Cosmetic world mutation: `no`

### `SpawnCosmeticActor`

- Enum: `EV2ModApiCapability::SpawnCosmeticActor`
- Description: Spawn a cosmetic-only actor from an approved template.
- Cosmetic world mutation: `yes`

### `ModifyCosmeticComponent`

- Enum: `EV2ModApiCapability::ModifyCosmeticComponent`
- Description: Modify an approved cosmetic component on a mod-owned target.
- Cosmetic world mutation: `yes`

### `RegisterEventListener`

- Enum: `EV2ModApiCapability::RegisterEventListener`
- Description: Subscribe to public mod, gameplay, or UI events.
- Cosmetic world mutation: `no`

### `CreateUIScreen`

- Enum: `EV2ModApiCapability::CreateUIScreen`
- Description: Create a constrained UI surface under an approved mod UI root.
- Cosmetic world mutation: `no`

### `ReadModStorage`

- Enum: `EV2ModApiCapability::ReadModStorage`
- Description: Read mod-scoped storage through the sandbox.
- Cosmetic world mutation: `no`

### `WriteModStorage`

- Enum: `EV2ModApiCapability::WriteModStorage`
- Description: Write mod-scoped storage through the sandbox.
- Cosmetic world mutation: `no`

## Examples

### Read public match state

Capability: `ReadPublicGameState`

Reads non-authoritative state exposed to the mod sandbox.

```lua
local round_time = api.read_public_game_state('match.round_time')
```

### Spawn a cosmetic actor

Capability: `SpawnCosmeticActor`

Spawns only approved cosmetic templates and never gameplay actors.

```lua
api.spawn_cosmetic_actor('Prop.ConfettiBurst', { attach_to = 'player.local' })
```

### Modify a cosmetic component

Capability: `ModifyCosmeticComponent`

Mutates an approved cosmetic component on a mod-owned target.

```lua
api.modify_cosmetic_component('player.local', 'CapeTint', { color = '#50B4FF' })
```

### Listen for a public event

Capability: `RegisterEventListener`

Subscribes to public mod, gameplay, or UI event namespaces.

```lua
api.on('Gameplay.Public.RoundStart', function(event) api.log(event.round_id) end)
```

### Create a mod UI panel

Capability: `CreateUIScreen`

Creates UI only under approved mod-owned surface roots.

```lua
api.create_ui_screen('Menu.ModPanel.LoadoutPreview', { title = 'Preview' })
```

### Read mod-scoped storage

Capability: `ReadModStorage`

Reads files from the storage area assigned to this mod.

```lua
local settings = api.read_mod_storage('settings.json')
```

### Write mod-scoped storage

Capability: `WriteModStorage`

Writes only to sandboxed mod storage and respects the manifest quota.

```lua
api.write_mod_storage('settings.json', settings)
```

## Safety Notes

Generated examples assume the mod has sandbox approval and manifest
permissions for the requested capability. Gameplay-affecting world
mutation, private event namespaces, unapproved UI roots, and network
requests remain denied by the default policy.