# Object state

> Every TableObjectState field and its 7 sub-collections — zones, snapPoints, vectorLines, decals, textLabels, joints and ui — with each schema.

- Source: https://diceytable.com/docs/mods/reference/object-state
- Last verified: 2026-09-30

`TableObjectState` is a [Scene Entity](https://diceytable.com/docs/editor/concepts/glossary#scene-entity)'s full
serialized state: what a `TableSnapshot` carries per entity, what replicates to every peer,
and what the persistence layer saves. Its schema is `tableObjectStateSchema` in
`packages/shared/src/tableObjects.ts`. `TableSnapshot` also carries **7 sub-collections**
for things that are not table objects — zones, snap points, vector lines, decals, text
labels, joints, and world-space UI — covered in the second half of this page.

> `packages/shared` type names were **not** renamed when the editor's user-facing labels
> changed (D-3 of the ECS work). `TableObjectState`, `label`, `displayName` and every other
> identifier below keeps its schema name even where the Inspector shows different English —
> see [ECS terminology](https://diceytable.com/docs/editor/concepts/glossary).

## The three names, at the schema level

Every entity carries three distinct name-shaped fields. Full treatment, including the
slug-normalization rules and the `Name`/`Slug` field split, lives at
[IDs, names and tags](https://diceytable.com/docs/editor/concepts/ids-names-tags); this section is the
field-by-field summary.

| Field | Schema type | Required | Addresses the entity? |
|---|---|---|---|
| `id` | `string`, 1–96 chars | yes | **Yes — the only one that does.** |
| `label` | `string`, 1–80 chars | yes | No. The slug: unique in the scene, machine-facing, and for `kind: "card"` the card's **identity** — it is what drives hidden-information redaction. |
| `displayName` | `string`, 1–80 chars, optional | no | No. The human name. Falls back to `label` when absent; `objectDisplayName()` is the one resolver every surface (Hierarchy row, entity name, status line, context menu) uses so they can never disagree. **Redacted with the card:** deleted from any copy — on the wire or from a mod read — whose viewer is not entitled to that `card`'s identity. |

Nothing — no script, no mod, no runtime lookup — resolves an entity by `label` or
`displayName`. `id` is assigned on creation and never edited by hand.

## `secretMetadata` — the place for a secret

`metadata` is public: apart from the two identity keys (`cardId` on a card, `cards` on a container)
it is identical in every copy of the snapshot. `secretMetadata` is the same shape
(`Record<string, unknown>`, any JSON value per key) with one difference — the host removes it
outright from any copy whose viewer is not entitled to the entity's identity. It exists so a card's
real identity has a home that is not the human-readable `Name`.

| Kind | Who receives it |
|---|---|
| `card` | Exactly whoever may see the card's face: it is face-up, or in the viewer's own hand, or revealed to the viewer's team. |
| `deck` | The host only, always. |
| every other kind | The host only, always. |

**A mod is not "whoever".** Since 2026-08-14 the six `read-world` reads answer as the
least-privileged viewer — a spectator with no seat and no team — on every peer including the host,
so a mod sees `secretMetadata` on exactly one thing: a card whose face is already public. Read the
table above as the *wire* rule; the mod rule is one line, and it is "no".

The card rule is the *same predicate* that governs `label` and `metadata.cardId`
(`isCardIdentityVisibleToViewer`) — there is deliberately no second notion of visibility to drift
out of sync with it. The deck and other-kind rule is the closed one on purpose: a deck has no
per-viewer identity concept at all (its ordered contents are withheld from every peer, D2), so
there is no entitlement to derive an answer from, and "host only" is the answer that cannot be
wrong. That also means the field can never be accidentally public on a kind nobody thought about.

Four things to know before you use it:

- **Capped at 2 048 bytes** of JSON per entity (`MAX_SECRET_METADATA_BYTES`), measured on the UTF-8
  encoding of `JSON.stringify(value)`. Over the cap the object fails schema validation. It rides on
  every entity of a snapshot capped at 5 000, which is why it is an order of magnitude tighter than
  the 16 KiB mod saved-data cap; anything bulky belongs in `modObjectSavedData`.
- **Absent, never `{}`.** An entity without a secret has no such field, so an empty bag can never
  enter a snapshot delta as a spurious change.
- **It is a replication boundary, not encryption.** The host's runtime holds it in full, and it is
  written to the save **unredacted** — a saved game keeps its full hidden state, so treat a save
  file as you would the host's own memory. Redaction is applied on the way *out* of the host: at
  the wire boundary, and — since 2026-08-14 — at the mod read boundary as well.
- **A mod running on the host does not read it.** That was true until 2026-08-14 and is the single
  most likely thing to trip up an existing mod. `read-world` no longer grants a frame the peer's
  own view; the elevated read is
  [`api.getUnredactedSnapshot`](https://diceytable.com/docs/scripting-api/api#apigetunredactedsnapshot), gated by the
  `read-hidden-information` capability, which a player can read in the mod's manifest.
- **A face-up card's secret is public.** The gate is the identity entitlement, not a separate
  switch. Anything that must stay hidden *after* a reveal does not belong here.

Absence is ambiguous: it means either "the author set none" or "you were not entitled", and nothing
distinguishes those. Write every mod rule to tolerate its absence, wherever the mod is running.

`migrateTableSnapshot()` **prunes** an over-cap or non-object `secretMetadata` on load rather than
rejecting the snapshot — the same policy as `parentId` below, for the same reason: a hand-edited
save must never be able to wedge a room.

## Field reference

Fields not already covered by [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) (which
covers the kind-specific meaning of `stackCount`, `containerMode`, `capacityLimit`,
`faceDown`, `metadata`) or the three-names table above:

| Field | Type | Notes |
|---|---|---|
| `kind` | `TableObjectKind` | See [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds). |
| `position`, `rotation`, `scale` | `Vector3Tuple` | Always **world-absolute** on the wire, even for a parented entity — every consumer (peers, mods, `listObjects`, the TTS/TTP bridges, saved games) already reads them as world, so keeping them local would make reconstruction order-dependent. |
| `color` | `string`, `#rrggbb` | Hex color; interpretation is kind-dependent (tint vs. accent). |
| `ownerSeat` | `string \| null`, ≤40 chars | The seat holding this entity in-hand. Any object with a non-empty `ownerSeat` counts as a hand card in `getHandObjectsFromSnapshot`, regardless of kind. |
| `locked` | `boolean` | Governs the [locked-entity action gate](https://diceytable.com/docs/mods/reference/object-actions#what-this-gate-is-for-and-what-it-is-not). Switches the rigidbody to static while locked; `unlock` restores the authored body type. |
| `tapped` | `boolean`, optional | Set by the `tap`/`untap` actions. Not gated by `isObjectActionAllowedForTarget` for any kind today — see [Object actions](https://diceytable.com/docs/mods/reference/object-actions). |
| `tags` | `string[]`, ≤100, each `[a-z0-9_-]` 1–32 chars | Author tags. The `dt:` prefix is reserved and unauthorable — see below. |
| `parentId` | `string \| null`, ≤96 chars, optional | The parent Scene Entity. Transform/organization only, never a physics constraint. `null` explicitly means "detached"; *absent* means "never parented" — the distinction matters for delta comparison (`strictEq`, which treats `null` and `undefined` as different values here). |
| `physics` | `ObjectPhysics`, optional | Per-object overrides (`bodyType`, `mass`, `friction`, `restitution`, `linearDamping`, `angularDamping`, `collisionShape`, `collisionSize`, `collisionOffset`, `rigidbodyEnabled`, `collisionEnabled`, `weldChildren`). Every field absent = use the runtime's per-kind default (see [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds#physics-defaults-at-a-glance)). |
| `components` | `ObjectComponentState[]`, optional | Optional engine components — see below. |
| `flippable` | `boolean`, optional | `token` only: whether it offers **Flip**. **Absent = decide from the shape** (flat pieces flip, tall ones do not), not `false`. Written at spawn from the model's [`.meta.json` `flippable`](https://diceytable.com/docs/mods/files/sidecars#flippable), editable per entity in the Inspector (**PIECE ▸ Flippable**), clearable over the wire. Ignored by every other kind: cards and decks always flip. See [Object kinds § Flipping a token](https://diceytable.com/docs/mods/reference/object-kinds#flipping-a-token). |
| `material` | `SoundMaterial`, optional | One of the 8 [sound materials](https://diceytable.com/docs/mods/reference/sound-sets); drives both the default sound set and (via `defaultObjectPhysicsForKind`'s suggestion path) editor placeholder physics. |
| `soundSetOverrides` | `Partial<Record<SoundAction, SoundRef>>`, optional | Per-`SoundAction` overrides; each value is a license-safe `SoundRef`, never a raw clip id. |
| `metadata` | `Record<string, unknown>` | The structured extension point, and **public** apart from the two identity keys — `cardId` is deleted and `cards` reduced to the publicly-visible front entry for a viewer not entitled to them, with `__redacted: true` set. Kind-specific data lives here — see [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) for what each kind actually reads. Keep it small: it rides in every snapshot. |
| `secretMetadata` | `Record<string, unknown>`, optional, ≤2 KiB of JSON | The **non-public** bag: stripped from any viewer not entitled to the entity's identity, which for a mod read means everyone. See [above](https://diceytable.com/docs/mods/reference/object-state#secretmetadata-the-place-for-a-secret). |
| `velocity`, `angularVelocity` | `Vector3Tuple` | Live physics state, present only on `TableObjectState` (not `TableObjectDefinition` — you cannot spawn an entity with a starting velocity). |

## Optional engine components

`components[]` is capped at **8** entries (`MAX_OBJECT_COMPONENTS`) with **at most one per
type**. The addable set today is `light` and `camera` (`OBJECT_COMPONENT_TYPES`) — **not**
`script`, which stays on `metadata.scriptId` with its own section, and not `render`,
`collision` or `rigidbody`, which are intrinsic to every entity and are configured through
`physics`/`metadata.materialId` rather than listed here. See
[ECS terminology §4](https://diceytable.com/docs/editor/concepts/glossary) for the two-tier reasoning.

- **`light`** — `{ type: "directional" | "omni" | "spot", color, intensity, range, innerConeAngle, outerConeAngle, castShadows }`, defaults to enabled.
- **`camera`** — `{ clearColor, fov, nearClip, farClip, projection, orthoHeight, priority }`, defaults to **disabled** on add and its `priority` is clamped by the runtime to stay below the table camera — a second enabled camera changes what the whole table renders through, so enabling one is a deliberate second action.

A component payload with a `type` this client does not recognize is **rejected at the
schema boundary**, not silently dropped — silently dropping it would let an older client
resave the entity and permanently discard a newer client's authoring.

## The reserved `dt:` tag namespace

Tags beginning `dt:` are platform-owned and cannot be authored: `OBJECT_TAG_PATTERN`
(`^[a-z0-9_-]+$`, case-insensitive) excludes `:`, so a setup file declaring `"dt:internal"`
fails schema validation outright rather than being accepted and ignored. They still appear
in anything that reads an entity's tags. Full list and rationale at
[IDs, names and tags](https://diceytable.com/docs/editor/concepts/ids-names-tags#the-reserved-dt-namespace).

## `parentId` and persistence — read this before assuming data loss

`TableSnapshot` itself carries **no explicit schema-version field** — the "v2" label lives
only in code comments and the `migrateTableSnapshot()` function name; everything ECS added
to `TableObjectState` (`parentId`, `components`, `displayName`,
`physics.rigidbodyEnabled`/`collisionEnabled`/`weldChildren`) is optional and additive on
top of that unversioned wire shape, so no migration bump was needed. `secretMetadata` landed
the same way — optional and additive, so an older save parses unchanged and there was again no
version bump.

`migrateTableSnapshot()` (`packages/shared/src/tableObjects/migrations.ts`) does one thing
to `parentId` on every load: it **prunes**, never backfills. Self-parents, dangling parent
references, cycles, and chains deeper than the configured maximum are all rewritten to
`null` before the snapshot is even parsed, so a hand-edited or corrupted save can never wedge
the runtime in an infinite parent walk.

On native (DiceyTable-format) export/import, `parentId` is **lossless** — the full schema
parses it like any other field. It is only the older, format-agnostic TTS/TTP bridge that
has a narrower field set, and that importer was recently *widened* (not narrowed) to also
carry `parentId`, `displayName`, `tags`, `tapped`, `physics`, `material`,
`soundSetOverrides`, `components`, `containerMode`, `capacityLimit` and `secretMetadata` where
the source data has them. Export is **unredacted** by design — a save keeps its full hidden
state — so an exported file carries every entity's `secretMetadata` in the clear. Treat a save
file as you would the host's own memory.

## The 7 sub-collections

`TableSnapshot` carries seven optional arrays beyond `objects[]`, each with a matching
`*DefinitionSchema` (spawn-time input) and `*StateSchema` (full serialized form) pair —
mirroring the `TableObjectDefinition` / `TableObjectState` split. All seven schemas live in
`packages/shared/src/tableObjects.ts`.

### Zones

A seat/interaction rectangle on the table (`tableZoneDefinitionSchema` /
`tableZoneStateSchema`). `id`, `label`, `position`, `size: { x, z }` (each 0 < value ≤ 24),
`rotationY`, `ownerSeat`, `interaction` (`allow` / `owner-seat-only` / `blocked`),
`visibility` (`all` / `owner-seat-only`), `metadata`.

### Snap points

A point that pulls a dropped entity into alignment (`tableSnapPointDefinitionSchema` /
`tableSnapPointStateSchema`). `id`, `label` (≤80, optional), `position`, `rotationY`,
`snapRadius` (0 < value ≤ 2), `ownerSeat`, `metadata`.

### Vector lines

A drawn/annotation line (`tableVectorLineDefinitionSchema` / `tableVectorLineStateSchema`).
`id`, `points` (2–1000 `Vector3Tuple`s), `color` (`#rrggbb`), `thickness` (0 < value ≤ 10),
`rotation`, `metadata`.

### Decals

A projected image on a surface (`tableDecalDefinitionSchema` / `tableDecalStateSchema`).
`id`, `name` (≤80), `url` (≤2048), `position`, `rotation`, `scale`, `metadata`.

### Text labels

Text drawn flat on the table (`tableTextLabelDefinitionSchema` / `tableTextLabelStateSchema`). `id`,
`text` (≤256), `position`, `scale` (0 < value ≤ 5), `color`, `fontSize` (0 < value ≤ 100),
`metadata`. How a label is drawn — yaw, line height, background plate, weight — lives under
`metadata.display` (`tableTextLabelDisplaySchema`, `packages/shared/src/tableTextLabels.ts`). An `id`
starting `script:` belongs to a table script's
[`world.setTextLabel`](https://diceytable.com/docs/scripting-api/world#worldsettextlabel).

### Joints

A physics constraint between two independently dynamic bodies
(`tableJointDefinitionSchema` / `tableJointStateSchema`) — never parenting; see
[the parenting/joint/weld split](https://diceytable.com/docs/editor/concepts/glossary#joint). `id`,
`type` (`fixed` / `hinge` / `spring`), `objectAId`, `objectBId`, `enableCollision`,
`breakForce` (0 < value ≤ 1,000,000), `metadata`.

### UI

World-space or screen-anchored mod UI (`tableUiElementDefinitionSchema` /
`tableUiElementStateSchema`, collected under `tableUiStateSchema` with a `revision`
counter). `id`, `parentId` (nesting within the UI tree, unrelated to entity `parentId`),
`type` (`text` / `button` / `checkbox` / `input` / `panel` / `canvas` / `layout`), `order`,
`ownerSeat`, `visibility` (`all` / `seat` / `team` / `players`, each scoped to a list),
`presentation` (`world`, or `screen` with an anchor + pixel offset), `layout`, `props`
(shape validated per `type` via a discriminated union), `metadata`, `ownerModId`.

## See also

- [Limits and caps](https://diceytable.com/docs/mods/reference/limits-and-caps) — the size cap on every array on this page.
- [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) — kind-specific field meaning.
- [IDs, names and tags](https://diceytable.com/docs/editor/concepts/ids-names-tags) — the full treatment of `id` / `label` / `displayName`.
- [Mod scripting API](https://diceytable.com/docs/scripting-api/api) — `TableObjectState`, the same fields as the mod declarations state them.
- [Mod hooks and capabilities](https://diceytable.com/docs/scripting-api/hooks-and-capabilities) — `ModTableEventPayload.object`, where a hook hands you one of these.
- [`ObjectHandle`](https://diceytable.com/docs/scripting-api/objecthandle) — `ObjectData`, the table-script view of the same entity, which is a different and smaller shape.
- [Types](https://diceytable.com/docs/scripting-api/types) — `SpawnObjectOptions`, the table-script side of creating one.

## `tableObjectDefinitionSchema`

Exported from `@diceytable/shared` as `tableObjectDefinitionSchema`. 63 fields across 7 tables.

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `id` | `string` | no | — | 1–96 chars | — | — | — |
| `kind` | `"card"` \| `"deck"` \| `"die"` \| `"token"` \| `"board"` \| `"bag"` \| `"custom"` \| `"card-holder"` \| `"button"` \| `"table"` \| `"coin"` | **yes** | — | — | — | — | — |
| `label` | `string` | **yes** | — | 1–80 chars | — | — | — |
| `position` | `vector3TupleSchema` | **yes** | — | — | — | — | — |
| `rotation` | `vector3TupleSchema` <br>same shape as `position` | no | — | — | — | — | — |
| `scale` | `vector3TupleSchema` <br>same shape as `position` | no | — | — | — | — | — |
| `color` | `string` | no | — | — | `^#[0-9a-f]{6}$` | — | — |
| `faceDown` | `boolean` | no | — | — | — | — | — |
| `locked` | `boolean` | no | — | — | — | — | — |
| `stackCount` | `integer` | no | — | >= 1, <= 1000 | — | — | — |
| `containerMode` | `"random"` \| `"stack"` \| `"queue"` | no | — | — | — | — | — |
| `capacityLimit` | `integer` | no | — | >= 1, <= 1000 | — | — | — |
| `tags` | `string[]` | no | — | <= 100 items; each 1–32 chars | `^[a-z0-9_-]+$` | — | — |
| `components` | `objectComponentSchema[]` | no | — | <= 8 items | — | 1 further cross-field rule (message built at validation time). | — |
| `displayName` | `string` | no | — | 1–80 chars | — | — | — |
| `tooltip` | `objectTooltipConfigSchema` | no | — | — | — | — | — |
| `physics` | `objectPhysicsSchema` | no | — | — | — | — | — |
| `castShadows` | `boolean` | no | — | — | — | — | — |
| `receiveShadows` | `boolean` | no | — | — | — | — | — |
| `flippable` | `boolean` | no | — | — | — | — | — |
| `material` | `soundMaterialSchema` | no | — | — | — | — | — |
| `soundSetOverrides` | `soundSetOverridesSchema` | no | — | — | — | — | — |
| `materialSlots` | `materialSlotsSchema` | no | — | — | — | materialSlots may not hold more than 64 entries. | — |
| `metadata` | `Record<string, unknown>` | no | — | — | — | — | — |
| `faceValue` | `integer` | no | — | >= -9999, <= 9999 | — | — | — |
| `overlay` | `tableObjectOverlayStateSchema` | no | — | — | — | — | — |
| `ownerSeat` | `string` \| `null` | no | — | <= 40 chars | — | — | — |
| `seat` | `"red"` \| `"blue"` \| `"green"` \| `"yellow"` \| `"purple"` \| `"orange"` \| `"pink"` \| `"cyan"` \| `"white"` \| `"brown"` | no | — | — | — | — | — |
| `parentId` | `string` \| `null` | no | — | 1–96 chars | — | — | — |
| `diceTray` | `diceTrayCustodySchema` | no | — | — | — | — | — |
| `secretMetadata` | `secretMetadataSchema` | no | — | — | — | secretMetadata exceeds 2048 bytes when JSON-encoded. | — |
| `container` | `containerStateSchema` | no | — | — | — | 1 further cross-field rule (message built at validation time). | — |

### `id`

The address, and the only thing that resolves an entity — neither `label` nor `displayName` does. Leave it
out and the host mints a UUID as it creates the entity (`createObject`,
`apps/web/src/playcanvas/TabletopRuntime.ts`), which is right for most entries: a piece nothing points at
never needs a name you chose.

Write one when something has to reach this entity — another entry's `parentId`, or a script that looks it
up. Uniqueness is then yours to keep. The runtime indexes objects by id and nothing rejects a repeat, so a
second entry claiming an id takes the address over and strands the first entity with nothing able to name
it. [Ids, names and tags](https://diceytable.com/docs/editor/concepts/ids-names-tags) has the full three-name split.

### `kind`

The one field with no default and no way back. `kind` fixes the collider and the mass, the fallback size
and color, the sound material, and which actions the entity answers — nothing in the intent vocabulary
changes it afterwards, so a different kind is a different entity. (The one rewrite is on load: a saved
`token` wearing a built-in coin preset variant becomes a `coin`.)

Most of the rest of this schema is scoped by it: `stackCount` means something only on `deck`, `faceDown`
only on `card` and `deck`, `scale` and `color` are ignored on both. `custom` is the escape hatch for an
imported model. [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) walks all eleven and what each is for.

### `label`

The slug — the machine key, unique in the scene, and the field Edit Mode's Inspector shows as `Slug`. It is
what a table script reads as `ObjectData.name`, and for `kind: "card"` it is also the card's identity:
`customDeckCardIdForObject` falls back to `label` when `metadata.cardId` is absent, and
`redactObjectForViewer` (`packages/shared/src/tableObjects/redaction.ts`) overwrites it with `Card` when a
viewer isn't entitled to see that card. Renaming a card for readability changes which card it is.

The schema checks only the length, so `Chess Board` parses here. Keep it lowercase, digits and dashes
anyway — that is what the editor writes and what every machine reader expects. `displayName` is where the
capitals and the spaces belong.

### `position`

Where the entity starts, in feet, and the only geometry field you must supply — `rotation` and `scale` both
fall back to per-kind defaults. The three numbers are **world-absolute even when `parentId` is set**:
parenting preserves the world transform rather than reinterpreting them as an offset from the parent, so a
child written at `{ x: 0, y: 1, z: 0 }` is one foot above the table origin, not one foot above its parent.

Spacing is yours to get right. Nothing de-overlaps a setup for you, so two dynamic entries sharing a spot
spawn interpenetrating and the solver pushes them apart on the first frame — a starting layout that looks
tidy in the file and scatters the moment the table loads.

### `rotation`

Euler angles in **degrees**, world-absolute, applied as the entity is created. Absent means
`{ x: 0, y: 0, z: 0 }`.

`y` is the yaw, and it is the one you almost always want: it turns a board to face a seat, or fans tokens
around the table without tipping them. `x` and `z` tip a piece off its resting face, which for a dynamic
body is a starting pose and not a resting one — a die authored at 30° on `x` falls flat as soon as the
simulation runs. Use them for furniture you have also marked `locked`, where nothing is going to knock the
angle back out.

### `scale`

The entity's local scale. For every built-in piece — the primitive shapes and the built-in preset models
alike — the three numbers are the piece's full size in feet (a built-in model is drawn at
`scale / referenceScale` of its true-size GLB, so its preset size is exactly its real size). On an
imported or project model they multiply the model's own dimensions instead, so `1, 1, 1` is the model
as authored.
Absent means the per-kind default (`normalizeObjectScale`,
`apps/web/src/playcanvas/physics/PhysicsEngine.ts`) — a die is 0.05 ft on a side, a board 1.2 × 0.9 ft.

Applies to: `die`, `token`, `board`, `bag`, `custom`, `card-holder`. On `card` and `deck` the host derives
the scale from the poker-card footprint and the stack height, at creation and again on every stack change
(`syncStackScale`), so whatever you write is discarded. A deck gets taller by holding more cards, not by
being scaled.

### `color`

The base tint of the primitive shape the entity spawns with. The pattern in the table above is matched
case-insensitively — a flag the column cannot show — so `#4F7CFF` parses as readily as `#4f7cff`, though
the editor always writes lowercase.

Applies to: `die`, `token`, `bag`, `custom`, `card-holder`, and `board` — except that a board carrying
`metadata.boardImageUrl` or `metadata.boardStyle` replaces its material outright and stops using `color`,
and so does any entity carrying a `metadata.materialId` that resolves to a project material. On `card` and
`deck` it is ignored entirely: those render through the shared card materials, so their faces come from the
deck art and their edges from the card body.

### `faceDown`

Which way up the entity starts. Absent means `false` everywhere except `kind: "deck"`, where the host
defaults it to `true` — a deck you say nothing about arrives backs-up, which is what a draw pile wants and
what a face-up discard pile has to opt out of.

Applies to: `card`, `deck`. On any other kind a full definition accepts the field and nothing reads it,
while a template or template reference that sets it is rejected outright. It is the other half of the
hidden-information rule: a face-up card is public to every peer regardless of `ownerSeat`, and only a
face-down one is redacted on the wire.

### `locked`

Freezes the entity. The host gives it a static body at creation and the pick, drag and transform paths all
skip it, so nothing a player does moves it. Absent means `false`.

This is the field for furniture — a board, a card rack, a scoreboard prop — that should stay exactly where
you placed it while the game happens around it. It also propagates upward through parenting: a grab on a
child stops escalating at a locked ancestor instead of dragging the whole assembly by it. The authored
`physics.bodyType` is left untouched, so unlocking restores the body the entity would otherwise have had.

### `stackCount`

How many cards a pile starts with, and the number its body height comes from — a deck is `stackCount`
sheets thick, each sheet the deck's paper thickness. That is 0.3 mm unless the deck carries its own
`metadata.paperThicknessMm` (0.05–3, set as **Paper thickness (mm)** in the Inspector's
[PIECE](https://diceytable.com/docs/editor/inspector/piece#paper-thickness-card-and-deck-pieces-only) panel), so a 52-card pack
stands 15.6 mm — about as tall as a real one.

Applies to: `deck`. This schema carries no cross-field refinement (the template schema does), so a `token`
or a `board` with a `stackCount` parses here and nothing ever reads it.

It is not the field that fills the deck. The host builds the contents from `metadata.cards`, or from
`metadata.customDeck`, or — given neither — from a standard 52-card French deck, then overwrites
`stackCount` with however many entries it built. Ask for 10 and name no cards and you get 52. Name the
cards and let the count follow.

### `containerMode`

Which end of a container a draw comes off: `stack` takes the card showing on the pile's face, `queue` takes
the one at the back, `random` picks any of them. Applies to: `deck` and `bag`, the two kinds that answer
`draw` and `deal`. On the other six the field parses and nothing consumes it.

This is the control, and writing it here is enough. `resolveContainerConfig`
(`packages/shared/src/tableContainers.ts`) owns the precedence — this field first, then the legacy
`metadata.containerMode` key, then the per-kind default (`random` for a `bag`, `stack` otherwise) — and both
draw paths reach it through `containerDrawModeFor` in `apps/web/src/playcanvas/TabletopRuntime.ts`, so the
host and every peer resolve the same answer. A `metadata.containerMode` on an older object still works, but
it is legacy: `migrateTableSnapshot` moves it onto this field and deletes the key on load, so after one save
cycle there is exactly one spelling of the draw order.

### `capacityLimit`

The ceiling on a container's contents, 1–1000. Applies to: `deck` and `bag`.

This is the number the host enforces. `containerCapacityFor`
(`apps/web/src/playcanvas/TabletopRuntime.ts`) resolves it through `resolveContainerConfig` — this field
first, then the legacy `metadata.containerCapacity` key, then unlimited — and refuses a `combine` whose
result would exceed it. A legacy `metadata.containerCapacity` still works but is migrated onto this field and
deleted from `metadata` on load, so write the field.

The check runs on the **merge target**, and it is the only capacity check in the runtime: nothing tests it
when a card returns to a pile by any other route, so a container can end up holding more than it declares. A
refused merge is silent — both piles simply stay as they were.

### `tags`

Author tags — the cheap grouping mechanism, and what a script's `tag` / `tags` filters match against. They
cost no schema and they are many-to-many, which makes them the right way to say "these twelve tokens are
the red army" when `id` can only say "this one token."

The character class is lowercase letters, digits, `_` and `-`. `:` sits deliberately outside it, and that
omission is the entire reason the platform's reserved `dt:` namespace — `dt:object`, `dt:internal`,
`dt:kind:card` — cannot be written from a mod (`packages/shared/src/objectTags.ts`). Uppercase fails the
parse here rather than being folded down for you, so `Red` rejects the file where `red` passes; the
runtime's `normalizeObjectTags` lowercases and de-duplicates only what reaches it later. See
[Tags and groups](https://diceytable.com/docs/editor/working/tags-and-groups).

### `components`

Optional **engine** components on this entity, and the addable set is exactly two: `light` and `camera`.
The intrinsic three — `render`, `collision`, `rigidbody` — are on every entity already and are configured
through the entity's `physics` state and `metadata.materialId`, never listed here and never removable.
Scripts are not in this array either: an object script attaches through `metadata.scriptId`.

At most one entry per type — that is the cross-field rule the table refers to, and a duplicate `light`
rejects the file rather than being ignored. A `camera` entry defaults to `enabled: false` on purpose: the
engine renders through every enabled camera, so switching a second one on puts the whole table inside your
prop. [Add component](https://diceytable.com/docs/editor/inspector/add-component) covers the same two from the Inspector side.

### `displayName`

The human name — free-form, capitals and spaces welcome (`Chess Board`). It fills the Hierarchy row, the
Inspector's `Name` field and `pc.Entity.name`, and when it is absent every one of those falls back to
`label` (`objectDisplayName`, `packages/shared/src/tableObjects.ts`), so an entity is never nameless.

Nothing resolves an entity by it; that is `id`'s job. A mod can read it back off `TableObjectState`, but a
table script cannot see it at all — `ObjectData.name` is the `label`. Set it whenever the slug you need for
machines is not the phrase you want a player to read.

### `tooltip`

The entity's authored **hover tooltip**: whether hovering it at the table shows one, the title and description
templates, whether the built-in detail lines appear, and named variables the templates read. Authored in the
Inspector's [TOOLTIP section](https://diceytable.com/docs/editor/inspector/platform-panels#tooltip) and changed at play time only by a
table script (`setTooltip` / `setTooltipVariable`, via the host-only `set-object-tooltip` intent).

**Absent means no tooltip**, and absent is the default. Every entity starts without this field, and every entity
in a save or setup file written before authored tooltips existed has none — so hovering shows nothing until an
author enables it. `enabled: false` means the same to a player but keeps the text, so switching it back on
restores it. A config that is disabled and carries nothing else is normalised away to "absent", so the two
encodings of "off with no text" cannot both reach the wire.

It is on the definition, not only on live state, because it is a property of the **piece**: it is saved with the
scene, rebuilt with the entity after a host migration, and carried with a card into a container and back out.

⚠ Redacted with identity. A tooltip can name a card as surely as its `displayName` does, and a script-set
variable can hold anything, so the whole field is stripped from the copy sent to any viewer not entitled to the
entity's identity — a face-down or team-hidden card, and anything in a hidden zone. One carve-out: a **deck's**
own tooltip describes the pile, not a card, so it stays visible while the deck is face down and is withheld only
by a hidden zone. Nothing here makes text secret on a card that is later turned face up.

### `physics`

Per-object physics, overriding the per-kind defaults field by field. Absent fields keep the default, so
`{ "collisionShape": "sphere" }` changes the collider and nothing else. An absent `physics` object entirely
means the entity is whatever its `kind` says it is: see `defaultObjectPhysicsForKind`
(`packages/shared/src/tableObjects.ts`) for the per-kind starting point.

The reason this is on the **definition** and not only on live state is that a spawn has to be able to carry
it. A setup file that places a modelled piece usually needs the collider matching its silhouette, and until
it could be written here the only way to get one was to edit the object after it existed. The built-in
checkers, go stones and Chinese-checkers marble use exactly this: each names the analytic shape its mesh
actually is, instead of taking the box a `token` would otherwise get.

### `castShadows`

Whether this entity casts a shadow. **Absent means "inherit", not "off".**

Three levels resolve it, most specific first:

1. `castShadows` on the entity, here — an explicit `true` or `false`.
2. The model's per-asset default: [`castShadows`](https://diceytable.com/docs/mods/files/sidecars#castshadows) in its
   `.meta.json` sidecar. That one is authoring config for the whole model, read locally by every
   peer from the mod tree, and never appears in a snapshot.
3. `true`. Every entity kind casts by default, so an existing table looks exactly as it did.

Because absent and `false` are different answers, write the key only when you mean to override the
model. Leaving it out is how an entity keeps following its model's default; setting it to `false`
opts that one entity out even when the model casts.

Shadow rendering is the single largest per-frame cost on a busy table — the shadow pass redraws every
casting mesh from the light's point of view — so this is the field to reach for on entities that
cannot visibly benefit: a flat playmat lying on the table, a backdrop, a large low decorative prop.
Turning it off on the pieces players actually look at is a visual downgrade for very little, and the
runtime already skips the shadow pass entirely while nothing is moving.

Replicated per entity, so changing it reaches every player, survives a save, and can be cleared back
to "inherit".

### `receiveShadows`

Whether shadows are drawn **onto** this entity. **Absent means "inherit", not "off".**

The mirror of [`castShadows`](https://diceytable.com/docs/mods/reference/object-state#castshadows) and resolved the same way: the value
here, else the model's per-asset default
([`receiveShadows`](https://diceytable.com/docs/mods/files/sidecars#receiveshadows) in its `.meta.json`), else `true`.

The two are independent, and the useful configurations are not symmetric. A table surface or playmat
usually wants `castShadows: false` with receiving left on — it is what the pieces cast onto, so
losing that is the one shadow players actually read. An entity that glows or is meant to look
self-lit is the opposite case: leave casting alone and set `receiveShadows: false` so nothing darkens
it.

Turning receiving off is cosmetic, not a performance lever. The cost of the shadow pass is driven by
what **casts**, not by what receives.

Replicated per entity, so changing it reaches every player, survives a save, and can be cleared back
to "inherit".

### `flippable`

Whether this `token` offers **Flip**. **Absent means "decide from the shape", not "off".**

Resolution, most specific first:

1. `flippable` on the entity, here — an explicit `true` or `false`. A model's
   [`.meta.json` `flippable`](https://diceytable.com/docs/mods/files/sidecars#flippable) lands here at spawn, and the
   Inspector's **PIECE ▸ Flippable** writes it (its **Auto** option removes it).
2. The shape: a token whose world-space height is at most half its narrower footprint is flat and
   flips (`isFlatTokenShape`, ratio `FLAT_TOKEN_MAX_HEIGHT_RATIO = 0.5`). A checker or coin flips;
   a meeple, a miniature or a cube does not.

A token that may flip turns over in place about its own X axis and does **not** toggle `faceDown`.
A token that may not flip has no Flip in any menu, and the host refuses a `flip` sent to it from
any source — a player, a table script's `handle.flip()`, or a mod's `api.objectAction`. See
[Object kinds § Flipping a token](https://diceytable.com/docs/mods/reference/object-kinds#flipping-a-token).

The participant gate (`isObjectActionAllowedForTarget`) reads only an explicit `false`; the shape
default is applied by the host's runtime, which has the geometry. Write the key only when the shape
gets it wrong.

Ignored for every kind but `token`: cards and decks always flip, other kinds never do. Replicated
per entity and clearable, so removing it reaches every peer as a return to the shape default.

### `material`

The entity's physical material, and despite the name this is a **sound** field: it decides which built-in
clip set every interaction resolves to, and it is the **struck surface** other pieces are heard through when they
land on this one (felt muffles, glass and stone ring). `felt`, `cloth`, `glass` and `stone` have no clips of their
own and borrow cardboard's or tile's when this entity is the one moving. `silent` is the sentinel for "make no noise at all". The visual
material is `metadata.materialId` — different key, different system, easy to reach for by mistake.

Absent means the per-kind default: `card` for `card` and `deck`, `plastic` for `die`, `token` and `button`,
`wood` for `board`, `card-holder` and `table`, `tile` for `bag`, `generic` for `custom`. Setting it in a setup file changes
sound only — the matching weight and friction live on `physics`, so a `metal` token becomes heavier as well
as louder only if you set both.
See [Sound sets](https://diceytable.com/docs/mods/reference/sound-sets) and [SoundMaterial](https://diceytable.com/docs/reference/enums/sound-material).

### `soundSetOverrides`

Per-action sound replacements for this one entity, keyed by sound action (`place`, `pickup`, `drop`,
`slide`, `shuffle`, `roll`, `fall`, `topple` and the rest). Each value is either
`{ kind: "builtin", material }` — borrow another material's clips for that action — or
`{ kind: "mod", modId, name }`, naming a set your manifest declares. A raw clip id, path or URL is not
expressible here, and that is a licensing boundary rather than an omission.

Resolution runs override first, then your mod's default mapping, then the built-in set for `material` or
the kind (`resolveSoundRef`, `apps/web/src/playcanvas/audio/`). Reach for an override when one entity
should sound unlike everything else of its material: a bell token that rings, a coin that lands soft.
See [Sound sets](https://diceytable.com/docs/mods/reference/sound-sets).

### `materialSlots`

Per-slot visual material assignment for an entity with a multi-material model: a map from a **source
material name** to the material to use in its place. The key is the name the material carries *inside the
model file* — `"TimerScreen_mat"`, `"d20_mat"` — which is also the name the Edit Mode slot list shows you.
The value is a material id: a `builtin:` preset or a project material's guid.

```json
{
  "kind": "custom",
  "label": "timer",
  "position": { "x": 0, "y": 0.2, "z": 0 },
  "materialSlots": {
    "TimerScreen_mat": "builtin:felt",
    "TimerCase_mat": "builtin:metal"
  }
}
```

**Keyed by name, never by mesh index.** Indices are an artifact of how the model was exported: adding a
mesh, reordering the export, or re-running an optimizer renumbers them, and an index-keyed assignment then
quietly points at a different part of the model with nothing to show for it. The material name survives all
of that. If a model genuinely uses one name for two materials they share a slot — the honest trade against
silent mis-assignment.

Four levels resolve what a given part of the model renders with, most specific first:

1. `materialSlots["<that part's source material name>"]`, here — an explicit assignment always wins.
2. [`metadata.materialId`](https://diceytable.com/docs/mods/reference/object-state#metadata) — the all-slots shorthand, unchanged and still fully supported. It is
   the fallback for every slot with no explicit entry, so a single-material entity needs nothing else and
   anything already setting it keeps behaving exactly as it did.
3. The model's own default binding (its sidecar's [`materialSlots`](https://diceytable.com/docs/mods/files/sidecars)) — the
   model's default look. Anything set on the entity, including `metadata.materialId`, overrides it.
4. The material embedded in the model.

A name that matches nothing in the model is inert, not an error, and a material id that resolves to nothing
leaves that slot on its model material — so a stale entry after a re-export degrades to the original look
rather than to a missing-texture entity.

At most 64 entries, keys up to 96 characters and ids up to 128. Replicated per entity, so an assignment
reaches every player, survives a save and an export, and can be cleared back to the model's own materials.

### `metadata`

The unvalidated escape hatch, and in practice where a good deal of an entity lives. It replicates and
persists like every other field, and nothing checks its shape, so a misspelled key is silent rather than a
scan error.

The runtime reads real behavior out of it: `cards` and `customDeck` (a deck's contents and its art),
`cardId` (a card's identity when `label` is not it), `standardPresetId`, `tokenShape`, `boardImageUrl`,
`materialId` (the visual material), `scriptId` (the object script to attach) and `grabbableWhileParented`.
`containerMode`, `containerCapacity` and `infinite` are **legacy** container keys: they are still read as a
fallback, but the first-class `containerMode` / `capacityLimit` / `container` fields outrank them and a load
moves them across and deletes them. `__redacted` is the host's own marker, written onto the wire copy
of an entity a viewer isn't entitled to see — never author it yourself.

### `faceValue`

The number printed on the face a settled die is showing, exactly as printed. The host computes it when
the die comes to rest and replicates it, so every peer reads the same number instead of each client
guessing at the geometry itself.

Absent means **no value** — never `null`, never `0`. A die that is tumbling, held or cocked (leaning on
a piece, wedged against a wall, or resting past half the angle between two of its faces) has no face to
read and the field is dropped rather than left stale; a die imported as a custom model carries no face
table and never gets one, which is why its tooltip — once an author has
[enabled one](https://diceytable.com/docs/editor/inspector/platform-panels#tooltip) — has no `Value` line and an empty `{value}`. There is
deliberately no default. The field is bounded to whole numbers from `-9999` to `9999` rather than
assumed positive, so a die that prints `0` or a negative is representable — and a default of `0` would
then make "settled on zero" indistinguishable from "not settled".

Applies to: `die`. Every other kind accepts the field in a full definition and nothing ever reads or
writes it. The dice shipped as standard presets print `1`–`sides`, including the d10, which is numbered
`1`–`10` here rather than `0`–`9`.

It is on the definition, not only on the state, because the runtime rebuilds an entity field by field
from whatever definition it is handed — on first sight of an object, and for **every** entity on the
table after a host migration. A field that lived only on the state would be dropped on exactly those
paths, and a die at rest never settles again, so its number would be lost for good.

⚠ Redacted with identity. A die inside a hidden seat zone does not publish what it landed on: the field
is stripped from the wire copy sent to any viewer not entitled to that entity's identity, the same way
`label` and `secretMetadata` are. Nothing in the schema itself makes it secret.

### `overlay`

Live **overlay values** and **counter counts** — the only part of the card overlay / counter feature that
is ever replicated.

A card overlay has two halves and the split is the whole design. Everything *presentational* — the region
rectangle a value is drawn into, its font size and colour, a counter's art, anchor and stacking mode, and
the layout template that decided which regions apply to this card at all — lives in the mod's
`data/cardSchema.json` and is resolved **locally** by every client from the mod's own repo. None of it is
expressible here. What crosses the wire is numbers:

```json
{ "values": { "pwr": 2, "tou": 2 }, "counters": { "plus-one": 3 } }
```

`values` is keyed by the **mapped field key** your schema already declares in `fields[]`, so a card's live
power really is "the `pwr` field, plus a delta" and a script reading it needs no translation table.
`counters` is keyed by counter definition id.

A spawn may carry this, so a mod's `setup.json` can place a card that starts with counters on it. Carrying
it on the definition is also what makes it survive an entity being **rebuilt** — first sight of an entity on
a joining peer, an editor Type change, and every entity on the table after host migration.

Changing a value on an entity that already exists is a different operation with a different gate: send a
[`card-overlay-set`](https://diceytable.com/docs/mods/reference/intents) intent. The host resolves the region or counter
definition from **its own** copy of `data/cardSchema.json`, refuses any key no definition declares, and
checks the per-definition `mutation` permission (`host` / `controller` / `seated` / `script`). None of that
depends on your UI having hidden a button.

**Per-entry visibility is redaction, not rendering.** Each region and counter declares `visibility:
"hidden" | "count-only" | "full"`, defaulting to `hidden`, and the host **strips** concealed entries from the
snapshot it sends to a peer who is not entitled to that card's identity. Nothing in this bag makes a value
secret by itself; the declaration in the card schema does.

### `ownerSeat`

Which seat holds this entity. `null` — the default — means the shared table. The ten seats are named
`red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`, `white` and `brown`; the schema only checks the length,
so a misspelled seat parses and then matches nobody.

It does two jobs. On a `card` it makes the body kinematic, which is what keeps a hand card from falling.
And on `card` and `deck` it is half the hidden-information rule: a face-down card *with* an owner is
visible to that seat and that seat's team, while a face-down card *without* one is host-only. Treat an
authored value as a starting state rather than a binding: the host recomputes `ownerSeat` from the entity's
position every time a player drops it, so a seat you wrote but did not place inside that seat's zone is
cleared on the first move.

### `seat`

The seat this entity **belongs to** — a seat id (`red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`,
`cyan`, `white`, `brown`), or absent for none. White's chess pieces carry `white`; a player's army carries theirs.
It is authored in the Inspector's **Seat** field, or for a whole folder or selection in `GROUP EDIT`, and a table
script reads it as `handle.seat`.

**Purely informational.** It changes nothing at the table: not visibility, not hidden-information redaction, not
physics, not who may pick the entity up. That is the difference from `ownerSeat`, which means "this card is in
that seat's hand" and is what conceals a hand from everyone else — putting chess pieces in a seat's hand would hide
them from the opponent. It is also not the seat template, which clones a holder per claimed seat; an entity with a
`seat` is one fixed entity.

Optional and clearable: "No seat" removes the key, and that replicates. A value that is not one of the ten seat
ids is dropped on load rather than failing the snapshot. Like `parentId` it describes where an entity stands, so a
container does not store it — an entity taken back out of a bag has no seat.

### `parentId`

The entity this one is attached to; absent or `null` makes it a root. Parenting is transform and
organization: the child is held kinematic so it cannot fight its parent's body, and `position` stays
world-absolute because the host preserves the world transform when it attaches. Chains cap at eight deep,
and a `parentId` naming a missing entity, itself, or anything that closes a cycle is pruned to `null` on
load rather than trusted.

Grabbing a child moves the whole assembly. That is deliberate — "I glued this token to its base, so moving
it should move the base" — and the per-child opt-out is `metadata.grabbableWhileParented`. For two pieces
that should both keep simulating while staying connected you want a joint instead. A mod reads this field
back off `TableObjectState`; a table script cannot see it at all.
See [Parenting](https://diceytable.com/docs/editor/working/parenting) and [Welding](https://diceytable.com/docs/editor/working/welding).

### `diceTray`

Marks a die as still belonging to the player who rolled it. Present on a die that is sitting where it landed
after a roll; **absent on every other entity and on every die a player has picked up and placed**.

Three fields, all required when the record is present: [`seat`](https://diceytable.com/docs/mods/reference/object-state#dicetrayseat), [`peerId`](https://diceytable.com/docs/mods/reference/object-state#dicetraypeerid) and
[`rollId`](https://diceytable.com/docs/mods/reference/object-state#dicetrayrollid). You do not author it — the host writes it when it spawns the dice for a roll and
unsets it when a player takes one — but it is in the snapshot, so a script or a save inspector will meet it.

**Two behaviours hang off its presence and nothing else.** Clearing a roll removes the dice the roller still
holds, which is exactly the dice that still carry this field; and a die in custody sits in a dedicated collision
group whose mask admits only the table surface, the roll region's walls and other rolling dice, so a roll cannot
shove the board around. Picking a die up and placing it unsets the field, which promotes it back to the ordinary
dynamic group — a kept die is an ordinary die again, collides with everything, and survives every subsequent
clear. That promotion is the feature: "roll, then keep some dice" is why rolled dice are real entities rather
than an animation.

**Applies to: `die`.** A custody record on any other kind is dropped on load, the same way `faceValue` is —
nothing writes it there, nothing would ever clear it, and a stray record would leave a permanent entity that a
clear can delete and that other entities pass through. The same normalisation drops a malformed record rather
than failing the whole snapshot, so a hand-edited save cannot wedge a room.

**It is public.** Dice are not hidden information: whose roll a die came from is already visible from where it
is sitting, so this field is not redacted for any viewer. It also cannot carry an identity leak onto a card,
because the load-time normalisation deletes it from anything that is not a die.

⚠ If you are writing a tool that edits snapshots, an unset that fails to arrive has two visible faces — a kept
die that a later clear deletes, and a kept die that other entities pass through. Clear the field by removing it,
never by writing a placeholder record.

### `secretMetadata`

The property bag that does **not** reach every player. It is shaped exactly like
[`metadata`](https://diceytable.com/docs/mods/reference/object-state) — a `Record<string, unknown>`, any JSON value per key —
and the one difference is the only thing that matters: the host strips it from the snapshot it sends to any
peer who is not entitled to that entity's identity.

The per-kind rule, enforced in `redactObjectForViewer` (`packages/shared/src/tableObjects/redaction.ts`):

| Kind | Who receives `secretMetadata` |
|---|---|
| `card` | Exactly whoever may see the card's identity — a face-up card, a card in the viewer's own hand, or one revealed to the viewer's team. A face-down card on the table, or in someone else's hand, is stripped. |
| `deck` | The host only, always. A deck has no per-viewer identity notion at all — its ordered contents are already withheld from everyone — so there is no entitlement to grant one from. |
| every other kind | The host only, always. Same reason: no entitlement exists, so "visible" cannot be justified. |

That table is the **wire** rule. A mod script is judged against it as a spectator with no seat and no team,
on every peer including the host, so the only `secretMetadata` a `read-world` read ever carries is a face-up
card's — which by then is not a secret. To read your own secret back while the card is still face down,
declare `read-hidden-information` and use
[`api.getUnredactedSnapshot`](https://diceytable.com/docs/scripting-api/api#apigetunredactedsnapshot).

This is the sanctioned home for *"which card is this really"*. `label` is a card's identity and is rewritten
to `Card` when hidden; `displayName` is the human name and is removed when hidden — but both are visible the
moment the card is face-up, and both are the fields the editor puts in front of an author. Put the answer
here instead of encoding it in a name.

**Capped at 2 048 bytes** of JSON per entity (`MAX_SECRET_METADATA_BYTES`), measured on the UTF-8 encoding of
`JSON.stringify(value)`. Over the cap, the whole definition fails validation and the spawn is rejected — the
field rides in every snapshot on an entity list capped at 5 000, so it is deliberately an order of magnitude
tighter than the 16 KiB mod saved-data cap. Anything bulky belongs in
[saved data](https://diceytable.com/docs/scripting-api/api#apisetsaveddata), keyed by entity id.

It is a **replication** boundary, not a cryptographic one. The host's runtime holds the value in full and it
is written to the save unredacted, so treat a save file as you would the host's own memory. It protects a
secret from the other players at the table; it does not protect one from whoever is hosting. It *does*
withhold the value from a mod running on the host, which has been true since 2026-08-14 and is the
assumption most likely to break an existing mod.

### `container`

The container contract: what sort of container this entity is, whether it ever runs out, what it dispenses,
and what it is holding. Applies to `kind: "bag"` — the wire kind behind everything the editor calls a
**Container**, bowls and trays included.

It is one nested object with five keys, each documented in
[`containerStateSchema`](https://diceytable.com/docs/mods/reference/object-state):

| Key | What it settles |
|---|---|
| `form` | `holder` (open, physical, stores nothing) or `bag` (closed, virtual, stores its contents). Required. |
| `infinite` | Never depletes; dispenses copies of `source`. |
| `source` | What an infinite container hands out. Absent means it adopts the first piece put in. |
| `contents` | A finite bag's stored pieces, insertion-ordered and run-length encoded. |
| `secretContents` | Opt-in hidden information, with a real bandwidth cost. |

**It is a first-class replicated field, not `metadata`, and that is the point.** `metadata.infinite` sat on the
`bag-infinite` preset for a long time as a label no code read. A real field is validated by Zod at every
boundary — spawn intent, `setup.json`, save load, import, a mod's `createObject` — compared field by field for
delta replication, and carried through the snapshot migration. Write it here.

Two rules worth knowing before you author one:

- **A `container` on any other kind is dropped on load.** Nothing writes it there and nothing would read it, so
  the loader removes it rather than leaving a key that quietly means nothing.
- **Every `bag` gets one.** A bag loaded without a `container` is backfilled with `{ "form": "bag" }`, which is
  exactly the behaviour a bag had before this field existed. You never have to add it to an old file to keep
  that file working — you add it to change the behaviour.

Containers do not nest: a stored piece's definition has no `container` key at all.

**What reads it today.** The field is validated at every boundary, replicated, migrated and preserved across
save and load, and the container's form and `infinite` flag already decide which actions its menu offers. The
behaviour the rest of this page describes — putting a piece in, taking one out, and the "looks full" fill —
arrives with the container runtime; author against the contract, and expect a container you write now to be
carried intact until it does.

### `tableObjectDefinitionSchema.position`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `x` | `number` | **yes** | — | — | — | — | — |
| `y` | `number` | **yes** | — | — | — | — | — |
| `z` | `number` | **yes** | — | — | — | — | — |

#### `position.x`

The lateral axis, in feet, measured from the table center. Positive `x` runs to one side, negative to the
other, and nothing about a piece changes when you mirror it across zero.

The table is not square, so equal offsets on `x` and `z` are not equally far out: the default seat ring is
an ellipse about 6 ft along `x` against 4 ft along `z`. A row of tokens laid out on `x` has much more room
before it reaches a seat than the same row laid out on `z`.

#### `position.y`

Height, in feet, as an absolute world Y. Where the tabletop is depends on the table the game assigns:
`2.0723` on Square Table (the default, used when a game assigns no table, and what new games start
on), `1.5` on the built-in Dining Table, or another table pack's own `tablePack.surface.surfaceY`.
Measure from that surface. (In a game scene that assigns no table, positions written for the old
built-in table, surface `-0.02`, are lifted onto Square Table when the scene loads - see
[The platform defaults](https://diceytable.com/docs/editor/workflows/assign-a-room-or-table#the-platform-defaults-modern-room-and-square-table).)

This is the axis that decides whether a piece rests or drops, and it is a center, not a base. A body rests
when its center is half its own height above the surface: about `0.025` for a 0.05 ft die, about `0.25` for
a 0.5 ft bag. Lower and it starts inside the table and the solver pushes it back out; higher and it falls,
which is what you want for a die and not for a board.

#### `position.z`

The remaining horizontal axis, in feet, from the table center — `x` and `z` together are the tabletop
plane, and `y` is up.

`z` is the short axis of the default seat ring, so it is the coordinate that separates the seats facing
each other: the `red` seat's zone is centered at `x: 0, z: 4` and measures 1.6 by 0.5 ft, with the other
seven spaced around from there. Placing a deck inside a zone does not itself give it an `ownerSeat` — that
is assigned from position when a player drops something — but it does put a shared pile inside one
player's reach, which is rarely what a starting layout meant.

### `tableObjectDefinitionSchema.tooltip`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `enabled` | `boolean` | **yes** | — | — | — | — | — |
| `title` | `string` | no | — | <= 120 chars | — | — | — |
| `description` | `string` | no | — | <= 1000 chars | — | — | — |
| `showDetails` | `boolean` | no | — | — | — | — | — |
| `vars` | `tooltipVariablesSchema` | no | — | — | — | A tooltip may not hold more than 32 variables. | — |

#### `tooltip.enabled`

Whether hovering the entity shows its tooltip. Required whenever `tooltip` is present. `false` keeps the rest of
the config stored, which is what makes it a switch rather than a delete: turning it back on shows the same
title, description and variables.

#### `tooltip.title`

The title template, at most 120 characters. Variables only — `{name}` and `{name|fallback}` are substituted, and
formatting characters are shown as typed; a newline becomes a space. Absent or blank means the entity's name: its
`displayName`, or its `label` when it has none.

#### `tooltip.description`

The description template, at most 1,000 characters including markup, drawn under the title. Supports `**bold**`,
`*italic*`, `[color=…]…[/color]`, `- ` bullets, line breaks and `{name}` / `{name|fallback}` variables — the full
syntax is under [Tooltip template syntax](https://diceytable.com/docs/editor/inspector/platform-panels#tooltip-template-syntax). Absent
or blank means no description.

#### `tooltip.showDetails`

Whether the built-in detail lines appear under the description: a die's `Value`, a deck's `Cards` count and the
card showing on it, a bag's `Contents` count, overlay values and counters, `Locked` and `Owner`.

**Absent means `true`**, and `true` is never written: the field only ever appears as `false`, when an author has
turned the details off. That keeps enabling a die's tooltip a one-switch job — its number shows without a second
setting — and keeps two configs that behave identically byte-identical on the wire.

#### `tooltip.vars`

Named values the templates read as `{name}`. Keys are identifiers — a letter or `_`, then up to 31 letters, digits
or `_`; dots are reserved for the built-in `counters.<key>` and `values.<key>`. Values are a string of at most 200
characters, a finite number or a boolean. At most **32** per entity. Absent or empty means none.

These are the entity's **own** variables and win over a built-in of the same name (`name`, `kind`, `value`,
`count`, `owner`). Authors set starting values in the Inspector; a table script changes them during play. Keys are
stored sorted, so the same variables written in a different order do not replicate as a change.

A variable's value is always inserted as plain text — formatting in it is shown literally, never interpreted —
so whoever writes the template, not whoever writes a variable, decides what the tooltip looks like.

### `tableObjectDefinitionSchema.physics`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `bodyType` | `"static"` \| `"dynamic"` \| `"kinematic"` | no | — | — | — | — | — |
| `mass` | `number` | no | — | > 0 | — | — | — |
| `friction` | `number` | no | — | >= 0, <= 1 | — | — | — |
| `restitution` | `number` | no | — | >= 0, <= 1 | — | — | — |
| `linearDamping` | `number` | no | — | >= 0, <= 1 | — | — | — |
| `angularDamping` | `number` | no | — | >= 0, <= 1 | — | — | — |
| `collisionShape` | `"auto"` \| `"box"` \| `"sphere"` \| `"capsule"` \| `"cylinder"` \| `"convexHull"` \| `"mesh"` | no | — | — | — | — | — |
| `collisionSize` | `positiveVector3TupleSchema` | no | — | — | — | — | — |
| `collisionOffset` | `vector3TupleSchema` <br>same shape as `position` | no | — | — | — | — | — |
| `rigidbodyEnabled` | `boolean` | no | — | — | — | — | — |
| `collisionEnabled` | `boolean` | no | — | — | — | — | — |
| `weldChildren` | `boolean` | no | — | — | — | — | — |

#### `physics.bodyType`

How the entity participates in simulation. `dynamic` is moved by forces and collisions, `kinematic` is
moved only by you but still pushes dynamic bodies, and `static` never moves at all and is the cheapest of
the three.

Absent means the per-kind default, which is `dynamic` for everything except `board` and `card-holder`. Note
that `locked` also produces a static body without touching this field, and the two are independent: an
unlocked entity with `bodyType: "static"` stays put and still responds to picks and transforms. Body type
also constrains the collider — see `collisionShape`, where `mesh` is invalid on a dynamic body.

#### `physics.mass`

Mass in kilograms; must be greater than zero. Only dynamic bodies have one — the field is accepted and
ignored on a static or kinematic entity, because in Ammo a zero-mass body is precisely what "static" means.

Absent means the per-kind default: 0.02 kg for a die, 0.05 for a card, 0.1 for a token, 0.2 for a custom
model, 0.3 for a deck or bag. These are real-ish figures and worth keeping so: mass is what decides whether
a thrown die scatters a stack of chips or bounces off it, and a piece an order of magnitude out of scale
with its neighbours behaves like a bug even though nothing is broken.

#### `physics.friction`

Coulomb friction, 0 to 1. Low values slide; high values grip. Absent means the per-kind default, which runs
from 0.5 on a die (it needs to tumble) through 0.6 on a card to 0.8 on a board.

This is the field that decides whether a piece stays where it lands on a crowded surface, and it is worth
setting alongside a smooth collider rather than after one misbehaves. A sphere is the clear case: give a
marble a true sphere collider and low friction and it will slide as well as roll, so the built-in
Chinese-checkers marble pairs its sphere with 0.45 here and leans on `angularDamping` to settle it.

#### `physics.restitution`

Bounciness, 0 to 1 — the fraction of speed kept through an impact. 0 is a dead drop, 1 would bounce back to
the height it fell from. Absent means the per-kind default: 0.05 for a card or deck, 0.1 for a token, 0.3
for a die, 0 for a board.

Keep it low for anything that should settle quickly. High restitution on a small light piece is the usual
cause of a spawn that will not come to rest, because each bounce also re-wakes the neighbours it lands on.
Glass and stone sit higher than wood or card — the built-in marble uses 0.25 — but even those stay well
under half.

#### `physics.linearDamping`

Drag on straight-line motion, 0 to 1: how quickly a moving entity loses speed with nothing touching it.
Absent means the per-kind default, 0.05 on a die up to 0.2 on a deck or bag.

Damping is the blunt instrument for a piece that travels too far after a flick. It is not friction — it
applies in the air as well as on the cloth — so raising it a long way makes throws feel syrupy. Prefer
friction when the problem is sliding across the table, and this when the problem is a piece that keeps
going after it should have run out of energy.

#### `physics.angularDamping`

Drag on rotation, 0 to 1 — the rotational twin of `linearDamping`. Absent means the per-kind default, 0.05
on a die (which must be free to tumble or rolls stop looking random) through 0.2 on a token to 0.3 on a
bag.

This field matters most to round pieces, and for a reason that is easy to miss: Ammo's rolling friction is
not exposed through PlayCanvas, so angular damping is the only lever that stops a sphere rolling. A box
collider hides the problem by catching on its own corners; swap in a true `sphere` and the entity will roll
until it leaves the table unless this comes up with it. The built-in marble uses 0.55.

#### `physics.collisionShape`

The collision geometry, which is usually the only field here worth setting. `auto` keeps whatever the kind
already configured, `box`, `sphere`, `capsule` and `cylinder` are analytic primitives fitted to the model's
measured bounds, `convexHull` wraps the mesh in its convex hull, and `mesh` is the full triangle mesh.

Pick the primitive that IS the shape rather than the most detailed option. For a disc, a `cylinder` is
exact and costs less than a hull of the same disc; for a sphere, `sphere` is exact and a hull is strictly
worse; a convex body such as a biconvex go stone is described exactly by `convexHull`, so nothing is
approximated there either. Reach for `mesh` only for genuinely concave static geometry — a
`btBvhTriangleMeshShape` is invalid on a dynamic body, and the host quietly substitutes `convexHull` when
you ask for one anyway. Both mesh-based shapes need loaded render geometry to build from, so on an entity
whose model is still downloading the change is deferred rather than lost.

Changing this rebuilds the Ammo shape and re-creates the body, which is not free; setting the same value
twice is a no-op.

#### `physics.collisionSize`

Explicit full dimensions for a box collider, in object-local units — that is, measured as though `scale`
were 1, because the host multiplies `scale` back in when it builds the shape. Absent means the collider is
auto-fitted to the model's measured bounds, which is the right answer nearly always.

This exists for imported models whose bounds are not what you want to collide with: one with a wide flat
base, or one whose exported bounding box includes empty space. It applies to box colliders only — the
analytic primitives and the mesh shapes take their size from the geometry and ignore it. Pair it with
`collisionOffset` when the box also needs to sit somewhere other than the model's centre.

#### `physics.collisionOffset`

Where the collision box sits relative to the entity origin, in object-local units. Absent means the
auto-fitted centre.

Paired with `collisionSize`, and like it, box colliders only. The case it solves is an imported model whose
origin is not in the middle of it — a piece authored standing on the world origin, say, whose auto-fitted
box is therefore centred half a model above where it should be.

#### `physics.rigidbodyEnabled`

Whether the entity's rigidbody component is switched on. Absent means enabled, so every existing setup file
keeps its behaviour.

Disabling freezes the entity without discarding what you authored: mass, friction and the rest stay on the
component and come back when it is re-enabled. That is deliberate, and it is why this is a flag rather than
a removal — `render`, `collision` and `rigidbody` are intrinsic to a table entity and can never be taken
off it.

#### `physics.collisionEnabled`

Whether the entity's collision component is switched on. Absent means enabled.

Disabling makes the entity non-colliding while leaving it fully visible — it will pass through everything
and everything will pass through it. Useful for a decorative prop that should not get in the way of play.
As with `rigidbodyEnabled` this disables rather than removes, so the authored shape survives and returns
intact.

#### `physics.weldChildren`

Welds this entity's children into it as a single rigid body, so an assembly collides as one shape instead
of as a loose pile of parts that can be knocked out of alignment.

This is a property of the parent, not of the children, and it changes what parenting means: ordinary
parenting is transform and organisation only, with a parented child held kinematic so it cannot fight its
parent. Welding goes further and merges the collision geometry. Unwelding restores each child's own
collider from the shape it had authored.

### `tableObjectDefinitionSchema.overlay`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `values` | `Record<string, cardOverlayValueSchema>` | no | — | — | — | An object may carry at most 24 overlay values. | — |
| `counters` | `Record<string, number>` | no | — | — | — | An object may carry at most 24 counters. | — |
| `concealedValues` | `integer` | no | — | >= 1, <= 24 | — | — | — |
| `concealedCounters` | `integer` | no | — | >= 1, <= 239976 | — | — | — |

#### `overlay.values`

Mutable values, keyed by the **mapped field key** from your schema's `fields[]` — not by an id space of its
own. `{ "pwr": 2 }` means "the `pwr` field, modified".

How the number combines with the card's printed value is a property of the **region**, not of this bag: a
`delta` region adds it to the catalogue value (base 2 power + 2 shows as 4), an `override` region replaces
it. That is why the same stored `2` can render as `4` on one template and `2` on another, and why the
combining rule never has to be replicated.

A value is `number` or `boolean`. There is deliberately **no string**: free-text entry at the table would
need host-side validation against the field's declared type, and every string a region can draw is either
static text from the definition or a catalogue value both sides already resolve locally.

At most **24** entries per entity, each within ±9,999. Both limits are enforced when the intent arrives, so a
peer cannot grow the snapshot with them.

#### `overlay.counters`

Counter counts, keyed by counter definition id (`counters[].id` in `data/cardSchema.json`). At most **24**
entries per entity, each 0–9,999 and additionally clamped to that counter's own declared `max`.

Zero parses — a hand-edited save is not rejected for it — but no mutation ever *produces* a zero: an entry
that reaches zero is removed. "Absent" and "zero" must not both be reachable through play, or the snapshot
delta churns between the two encodings forever.

A counter's art, colour, anchor, offset and stacking mode are definition data and resolve locally. So is its
**flip lifecycle**: on a `flip` the host applies `persist` (nothing happens — the default), `discharge` (the
count is cleared) or `transfer` (the count moves into another counter). A chain is impossible by
construction — a `transferTo` target may not itself transfer — so one flip is always one hop.

#### `overlay.concealedValues`

**Redaction output only.** How many overlay values were withheld from *this* recipient because their region
declared `visibility: "count-only"`.

It is never written by the host's own authoritative state, never persisted, and stripped on load — a saved
game is unredacted by design, so a persisted tally would be a lie the next session inherited. If you are
reading it on the host, or in a save file, something is wrong.

`count-only` is the deliberate middle ground between `hidden` and `full`: the entry's identity is removed but
its magnitude survives, so a client can draw "this card has *something* on it" without learning what.

#### `overlay.concealedCounters`

**Redaction output only** — the summed count of every counter withheld from this recipient by a
`count-only` declaration, so a client can draw N anonymous chips without learning which counters they were.

Same contract as [`concealedValues`](https://diceytable.com/docs/mods/reference/object-state): produced on the wire, never by
the host's own state, never persisted, stripped on load.

### `tableObjectDefinitionSchema.diceTray`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `seat` | `string` \| `null` | **yes** | — | <= 40 chars | — | — | — |
| `peerId` | `string` | **yes** | — | 1–96 chars | — | — | — |
| `rollId` | `string` | **yes** | — | 1–64 chars | — | — | — |
| `clearAt` | `number` | no | — | >= 0 | — | — | — |

#### `diceTray.seat`

The seat the roller was sitting in, or `null` when they held none. Required inside the record — `null` is a
value here, not an omission.

It is the label half of custody, and it is what lets a roll be shown as *red's roll* rather than as a peer id. A
spectating host who rolls produces a record with `seat: null`; that is an ordinary roll, not a broken one.

**Custody is keyed to [`peerId`](https://diceytable.com/docs/mods/reference/object-state#dicetraypeerid), not to this.** Seats change hands — a player leaves, someone
else sits down — and a clear must still remove the dice of the person who rolled them rather than the dice of
whoever happens to be sitting there now. Read `seat` for display and grouping; read `peerId` for ownership.

Capped at 40 characters, matching every other seat identifier in the schema.

#### `diceTray.peerId`

The player whose roll this die came from. Required, 1–96 characters, and **the identity custody is actually
keyed to**.

A peer, not a seat, because a seat can change hands mid-session while a roll cannot: clearing a roll must remove
the dice of the person who rolled them, and a seatless spectator who rolls still owns their dice. This is the
field a clear compares against.

It is a peer id, so it dies with the connection — the same person rejoining is a different peer, and dice left
behind by a departed player are no longer matched by any live roller's clear. They are ordinary entities on the
table at that point; delete them like any other entity if your game wants them gone.

Not redacted: dice are public, and so is whose roll they came from.

#### `diceTray.rollId`

Which roll this die belongs to. Required, 1–64 characters, and shared by every die spawned for the same throw.

It is the same id the roll summary carries, which is what lets a summary panel highlight the dice it is
describing, and what lets a script that stored a
[`DiceRollSummary`](https://diceytable.com/docs/scripting-api/types#dicerollsummary) find those dice again later: compare this field
rather than searching by position or by time.

A player who rolls twice in quick succession produces two batches with two ids, and both sets of dice stay in
their custody until a clear. Grouping dice by roller alone would merge them; this is the field that keeps them
apart.

It identifies a throw, not an entity — the die's own id is `id`. Nothing persists a roll id beyond the session,
so it is not a useful key for saved data across loads.

#### `diceTray.clearAt`

When this die clears itself: milliseconds since the epoch on the host's clock. Optional, and absent on a die that
stays until someone clears it.

The host stamps it when the roll settles, from the game's
[`diceClearAfterSeconds`](https://diceytable.com/docs/mods/manifest/reference#diceclearafterseconds) or a script request's own
`clearAfterSeconds`, and removes the die once the time has passed — unless someone is holding it. Picking the die
up ends its custody (the whole `diceTray` record goes), so a kept die is never cleared.

Because it rides the replicated die, a new host after a migration clears the dice on time too. It is a host
deadline, not a countdown to display: a peer's clock may differ by a little.

### `tableObjectDefinitionSchema.physics.collisionSize`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `x` | `number` | **yes** | — | > 0 | — | — | — |
| `y` | `number` | **yes** | — | > 0 | — | — | — |
| `z` | `number` | **yes** | — | > 0 | — | — | — |

#### `physics.collisionSize.x`

Full width of the collision box in object-local units, before `scale`. Must be greater than zero.

#### `physics.collisionSize.y`

Full height of the collision box in object-local units, before `scale`. Must be greater than zero. This is
the one to check first when an imported model floats above the cloth or sinks into it.

#### `physics.collisionSize.z`

Full depth of the collision box in object-local units, before `scale`. Must be greater than zero.

## `containerStateSchema`

Exported from `@diceytable/shared` as `containerStateSchema`. 12 fields across 4 tables.

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `form` | `"holder"` \| `"bag"` | **yes** | — | — | — | — | — |
| `infinite` | `boolean` | no | — | — | — | — | — |
| `source` | `containerSourceSchema` | no | — | — | — | — | — |
| `contents` | `containerContentRunSchema[]` | no | — | <= 256 items | — | — | — |
| `secretContents` | `boolean` | no | — | — | — | — | — |

Whole-object rules:

- 1 further cross-field rule (message built at validation time).

### `form`

What sort of container this is — the one required key, and the one that decides whether the container stores
anything at all.

| `form` | What it is | Where its contents live |
|---|---|---|
| `"holder"` | **Open and physical** — a bowl, a tray. Pieces fall in and sit there under physics, visible to everyone. | Nowhere. A holder stores no contents data; the pieces inside it are ordinary entities on the table with their own ids. |
| `"bag"` | **Closed and virtual** — the contents are not on the table. A piece put into one stops existing as a body and is appended to [`contents`](https://diceytable.com/docs/mods/reference/object-state). | `contents`, on this field. |

That difference is the whole model, so pick it first. A holder's count is however many entities happen to be
resting inside it right now — the schema refuses a `contents` array on a holder rather than letting you author
one that nothing would ever read. A bag's count is the sum of its runs.

`"bag"` is a wire value, not a label: both forms are **Containers** in the editor and in anything you show a
player.

The field is required because there is no safe default. A container whose form was guessed would either
swallow pieces that were meant to rest in it or leave pieces loose that were meant to be stored, and neither
mistake announces itself.

### `infinite`

The container never depletes. Default `false`.

An infinite container dispenses copies of one authored piece — its [`source`](https://diceytable.com/docs/mods/reference/object-state)
— and its state does not change when it is drawn from. Fifty draws leave the object's `container` field
byte-identical, which is exactly the point: nothing to replicate, nothing to run out of, and a supply pile that
cannot quietly be emptied by one player.

It is mutually exclusive with stored contents. The schema refuses `infinite: true` alongside a non-empty
`contents` array, because an infinite container has nothing to hold: everything it hands out comes from
`source`, and a matching piece put back into it is destroyed rather than accumulated.

Both forms can be infinite. An infinite `holder` is the bottomless bowl — it shows a "looks full" fill that
never shrinks; an infinite `bag` is the same supply with nothing visible inside it.

This replaces `metadata.infinite`, which the `bag-infinite` preset carried for a long time and which no code
ever read. A snapshot loaded from the old key is migrated onto this field, but write the real field in a
hand-authored file: the point of the change is that a flag nothing reads is worse than no flag at all.

### `source`

What an infinite container dispenses — one piece definition, plus optional provenance for the editor.

`source` is meaningful only when [`infinite`](https://diceytable.com/docs/mods/reference/object-state) is `true`, and the schema
refuses it otherwise rather than letting a finite bag carry a source nothing would consult.

**Absent means "not chosen yet", not "nothing".** An infinite container with no source **adopts the first
piece put into it** and dispenses that from then on. This is deliberate parity with Tabletop Simulator, and it
is what lets a mod ship an empty bowl an author fills by dropping one stone in rather than by hand-writing a
definition. Changing or clearing an adopted source afterwards is host-only.

Once a source is set, the container is **single-type**: a piece matching it is destroyed when it is put back
in, and a piece that does not match is refused and returned to where it was picked up. Matching is by identity
key — see [`contents.key`](https://diceytable.com/docs/mods/reference/object-state) for what that covers, and note that a colour or
material variant counts as a *different* piece.

### `contents`

What a finite bag is holding: an **insertion-ordered, run-length encoded** list of piece definitions.

Each entry is a *run* — `count` copies of one definition — so a bag of 200 identical go stones is one entry of
a few hundred bytes rather than 200 copies of the same object. A piece put in merges into the run in front of
it when it is the same piece (see [`contents.key`](https://diceytable.com/docs/mods/reference/object-state)); a different piece
starts a new run. Order is preserved because the draw modes depend on it: `stack` takes from the end, `queue`
from the start, and `random` picks a *piece* uniformly rather than a run — so 199 black stones and one white
one hand out white about once in 200 draws, not half the time.

**Finite bags only.** The schema rejects a non-empty `contents` on a `holder`, whose pieces are loose entities
resting on the table with their own ids, and on an `infinite` container, which dispenses from `source` and
stores nothing.

**One lane per bag.** A bag holds *either* cards — `metadata.cards`, the existing deck machinery, with draw,
peek, search and hidden-information redaction already working on it — *or* pieces, here. Once it holds one
sort it refuses the other. Mixing the two would need a cross-lane order for `stack`/`queue` and a second
redaction story, and no game has asked for one.

Three caps bound the field, and hitting any of them is a refusal reported to whoever put the piece in — "this
container is full" — never a silent drop: **256 runs**, **10,000 pieces per run**, and **48 KiB** for the
serialised `container` field as a whole. The size cap is the one that bites a bag of many *distinct* pieces;
roughly 250 authored definitions fit.

Contents are **not hidden information by default** — read
[`secretContents`](https://diceytable.com/docs/mods/reference/object-state) before assuming they are.

### `secretContents`

Opt-in hidden information: hide the bag's contents from every peer but the host. **Off by default, and the
default is the right answer for almost every game.**

**Why contents are public by default.** A piece bag's contents are *unseen*, not *secret* — everyone watched
each piece go in, and authored starting contents sit in the mod's public GitHub repo where anyone can read
them. The thing that must stay secret, *which piece the next draw yields*, is chosen by the host's private RNG
at draw time and is not derivable from the contents at all. So the contents ride the wire in clear, the
interface simply does not show them, and the public number is the count. That costs nothing: delta compression
stays on and a draw patches one object.

**What turning it on costs.** For as long as a secret bag is non-empty, the **whole table** switches to
per-peer redacted full snapshots with **delta compression disabled** — the host re-serialises the entire table
once per peer on every broadcast. This is the same scaling cliff a deck of face-down cards already puts a
table on, and it is why the flag is per bag rather than the default. On a card table that cost is unavoidable;
on a bag of wooden pieces it usually buys no secrecy at all.

Turn it on when pieces are added privately (a blind bid, a hidden draft pool), or when `stack`/`queue` order
would tell anyone reading the snapshot what the next draw is. Leave it off otherwise.

A bag holding **cards** is hidden information already, through the existing card machinery, and needs nothing
here.

### `containerStateSchema.source`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `ref` | `object` | no | — | — | — | — | — |
| `definition` | `containerItemDefinitionSchema` | **yes** | — | — | — | — | — |

#### `source.ref`

Where the source piece came from — **provenance for the editor only**.

The runtime never resolves it. A draw spawns [`source.definition`](https://diceytable.com/docs/mods/reference/object-state) and
nothing else; `ref` exists so the editor can offer "refresh from source" after you edit the preset, model or
template the piece was built from, and so a panel can name what the container dispenses.

That split is on purpose. If the runtime resolved `ref` at draw time, a container whose model had since been
deleted from the mod would spawn a placeholder box — an asset that silently degrades into a grey cube is worse
than one that refuses the draw and says the source is missing.

Optional, and safe to omit in a hand-written file. A source with no `ref` still dispenses; you lose only the
editor's ability to re-resolve it.

#### `source.definition`

The piece an infinite container dispenses — a full spawn definition minus everything positional.

It is a [`containerItemDefinitionSchema`](https://diceytable.com/docs/mods/reference/object-state): what the piece *is* (`kind`,
`label`, its look, `metadata`, `physics`, `components`), with the fields that say where an instance currently
sits removed — no `id`, `position`, `ownerSeat` or `parentId` — and no `container` of its own, which is what
makes "containers do not nest" structural rather than a rule to remember.

Every draw spawns a fresh copy of exactly this, and the container's own state does not change. It is also
what an incoming piece is matched against: its identity key (see
[`contents.key`](https://diceytable.com/docs/mods/reference/object-state)) decides whether a piece put back in is destroyed as a
returning copy or refused as the wrong piece — so a definition that is *nearly* right, differing by a tint or
a scale, produces a container that rejects the pieces it hands out.

Required whenever `source` is present. A `ref` without a `definition` would leave the runtime resolving an
asset path at draw time, which is precisely what [`source.ref`](https://diceytable.com/docs/mods/reference/object-state) exists not
to do.

### `containerStateSchema.contents`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `key` | `string` | **yes** | — | 1–512 chars | — | — | — |
| `count` | `integer` | **yes** | — | >= 1, <= 10000 | — | — | — |
| `definition` | `containerItemDefinitionSchema` | **yes** | — | — | — | — | — |

#### `contents.key`

The run's **identity key** — the answer to "is this the same piece?", cached so the host does not recompute it
on every insertion.

It is built from what a player can see and what a draw would reproduce: the `kind`, the model reference
(`metadata.customModelAssetId`, else `metadata.standardPresetId`, else the primitive shape, plus the die type
and side count for a `die`), the look (`color` lower-cased, `materialSlots` key-sorted, `metadata.materialId`)
and `scale` rounded to four decimal places. Deliberately **not** part of it: `id`, `label`, `displayName`,
transform, `faceDown`, `locked`, `ownerSeat`, `tags`, `physics` and sound overrides — two pieces differing only
in those are the same piece to a player, and folding them together is what keeps a bowl of stones at one run.

**Colour and material variants are different pieces.** A blue cube is refused by a bowl of red cubes rather
than accepted. The rule errs toward never destroying a piece that differs from what would come back out: if
the blue cube were accepted it would be silently recoloured.

**Never trusted from a file.** Every key is recomputed from its own `definition` when a save or an incoming
snapshot is loaded, and a wrong one is corrected in place. So a hand-edited save cannot forge a key that makes
the wrong piece match, and you do not need to compute one when authoring — write the `definition` and let the
platform key it.

#### `contents.count`

How many copies of this run's [`definition`](https://diceytable.com/docs/mods/reference/object-state) the bag holds, from 1 to
10,000.

This is the run-length half of the encoding: 200 stones are `count: 200` on one run, not 200 entries. A run
that falls to zero is removed rather than kept as an empty entry, which is why the minimum is 1.

The per-run ceiling is not the bag's ceiling. 256 runs and the 48 KiB size cap bound the field as a whole, and
the container's own `capacityLimit`, when set, bounds the piece count further. An insertion that would bust
any of them is refused and reported, never truncated.

#### `contents.definition`

The piece this run is made of — a full spawn definition minus everything positional.

It is a [`containerItemDefinitionSchema`](https://diceytable.com/docs/mods/reference/object-state): the fields that describe *what*
the piece is (`kind`, `label`, its look, `metadata`, `physics`, `components`) with the fields that describe
*where it currently is* removed — no `id`, `position`, `ownerSeat` or `parentId` — and no `container` of its
own, which is what makes "containers do not nest" structural rather than a rule someone has to remember.

Taking a piece out spawns this definition at the container's mouth. Because a run merges pieces that differ
only in the fields the identity key ignores, the copy that comes out is this definition and not a record of any
particular instance that went in — treat it as the canonical piece.

### `containerStateSchema.source.ref`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `type` | `"preset"` \| `"model"` \| `"template"` | **yes** | — | — | — | — | — |
| `id` | `string` | **yes** | — | 1–160 chars | — | — | — |

#### `source.ref.type`

Which catalogue [`source.ref.id`](https://diceytable.com/docs/mods/reference/object-state) names: a built-in `preset`, a `model`
asset in the mod's own file tree, or a `template` from `setup.json`.

Editor metadata, like the rest of `ref` — it changes nothing about what a draw spawns.

#### `source.ref.id`

The identifier within [`source.ref.type`](https://diceytable.com/docs/mods/reference/object-state)'s catalogue — a preset id, a
repo-relative model path, or a template id from `setup.json`.

Editor metadata. It is not resolved at draw time, so an id that has gone stale costs you the "refresh from
source" button and nothing else.

## `containerItemDefinitionSchema`

Exported from `@diceytable/shared` as `containerItemDefinitionSchema`. 51 fields across 6 tables.

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `kind` | `"card"` \| `"deck"` \| `"die"` \| `"token"` \| `"board"` \| `"bag"` \| `"custom"` \| `"card-holder"` \| `"button"` \| `"table"` \| `"coin"` | **yes** | — | — | — | — | — |
| `label` | `string` | **yes** | — | 1–80 chars | — | — | — |
| `rotation` | `vector3TupleSchema` | no | — | — | — | — | — |
| `scale` | `vector3TupleSchema` <br>same shape as `rotation` | no | — | — | — | — | — |
| `color` | `string` | no | — | — | `^#[0-9a-f]{6}$` | — | — |
| `faceDown` | `boolean` | no | — | — | — | — | — |
| `locked` | `boolean` | no | — | — | — | — | — |
| `stackCount` | `integer` | no | — | >= 1, <= 1000 | — | — | — |
| `containerMode` | `"random"` \| `"stack"` \| `"queue"` | no | — | — | — | — | — |
| `capacityLimit` | `integer` | no | — | >= 1, <= 1000 | — | — | — |
| `tags` | `string[]` | no | — | <= 100 items; each 1–32 chars | `^[a-z0-9_-]+$` | — | — |
| `components` | `objectComponentSchema[]` | no | — | <= 8 items | — | 1 further cross-field rule (message built at validation time). | — |
| `displayName` | `string` | no | — | 1–80 chars | — | — | — |
| `tooltip` | `objectTooltipConfigSchema` | no | — | — | — | — | — |
| `physics` | `objectPhysicsSchema` | no | — | — | — | — | — |
| `castShadows` | `boolean` | no | — | — | — | — | — |
| `receiveShadows` | `boolean` | no | — | — | — | — | — |
| `flippable` | `boolean` | no | — | — | — | — | — |
| `material` | `soundMaterialSchema` | no | — | — | — | — | — |
| `soundSetOverrides` | `soundSetOverridesSchema` | no | — | — | — | — | — |
| `materialSlots` | `materialSlotsSchema` | no | — | — | — | materialSlots may not hold more than 64 entries. | — |
| `metadata` | `Record<string, unknown>` | no | — | — | — | — | — |
| `faceValue` | `integer` | no | — | >= -9999, <= 9999 | — | — | — |
| `overlay` | `tableObjectOverlayStateSchema` | no | — | — | — | — | — |

### `kind`

What the stored piece is — the one required field, and the one that cannot be changed later: a different kind
is a different piece. See [`tableObjectDefinitionSchema.kind`](https://diceytable.com/docs/mods/reference/object-state) for the ten
kinds and [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) for what each is for.

It is also the first component of the run's [identity key](https://diceytable.com/docs/mods/reference/object-state), so a token and
a die never share a run even if everything else about them matches.

### `label`

The stored piece's slug — the machine key a script reads as its name. Same field as
[`tableObjectDefinitionSchema.label`](https://diceytable.com/docs/mods/reference/object-state); it is not unique here, because a run
of 200 stones is one definition with one label.

**Not part of the identity key.** Two pieces differing only in `label` merge into the same run, and the label
that survives is the one the run was created with — so do not use `label` to tell stored pieces apart.

### `rotation`

The resting orientation a drawn copy is spawned with, Euler XYZ in degrees. Same field as
[`tableObjectDefinitionSchema.rotation`](https://diceytable.com/docs/mods/reference/object-state).

Not part of the identity key — a piece stored while lying on its side comes back out at this orientation, not
at the one it happened to be in. Set it to how the piece should look when it arrives on the table.

### `scale`

The stored piece's size multiplier. Same field as
[`tableObjectDefinitionSchema.scale`](https://diceytable.com/docs/mods/reference/object-state).

**Part of the identity key**, rounded to four decimal places: a large stone and a small one of the same model
are different pieces, kept in separate runs, and an infinite container set up with one refuses the other.

### `color`

The stored piece's tint, `#rrggbb`. Same field as
[`tableObjectDefinitionSchema.color`](https://diceytable.com/docs/mods/reference/object-state).

**Part of the identity key** (compared lower-cased). A blue cube is a different piece from a red one — it
starts its own run in a finite bag, and an infinite container holding red cubes refuses it rather than
absorbing it and quietly turning it red.

### `faceDown`

Whether a drawn copy arrives face down. Same field as
[`tableObjectDefinitionSchema.faceDown`](https://diceytable.com/docs/mods/reference/object-state).

Not part of the identity key — a card put in face down and one put in face up are the same card, which is the
answer a player expects.

### `locked`

Whether a drawn copy arrives locked in place. Same field as
[`tableObjectDefinitionSchema.locked`](https://diceytable.com/docs/mods/reference/object-state).

Not part of the identity key. Rarely what you want on a stored piece: a piece that spawns locked cannot be
picked up until someone unlocks it.

### `stackCount`

How many cards a stored `deck` piece holds. Same field as
[`tableObjectDefinitionSchema.stackCount`](https://diceytable.com/docs/mods/reference/object-state), and accepted only on a `deck`.

Note the one-lane rule before reaching for it: a bag holds either cards or pieces, so a bag whose `contents`
are pieces refuses a deck, and a bag holding cards keeps them in `metadata.cards` rather than here.

### `containerMode`

Which end a draw comes off — `stack`, `queue` or `random` — carried on the stored piece so a drawn `deck` or
`bag` keeps its draw order. Same field as
[`tableObjectDefinitionSchema.containerMode`](https://diceytable.com/docs/mods/reference/object-state).

Not part of the identity key.

### `capacityLimit`

The ceiling a drawn `deck` or `bag` carries. Same field as
[`tableObjectDefinitionSchema.capacityLimit`](https://diceytable.com/docs/mods/reference/object-state). It is the *stored piece's*
capacity, not the capacity of the container holding it — that one lives on the container's own object.

Not part of the identity key.

### `tags`

The stored piece's author tags, lowercase and dash-separated, up to 100 of them. Same field as
[`tableObjectDefinitionSchema.tags`](https://diceytable.com/docs/mods/reference/object-state).

Not part of the identity key, so pieces differing only in tags merge and the run keeps the first one's tags.
Tags are how a script finds a drawn copy afterwards, so put them on the definition rather than expecting a
tag added to one instance to survive storage.

### `components`

Engine components authored on the stored piece — `render`, `rigidbody`, `collision`, `light`, `camera`,
`script` — up to eight. Same field as
[`tableObjectDefinitionSchema.components`](https://diceytable.com/docs/mods/reference/object-state).

Not part of the identity key. They are rebuilt on the copy a draw spawns, so a light or a script attached here
comes back with every piece taken out.

### `displayName`

The human-readable name shown for the stored piece — in a search overlay, in a container's menu header, and on
whatever comes out of it. Same field as
[`tableObjectDefinitionSchema.displayName`](https://diceytable.com/docs/mods/reference/object-state).

Not part of the identity key, so it merges away like `label`. Worth setting anyway: it is the name a player
reads when an infinite container refuses a piece ("Only Black Stones go in this container").

### `tooltip`

The stored piece's hover tooltip. Same shape and rules as
[`tableObjectDefinitionSchema.tooltip`](https://diceytable.com/docs/mods/reference/object-state#tooltip), and like that field, absent
means the piece shows no tooltip.

Not part of the identity key. Two pieces that differ only in their tooltip are the same piece to a container, so a
drop can merge into a run whose stored tooltip is different, and what comes out is whatever the run was created
with. Treat a tooltip here as the one a drawn piece starts with.

### `physics`

Physics overrides for the stored piece: body type, mass, friction, restitution, damping and the collider. Same
shape as [`tableObjectDefinitionSchema.physics`](https://diceytable.com/docs/mods/reference/object-state), and absent means the
per-kind defaults.

Not part of the identity key — two pieces differing only in mass are the same piece to a player, and the run
keeps the first one's values.

### `castShadows`

Whether the drawn copy casts a shadow. Same field as
[`tableObjectDefinitionSchema.castShadows`](https://diceytable.com/docs/mods/reference/object-state).

Not part of the identity key. Worth a thought for a piece stored in hundreds: shadow casting is per instance,
and a bowl that empties onto the table all at once multiplies whatever you set here.

### `receiveShadows`

Whether the drawn copy receives shadows. Same field as
[`tableObjectDefinitionSchema.receiveShadows`](https://diceytable.com/docs/mods/reference/object-state).

### `flippable`

Whether the drawn copy, when it is a `token`, offers **Flip**. Same field as
[`tableObjectDefinitionSchema.flippable`](https://diceytable.com/docs/mods/reference/object-state#flippable): absent
means "decide from the shape".

Not part of the identity key (`containerItemIdentityKey`), so two tokens that differ only in
`flippable` count as the same piece to an infinite container and to a bag's run-merging.

### `material`

The stored piece's physical surface — `wood`, `cardboard`, `metal`, and the rest of the twelve
[`SoundMaterial`](https://diceytable.com/docs/reference/enums/sound-material) values — driving impact sounds and the physics
baseline. Same field as [`tableObjectDefinitionSchema.material`](https://diceytable.com/docs/mods/reference/object-state).

Not part of the identity key. Absent means the kind's default, resolved when the copy spawns.

### `soundSetOverrides`

Per-object sound set overrides carried on the stored piece, so a drawn copy sounds right from its first
contact. Same field as [`tableObjectDefinitionSchema.soundSetOverrides`](https://diceytable.com/docs/mods/reference/object-state).

Not part of the identity key: two pieces differing only in their sounds merge into one run, and the surviving
run keeps the first one's overrides.

### `materialSlots`

Per-slot material overrides for the stored piece. Same field as
[`tableObjectDefinitionSchema.materialSlots`](https://diceytable.com/docs/mods/reference/object-state); at most 64 entries.

**Part of the identity key**, compared key-sorted. Two copies of one model finished differently are different
pieces, for the same reason as `color`.

### `metadata`

The stored piece's free-form metadata — and the field that carries most of what makes it a *particular* piece:
the model reference (`customModelAssetId`, `standardPresetId`, `tokenShape`), the die type and side count, and
`materialId`. Same field as [`tableObjectDefinitionSchema.metadata`](https://diceytable.com/docs/mods/reference/object-state).

**Those keys are part of the identity key; the rest of `metadata` is not.** So two tokens carrying different
game state under their own keys merge into one run, and whichever state the run was created with is what every
copy taken out of it carries. If a piece's metadata must survive being put into a container and taken back
out, that is a per-instance value, and a container does not preserve per-instance values.

### `faceValue`

The stored piece's face value — the number a die or token is showing. Same field as
[`tableObjectDefinitionSchema.faceValue`](https://diceytable.com/docs/mods/reference/object-state).

Not part of the identity key, and this is the one people expect to be: a d6 stored showing 4 and one stored
showing 1 merge into the same run, and what comes out is whatever the run was created with. Dice are rolled
after they leave a container, so the stored value is a starting state, not a memory.

### `overlay`

Overlay values and counters carried on the stored piece — the badges drawn on top of it. Same shape as
[`tableObjectDefinitionSchema.overlay`](https://diceytable.com/docs/mods/reference/object-state).

Not part of the identity key. A counter incremented on one instance does not survive storage: the run keeps
the definition it was created with, so treat an overlay here as the state a piece *starts* with.

### `containerItemDefinitionSchema.rotation`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `x` | `number` | **yes** | — | — | — | — | — |
| `y` | `number` | **yes** | — | — | — | — | — |
| `z` | `number` | **yes** | — | — | — | — | — |

#### `rotation.x`

Pitch in degrees, applied to the copy a draw spawns.

#### `rotation.y`

Yaw in degrees, applied to the copy a draw spawns. The usual one to set — a piece with a front, such as a
printed tile, needs a facing when it arrives.

#### `rotation.z`

Roll in degrees, applied to the copy a draw spawns.

### `containerItemDefinitionSchema.tooltip`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `enabled` | `boolean` | **yes** | — | — | — | — | — |
| `title` | `string` | no | — | <= 120 chars | — | — | — |
| `description` | `string` | no | — | <= 1000 chars | — | — | — |
| `showDetails` | `boolean` | no | — | — | — | — | — |
| `vars` | `tooltipVariablesSchema` | no | — | — | — | A tooltip may not hold more than 32 variables. | — |

#### `tooltip.enabled`

Whether the stored piece's tooltip shows once it is drawn. See
[`tableObjectDefinitionSchema.tooltip.enabled`](https://diceytable.com/docs/mods/reference/object-state#tooltip).

#### `tooltip.title`

The stored piece's title template, at most 120 characters. See
[`tableObjectDefinitionSchema.tooltip.title`](https://diceytable.com/docs/mods/reference/object-state#tooltip).

#### `tooltip.description`

The stored piece's description template, at most 1,000 characters. See
[`tableObjectDefinitionSchema.tooltip.description`](https://diceytable.com/docs/mods/reference/object-state#tooltip).

#### `tooltip.showDetails`

Whether the stored piece's tooltip shows its built-in detail lines; absent means shown. See
[`tableObjectDefinitionSchema.tooltip.showDetails`](https://diceytable.com/docs/mods/reference/object-state#tooltip).

#### `tooltip.vars`

The stored piece's tooltip variables — the values a drawn copy starts with, not a record of what any instance
reached during play. See
[`tableObjectDefinitionSchema.tooltip.vars`](https://diceytable.com/docs/mods/reference/object-state#tooltip).

### `containerItemDefinitionSchema.physics`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `bodyType` | `"static"` \| `"dynamic"` \| `"kinematic"` | no | — | — | — | — | — |
| `mass` | `number` | no | — | > 0 | — | — | — |
| `friction` | `number` | no | — | >= 0, <= 1 | — | — | — |
| `restitution` | `number` | no | — | >= 0, <= 1 | — | — | — |
| `linearDamping` | `number` | no | — | >= 0, <= 1 | — | — | — |
| `angularDamping` | `number` | no | — | >= 0, <= 1 | — | — | — |
| `collisionShape` | `"auto"` \| `"box"` \| `"sphere"` \| `"capsule"` \| `"cylinder"` \| `"convexHull"` \| `"mesh"` | no | — | — | — | — | — |
| `collisionSize` | `positiveVector3TupleSchema` | no | — | — | — | — | — |
| `collisionOffset` | `vector3TupleSchema` <br>same shape as `rotation` | no | — | — | — | — | — |
| `rigidbodyEnabled` | `boolean` | no | — | — | — | — | — |
| `collisionEnabled` | `boolean` | no | — | — | — | — | — |
| `weldChildren` | `boolean` | no | — | — | — | — | — |

#### `physics.bodyType`

`dynamic`, `kinematic` or `static` for the copy a draw spawns. See
[`tableObjectDefinitionSchema.physics.bodyType`](https://diceytable.com/docs/mods/reference/object-state).

Leave it dynamic unless the piece is scenery. A `static` piece taken out of a container cannot be picked up
or pushed.

#### `physics.mass`

The drawn copy's mass in kilograms, greater than zero, and meaningful only on a dynamic body. See
[`tableObjectDefinitionSchema.physics.mass`](https://diceytable.com/docs/mods/reference/object-state) for the per-kind defaults.

#### `physics.friction`

Surface friction for the drawn copy. See
[`tableObjectDefinitionSchema.physics.friction`](https://diceytable.com/docs/mods/reference/object-state). Worth setting on a piece
that lives in a bowl: too little and a heap of them slides apart.

#### `physics.restitution`

Bounciness for the drawn copy. See
[`tableObjectDefinitionSchema.physics.restitution`](https://diceytable.com/docs/mods/reference/object-state). Keep it low for
anything dropped into a container repeatedly — a bouncy piece leaves the bowl it was aimed at.

#### `physics.linearDamping`

How quickly the drawn copy loses linear velocity. See
[`tableObjectDefinitionSchema.physics.linearDamping`](https://diceytable.com/docs/mods/reference/object-state).

#### `physics.angularDamping`

How quickly the drawn copy loses spin. See
[`tableObjectDefinitionSchema.physics.angularDamping`](https://diceytable.com/docs/mods/reference/object-state).

#### `physics.collisionShape`

The collider the drawn copy is given. See
[`tableObjectDefinitionSchema.physics.collisionShape`](https://diceytable.com/docs/mods/reference/object-state).

Not part of the identity key — the collider is not something a player can see, so it never splits a run.

#### `physics.collisionSize`

The collider's **full** dimensions in feet, at the piece's identity scale. See
[`tableObjectDefinitionSchema.physics.collisionSize`](https://diceytable.com/docs/mods/reference/object-state).

#### `physics.collisionOffset`

The collider's centre offset from the piece's origin, in object-local feet. See
[`tableObjectDefinitionSchema.physics.collisionOffset`](https://diceytable.com/docs/mods/reference/object-state).

#### `physics.rigidbodyEnabled`

Whether the drawn copy gets a rigidbody at all. See
[`tableObjectDefinitionSchema.physics.rigidbodyEnabled`](https://diceytable.com/docs/mods/reference/object-state). A piece taken out
of a container with no rigidbody does not fall, settle or collide.

#### `physics.collisionEnabled`

Whether the drawn copy collides. See
[`tableObjectDefinitionSchema.physics.collisionEnabled`](https://diceytable.com/docs/mods/reference/object-state).

#### `physics.weldChildren`

Whether the drawn copy's parented children are welded into one compound body rather than simulated
separately. See [`tableObjectDefinitionSchema.physics.weldChildren`](https://diceytable.com/docs/mods/reference/object-state).

### `containerItemDefinitionSchema.overlay`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `values` | `Record<string, cardOverlayValueSchema>` | no | — | — | — | An object may carry at most 24 overlay values. | — |
| `counters` | `Record<string, number>` | no | — | — | — | An object may carry at most 24 counters. | — |
| `concealedValues` | `integer` | no | — | >= 1, <= 24 | — | — | — |
| `concealedCounters` | `integer` | no | — | >= 1, <= 239976 | — | — | — |

#### `overlay.values`

The overlay's labelled values as stored on the piece. See
[`tableObjectDefinitionSchema.overlay.values`](https://diceytable.com/docs/mods/reference/object-state).

#### `overlay.counters`

The overlay's counters as stored on the piece — the starting numbers a drawn copy arrives with, not a record
of what any instance reached. See
[`tableObjectDefinitionSchema.overlay.counters`](https://diceytable.com/docs/mods/reference/object-state).

#### `overlay.concealedValues`

**Redaction output only**, and it has no business in an authored definition: it counts the overlay values
withheld from one recipient. See
[`tableObjectDefinitionSchema.overlay.concealedValues`](https://diceytable.com/docs/mods/reference/object-state).

If you are reading a non-zero value here in a save file or on the host, something is wrong.

#### `overlay.concealedCounters`

**Redaction output only**, like `concealedValues` — the number of counters withheld from one recipient. See
[`tableObjectDefinitionSchema.overlay.concealedCounters`](https://diceytable.com/docs/mods/reference/object-state).

Never authored, never persisted.

### `containerItemDefinitionSchema.physics.collisionSize`

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `x` | `number` | **yes** | — | > 0 | — | — | — |
| `y` | `number` | **yes** | — | > 0 | — | — | — |
| `z` | `number` | **yes** | — | > 0 | — | — | — |

#### `physics.collisionSize.x`

Collider width in feet — a full dimension, not a half-extent.

#### `physics.collisionSize.y`

Collider height in feet — a full dimension, not a half-extent.

#### `physics.collisionSize.z`

Collider depth in feet — a full dimension, not a half-extent.
