# Mod Capabilities

> The 16 capabilities that gate the mod api object — which methods each unlocks, how one is detected, and what the table discloses to players.

- Source: https://diceytable.com/docs/mods/manifest/capabilities
- Last verified: 2026-10-11

A mod's `entry.script` runs with `exports.setup(api, manifest)` inside a sandboxed
iframe. The `api` object it receives is capability-gated: `manifest.capabilities.allowed`
is a list drawn from 16 fixed slugs, and every gated method throws unless its capability
is on that list. Declaring fewer capabilities than a mod's script uses fails validation.
Declaring more than it uses is only a warning ([below](https://diceytable.com/docs/mods/manifest/capabilities#declaring-a-capability-you-do-not-use--a-warning)).

If `capabilities` is omitted from the manifest entirely, it defaults to
`{ version: "1", allowed: ["log"] }` — a mod with no `capabilities` block can only call
`api.log()`.

## The capability → method matrix

| Capability | `api` methods it gates |
|---|---|
| `log` | `log(message)` |
| `spawn-object` | `createObject(object)` |
| `register-action` | `registerAction(action)` |
| `read-context` | `getMySeat()`, `getMyTeam()`, `getTurn()`, `listBots()` |
| `read-world` | `getSnapshot()`, `getObject(objectId)`, `listObjects(filter?)`, `getContainerContents(objectId)`, `getHandObjects(seat?)`, `getZoneObjects(seat, zoneId)` — **all six least-privileged**, on every peer including the host — and it is additionally *demanded* by an `onZoneEnter`/`onZoneLeave`/`onTriggerEnter`/`onTriggerLeave` subscription |
| `read-hidden-information` | `getUnredactedSnapshot()` — the elevated read, and the only route to real card faces, pile order and `secretMetadata`. Never implied by `read-world`, never granted by default. |
| `object-action` | `objectAction(objectId, action)` |
| `saved-data` | `getSavedData(scope?)`, `setSavedData(data, scope?)` |
| `subscribe-events` | `on(eventName, handler)` |
| `ui` | The basic widgets: `getUiState()`, `listUiElements()`, `setUiElement(element)`, `deleteUiElement(elementId)`. The [Game UI](https://diceytable.com/docs/scripting/concepts/game-ui): `uiShow(widget, overrides?)`, `uiUpdate(id, patch)`, `uiHide(ids)`, `uiSet(values, seat?, options?)`, `uiToast(text, options?)`, `uiLog(text, options?)`, `uiPrompt(seat, spec)` — and it is additionally *demanded* by an `onUiAction` subscription |
| `play-sound` | `playSound(params)`, `setObjectSound(objectId, action, ref)` |
| `plugin-call` | `listPlugins()`, `callPlugin(pluginId, functionName, params?)` — naming a **declared** function on an **installed** plugin your manifest also declares in `plugins`. **Not network access**; see below. |
| `read-cards` | `resolveCards(cardIds)` — your game's **own** shipped card catalogue. The table-script [`world.resolveCards(ids)`](https://diceytable.com/docs/scripting-api/world#worldresolvecards) is gated on it too: a scene script that calls it must declare it, and the host refuses the call without it. |
| `ai-inference` | `ai.evaluate(modelId, inputs, opts?)` — running one of **your own** declared [AI models](https://diceytable.com/docs/mods/manifest/reference#aimodels) on the host. **Not code execution and not network access**; see [`ai-inference`](https://diceytable.com/docs/mods/manifest/capabilities#ai-inference). |

| `read-decks` | `listDecks()`, `getDeck(deckId)` — the **player's own** saved decks. Not needed for a lobby deck pick: a [`lobbyRequirements`](https://diceytable.com/docs/mods/manifest/reference#lobbyrequirements) deck is chosen and dealt by the platform, with no script involved. |
| `host-message` | `sendToHost(message)` — the one outbound call a non-host peer's copy of your mod can make; the host's copy receives it as `onHostMessage`. |

See [the `api` reference](https://diceytable.com/docs/scripting-api/api) for full parameter and return details
on every method above.

### Table scripts need almost none of these

Capabilities gate the **mod script's** `api` object. A [table script](https://diceytable.com/docs/scripting/concepts/game-ui) — the
`world`, `ui`, `match`, `bots` and `ai` globals a game's scene scripts use — runs on the host's authority and
needs **no** capability for any of them, with one exception: `world.resolveCards` needs `read-cards`, because it
reads the same catalogue `api.resolveCards` does. A game whose rules live entirely in table scripts therefore
declares `log`, `read-cards` if it resolves cards, and `plugin-call` if it lists plugin functions (a lobby
[deck database](https://diceytable.com/docs/mods/manifest/reference#lobbyrequirements) counts) — and nothing else. Declaring `ui`,
`read-world` or `subscribe-events` for a table script's HUD, reads or events does nothing except warn every player
about a mod script that does not exist.

> **`plugin-call` is not a network grant, and describing it as one is wrong.** A mod names a
> function; the platform performs the request from its own servers, to an origin the *plugin*
> declared, under that plugin's quota and circuit breaker. A mod cannot express a destination or
> a payload the plugin did not declare a schema for, and every network pattern in the scanner
> still rejects the script at publish. It also requires a matching `plugins` declaration — see
> [Calling a plugin from a mod](https://diceytable.com/docs/plugins/calling-from-a-mod).

## How a declaration is checked

Almost every capability is detected by matching literal `api.<method>(` call syntax in the
entry script's source — a whole-word, unlexed regex, the same style as the scanner's
5 banned-pattern rules. There is no AST parse: matching happens against raw text. The exception is `read-cards`, which matches the bare
property read (see its row).

| Capability | Detector |
|---|---|
| `spawn-object` | `/\bapi\.createObject\s*\(/` |
| `register-action` | `/\bapi\.registerAction\s*\(/` |
| `read-context` | `/\bapi\.(getMySeat\|getMyTeam\|getTurn\|listBots)\s*\(/` |
| `read-world` | `/\bapi\.(getSnapshot\|getObject\|listObjects\|getContainerContents\|getHandObjects\|getZoneObjects)\s*\(/` |
| `read-world` (zone/trigger hook) | An `api.on("onZoneEnter" \| "onZoneLeave" \| "onTriggerEnter" \| "onTriggerLeave", …)` subscription demands `read-world` too, because those hooks are only delivered to a frame that was granted it. |
| `read-hidden-information` | `/\bapi\.getUnredactedSnapshot\s*\(/` |
| `object-action` | `/\bapi\.objectAction\s*\(/` |
| `saved-data` | `/\bapi\.(getSavedData\|setSavedData)\s*\(/` |
| `ui` | `/\bapi\.(getUiState\|listUiElements\|setUiElement\|deleteUiElement\|uiShow\|uiUpdate\|uiHide\|uiSet\|uiToast\|uiLog\|uiPrompt)\s*\(/` |
| `ui` (Game UI hook) | An `api.on("onUiAction", …)` subscription demands `ui` too, on top of `subscribe-events`, because that hook is only delivered to a frame that was granted it. |
| `subscribe-events` | `/\bapi\.on\s*\(/` |
| `play-sound` | `/\bapi\.(playSound\|setObjectSound)\s*\(/` |
| `plugin-call` | `/\bapi\.(listPlugins\|callPlugin)\s*\(/` — plus a second, finer pass that reads each `api.callPlugin("id", "fn"` pair out of the source and rejects any the manifest's `plugins` array does not declare, or any call site whose two targets are not plain string literals |
| `read-cards` | `/\bapi\.resolveCards\b/`, and for scene scripts `/\bworld\.resolveCards\b/` — the bare property read, not only a call, so a script that feature-checks the method or takes it into a local (`const resolve = world.resolveCards`) is still caught |
| `ai-inference` | `/\bapi\.ai\.(evaluate\|mcts)\s*\(/` — `mcts` is not on the mod surface; it is named so that adding it later cannot ship undeclared |
| `log` | `/\bapi\.log\s*\(/` |

Because the detectors match a literal `api.` prefix, a call reached through a renamed
binding (`const a = api; a.createObject(...)`) or computed property access
(`api["createObject"](...)`) is **not** detected — and will then fail at run time with a
missing-capability throw instead. Call the methods the plain way.

This check runs at three points, all calling the same `validateManifestCapabilities()`:

1. **GitHub registration / scan** — an undeclared capability is a `severity: "error"`
   issue, which sets the mod's scan status to `incompatible`. An incompatible mod cannot
   be registered or selected for a room.
2. **Serve time** — re-run every time an already-registered mod is loaded into a room.
   If the script changed since the last scan and now uses a capability the manifest does
   not declare, the mod fails to load with
   `"Mod script no longer passes sandbox compatibility checks."` — even though it was
   `compatible` at registration.
3. **Local editor draft** — the same check runs while you are authoring, before anything
   is published.

### The exact rejection

```
Script uses capability "<capability>" but it is not declared in manifest.capabilities.allowed.
```

with `code: "undeclared-capability"`, `severity: "error"`. For a script that calls
`api.createObject(...)` while `capabilities.allowed` is `["log"]`:

```
Script uses capability "spawn-object" but it is not declared in manifest.capabilities.allowed.
```

### Declaring a capability you do not use — a warning

The validator also walks the declared list the other way: a capability that nothing your mod ships appears to use is
reported as [`scene-script-capability-unused`](https://diceytable.com/docs/mods/scanner/what-gets-rejected#scene-script-capability-unused)
— in the editor's Problems list and at publish. It is a **warning, never a refusal**: the detectors above match text,
so a call they cannot see would otherwise refuse working code, and over-declaring only over-warns. "Used" is the union
of the entry script and every scene script, `log` is exempt, and a lobby deck database counts as a use of
`plugin-call`.

Take the warning seriously all the same. Every declared capability is shown to every player before they load the mod,
so an idle one warns them for nothing — and an idle `read-hidden-information` is what a reviewer and a player read as
"this mod can see hidden cards". Before you trim one, check the call really is gone: the warning only means the
detectors found no call, and a table script that needs `read-cards` but loses it fails when its match starts.

`plugin-call` has one extra rule: a `plugins` entry naming at least one function without `plugin-call` is rejected
as `undeclared-capability`, because that manifest contradicts itself. To trim it, empty each plugin's `functions`
list as well. A resource-only entry (`"functions": []`) names no call and needs no capability.

### What a declared capability list actually guarantees

At run time **10 of the 12** capabilities are enforced in two places, and only one of them
counts:

1. **In the frame.** Each gated `api` method begins with `requireCapability`, which throws
   `Missing mod capability: <capability>` synchronously
   (`apps/web/src/mods/sandbox/modSandbox.html`). This is the error you will see while
   developing — and it executes in the same sandboxed JavaScript realm as the mod script,
   so it is a courtesy, not a boundary: a script that posts a message straight at the host
   never runs it.
2. **On the host — the authoritative one.** Before acting on any gated message from a mod
   frame, the host re-validates it against that mod's granted capabilities using the shared
   `MOD_API_METHOD_CAPABILITIES` map (`apps/web/src/mods/SandboxedModRunner.ts`, the
   `requireCapability` helper in `run`). A fire-and-forget message — `log`, `createObject`,
   `registerAction`, `objectAction`, `playSound`, `setObjectSound` — is **dropped** and
   reported as a runtime mod diagnostic reading
   `Missing mod capability: <capability> (blocked <method> from sandbox).` A read or write
   that expects an answer (`requestWorld`) is answered with a `worldResponse` carrying
   `error: "Missing mod capability: <capability>"`, which surfaces in the mod as a rejected
   promise.

That second check covers `log`, `spawn-object`, `register-action`, `read-world`,
`read-hidden-information`, `object-action`, `play-sound`, `saved-data`, `ui` and
`plugin-call`.

### The one capability that is a wall rather than a disclosure

`read-hidden-information` is the exception to the framing in this whole section. For the
other eleven, the host check stops a *message* — it does not, on its own, decide what the mod
could have learned some other way. For this one it decides exactly that: the six
`read-world` reads are redacted to the least-privileged view on **every peer including the
host**, so hidden card faces, pile order and `secretMetadata` are simply not in any answer
a mod can obtain without this slug. Its host-side check runs before the state is served,
using the same `MOD_API_METHOD_CAPABILITIES` map, so a frame that forges the
`requestWorld` message is refused rather than served. It is the only grant whose absence
withholds data rather than declaring an intent.

### The two capabilities the host cannot re-check

`read-context` and `subscribe-events` gate no message to the host, so there is nothing for
the host to re-validate. `getMySeat`, `getMyTeam`, `getTurn` and `on` are all answered
inside the frame, from state the host has already delivered — and it delivers that state
**unconditionally**: `updateContext` posts a `contextUpdate` and `dispatchEvent` posts a
`hookEvent` to every running mod frame regardless of what that mod declared
(`apps/web/src/mods/SandboxedModRunner.ts`). A frame granted neither capability still holds
the seat, team and turn context and still receives every hook payload, in its own realm,
reachable by ordinary property access — and `self` is not one of the five banned script
patterns, which reject `document`, `window`, `parent`, `top` and `opener`.

For these two, a declaration is **disclosure, not enforcement**. Withholding `read-context`
from a mod does not hide the seat map from it; withholding `subscribe-events` does not stop
hook payloads reaching its frame. Both remain worth declaring accurately — that is what the
list is for — but do not design a game's hidden information around either one.

What none of this changes is what a capability list *means*. It is still a scanned
declaration, verified against literal `api.<method>(` call sites in the script that was
scanned — least-privilege disclosure, and the thing a reviewer or a player can read before
opening a mod's code. It is not a statement about a mod's intentions, and, as the section
above says, a manifest may declare more than the script uses without being flagged.

The boundaries that hold regardless of anything a manifest declares are unchanged and
independent of all of this: the opaque-origin iframe and its CSP, the neutered DOM,
network and storage globals, the five banned script patterns, the ten-item object-action
allowlist, the per-mod namespacing of saved data, and the ownership check on sound
references. A mod cannot reach `fetch`, `localStorage`, `eval`, another mod's saved data,
or an object action outside the ten, whatever it declares.

## Reading a manifest's declared capabilities

`mods/example`'s manifest declares:

```json
"capabilities": {
  "version": "1",
  "allowed": ["log", "spawn-object", "register-action", "read-world", "object-action", "saved-data", "subscribe-events"]
}
```

Seven of the sixteen. A reviewer reading only this list — before opening the script — can
correctly infer: this mod writes diagnostic log lines, spawns objects, adds a custom
action button, reads the table state *as a spectator sees it*, dispatches one of the 10
safe object actions, persists small per-mod values, and reacts to lifecycle events. It
does **not** read seat/team/turn context, does not touch the table UI overlay, does not
play or override sound, and — because `read-hidden-information` is absent — **cannot see
a face-down card, a pile's order or any `secretMetadata`, on any peer**. That absence is
exactly as informative as the presence — a mod with `ui`
declared is one whose author says it draws its own interface (Game UI widgets, basic widgets
or both); a mod without it cannot, because its `api.uiShow` or `api.setUiElement` call would fail
scanning.

## What players are told, at the table

A capability list is not only read by reviewers. Since the room-level disclosure landed,
the capabilities of every mod a table runs are **shown to everyone at that table** — not
only to whoever loaded them.

Two independent sources produce that disclosure and the client **unions** them, so
neither can shrink the other:

| Source | Derived from | Cannot be suppressed by |
|---|---|---|
| Registry | `room.selectedModIds` and the stored manifests, served by `GET /api/rooms/:roomId/capabilities` | the host — the joining client fetches it directly, before any peer connection exists |
| Host | the mods whose sandbox frames actually started, published on the replicated room state | the registry — it is the only source that can see a mod loaded outside the room's selection |

What that produces, in the product:

- **Before joining.** A player who opens a table whose capability set includes
  `read-hidden-information` gets a blocking prompt naming every mod and its capabilities,
  and nothing connects until they accept. This is fetched from the server, so a host
  cannot skip it.
- **While playing.** A persistent indicator — a "recording light" — stays visible for as
  long as such a mod is loaded. It is platform-owned chrome: no mod UI, panel, overlay or
  fullscreen mode can cover it, and it has its own world-space surface inside an
  immersive-VR session, where none of the page's 2D chrome renders at all.
- **When it changes.** The disclosure is identified by a fingerprint over
  `(mod id, version, capabilities)`. If a mod is added, a capability appears, **or a
  version changes** under a player who already accepted, they are prompted again. A room
  that installed a package at `1.0.0` stays pinned to `1.0.0` rather than drifting to
  whatever was published since.

Only `read-hidden-information` blocks. Every other capability is disclosed in the same
places without a modal — making a `log`-only mod interrupt a join would train players to
click through the one prompt that matters. Players can re-read the full list at any time
from the player menu.

**Two things this does not claim.** It is a disclosure layer, not an enforcement one:
nothing here narrows what a mod may do, and everything in the sections above still decides
that. And a host that runs a mod outside the room's selection *and* misreports its own
live set is not detectable from another peer — the host is the party running the code.
What the disclosure closes is the *silent* case (nobody was told) and the *drift* case
(the set changed after people agreed to it).

For authors, the practical consequence is the one already stated above: an idle
`read-hidden-information` declaration is not just a reviewer's impression any more. It
turns a blocking prompt on for every player at every table that loads your mod, and lights
a permanent indicator while it runs. Take it off the list when the call goes.

## Capability reference

### `log`

Gates `log(message)`. The only capability granted by omitting `capabilities` from the
manifest entirely. Declaring only `log` is a statement that a mod does nothing observable
at the table — useful while scaffolding, or for a diagnostics-only mod.

### `spawn-object`

Gates `createObject(object)`. Fire-and-forget — the call returns nothing, not even the
new object's id. A mod that needs to act on what it just spawned also needs `read-world`
to look the object back up (by a `label` or tag it chose) after the fact.

### `register-action`

Gates `registerAction(action)`, which adds a labeled entry to the app UI. It grants no
ability to do anything when that entry is used — whatever it triggers is gated by whatever
other capability that code path uses.

### `read-context`

Gates `getMySeat()`, `getMyTeam()`, `getTurn()` and `listBots()`. The narrowest read capability: this
peer's own seat, team and turn state, from a locally cached value pushed by the host, plus the public
roster of the [bots](https://diceytable.com/docs/mods/concepts/bots) seated at the table — which every player already sees in the
seat list. It exposes no roster of other people.

### `read-world`

Gates `getSnapshot()`, `getObject(objectId)`, `listObjects(filter?)`,
`getContainerContents(objectId)`, `getHandObjects(seat?)` and `getZoneObjects(seat, zoneId)`.
`listObjects`'s `tags` filter is capped at 32 entries and `match` is coerced to `"any"` or
`"all"` on the frame side and the host side independently.

**All six return the least-privileged view, on every peer including the host.** They are
passed through the same redactors a spectator with no seat and no team gets, so a
face-down card arrives as `label: "Card"` with `metadata.__redacted === true` and no
`displayName`, `metadata.cardId` or `secretMetadata`; a deck or bag reports at most its
single publicly visible face-up first card and never its order; an entity a `hidden` seat
zone conceals is dropped from lists and resolves `null` from `getObject`; and a hand whose
entries are all concealed is dropped rather than returned empty. A mod is granted nothing
extra by the peer it happens to run on, and these six never change behaviour based on what
else the manifest declares — one call site, one meaning. Reading a hidden face needs
`read-hidden-information` below.

`read-world` is also what the four **zone/trigger hooks** need: `onZoneEnter`,
`onZoneLeave`, `onTriggerEnter` and `onTriggerLeave` are delivered only to a frame granted
it, so subscribing to one without declaring `read-world` is a `severity: "error"` at
publish time even though `api.on` itself is gated by `subscribe-events`.

### `read-hidden-information`

Gates `getUnredactedSnapshot()`, and nothing else. It resolves the host's table state with
no redaction at all: real card faces, a deck's and a bag's ordered `metadata.cards`, every
seat's hand, `secretMetadata` on every kind, and the entities a `hidden` seat zone
conceals. It exists because the six `read-world` reads above stopped returning any of that.

Four things make it different from every other slug on this page. It is **never implied by
`read-world`** and never granted by default. It is **re-checked host-side** before the
state is served, so forging the underlying `postMessage` does not get past it. It is
**visible to the publish scanner** — `detectScriptCapabilities` matches
`api.getUnredactedSnapshot(` by name, so calling it without declaring it is an
`undeclared-capability` rejection, which means "this mod reads hidden information" is a
fact a reviewer can establish from the script rather than only the manifest. And a
capability **cannot grant what a peer does not hold**: on a player or spectator client
this resolves that client's own received snapshot, which the host redacted at the wire
boundary before broadcasting, so only on the host is it the full table. Write anything
that adjudicates secrets to run on the host.

### `object-action`

Gates `objectAction(objectId, action)`. `action` is independently re-checked host-side
against a fixed 10-item allowlist (`flip`, `rotate`, `lock`, `unlock`, `shuffle`, `draw`,
`deal`, `split`, `combine`, `roll`). That re-check happens regardless of capability
declaration, so every other engine action — `tap`, `untap`, `delete`, `lift`, `flick`, `press`,
`toss`, the `reveal-*` and `search*` actions among them — is unreachable from a mod under any
capability. See
[Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies).

### `saved-data`

Gates `getSavedData(scope?)`, `setSavedData(data, scope?)`. `scope.objectId` is the only
thing the mod supplies — the host injects the mod's own id before storage, so one mod can
never read or write another mod's saved data regardless of what `scope` it passes.

### `subscribe-events`

Gates `on(eventName, handler)`. Unlike every other gated method, this one does not message
the host per call — it only registers a local handler. The host pushes lifecycle events
into the frame independently; declaring `subscribe-events` is what lets the mod's
`api.on(...)` registration succeed, not what lets events reach the frame.

### `ui`

Gates two families that draw a mod's interface, and one hook.

- **The basic widgets:** `getUiState()`, `listUiElements()`, `setUiElement(element)`,
  `deleteUiElement(elementId)`. `setUiElement` and `deleteUiElement` scope to the calling
  mod's own id, injected host-side — a mod cannot create or delete another mod's UI
  elements.
- **The [Game UI](https://diceytable.com/docs/scripting/concepts/game-ui)** (the HUD): `uiShow`, `uiUpdate`, `uiHide`,
  `uiSet`, `uiToast`, `uiLog` and `uiPrompt`. Every one is a request the **host** answers, so the
  capability is re-checked host-side for all seven, and every one is host-only: on a player or
  spectator it rejects with `Only the host can update mod UI state.` The owner of every widget,
  state key and log line is the mod's own id, stamped by the host — a mod cannot show, change,
  hide, read or press another mod's or a table script's widgets. Each write is validated strictly
  (no HTML, no CSS, no URL, no code; images are repo-relative raster paths; icons and fonts come
  from fixed lists) and resolves a [`ModUiWriteResult`](https://diceytable.com/docs/scripting-api/api#moduiwriteresult)
  whose refusal codes are deliberately coarse, so a mod cannot measure what other mods hold.
- **The `onUiAction` hook:** a press on one of this mod's Game UI widgets. The host delivers it
  only to the host's copy of the owning mod, and only when that mod was granted `ui`; the scanner
  therefore demands `ui` for an `api.on("onUiAction", …)` subscription, on top of
  `subscribe-events`.

Private widgets and private seat state are sent only to the players in their audience, never in
the table state everyone receives. A mod's snapshot reads never include any seat's private Game
UI — not even `getUnredactedSnapshot()`, because `read-hidden-information` grants hidden cards,
not another seat's interface.

### `play-sound`

Gates `playSound(params)`, `setObjectSound(objectId, action, ref)`. Semantic-only by
design: a mod names a material × action event, an object id and action pair, or one of its
own declared sounds from `manifest.soundSets` — never a raw clip id. `setObjectSound`'s
`ref` is host-validated against the mod's own declared sound names, so a mod cannot set
another mod's sound as an override.

### `plugin-call`

Gates `listPlugins()` and `callPlugin(pluginId, functionName, params?)`. It is the only
capability that also requires a second manifest field: `plugins`, naming each plugin id and
each function on it your script calls. Both targets of every `api.callPlugin(` must be plain
string literals so the scanner can read them, an undeclared pair is rejected at publish, and
the mod-visible surface deliberately never includes a plugin's endpoints, origins or auth
shape. Full rules on [Calling a plugin from a mod](https://diceytable.com/docs/plugins/calling-from-a-mod).

### `ai-inference`

Gates `api.ai.evaluate(modelId, inputs, opts?)` — the one `api` member reached through a namespace. It runs one
of the models your manifest declares in [`aiModels`](https://diceytable.com/docs/mods/manifest/reference#aimodels) on a batch of
positions and hands back typed arrays.

> **`ai-inference` is not code execution and not network access, and describing it as either is wrong.** A model
> is a file in your own repository that the publish scanner parsed and held to a fixed list of plain operators
> ([the rules](https://diceytable.com/docs/mods/scanner/what-gets-rejected#ai-model-rules)). The **host** evaluates it in its own
> background workers and returns numbers. Your frame gets no worker, no session and no model bytes, cannot name a
> model its manifest does not declare, and nothing the model returns is replicated.

Like every call that waits for an answer, it is **re-checked host-side** against `MOD_API_METHOD_CAPABILITIES`, so
forging the message does not get past it — and the host also refuses it on any peer that is not the host
(`not-host`): evaluation spends the host's device on the host's authority. A game's [bots](https://diceytable.com/docs/mods/concepts/bots)
do not need this capability: they are played by the game's scene script, which needs no capability to call `ai.*`. Declare it
only if your **mod script** calls `api.ai.evaluate` itself. See [`api.ai.evaluate`](https://diceytable.com/docs/scripting-api/api#apiaievaluate).

## See also

- [Manifest reference](https://diceytable.com/docs/mods/manifest/reference) — the `capabilities` field itself, its schema and defaults.
- [The `api` reference](https://diceytable.com/docs/scripting-api/api) — full signatures, badges and examples for every method above.
- [What gets rejected](https://diceytable.com/docs/mods/scanner/what-gets-rejected) — `undeclared-capability` alongside the other rejection rules.
- [`ModCapability`](https://diceytable.com/docs/reference/enums/mod-capability) — the 12 slugs in one table.
- [Calling a plugin from a mod](https://diceytable.com/docs/plugins/calling-from-a-mod) — the `plugins` declaration `plugin-call` requires.
- [`SANDBOX_SAFE_OBJECT_ACTIONS`](https://diceytable.com/docs/reference/enums/sandbox-safe-object-actions) — the 10 action names `object-action` unlocks.
- [Scanner rule codes](https://diceytable.com/docs/reference/enums/scanner-rule-codes) — the codes an undeclared-capability rejection is reported under.
- [Known limitations](https://diceytable.com/docs/reference/known-limitations) — the maintained list of gaps, including the two capabilities the host cannot re-check.
- [Mod hooks and capabilities](https://diceytable.com/docs/scripting-api/hooks-and-capabilities) — which capability each `api` method and each hook needs.

## `modCapabilitySchema`

16 values. Declared in `manifest.capabilities.allowed`. Using one without declaring it is an `undeclared-capability` rejection.

| Capability |
|---|
| `log` |
| `spawn-object` |
| `register-action` |
| `read-context` |
| `read-world` |
| `read-hidden-information` |
| `object-action` |
| `saved-data` |
| `subscribe-events` |
| `ui` |
| `play-sound` |
| `plugin-call` |
| `read-cards` |
| `read-decks` |
| `host-message` |
| `ai-inference` |

Eleven slugs, listed in `manifest.capabilities.allowed`, each gating a group of `api` methods. Omit the
block and a mod gets `["log"]` and nothing more. The scanner infers what a script uses from literal
`api.<method>(` call sites, so declaring fewer than you call is an `undeclared-capability` rejection while
declaring more than you call is not flagged at all — least privilege here is your discipline, not a check.

Nine of the eleven are re-checked host-side, and that is the enforcement that counts. Before acting on a
message from a mod frame the host revalidates it against that mod's granted set through
`MOD_API_METHOD_CAPABILITIES` (`apps/web/src/mods/SandboxedModRunner.ts`), covering `log`, `spawn-object`,
`register-action`, `read-world`, `read-hidden-information`, `object-action`, `play-sound`, `saved-data`
and `ui`.

**`read-hidden-information` is the one slug that withholds data rather than declaring an intent.** It gates
`api.getUnredactedSnapshot()` alone. Every `read-world` read is redacted to the least-privileged view on
*every* peer, the host included, so hidden card faces, a pile's order and `secretMetadata` are not in any
answer a mod can obtain without it — running on the host does not help. Its host-side check runs before the
state is served, it is never implied by `read-world`, it is never granted by default, and
`detectScriptCapabilities` matches `api.getUnredactedSnapshot(` by name so an undeclared call is rejected
at publish time.

`read-context` and `subscribe-events` send the host nothing to re-check. `getMySeat`, `getMyTeam`, `getTurn`
and `on` are answered inside the frame from state the host pushes to every running mod — `updateContext` posts
a `contextUpdate`, and `dispatchEvent` posts a `hookEvent` whatever the mod declared for every hook except the
four narrowed ones below — and that state rests on `self.__diceytableCtx` and `self.__diceytableHooks`,
reachable by ordinary property access, with `self` absent from the five banned script patterns. For those two a
declaration is disclosure rather than enforcement: withholding either hides nothing from the frame. Declare
them accurately anyway, and do not rest a game's hidden information on them.

**`read-world` gates four hook *deliveries* as well as six pull methods**, and this is the one narrowing of its
kind. `MOD_HOOK_EVENT_CAPABILITIES` maps `onZoneEnter`, `onZoneLeave`,
[`onTriggerEnter`](https://diceytable.com/docs/scripting-api/hooks-and-capabilities#modhookeventmapontriggerenter) and
[`onTriggerLeave`](https://diceytable.com/docs/scripting-api/hooks-and-capabilities#modhookeventmapontriggerleave) to `read-world`,
and `SandboxedModRunner.dispatchEvent` never posts one of those messages into a frame that was not granted it —
so the handler is simply never called, with nothing reported. It is genuinely host-side: `requireCapability`
inside `modSandbox.html` runs in the untrusted frame's own realm, whereas this check does not, so a frame
cannot opt itself back into a hook it was not granted. Everything else is fanned out to every running mod.

Those four payloads are sent in full — they carry an `objectId` (and, for a trigger, an `ownerObjectId`)
for **every** entity that crosses, face-down and hidden-zone ones included, and the host-side capability
gate is the only control on them. Note the asymmetry this now creates: since the `read-world` *pull* reads
became least-privileged, a hook can name an id that
[`api.getObject`](https://diceytable.com/docs/scripting-api/api#apigetobject) then resolves to `null` and
[`api.getZoneObjects`](https://diceytable.com/docs/scripting-api/api#apigetzoneobjects) omits. The push tells you *that* something
crossed; it does not tell you what, and the pull will not fill the gap in. **The trigger hooks added no new
capability value** — neither `subscribe-events` nor the sandbox was widened for them.

The scanner covers all four on the way in: subscribing with `api.on("onZoneEnter" | "onZoneLeave" |
"onTriggerEnter" | "onTriggerLeave", …)` counts as a use of `read-world`, so a manifest that omits it is rejected
at publish time with `undeclared-capability` rather than shipping a handler that silently never runs. That
detection only ever *demands* a declaration; it never grants one.
See [ModCapability](https://diceytable.com/docs/reference/enums/mod-capability).
