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

- Source: https://diceytable.com/docs/scripting-api
- Last verified: 2026-09-30

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](https://diceytable.com/docs/scripting/concepts/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`](https://diceytable.com/docs/scripting-api/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`](https://diceytable.com/docs/scripting-api/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`](https://diceytable.com/docs/scripting-api/objecthandle) — one entity, with fourteen methods, ten read-only
  `ObjectData` fields and eight entity-scoped delegates.
- [Object Types](https://diceytable.com/docs/scripting-api/object-types) — the per-kind handles `ObjectHandle` narrows into, what a
  card and a container each add, and how `refObject` gets one.
- [Events](https://diceytable.com/docs/scripting-api/events) — the sixteen `globalEvents` delegates, what each payload carries, and
  which peer raises it.
- [Types](https://diceytable.com/docs/scripting-api/types) — `Vec3`, `ObjectKind`, `ObjectAction`, `SpawnObjectOptions`, `PlayerInfo`
  and `TurnInfo`.
- [Bots and AI](https://diceytable.com/docs/scripting-api/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](https://diceytable.com/docs/scripting-api/api) — every method, each with the capability that gates
  it and what the host does with the call.
- [Mod hooks and capabilities](https://diceytable.com/docs/scripting-api/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](https://diceytable.com/docs/scripting/concepts) 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](https://diceytable.com/docs/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

- [Scripting concepts](https://diceytable.com/docs/scripting/concepts) — host authority, execution order, events, async, the sandbox.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — the eighteen engine actions, the thirteen a table
  script may request, and the ten a mod may.
- [Known limitations](https://diceytable.com/docs/reference/known-limitations) — every documented gap and deliberate boundary.
- [The Script editor](https://diceytable.com/docs/editor/item-editors/script) — writing, compiling and running a table script.
- [Anatomy of a mod](https://diceytable.com/docs/mods/getting-started/anatomy-of-a-mod) — where a mod script sits in a repository.
