Enums and Constants
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.
On this page3 sections
The sixteen slugs manifest.capabilities.allowed can contain. Every one of the 25
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 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. |
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, 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 — 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-informationis the exception to everything below. It is the one grant whose absence genuinely withholds data rather than declaring an intent. Everyread-worldread 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;getUnredactedSnapshotis the only door, its host-side check runs before the state is served, anddetectScriptCapabilitiesmatches 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.
See also#
- Mod capabilities — the matrix, the detectors and the rejection text.
- The mod api object — every method, with its capability badge.
- Manifest reference — the
capabilitiesfield's own schema and defaults. - Scanner rule codes — the other thing that rejects a script.
- Sandbox limits — what the capability model is and is not for.
- Calling a plugin from a mod — what
plugin-calldoes and does not grant.
