Dicey Table

Scripting API

The two DiceyTable script surfaces side by side - Table Scripting's world, globalEvents and refObject, and Mod Scripting's api - and how to pick one.

pages
20
for the Start here pages
~13 min

Start here

  1. Choosing a surface3 min · table script or mod script
  2. Host authority5 min · who runs your code
  3. World2 min · the table script API
  4. Events3 min · react when things happen

DiceyTable has two scripting surfaces. They are separate products that happen to share a table: different languages, different globals, different security models, different event names. Nothing you learn about one transfers automatically to the other, and moving a game from one to the other is a rewrite rather than a port.

Read Choosing a surface first if you have not picked one.

The two surfaces#

Table Scripting Mod Scripting
Language TypeScript, transpiled in the editor JavaScript, a file in the mod's GitHub repo
Globals world, globalEvents, refObject, bots, ai api, passed to exports.setup(api, manifest)
Event style Delegates — globalEvents.onX.add(fn) Callback registry — api.on("onX", fn)
Entities A live ObjectHandle with mutators Plain TableObjectState data plus api.objectAction(id, action)
Security An intent allowlist enforced on the host; one capability (read-cards, for world.resolveCards) Capabilities declared in the manifest
Where it runs The host peer only Every peer that loaded the mod, in a sandboxed iframe

world does not exist in a mod's runtime. api does not exist in a table script's runtime. Their event names look alike and are unrelated: the mod hook is onTurnStart, the table-script delegate is onTurnStarted.

Table Scripting — Surface A#

  • World — the nineteen methods on the world global: find, spawn, read the layout and the room, add context-menu entries and text labels, log, broadcast, persist and pace.
  • ObjectHandle — one entity, with fourteen methods, ten read-only ObjectData fields and eight entity-scoped delegates.
  • Object Types — the per-kind handles ObjectHandle narrows into, what a card and a container each add, and how refObject gets one.
  • Events — the sixteen globalEvents delegates, what each payload carries, and which peer raises it.
  • Types — Vec3, ObjectKind, ObjectAction, SpawnObjectOptions, PlayerInfo and TurnInfo.
  • Bots and AI — the bots and ai globals: register the code that plays a game bot, search with a rules kernel, and run the game's own AI models.

Mod Scripting — Surface B#

  • The mod api object — every method, each with the capability that gates it and what the host does with the call.
  • Mod hooks and capabilities — the hook events, their exact payload shapes, the unbounded custom UI-hook channel, and the twelve capability slugs.

How to read a reference entry#

Every member carries a four-row badge table — authority, timing, capability, availability — under a byline that names its surface. Each value is defined exactly once, on the concepts page that owns the idea, and the entry links there rather than restating it. Every runnable example is compiled against the same declaration the editor's autocomplete uses, and every mod example is additionally run through the scanner that gates real publishing. See Reading these docs.

Where a surface has a gap — a stale declaration, a type union with no way to call part of it, an event that fires correctly and reports null — it is disclosed on the entry and collected on one dated page.

See also#

Concepts

Scripting concepts

The shared ideas behind both DiceyTable script surfaces - where code runs, in what order, how events arrive, and what every reference badge means.

2 min

Host authority

Why a table script runs on exactly one peer, what the other players actually receive, and what the host-only, all-peers and host-authoritative badges mean.

5 min

Execution order

The deterministic order a table script host boots in - handles, scene scripts, object scripts - what already exists when your code runs, and what never re-runs.

5 min

Events and delegates

Delegate scope, handler ordering, how many times each table event fires, which peer raises it, and the plain fact that nothing can cancel an action.

8 min

Async and snapshots

What a promise means when the answer comes back from the host, why a sync mutator leaves its own handle stale, and when the rest of the table finds out.

5 min

Sandbox limits

The ES-only language subset both script surfaces compile against, what the sandbox frame removes at run time, and the static scanner that reads your comments.

8 min

Choosing a surface

Table script or mod script? A capability-by-capability decision table, what each surface alone can do, and why moving between them later is a rewrite.

3 min

Game UI (HUD)

The Game UI, or HUD - status lines, prompts, action strips, logs and hints drawn off the table, private per seat, from a table script or a mod.

24 min

Highlights and clicks

Outline entities with named styles, publicly or privately per seat, and hear which entity a player clicked - the pick-a-card loop of a scripted game.

6 min

Asset Pack Script Scope

A prefab's script runs under its own pack scope, pinned to a version, so it cannot read another pack's saved data or the game's - and what follows for authors.

5 min

Table Scripting (Surface A)

Mod Scripting (Surface B)