# ObjectKind vs TableObjectKind

> The eleven entity kinds the engine can spawn, which of the two declared unions names each one, and the open escape hatch that keeps a typo from erroring.

- Source: https://diceytable.com/docs/reference/enums/object-kind
- Last verified: 2026-10-06

An entity's **kind** is fixed at spawn and decides which physics defaults the runtime applies, which
collision geometry it builds, and which of the optional state fields mean anything. There are **eleven**
kinds. There are also two declared unions that name them, and they agree on every concrete value.

| Union | Where | Names |
|---|---|---|
| `TABLE_OBJECT_KINDS` | `packages/shared/src/tableObjects/kinds/index.ts` | **11** — the engine's own list, and the authority. |
| `TableObjectKind` (mod scripting) | `DICEYTABLE_MOD_API_DTS` | **11** — matches the engine exactly. |
| `ObjectKind` (table scripting) | `DICEYTABLE_SCRIPT_API_DTS` | **11**, plus an open `(string & {})` escape hatch. |

## The values

| Value | What it is | Contexts that accept it | Surfaces that name it |
|---|---|---|---|
| `card` | A single card. Its `label` **is** its identity, and that identity drives hidden-information redaction. | Every spawn path; the only kind a container's contents are made of. | Engine · mod `TableObjectKind` · table-script `ObjectKind` |
| `deck` | An ordered stack of cards. Carries `stackCount` and a contents list; `draw`, `deal`, `shuffle` and `split` are meaningful. | Every spawn path. | Engine · mod · table script |
| `die` | A die. `roll` throws it with a randomized impulse and lets physics settle it. | Every spawn path. | Engine · mod · table script |
| `token` | A general-purpose piece — a marker, a pawn, a counter. | Every spawn path. | Engine · mod · table script |
| `board` | A large, usually static surface other pieces sit on. One of the two kinds players cannot `flick`. | Every spawn path. | Engine · mod · table script |
| `bag` | A container that hands out its contents in `random`, `stack` or `queue` order. | Every spawn path. | Engine · mod · table script |
| `custom` | Anything driven by a mod's own model. Also the **fallback** a table script's spawn coerces an unrecognized kind to. | Every spawn path. | Engine · mod · table script |
| `card-holder` | A rack that holds cards in view of one seat. | Every spawn path, including a table script's. | Engine · mod · table script |
| `button` | A pressable control — a coloured cap in a frame — that raises a `press` action a script can observe as `onPressed`. | Every spawn path. | Engine · mod · table script |
| `table` | Furniture the game is played **on**, placed as an entity inside a scene — not a table pack. Its surface material colours the sound of everything that lands on it; like `board`, it cannot be `flick`ed. | Every spawn path. | Engine · mod · table script |
| `coin` | A flat piece that turns over and stacks like a `token` and can also be **tossed** (`toss`, Flip Coin) — the only kind that can. The built-in coin presets are coins, and so is any model whose Type is set to Coin. | Every spawn path. | Engine · mod · table script |

## Both surfaces name all eleven

The table-scripting `ObjectKind` union and the mod surface's `TableObjectKind` both name every kind in
the engine's `TABLE_OBJECT_KINDS`, `card-holder`, `button`, `table` and `coin` included. Kinds were added to the
table-script union after it was first written — `card-holder` alongside the per-kind handle types,
`button` with the button object, `table` with the table entity, `coin` with the coin kind — and each had cost only an autocomplete
entry beforehand, because the sandbox's own `KNOWN_KINDS` list accepted them. The mod union lagged the
same way: until the `table` kind landed it did not name `button` either, so a mod passing
`{ kind: "button" }` to `api.listObjects` got a type error for a kind the host accepted. So `world.getAllObjects({ kind: "card-holder" })`
now completes and narrows to [`CardHolderObject`](https://diceytable.com/docs/scripting-api/object-types#cardholderobject), and
`world.getAllObjects({ kind: "button" })` narrows to
[`ButtonObject`](https://diceytable.com/docs/scripting-api/types#buttonobject), and `world.getAllObjects({ kind: "table" })` to
[`TableFurnitureObject`](https://diceytable.com/docs/scripting-api/types#tablefurnitureobject), and `world.getAllObjects({ kind: "coin" })` to
[`CoinObject`](https://diceytable.com/docs/scripting-api/types#coinobject).

The one difference that remains is the table-script union's open `(string & {})` arm, which keeps a typo
from being a type error — see below.

## What an unknown kind does, per surface

The two surfaces disagree here too, and the difference is worth knowing before you pass a kind that came
from data rather than a literal:

- **Table scripting:** an unrecognized kind is **silently replaced with `"custom"`** in the sandbox. No
  error, no log line — a typo such as `"dice"` produces a plain custom entity that never rolls. Read
  `handle.kind` back to check.
- **Mod scripting:** an unrecognized kind fails the host's schema parse, and the parse failure drops the
  **whole spawn**. The entity never appears and the only signal is a mod-console diagnostic.

## See also

- [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) — per-kind physics defaults, scale, color and which fields matter.
- [`api.createObject`](https://diceytable.com/docs/scripting-api/api#apicreateobject) — spawning from a mod.
- [`world.spawnObject`](https://diceytable.com/docs/scripting-api/world#worldspawnobject) — spawning from a table script.
- [Object actions](https://diceytable.com/docs/mods/reference/object-actions) — the kind-by-action matrix.
- [Runtime sound events](https://diceytable.com/docs/reference/enums/runtime-sound-event) — which sound each kind makes, per moment.
