# Object kinds

> The 11 TableObjectKind values (card to coin) — what each does at the table, its physics defaults, its default scale/color, and which fields matter.

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

`TableObjectKind` is a Scene Entity's [Platform kind](https://diceytable.com/docs/editor/concepts/glossary#platform-kind)
— shown as `TYPE` in the Inspector's `PIECE` panel. There are **11** values, defined as plain
string constants in `packages/shared/src/tableObjects/kinds/index.ts` and collected into
`TABLE_OBJECT_KINDS`:

```
card · deck · die · token · board · bag · custom · card-holder · button · table · coin
```

The kind is fixed at spawn time (an existing entity's kind is never changed in place) and
drives three things: which physics defaults the runtime applies when the entity has no
`physics` override, the collision geometry the runtime builds, and which of the
optional `TableObjectState` fields are meaningful. It does **not** gate which
[actions](https://diceytable.com/docs/mods/reference/object-actions) can target the entity — that is a related
but separate table.

## Physics defaults, at a glance

These are the values `apps/web/src/playcanvas/physics/collisionHelpers.ts` (`createRigidbodyConfig`,
called from `TabletopRuntime.createObject`) reads from
`apps/web/src/playcanvas/physics/PhysicsEngine.ts`'s per-kind functions
(`massForKind`, `frictionForKind`, `restitutionForKind`, `linearDampingForKind`,
`angularDampingForKind`) when building an entity's rigidbody and it has no explicit
`physics.mass` / `physics.friction` / … override. A kind missing from one of those switch
statements falls through to that function's `default` case, called out below.

| Kind | Mass | Friction | Restitution | Linear damping | Angular damping | Default sound material |
|---|--:|--:|--:|--:|--:|---|
| `card` | 0.05 | 0.72 | 0.1 (default) | 0.07 | 0.08 (default) | `card` |
| `deck` | 1.6 | 0.76 | 0.1 (default) | 0.05 (default) | 0.08 (default) | `card` |
| `die` | 0.35 | 0.82 | 0.52 | 0.02 | 0.015 | `plastic` |
| `token` | 0.18 | 0.78 | 0.14 | 0.04 | 0.06 | `plastic` |
| `coin` | 0.18 | 0.78 | 0.14 | 0.04 | 0.06 | `metal` |
| `board` | 4 | 0.92 | 0.1 (default) | 0.05 (default) | 0.08 (default) | `wood` |
| `bag` | 0.8 (default) | 0.8 | 0.1 (default) | 0.05 (default) | 0.08 (default) | `tile` |
| `custom` | 0.8 (default) | 0.82 | 0.1 (default) | 0.05 (default) | 0.08 (default) | `generic` |
| `card-holder` | 0.8 (default) | 0.8 (default) | 0.1 (default) | 0.05 (default) | 0.08 (default) | `wood` |
| `button` | 0.8 (default) | 0.95 | 0.04 | 0.12 | 0.3 | `plastic` |
| `table` | 0.8 (default) | 0.8 (default) | 0.1 (default) | 0.05 (default) | 0.08 (default) | `wood` |

`die`'s friction (0.82) is deliberately high — it converts a thrown die's slide into
roll/tumble rather than letting it skate flat, and pairs with the highest restitution
(0.52) of any kind so it actually bounces.

> **A second, unrelated set of "default physics" exists — do not confuse the two.**
> `packages/shared/src/tableObjects.ts` also exports `defaultObjectPhysicsForKind()`, whose
> numbers **do not match the table above** (e.g. it gives `deck` a mass of `0.3` against the
> runtime's `1.6`, and `die` a mass of `0.02` against the runtime's `0.35`). That function
> is explicitly documented as "suggestions only" for the editor's physics inspector
> placeholders (`TableEditModeShell.tsx`) — it is never written onto object state and never
> applied by the runtime. The table above, from `PhysicsEngine.ts`, is what a spawned
> object actually gets.

## Default scale and color

When a spawn omits `scale` / `color` (and does not come from a
[standard preset](https://diceytable.com/docs/mods/reference/standard-presets), which supplies its own), the
runtime falls back to `DEFAULT_SCALE` / `DEFAULT_COLOR` in `TabletopRuntime.ts`:

| Kind | Default scale (ft) | Default color |
|---|---|---|
| `card` | 0.2083 × 0.000984 × 0.2917 (a 2.5 × 3.5 in poker card, one 0.3 mm sheet) | `#f6f1df` |
| `deck` | 0.2083 × (52 × 0.000984 = 0.0512) × 0.2917 (15.6 mm tall) | `#a23c3c` |
| `die` | 0.05 × 0.05 × 0.05 | `#f4f6f8` |
| `token` | 0.12 × 0.04 × 0.12 | `#4c8c6a` |
| `coin` | 0.08187 × 0.01575 × 0.08187 (the built-in coin's real size, 25 mm across) | `#c9a227` |
| `board` | 1.2 × (board thickness) × 0.9 | `#2c6e6a` |
| `bag` | 0.5 × 0.5 × 0.5 | `#7257a6` |
| `custom` | 0.6 × 0.2 × 0.6 | `#60758f` |
| `card-holder` | 0.6 × 0.04 × 0.36 | `#3a5f7a` |
| `button` | 0.396 × 0.101 × 0.296 (the default rect button's footprint; a configured button sizes itself from `metadata.button`) | `#ff5b5b` |
| `table` | 6 × 0.2 × 4 (a placeholder slab, drawn only while — or if — the table's model never loads) | `#6b4a32` |

A `card`'s and a `deck`'s Y is the one dimension that is *not* static, and not yours to
author: `syncStackScale` (`TabletopRuntime.ts`) rewrites it on every spawn and every change
of count. A card is one sheet of paper and a deck is `stackCount` sheets, so a 10-card deck
is thinner than a 52-card one whatever `scale` says. A sheet is **0.3 mm** — a standard
playing card — unless the entity carries `metadata.paperThicknessMm`
(see [Card](https://diceytable.com/docs/mods/reference/object-kinds#card) and [Deck](https://diceytable.com/docs/mods/reference/object-kinds#deck)).

## Card

A single playing card. `label` is the card's **identity** for hidden-information
redaction — see [IDs, names and tags](https://diceytable.com/docs/editor/concepts/ids-names-tags#for-a-card-the-slug-is-the-card).

- **`faceDown`** — whether the card is showing its back. `flip` toggles it.
- **`ownerSeat`** — when set, the card is in that seat's hand (`getHandObjectsFromSnapshot`
  treats any object with a non-empty `ownerSeat` as a hand card, regardless of kind).
- **`metadata.cardCornerRadius`** — corner rounding for the rendered card mesh; backfilled
  to a default if missing or non-numeric.
- **`metadata.paperThicknessMm`** — how thick the card is, in **millimetres** (always mm,
  whatever unit the editor displays). 0.05–3; absent means 0.3, a standard playing card. A
  value outside the range is clamped, and anything that is not a positive number is read as
  the default. A card drawn or dealt from a deck inherits the deck's value. Authored as
  **Paper thickness (mm)** in the Inspector's
  [PIECE](https://diceytable.com/docs/editor/inspector/piece#paper-thickness-card-and-deck-pieces-only) panel.
- **`metadata.customDeck`** — when the card belongs to a custom deck sprite sheet, the
  sheet slice used to render its face.
- **`metadata.faceUrl`** — a **direct image URL for the card's front face** (F4): an
  absolute `http(s)` URL or a repo-relative asset path (resolved the same way any other mod
  asset is). It textures the whole card face — no sprite sheet, no catalogue — and is the
  simplest way for a mod script to spawn a card with custom art: `createObject({ kind:
  "card", metadata: { faceUrl: "https://…/anakin.jpg" } })`. It renders on the 3D table
  **and** in the hand drawer.
  **A face URL identifies the card, so it is redacted exactly like `cardId`**: a face-down
  card in another player's hand (or an unowned face-down card on the table) never sends its
  `faceUrl` to other peers — it shows the back. Only face-up (or owner/team-visible) cards
  expose it.
- **`metadata.backUrl`** — a direct image URL for the card's **back**. Public (a back is
  what a hidden card is shown as); omit it to use the standard card back.
- Collision: a thin box collider, half-height `max(scaleY / 2, 0.01)` — the smallest
  clearance of any kind (`collisionHalfHeightForObject`).

Reachable actions: `lift`, `flip`, `rotate`, `lock`/`unlock`, `combine`, `flick`,
`reveal-all`/`reveal-team-a`/`reveal-team-b`, `delete`. Not `shuffle`, `draw`, `deal`,
`split`, `roll` — see the [per-kind action matrix](https://diceytable.com/docs/mods/reference/object-actions).

## Deck

A container of cards that behaves as one physical stack.

- **`stackCount`** — how many cards the deck holds; also feeds the height derivation
  above. 1–1000.
- **`metadata.paperThicknessMm`** — the thickness of one card in the pile, in millimetres;
  same range and default as on a [card](https://diceytable.com/docs/mods/reference/object-kinds#card). The deck stands
  `paperThicknessMm × stackCount` tall — 52 cards at the default 0.3 mm is 15.6 mm — and
  every card that leaves the deck takes the value with it.
- **`faceDown`** — the deck's face; `flip` flips every card entry too and re-derives the
  visible face.
- **`metadata.cards`** — the ordered container entries (`cardId` + per-card `faceDown`).
  Absent on a `deck`, the runtime synthesizes a standard 52-card deck on first read
  (`buildStandardDeckCardEntries`).
- **`metadata.customDeck`** — as for `card`, when the deck's faces come from a custom
  sprite sheet rather than the built-in playing-card art.
- **`metadata.faceUrls`** — a **direct-URL face map** `{ [cardId]: url }` (F4), one entry
  per distinct `cardId` in `metadata.cards`. The runtime textures the deck's top/bottom
  card from the matching URL; a card **drawn** from the deck copies the map (and any shared
  `metadata.backUrl`) so it stays self-describing. It is the deck-scale sibling of a single
  card's `metadata.faceUrl`.
  **The whole map is host-only.** Its keys are the deck's ordered card ids, which no peer
  may learn (a deck's order is secret), so redaction rebuilds it to at most the single
  publicly-visible top card's entry — in lockstep with how it strips the ordered
  `metadata.cards` to the visible top. The one exception is a **private peek**: a player who
  runs the `peek` action receives the top-*N* entries (and their face URLs) un-redacted in
  their own snapshot only, for as long as the host holds the reveal.
- **`metadata.backUrl`** — a shared direct-URL back for every card the deck holds. Public.
- `split` requires `stackCount > 1`; `draw`/`deal`/`shuffle` operate on `metadata.cards`.

Reachable actions: everything a card can do, plus `shuffle`, `draw`, `deal`, `split`, `peek`.

## Die

A single die. `label` defaults to the generic name `"D6"` regardless of the die's actual
face count — `labelForKind()` (`apps/web/src/playcanvas/objectHelpers.ts`) has one
case for `die` and does not branch on `metadata.dieSides`. The face count itself lives in
metadata, not the schema:

- **`metadata.dieSides`** — 4/6/8/10/12/20 in the standard presets. It is written by the
  presets (`packages/shared/src/standardObjects.ts`) and read by nothing: the model and its
  face numbering are both resolved from `metadata.standardPresetId`, not from this. Treat it
  as informational.
- **`metadata.dieFaceStyle`** — e.g. `"dots"` for a pipped d6.
- Collision: a convex hull by default (`basePhysicsForKind`'s *suggestion*), so bevels and
  faces tumble faithfully; the runtime's actual applied physics (table above) uses the
  generic collider path since `die` has no case in `collisionHalfHeightForObject`.
- Highest restitution and friction of any kind — see the physics table above.
- **`faceValue`** — a schema field, not metadata: the number printed on the face a settled die
  is showing. The host computes it on settle and replicates it, and drops it while the die is
  tumbling, held or cocked. A die imported as a custom model has no face table and never gets
  one. See [`faceValue`](https://diceytable.com/docs/mods/reference/object-state#facevalue).

Reachable actions: `lift`, `rotate`, `lock`/`unlock`, `roll`, `flick`, `delete`. Not `flip`,
`shuffle`, `draw`, `deal`, `split`, `combine`, or any `reveal-*`.

## Token

A small marker or piece — checkers, chips, pawns of a generic shape.

- **`metadata.tokenShape`** — `"cylinder"` or `"box"`, selecting the rendered primitive.
- **`metadata.chipValue`** — casino-chip presets attach a numeric value here; purely
  cosmetic/informational, not read by any gameplay path in `packages/shared`.
- **`metadata.dualSided`** — e.g. the Reversi chip, which renders two colors on opposite
  faces.
- **[`flippable`](https://diceytable.com/docs/mods/reference/object-state#flippable)** — whether the token offers
  **Flip**. A top-level field, not a `metadata` key. Absent means "decide from the shape".

### Flipping a token

Checkers, Othello discs and punchboard chits get turned over (a coin is its own [kind](https://diceytable.com/docs/mods/reference/object-kinds#coin), and turns over the same way); meeples and miniatures do
not. A token therefore answers "can I flip?" in this order:

1. its own `flippable` (`true` or `false`), set in `setup.json`, by the Inspector's
   **PIECE ▸ Flippable**, or copied at spawn from its model's
   [`.meta.json` `flippable`](https://diceytable.com/docs/mods/files/sidecars#flippable);
2. otherwise its **shape**: a token is flat — and flips — when its height is at most half its
   narrower footprint (`isFlatTokenShape`, `FLAT_TOKEN_MAX_HEIGHT_RATIO = 0.5`). A checker
   (0.36 in tall on a 1.42 in footprint) is flat; a meeple, a miniature or a cube is not. The
   shape is measured on the piece's real world-space size, so a custom model is judged by the
   geometry it actually has.

A token that may flip turns over **180° about its own X axis, in place**: its collider keeps its
centre X/Z and its underside stays on whatever it was resting on, so a model whose origin is its
base does not sink into the table. It does **not** toggle `faceDown` — a token has no hidden face;
which side is up *is* its rotation — and nothing else changes. With `metadata.tokenFaceImage` /
`tokenFaceBackImage` set, a flip is what shows the back art.

A token that may not flip does not show Flip in the context menu, on the touch rail or in the VR
object menu, and a `flip` addressed to it — from a player, a table script's `handle.flip()` or a
mod's `api.objectAction(id, "flip")` — is refused by the host and changes nothing.

Set `flippable` explicitly only when the shape guesses wrong: `true` for a chunky two-sided
marker taller than half its width, `false` for a flat standee that must stay face up.

### Printed faces

A token can carry **art on its flat faces** — a punchboard counter, a printed chip, a
damage marker — while keeping `color` as the body.

- **`metadata.tokenFaceImage`** — art printed on the up-facing side. A repo-relative asset
  path, a public path (`/mods/…`), or an `http(s)`/`data:`/`blob:` URL.
- **`metadata.tokenFaceBackImage`** — art for the down-facing side. Omit it for a
  double-sided counter: the face art is used on both sides rather than leaving a blank back.
- **`metadata.tokenFaceFit`** — `"cover"` crops the art to fill the face; anything else (the
  default) maps it to the face as authored.

The art is **alpha-blended over the body colour**, so a PNG/WebP with transparency reads as
an overlay printed on a coloured chip and an opaque image simply hides the colour. Only the
two flat faces are printed — the rim stays `color`, which is what keeps a picked-up token
looking like a physical counter instead of a cube wrapped in one image. (That wrapping is
what `metadata.customTextureAssetId` does, and it is the right choice for a flat tile viewed
from above.)

**Printed faces require `metadata.tokenShape: "box"`.** The face is a rectangular plane
matching the token's footprint, so on a `"cylinder"` token its corners would overhang the
round body; a cylinder token therefore ignores these keys and keeps its plain colour. Set the
token's `scale.x`/`scale.z` to the art's aspect ratio — the face is mapped to the footprint,
so a square image on a non-square token stretches unless you use `"cover"`.

```json
{
  "kind": "token",
  "label": "Force",
  "position": { "x": 0, "y": 0.0, "z": 0 },
  "scale": { "x": 0.105, "y": 0.018, "z": 0.105 },
  "color": "#b32222",
  "metadata": {
    "tokenShape": "box",
    "tokenFaceImage": "assets/textures/counter-force.webp"
  }
}
```

An unresolved path leaves the token its plain body colour rather than erroring — a
repo-relative path whose asset resolver has not primed yet prints as soon as it does.

Reachable actions: `lift`, `rotate`, `lock`/`unlock`, `flick`, `delete`, and `flip` for a
token that may turn over (see [above](https://diceytable.com/docs/mods/reference/object-kinds#flipping-a-token)). No container actions, `roll`,
`combine`, or `reveal-*`.

## Board

A static playing surface — a game board, mat, or other furniture-like piece.

- Nearly every board preset ships **`locked: true`** — boards are meant to stay put once
  placed.
- **`metadata.boardStyle`** — selects the rendered board art/grid (e.g. `"chess-wood"`,
  `"go-grid"`).
- **`metadata.boardImageUrl`** — a board face image, which takes precedence over
  `boardStyle`. Accepts a repo-relative asset path (`assets/textures/mat.webp`), a public
  path (`/mods/…`), or an `http(s)`/`data:`/`blob:` URL — all resolved the same way every
  other asset reference is. An unresolved path leaves the board its base colour; it does
  **not** fall back to a grid pattern, so a mod's art is never silently replaced by a
  checkerboard.
- Heaviest default mass (4) and highest default friction (0.92) of any kind, consistent
  with something static and not meant to slide.
- Collision: `collisionHalfHeightForObject` gives `board` its own case — half-height is the
  scale-derived value *plus* a configured top clearance, rather than the generic
  `scaleY / 2` every other kind gets, so pieces resting on it do not clip through.
- **A piece authored *inside* a board is lifted out, not dropped through.** With a recessed
  mesh board (a tray, a backgammon case) it is easy to place a checker a little below the felt
  in Edit Mode. The host checks loose, unlocked, unparented pieces against boards when the table
  goes live, when a board's real collider finishes loading, and when a piece becomes dynamic,
  and moves any piece found inside a board's collider up onto the floor above it. The drop-height
  probe does the same for a piece that starts a drop inside a board, so it rests on the felt
  rather than on the board's underside.

Reachable actions: `lift`, `rotate`, `lock`/`unlock`, `delete`. `flick` is withheld from `board`
and from [`table`](https://diceytable.com/docs/mods/reference/object-kinds#table), and from no other kind
(`isObjectActionAllowedForTarget`'s `flick` case is `target.kind !== "board" && target.kind !== "table"`).

## Bag

A random-draw or ordered container that is not a deck of cards — a dice bag, a chip bank,
a Go bowl.

- **`containerMode`** — `"random"`, `"stack"`, or `"queue"`, selecting draw order. The host resolves it
  from this field first, then the legacy `metadata.containerMode` key, then the per-kind default
  (`random` for a `bag`, `stack` otherwise) — `resolveContainerConfig`,
  `packages/shared/src/tableContainers.ts`. Write the field.
- **`capacityLimit`** — 1–1000, resolved by the same precedence over the legacy
  `metadata.containerCapacity`. It refuses a `combine` that would overflow the target pile, and that is
  the only route it gates. The standard presets: 60 (Bowl), 100 (Bag), 200 (each Go Bowl), 1000
  (Infinite Bag).
- **`container`** — the replicated container configuration: `form` (`"holder"` or `"bag"`), `infinite`,
  and the piece `contents` of a finite bag. Every `bag` is given one on load, defaulting to
  `{ form: "bag" }`. A legacy `metadata.infinite` — the "Infinite Bag" preset's flag, which no code
  once read — is moved onto `container.infinite` and deleted from `metadata` by the same load. `form`
  and `infinite` already decide which container actions a target will accept
  (`isObjectActionAllowedForTarget`); the drop-to-absorb and infinite-draw behaviours they describe are
  still being built, so treat the rest of the field as configuration the platform records and validates
  rather than something that yet changes play.

Reachable actions: `lift`, `rotate`, `lock`/`unlock`, `draw`, `deal`, `flick`,
`delete`. Not `flip`, `split`, `combine`, `roll`, any `reveal-*`, or `shuffle` — a bag
draws at **random**, so it has no order for a shuffle to change.

## Custom

The escape hatch for anything that is not one of the other nine shapes — chess pieces,
dominoes, mahjong tiles, blocks, notecards, a digital clock, 3D text. Most of a mod's
custom-modeled content is `custom`.

- Collision defaults to `"auto"` in the *suggestion* function (`basePhysicsForKind`) —
  meaning "keep the runtime's current per-kind auto behavior" rather than a fixed
  primitive; author an explicit `physics.collisionShape` for anything with an unusual
  silhouette.
- `metadata` is where all of the kind-specific behavior lives, because there is no
  dedicated schema surface for it: `tokenShape`, `text` (the "3D Text" preset), and every
  other preset-specific key in [Standard presets](https://diceytable.com/docs/mods/reference/standard-presets).
- The "Card Holder" **preset** (id `card-holder`) is `kind: "custom"`, not
  `kind: "card-holder"` — see the next section for why that is not a contradiction.

Reachable actions: `lift`, `rotate`, `lock`/`unlock`, `flick`, `delete`. Same narrow set as
`token`.

## Card holder

A seat- or hand-associated holder entity. **Watch the naming**: the preset **id** `card-holder`
(labelled "Card Holder") is actually `kind: "custom"`, so its name is not a guide to its kind.
The one preset in `STANDARD_OBJECT_PRESETS` that really is `kind: "card-holder"` is the KayKit
`card-stand` ("Card Stand"). So a `card-holder` entity is usually authored directly (a spawn or
template with `kind: "card-holder"`), and there is exactly one catalog preset that spawns one.

It also has **no dedicated case** in any of the runtime's per-kind physics functions or in
`collisionHalfHeightForObject` — every one of those falls through to its generic `default`
case for `card-holder`, which is why the physics table above shows five "(default)" values
for this kind, more than any other.

**Holder behavior is driven by metadata, not by the kind.** A holder captures a card or deck
dropped within a scale-derived planar radius and stamps `metadata.holderId` on it; what makes an
entity act as a holder at all is `metadata.cardHolder === true`, so **any** kind can be one and
`card-holder` is simply the stock shape for it.

⚠ **A holder no longer confers a seat's ownership by itself.** It used to: a holder that had
drifted inside a seat's zone stamped every card it captured with that seat, competing with — and
quietly overriding — the seat's own hand zone. That implicit fallback was removed. What remains
is an **explicit** opt-in: set `metadata.holderOwnerSeat` and the holder is treated as that
seat's rack, cards included, exactly as before. With neither, seat membership comes only from
the seat's `hand` zone. A holder published *before* that opt-in existed is promoted on load —
its own `ownerSeat` is copied into `metadata.holderOwnerSeat` once, so an existing mod's rack
keeps gating who may take cards out of it. The promotion never overwrites a value you wrote,
including an explicit `null`. See
[Player Zones and seat templates](https://diceytable.com/docs/editor/working/zones-and-seats#hand-zone-or-card-holder)
for when to reach for which.

Reachable actions: `lift`, `rotate`, `lock`/`unlock`, `flick`, `delete` — identical to
`custom` and `token`.

## Button

A pressable control: a coloured cap sitting in a frame, with optional text or an image on its
top face. Pressing it dips the cap, plays a sound and raises the `press` action — which a
table or mod script observes as
[`onPressed`](https://diceytable.com/docs/scripting-api/types#buttonobjectonpressed).

Two presets ship it: **Button** (rectangular) and **Round Button**. They are the SAME kind —
`shape` is configuration, not a separate type — so everything below applies to both.

### Configuration

Everything about a button lives in `metadata.button`, validated by `buttonConfigSchema`
(`packages/shared/src/tableButtons.ts`). It is metadata rather than object-state fields on
purpose: metadata already travels through the schema, the snapshot delta, migrations and
persistence with no threading, and a button needs a dozen knobs, none of which the server
ever queries.

Every field has a default, and a field the schema rejects (a `travel` below its minimum, a
color that is not `#rrggbb`) is dropped on its own and takes that default; the rest of the
configuration is kept. Nothing reports the dropped field, so a button that ignores one setting
is worth checking against the ranges in `buttonConfigSchema`.

| Field | Default | What it does |
|---|---|---|
| `shape` | `"rect"` | `"rect"` or `"round"`. Round uses `width` as the diameter and ignores `depth`. |
| `width` / `depth` / `height` | 0.34 / 0.24 / 0.075 | The cap's footprint and how tall it stands, in table units (1 unit = 1 ft). |
| `travel` | 0.032 | How far the cap sinks on a press. Clamped to 80% of `height` at render time. |
| `pressSeconds` | 0.11 | Duration of the dip-and-return. |
| `colors` | see below | `cap`, `capPressed`, `frame`, `base`, `text`. |
| `frame` | on, 0.028 / 0.026 | The bezel: `enabled`, `thickness`, `height`. |
| `face` | `{ kind: "none" }` | `none`, `{ kind: "text", text, size, bold }`, or `{ kind: "image", texturePath, inset }`. |
| `eventName` | `"button-press"` | The name a press reports to scripts. |

`capPressed` is optional: leave it out and the runtime darkens `cap` by 22% for the held
state, which is usually what you want and always readable.

An **image** face is a repo-relative path resolved through the same `AssetResolver` as every
other asset, so it works local-first in the editor and from GitHub for remote peers. A
**text** face is drawn to a canvas locally and never crosses the wire — the same rule prop
surfaces follow.

### Geometry

The button is built from primitives at runtime, not from a `model.glb`. That is deliberate:
it is fully described by the numbers you are already editing, so it is correct the instant it
spawns, resizes live as you drag those numbers, and has no asset that can 404 (unlike most
prop presets, which render as placeholder boxes when their model file is absent). The stack,
bottom to top, is plinth → frame → cap → face, with the cap the only part that moves.

The object's `scale` IS `buttonOuterFootprint(config)` and every child is a fraction of it,
so there is exactly one place that decides how big a button is.

### Pressing

Click it. The press claims the pointer before the grab path — the same way a prop-surface
button does — so pushing a button never also starts dragging it.

A press is an ordinary `press` object action, which means it is host-authoritative and
replicated like any other mutation: a peer's click sends an intent, the host applies it, and
every client animates its own cap. The cap dip is **local cosmetics** and starts immediately
on click, because feedback that waits for a round trip feels broken.

**A locked button is still pressable.** Both presets ship `locked` because locking is how a
control stays put — a stray drag sliding the End Turn button across the table is never what
anyone meant — so `isObjectActionAllowedForTarget` exempts `press` from the locked gate.
Unlock it in the inspector to reposition it.

Reachable actions: `press`, `lift`, `rotate`, `lock`/`unlock`, `flick`, `delete`.

### Sound

The press sound rides the ordinary sound path: the `press` object action raises the `press`
runtime event, which `OBJECT_SOUND_EVENT_MAP.button` binds to the `press` sound action. For a
`plastic` (the default) or `generic` button that resolves to the bundled sharp click
(`counter.land`) rather than the `place` thud, which read as the button being dropped. To give
one button its own click, set a per-object override in `soundSetOverrides` — the same mechanism
every other kind uses, so there is no button-specific sound API to learn.

## Table

Furniture the game is played **on** — a dining table, a card table with a felt top, a glass
coffee table — placed as an entity inside a scene. The author-facing name is **Table**.

**Not the same thing as a table pack.** A [table pack](https://diceytable.com/docs/editor/workflows/assign-a-room-or-table)
is the surface a whole game sits on: it is assigned to a scene, it is not an entity, and it never
appears in the Hierarchy's `Entities` folder. A `table` entity is an ordinary scene entity that
happens to be furniture — a side table beside the play area, a second table in a room, or the
table itself when you would rather place it than assign a pack. Both carry a surface material,
and both colour the sound of what lands on them the same way.

- **It is always an authored model** — legs, rails, a recessed top — so its suggested collision
  shape is `"auto"` (built from the model) rather than a box. The `6 × 0.2 × 4` default scale and
  `#6b4a32` colour above are only the placeholder slab drawn while (or if) the model never loads.
- **Physics.** The runtime's per-kind functions have no `table` case, so every value in the
  physics table above is the generic default. The editor's *suggestion*
  (`defaultObjectPhysicsForKind`) is a static body with friction 0.8 and no bounce.
- **Static by kind, and locked from the Model editor.** A `table` is the one kind the runtime makes
  static on the strength of its kind alone: with no `physics.bodyType` it spawns static even when
  unlocked, so it never topples under its own legs. Static is not the same as unmovable, though —
  `locked` is what stops a player dragging it. Setting a model's Type to **Table** in the Model
  editor writes `locked: true` and `bodyType: "static"` into its sidecar (unless you had already
  set either), so a table placed from it is fixed; a table spawned by a script should pass
  `locked: true` itself. (A `board`, by contrast, is dynamic until locked — see
  [RIGIDBODY](https://diceytable.com/docs/editor/inspector/rigidbody).)
- **It is a surface.** A scripted deal or draw into a zone that sits over a table lands the card on
  the table's top, exactly as it would on a board, rather than on the pack's play-surface plane
  underneath.
- **It is never lifted out of a board.** The host's check that moves a piece authored *inside* a
  board up onto its floor (see [Board](https://diceytable.com/docs/mods/reference/object-kinds#board)) skips tables, so a table overlapping a board's
  footprint stays where you put it.
- **It survives a blank reset.** Starting a blank table keeps every `table` entity (and every
  locked `board`) and clears the rest — the furniture is not a piece of the game.
- **Sound.** Default material `wood`. `OBJECT_SOUND_EVENT_MAP.table` binds `release` and `settle`
  to `place`, `fall` to `fall` and `topple` to `topple` — the board's set without `board-clear`,
  because a table is set down and in principle knocked over, never swept. Its own sound matters
  far less than its **Surface**: every piece that lands on it is heard through that material, so
  a felt-topped table muffles a die and a glass one makes it ring. See
  [Sound material § Struck-surface tone](https://diceytable.com/docs/reference/enums/sound-material#struck-surface-tone).
- **Scripting.** A table script's `refObject` is a
  [`TableFurnitureObject`](https://diceytable.com/docs/scripting-api/types#tablefurnitureobject), which adds nothing to
  `ObjectHandle`; a table's starter script opens on `globalEvents.onObjectDropped`.

Reachable actions: `lift`, `rotate`, `lock`/`unlock`, `delete`. Not `flick` — the same exception
as `board` — and none of the container, card, die or button actions.

## Coin

A coin — a flat piece that does everything a [token](https://diceytable.com/docs/mods/reference/object-kinds#token) does, and can also be **tossed**.
Its Type in the Inspector's PIECE panel reads **Coin**, and its default label is `Coin`.

- **The built-in coins are coins.** The five built-in coin presets — `coin`, `coin-1`, `coin-2`,
  `coin-5` and `coin-10` — spawn as kind `coin`.
- **Your own coin model is a coin too.** Set an imported model's Type to **Coin** (in the
  Inspector's PIECE panel, or the Model editor's Type for its sidecar) and it tosses exactly like
  a built-in one. Nothing about tossing depends on the preset.
- **Older saves are upgraded on load.** Before this kind existed, the built-in coins were
  `token`s. `migrateTableSnapshot` rewrites a saved `token` whose `metadata.standardPresetVariant`
  is one of the five built-in coin variants (`BUILTIN_COIN_PRESET_VARIANTS`) to `coin`, and the
  runtime applies the same rewrite when it spawns an entity, so an already-published `setup.json`
  holding a coin token loads as a coin too. The rewrite is idempotent and does not change the
  snapshot's schema version. A `token` that is not one of those built-in variants — including a
  coin-shaped model you imported as a token — stays a token; change its Type to **Coin** to make
  it toss.
- **Physics, stacking and printed faces are a token's.** The runtime treats `token` and `coin`
  as the same flat piece (`isFlatPieceKind`): the same physics row above, the same disc collider,
  the same stacking, and the same `metadata.tokenShape` and printed-face keys
  (`tokenFaceImage`, `tokenFaceBackImage`, `tokenFaceFit` — see [Printed faces](https://diceytable.com/docs/mods/reference/object-kinds#printed-faces)).
- **Defaults that differ from a token's:** sound material `metal` (a token's is `plastic`), colour
  `#c9a227`, and a default scale of 0.08187 × 0.01575 × 0.08187 ft — the built-in coin's real
  size.
- **Sound.** `OBJECT_SOUND_EVENT_MAP.coin` is the token's set — `grab` → `pickup`, `release` →
  `drop`, `settle` and `collide` → `place`, `fall` → `fall`, `topple` → `topple`. A toss has no
  clip of its own.

### Flipping a coin

A coin offers **Flip** — turn over 180° in place — by default. It is flat by definition, so it
does not consult its shape the way a token does: `flippable` absent or `true` means it flips,
and only an explicit `flippable: false` (the Inspector's **PIECE ▸ Flippable**) turns Flip off.
Flip works exactly as it does for a [token](https://diceytable.com/docs/mods/reference/object-kinds#flipping-a-token): it changes the rotation and
nothing else.

### Tossing a coin

Every coin also offers **Flip Coin**, the `toss` action. In the context menu it reads **Flip
Coin**; the touch rail and the VR object menu shorten it to **Toss**. `toss` is different from
Flip: Flip turns the piece over in place, while a toss throws the coin straight up 6 to 12 in,
spinning end over end about a random horizontal axis with a slight sideways drift, and lets
physics decide which side lands up. The table's global speed limit caps the highest tosses at
about 11.5 in. The coin makes no sound of its own going up; you hear it land through its
ordinary settle and collide sounds. Nothing reports heads or tails. Read the coin's orientation
after it settles if your game needs the result.

The test is the kind and nothing else: `isTossableCoin(target)` is `target.kind === "coin"`. A
**locked** coin does not toss. The host refuses a toss on a locked coin, or on any entity that
is not a coin, on every path — its own menus and an AI agent included — with no log line and no
movement. A coin parented to another entity is held in place and is not thrown. Players, and AI
agents through `table_object_action`, can toss a coin. Table scripts and mods cannot request it;
a table script observes it as `"toss"` on `onObjectAction` / `onAction`, and a coin's own script
through [`CoinObject.onTossed`](https://diceytable.com/docs/scripting-api/types#coinobjectontossed). See
[Object actions](https://diceytable.com/docs/mods/reference/object-actions#the-kind-action-matrix).

The touch multi-select bar offers it for a selection made only of coins, and tosses every one of
them, the way an all-die selection rolls every die; a locked coin in the selection is refused.

- **Scripting.** A coin script's `refObject` is a
  [`CoinObject`](https://diceytable.com/docs/scripting-api/types#coinobject), whose one addition is `onTossed`; a
  coin's starter script opens on it.

Reachable actions: `lift`, `rotate`, `lock`/`unlock`, `flick`, `delete`, `flip` (unless
`flippable: false`) and `toss`. No container actions, `roll`, `combine`, or `reveal-*`.

## See also

- [Object actions](https://diceytable.com/docs/mods/reference/object-actions) — the full kind × action gating matrix.
- [Object state](https://diceytable.com/docs/mods/reference/object-state) — every `TableObjectState` field, kind-agnostic.
- [Standard presets](https://diceytable.com/docs/mods/reference/standard-presets) — the ready-made definitions built on these kinds.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — the three action vocabularies (engine/table-script/mod), a different axis from this page's per-kind gating.
- [`ObjectKind`](https://diceytable.com/docs/reference/enums/object-kind) — the eleven kinds the table-script declaration names.
- [Runtime sound events](https://diceytable.com/docs/reference/enums/runtime-sound-event) — the sound events these kinds emit.
- [`SoundMaterial`](https://diceytable.com/docs/reference/enums/sound-material) — the materials behind each kind's default sound, and how a surface colours what lands on it.
- [Mod scripting API](https://diceytable.com/docs/scripting-api/api) — `TableObjectState.kind`, reading a kind from a mod.
- [`ObjectHandle`](https://diceytable.com/docs/scripting-api/objecthandle) — `ObjectData.kind`, reading it from a table script.
- [Types](https://diceytable.com/docs/scripting-api/types) — `SpawnObjectOptions.kind`, choosing a kind at spawn.
