Dicey Table

The Manifest

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.

On this page7 sections

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).

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: 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) 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 on the host. Not code execution and not network access; see ai-inference.

| read-decks | listDecks(), getDeck(deckId) — the player's own saved decks. Not needed for a lobby deck pick: a 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 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 — 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 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.

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 — 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 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.

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 (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 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.

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 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). 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 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.

See also#

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 and onTriggerLeave 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 then resolves to null and api.getZoneObjects 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.

Did this page answer your question?