# ModCapability

> The 16 capability slugs a mod manifest can declare, the api methods each one unlocks, and which context reads them - as a compact value table.

- Source: https://diceytable.com/docs/reference/enums/mod-capability
- Last verified: 2026-10-11

The sixteen slugs `manifest.capabilities.allowed` can contain. Every one of the 25
[`api`](https://diceytable.com/docs/scripting-api/api) methods is gated on exactly one of them, and calling a method whose slug is
absent throws `Missing mod capability: <capability>` synchronously — including for the methods that return
a promise.

**16 values**, declared as `modCapabilitySchema` in `packages/shared/src/modManifest.ts`.

Omitting the `capabilities` block entirely defaults it to `{ version: "1", allowed: ["log"] }`, so a mod
that declares nothing can call `api.log()` and nothing else.

This page is the value table. [Mod capabilities](https://diceytable.com/docs/mods/manifest/capabilities) owns the full
capability-to-method matrix, the thirteen detector regexes, the three checkpoints a declaration is validated
at, and the exact rejection text — read that page when you are debugging a declaration.

## The values

| Value | Unlocks | Contexts that accept it | Surfaces it applies to |
|---|---|---|---|
| `log` | `log` | `manifest.capabilities.allowed`; the default when the block is omitted. | Mod scripting only |
| `spawn-object` | `createObject` | `manifest.capabilities.allowed` | Mod scripting only |
| `register-action` | `registerAction` | `manifest.capabilities.allowed` | Mod scripting only |
| `read-context` | `getMySeat`, `getMyTeam`, `getTurn`, `listBots` | `manifest.capabilities.allowed` | Mod scripting only |
| `read-world` | `getSnapshot`, `getObject`, `listObjects`, `getContainerContents`, `getHandObjects`, `getZoneObjects` — all six **least-privileged** on every peer | `manifest.capabilities.allowed` | Mod scripting only |
| `read-hidden-information` | `getUnredactedSnapshot` — the **elevated** read: real card faces, pile order and `secretMetadata`, from the host. Never implied by `read-world`, never granted by default. | `manifest.capabilities.allowed` | Mod scripting only |
| `object-action` | `objectAction` | `manifest.capabilities.allowed` | Mod scripting only |
| `saved-data` | `getSavedData`, `setSavedData` | `manifest.capabilities.allowed` | Mod scripting only |
| `subscribe-events` | `on` — and therefore every hook | `manifest.capabilities.allowed` | Mod scripting only |
| `ui` | `getUiState`, `listUiElements`, `setUiElement`, `deleteUiElement` | `manifest.capabilities.allowed` | Mod scripting only |
| `play-sound` | `playSound`, `setObjectSound` | `manifest.capabilities.allowed` | Mod scripting only |
| `plugin-call` | `listPlugins`, `callPlugin` — naming a **declared** function on an **installed** plugin. Also requires a matching `manifest.plugins` entry, and is **not** network access. | `manifest.capabilities.allowed` | Mod scripting only |
| `read-cards` | `resolveCards` — reading the game's **own** shipped card catalogue. Also gates the table-script [`world.resolveCards`](https://diceytable.com/docs/scripting-api/world#worldresolvecards). | `manifest.capabilities.allowed` | Mod scripting **and** table scripting (`world.resolveCards`) |
| `read-decks` | `listDecks`, `getDeck` — the **player's own** saved decks. A lobby deck pick needs nothing: the platform deals it. | `manifest.capabilities.allowed` | Mod scripting only |
| `host-message` | `sendToHost` — the one outbound call a non-host peer can make; the host receives it as `onHostMessage`. | `manifest.capabilities.allowed` | Mod scripting only |
| `ai-inference` | `ai.evaluate` (written `api.ai.evaluate`) — running one of the mod's **own** declared [AI models](https://diceytable.com/docs/mods/manifest/reference#aimodels), on the host only. **Not** code execution and **not** network access. | `manifest.capabilities.allowed` | Mod scripting only |

**Table scripting has almost no capability model.** It is restricted instead by an intent allowlist
enforced on the host (`spawn`, `object-action`, `transform`, `set-object-tooltip`, and a counter-only
`card-overlay-set`), and every table-scripting reference entry carries `capability: none`. The one
exception is `read-cards`: a scene script that calls `world.resolveCards` must declare it, and the
host refuses the call without it.

## Two things a capability list does not do

**It does not refuse you for declaring more than you use.** A declared capability nothing your mod ships
appears to use is only a **warning**,
[`scene-script-capability-unused`](https://diceytable.com/docs/mods/scanner/what-gets-rejected#scene-script-capability-unused) — in
the editor and at publish — because the detectors match text and could miss a real call. Trim what it names, but
check the call really is gone first. Declaring `plugins` *without* `plugin-call` runs the other way and is
rejected, because that manifest contradicts itself.

**It does not tell you what a mod intends.** It tells you what its script was scanned as calling.

> **`read-hidden-information` is the exception to everything below.** It is the one grant whose absence
> genuinely withholds data rather than declaring an intent. Every `read-world` read is redacted to the
> least-privileged view on **every peer, the host included**, so a mod cannot reach a hidden card face by
> arranging to run on the host; `getUnredactedSnapshot` is the only door, its host-side check runs before
> the state is served, and `detectScriptCapabilities` matches the call by name so an undeclared use is a
> publish-time rejection. Treat its presence in a listing as "this mod can see hidden cards".

> **By design.** Ten of the twelve grants are enforced in two places. `requireCapability` throws from inside
> the same untrusted JavaScript realm as the mod script (`apps/web/src/mods/sandbox/modSandbox.html`) — the
> error you meet while developing — and the host then re-validates the gated message against the mod's grants
> before acting on it, using the shared `MOD_API_METHOD_CAPABILITIES` map
> (`apps/web/src/mods/SandboxedModRunner.ts`). **The host check is the authoritative one**, because a
> script that posts to the host directly never runs the in-frame one. That covers `log`, `spawn-object`,
> `register-action`, `read-world`, `read-hidden-information`, `object-action`, `play-sound`, `saved-data`,
> `ui` and `plugin-call`.
>
> **`read-context` and `subscribe-events` are frame-local only.** Neither sends the host a message to check:
> `getMySeat`, `getMyTeam`, `getTurn` and `on` are answered inside the frame, and the host pushes
> `contextUpdate` and `hookEvent` to every running frame unconditionally
> (`apps/web/src/mods/SandboxedModRunner.ts`, `updateContext` and `dispatchEvent`). A frame granted neither
> still holds seat, team and turn state and receives every hook payload in its own realm. For those two the
> declaration is disclosure, not a wall. Read a capability list as
> least-privilege *disclosure* all the same: what the platform scanned for, and what a reviewer or player
> can know about a mod before opening its code. The boundaries that hold regardless of what a manifest
> declares are separate from all of it — the opaque-origin iframe and its CSP, the neutered DOM, network
> and storage globals, the five scanner patterns, the host-side ten-action allowlist, the per-mod
> namespacing of saved data, and the ownership check on sound references.
> See [Known limitations](https://diceytable.com/docs/reference/known-limitations#capabilities-are-enforced-in-two-places).

## See also

- [Mod capabilities](https://diceytable.com/docs/mods/manifest/capabilities) — the matrix, the detectors and the rejection text.
- [The mod api object](https://diceytable.com/docs/scripting-api/api) — every method, with its capability badge.
- [Manifest reference](https://diceytable.com/docs/mods/manifest/reference) — the `capabilities` field's own schema and defaults.
- [Scanner rule codes](https://diceytable.com/docs/reference/enums/scanner-rule-codes) — the other thing that rejects a script.
- [Sandbox limits](https://diceytable.com/docs/scripting/concepts/sandbox-limits) — what the capability model is and is not for.
- [Calling a plugin from a mod](https://diceytable.com/docs/plugins/calling-from-a-mod) — what `plugin-call` does and does not grant.
