Reference
Object kinds
The 11 TableObjectKind values (card to coin) — what each does at the table, its physics defaults, its default scale/color, and which fields matter.
On this page14 sections
TableObjectKind is a Scene Entity's Platform kind
— shown as TYPE in the Inspector's PIECE panel. There are 11 values, defined as plain
string constants in packages/shared/src/tableObjects/kinds/index.ts and collected into
TABLE_OBJECT_KINDS:
card · deck · die · token · board · bag · custom · card-holder · button · table · coin
The kind is fixed at spawn time (an existing entity's kind is never changed in place) and
drives three things: which physics defaults the runtime applies when the entity has no
physics override, the collision geometry the runtime builds, and which of the
optional TableObjectState fields are meaningful. It does not gate which
actions can target the entity — that is a related
but separate table.
Physics defaults, at a glance#
These are the values apps/web/src/playcanvas/physics/collisionHelpers.ts (createRigidbodyConfig,
called from TabletopRuntime.createObject) reads from
apps/web/src/playcanvas/physics/PhysicsEngine.ts's per-kind functions
(massForKind, frictionForKind, restitutionForKind, linearDampingForKind,
angularDampingForKind) when building an entity's rigidbody and it has no explicit
physics.mass / physics.friction / … override. A kind missing from one of those switch
statements falls through to that function's default case, called out below.
| Kind | Mass | Friction | Restitution | Linear damping | Angular damping | Default sound material |
|---|---|---|---|---|---|---|
card |
0.05 | 0.72 | 0.1 (default) | 0.07 | 0.08 (default) | card |
deck |
1.6 | 0.76 | 0.1 (default) | 0.05 (default) | 0.08 (default) | card |
die |
0.35 | 0.82 | 0.52 | 0.02 | 0.015 | plastic |
token |
0.18 | 0.78 | 0.14 | 0.04 | 0.06 | plastic |
coin |
0.18 | 0.78 | 0.14 | 0.04 | 0.06 | metal |
board |
4 | 0.92 | 0.1 (default) | 0.05 (default) | 0.08 (default) | wood |
bag |
0.8 (default) | 0.8 | 0.1 (default) | 0.05 (default) | 0.08 (default) | tile |
custom |
0.8 (default) | 0.82 | 0.1 (default) | 0.05 (default) | 0.08 (default) | generic |
card-holder |
0.8 (default) | 0.8 (default) | 0.1 (default) | 0.05 (default) | 0.08 (default) | wood |
button |
0.8 (default) | 0.95 | 0.04 | 0.12 | 0.3 | plastic |
table |
0.8 (default) | 0.8 (default) | 0.1 (default) | 0.05 (default) | 0.08 (default) | wood |
die's friction (0.82) is deliberately high — it converts a thrown die's slide into
roll/tumble rather than letting it skate flat, and pairs with the highest restitution
(0.52) of any kind so it actually bounces.
A second, unrelated set of "default physics" exists — do not confuse the two.
packages/shared/src/tableObjects.tsalso exportsdefaultObjectPhysicsForKind(), whose numbers do not match the table above (e.g. it givesdecka mass of0.3against the runtime's1.6, anddiea mass of0.02against the runtime's0.35). That function is explicitly documented as "suggestions only" for the editor's physics inspector placeholders (TableEditModeShell.tsx) — it is never written onto object state and never applied by the runtime. The table above, fromPhysicsEngine.ts, is what a spawned object actually gets.
Default scale and color#
When a spawn omits scale / color (and does not come from a
standard preset, which supplies its own), the
runtime falls back to DEFAULT_SCALE / DEFAULT_COLOR in TabletopRuntime.ts:
| Kind | Default scale (ft) | Default color |
|---|---|---|
card |
0.2083 × 0.000984 × 0.2917 (a 2.5 × 3.5 in poker card, one 0.3 mm sheet) | #f6f1df |
deck |
0.2083 × (52 × 0.000984 = 0.0512) × 0.2917 (15.6 mm tall) | #a23c3c |
die |
0.05 × 0.05 × 0.05 | #f4f6f8 |
token |
0.12 × 0.04 × 0.12 | #4c8c6a |
coin |
0.08187 × 0.01575 × 0.08187 (the built-in coin's real size, 25 mm across) | #c9a227 |
board |
1.2 × (board thickness) × 0.9 | #2c6e6a |
bag |
0.5 × 0.5 × 0.5 | #7257a6 |
custom |
0.6 × 0.2 × 0.6 | #60758f |
card-holder |
0.6 × 0.04 × 0.36 | #3a5f7a |
button |
0.396 × 0.101 × 0.296 (the default rect button's footprint; a configured button sizes itself from metadata.button) |
#ff5b5b |
table |
6 × 0.2 × 4 (a placeholder slab, drawn only while — or if — the table's model never loads) | #6b4a32 |
A card's and a deck's Y is the one dimension that is not static, and not yours to
author: syncStackScale (TabletopRuntime.ts) rewrites it on every spawn and every change
of count. A card is one sheet of paper and a deck is stackCount sheets, so a 10-card deck
is thinner than a 52-card one whatever scale says. A sheet is 0.3 mm — a standard
playing card — unless the entity carries metadata.paperThicknessMm
(see Card and Deck).
Card#
A single playing card. label is the card's identity for hidden-information
redaction — see IDs, names and tags.
faceDown— whether the card is showing its back.fliptoggles it.ownerSeat— when set, the card is in that seat's hand (getHandObjectsFromSnapshottreats any object with a non-emptyownerSeatas a hand card, regardless of kind).metadata.cardCornerRadius— corner rounding for the rendered card mesh; backfilled to a default if missing or non-numeric.metadata.paperThicknessMm— how thick the card is, in millimetres (always mm, whatever unit the editor displays). 0.05–3; absent means 0.3, a standard playing card. A value outside the range is clamped, and anything that is not a positive number is read as the default. A card drawn or dealt from a deck inherits the deck's value. Authored as Paper thickness (mm) in the Inspector's PIECE panel.metadata.customDeck— when the card belongs to a custom deck sprite sheet, the sheet slice used to render its face.metadata.faceUrl— a direct image URL for the card's front face (F4): an absolutehttp(s)URL or a repo-relative asset path (resolved the same way any other mod asset is). It textures the whole card face — no sprite sheet, no catalogue — and is the simplest way for a mod script to spawn a card with custom art:createObject({ kind: "card", metadata: { faceUrl: "https://…/anakin.jpg" } }). It renders on the 3D table and in the hand drawer. A face URL identifies the card, so it is redacted exactly likecardId: a face-down card in another player's hand (or an unowned face-down card on the table) never sends itsfaceUrlto other peers — it shows the back. Only face-up (or owner/team-visible) cards expose it.metadata.backUrl— a direct image URL for the card's back. Public (a back is what a hidden card is shown as); omit it to use the standard card back.- Collision: a thin box collider, half-height
max(scaleY / 2, 0.01)— the smallest clearance of any kind (collisionHalfHeightForObject).
Reachable actions: lift, flip, rotate, lock/unlock, combine, flick,
reveal-all/reveal-team-a/reveal-team-b, delete. Not shuffle, draw, deal,
split, roll — see the per-kind action matrix.
Deck#
A container of cards that behaves as one physical stack.
stackCount— how many cards the deck holds; also feeds the height derivation above. 1–1000.metadata.paperThicknessMm— the thickness of one card in the pile, in millimetres; same range and default as on a card. The deck standspaperThicknessMm × stackCounttall — 52 cards at the default 0.3 mm is 15.6 mm — and every card that leaves the deck takes the value with it.faceDown— the deck's face;flipflips every card entry too and re-derives the visible face.metadata.cards— the ordered container entries (cardId+ per-cardfaceDown). Absent on adeck, the runtime synthesizes a standard 52-card deck on first read (buildStandardDeckCardEntries).metadata.customDeck— as forcard, when the deck's faces come from a custom sprite sheet rather than the built-in playing-card art.metadata.faceUrls— a direct-URL face map{ [cardId]: url }(F4), one entry per distinctcardIdinmetadata.cards. The runtime textures the deck's top/bottom card from the matching URL; a card drawn from the deck copies the map (and any sharedmetadata.backUrl) so it stays self-describing. It is the deck-scale sibling of a single card'smetadata.faceUrl. The whole map is host-only. Its keys are the deck's ordered card ids, which no peer may learn (a deck's order is secret), so redaction rebuilds it to at most the single publicly-visible top card's entry — in lockstep with how it strips the orderedmetadata.cardsto the visible top. The one exception is a private peek: a player who runs thepeekaction receives the top-N entries (and their face URLs) un-redacted in their own snapshot only, for as long as the host holds the reveal.metadata.backUrl— a shared direct-URL back for every card the deck holds. Public.splitrequiresstackCount > 1;draw/deal/shuffleoperate onmetadata.cards.
Reachable actions: everything a card can do, plus shuffle, draw, deal, split, peek.
Die#
A single die. label defaults to the generic name "D6" regardless of the die's actual
face count — labelForKind() (apps/web/src/playcanvas/objectHelpers.ts) has one
case for die and does not branch on metadata.dieSides. The face count itself lives in
metadata, not the schema:
metadata.dieSides— 4/6/8/10/12/20 in the standard presets. It is written by the presets (packages/shared/src/standardObjects.ts) and read by nothing: the model and its face numbering are both resolved frommetadata.standardPresetId, not from this. Treat it as informational.metadata.dieFaceStyle— e.g."dots"for a pipped d6.- Collision: a convex hull by default (
basePhysicsForKind's suggestion), so bevels and faces tumble faithfully; the runtime's actual applied physics (table above) uses the generic collider path sincediehas no case incollisionHalfHeightForObject. - Highest restitution and friction of any kind — see the physics table above.
faceValue— a schema field, not metadata: the number printed on the face a settled die is showing. The host computes it on settle and replicates it, and drops it while the die is tumbling, held or cocked. A die imported as a custom model has no face table and never gets one. SeefaceValue.
Reachable actions: lift, rotate, lock/unlock, roll, flick, delete. Not flip,
shuffle, draw, deal, split, combine, or any reveal-*.
Token#
A small marker or piece — checkers, chips, pawns of a generic shape.
metadata.tokenShape—"cylinder"or"box", selecting the rendered primitive.metadata.chipValue— casino-chip presets attach a numeric value here; purely cosmetic/informational, not read by any gameplay path inpackages/shared.metadata.dualSided— e.g. the Reversi chip, which renders two colors on opposite faces.flippable— whether the token offers Flip. A top-level field, not ametadatakey. Absent means "decide from the shape".
Flipping a token#
Checkers, Othello discs and punchboard chits get turned over (a coin is its own kind, and turns over the same way); meeples and miniatures do not. A token therefore answers "can I flip?" in this order:
- its own
flippable(trueorfalse), set insetup.json, by the Inspector's ▸ , or copied at spawn from its model's.meta.jsonflippable; - otherwise its shape: a token is flat — and flips — when its height is at most half its
narrower footprint (
isFlatTokenShape,FLAT_TOKEN_MAX_HEIGHT_RATIO = 0.5). A checker (0.36 in tall on a 1.42 in footprint) is flat; a meeple, a miniature or a cube is not. The shape is measured on the piece's real world-space size, so a custom model is judged by the geometry it actually has.
A token that may flip turns over 180° about its own X axis, in place: its collider keeps its
centre X/Z and its underside stays on whatever it was resting on, so a model whose origin is its
base does not sink into the table. It does not toggle faceDown — a token has no hidden face;
which side is up is its rotation — and nothing else changes. With metadata.tokenFaceImage /
tokenFaceBackImage set, a flip is what shows the back art.
A token that may not flip does not show Flip in the context menu, on the touch rail or in the VR
object menu, and a flip addressed to it — from a player, a table script's handle.flip() or a
mod's api.objectAction(id, "flip") — is refused by the host and changes nothing.
Set flippable explicitly only when the shape guesses wrong: true for a chunky two-sided
marker taller than half its width, false for a flat standee that must stay face up.
Printed faces#
A token can carry art on its flat faces — a punchboard counter, a printed chip, a
damage marker — while keeping color as the body.
metadata.tokenFaceImage— art printed on the up-facing side. A repo-relative asset path, a public path (/mods/…), or anhttp(s)/data:/blob:URL.metadata.tokenFaceBackImage— art for the down-facing side. Omit it for a double-sided counter: the face art is used on both sides rather than leaving a blank back.metadata.tokenFaceFit—"cover"crops the art to fill the face; anything else (the default) maps it to the face as authored.
The art is alpha-blended over the body colour, so a PNG/WebP with transparency reads as
an overlay printed on a coloured chip and an opaque image simply hides the colour. Only the
two flat faces are printed — the rim stays color, which is what keeps a picked-up token
looking like a physical counter instead of a cube wrapped in one image. (That wrapping is
what metadata.customTextureAssetId does, and it is the right choice for a flat tile viewed
from above.)
Printed faces require metadata.tokenShape: "box". The face is a rectangular plane
matching the token's footprint, so on a "cylinder" token its corners would overhang the
round body; a cylinder token therefore ignores these keys and keeps its plain colour. Set the
token's scale.x/scale.z to the art's aspect ratio — the face is mapped to the footprint,
so a square image on a non-square token stretches unless you use "cover".
{
"kind": "token",
"label": "Force",
"position": { "x": 0, "y": 0.0, "z": 0 },
"scale": { "x": 0.105, "y": 0.018, "z": 0.105 },
"color": "#b32222",
"metadata": {
"tokenShape": "box",
"tokenFaceImage": "assets/textures/counter-force.webp"
}
}
An unresolved path leaves the token its plain body colour rather than erroring — a repo-relative path whose asset resolver has not primed yet prints as soon as it does.
Reachable actions: lift, rotate, lock/unlock, flick, delete, and flip for a
token that may turn over (see above). No container actions, roll,
combine, or reveal-*.
Board#
A static playing surface — a game board, mat, or other furniture-like piece.
- Nearly every board preset ships
locked: true— boards are meant to stay put once placed. metadata.boardStyle— selects the rendered board art/grid (e.g."chess-wood","go-grid").metadata.boardImageUrl— a board face image, which takes precedence overboardStyle. Accepts a repo-relative asset path (assets/textures/mat.webp), a public path (/mods/…), or anhttp(s)/data:/blob:URL — all resolved the same way every other asset reference is. An unresolved path leaves the board its base colour; it does not fall back to a grid pattern, so a mod's art is never silently replaced by a checkerboard.- Heaviest default mass (4) and highest default friction (0.92) of any kind, consistent with something static and not meant to slide.
- Collision:
collisionHalfHeightForObjectgivesboardits own case — half-height is the scale-derived value plus a configured top clearance, rather than the genericscaleY / 2every other kind gets, so pieces resting on it do not clip through. - A piece authored inside a board is lifted out, not dropped through. With a recessed mesh board (a tray, a backgammon case) it is easy to place a checker a little below the felt in Edit Mode. The host checks loose, unlocked, unparented pieces against boards when the table goes live, when a board's real collider finishes loading, and when a piece becomes dynamic, and moves any piece found inside a board's collider up onto the floor above it. The drop-height probe does the same for a piece that starts a drop inside a board, so it rests on the felt rather than on the board's underside.
Reachable actions: lift, rotate, lock/unlock, delete. flick is withheld from board
and from table, and from no other kind
(isObjectActionAllowedForTarget's flick case is target.kind !== "board" && target.kind !== "table").
Bag#
A random-draw or ordered container that is not a deck of cards — a dice bag, a chip bank, a Go bowl.
containerMode—"random","stack", or"queue", selecting draw order. The host resolves it from this field first, then the legacymetadata.containerModekey, then the per-kind default (randomfor abag,stackotherwise) —resolveContainerConfig,packages/shared/src/tableContainers.ts. Write the field.capacityLimit— 1–1000, resolved by the same precedence over the legacymetadata.containerCapacity. It refuses acombinethat would overflow the target pile, and that is the only route it gates. The standard presets: 60 (Bowl), 100 (Bag), 200 (each Go Bowl), 1000 (Infinite Bag).container— the replicated container configuration:form("holder"or"bag"),infinite, and the piececontentsof a finite bag. Everybagis given one on load, defaulting to{ form: "bag" }. A legacymetadata.infinite— the "Infinite Bag" preset's flag, which no code once read — is moved ontocontainer.infiniteand deleted frommetadataby the same load.formandinfinitealready decide which container actions a target will accept (isObjectActionAllowedForTarget); the drop-to-absorb and infinite-draw behaviours they describe are still being built, so treat the rest of the field as configuration the platform records and validates rather than something that yet changes play.
Reachable actions: lift, rotate, lock/unlock, draw, deal, flick,
delete. Not flip, split, combine, roll, any reveal-*, or shuffle — a bag
draws at random, so it has no order for a shuffle to change.
Custom#
The escape hatch for anything that is not one of the other nine shapes — chess pieces,
dominoes, mahjong tiles, blocks, notecards, a digital clock, 3D text. Most of a mod's
custom-modeled content is custom.
- Collision defaults to
"auto"in the suggestion function (basePhysicsForKind) — meaning "keep the runtime's current per-kind auto behavior" rather than a fixed primitive; author an explicitphysics.collisionShapefor anything with an unusual silhouette. metadatais where all of the kind-specific behavior lives, because there is no dedicated schema surface for it:tokenShape,text(the "3D Text" preset), and every other preset-specific key in Standard presets.- The "Card Holder" preset (id
card-holder) iskind: "custom", notkind: "card-holder"— see the next section for why that is not a contradiction.
Reachable actions: lift, rotate, lock/unlock, flick, delete. Same narrow set as
token.
Card holder#
A seat- or hand-associated holder entity. Watch the naming: the preset id card-holder
(labelled "Card Holder") is actually kind: "custom", so its name is not a guide to its kind.
The one preset in STANDARD_OBJECT_PRESETS that really is kind: "card-holder" is the KayKit
card-stand ("Card Stand"). So a card-holder entity is usually authored directly (a spawn or
template with kind: "card-holder"), and there is exactly one catalog preset that spawns one.
It also has no dedicated case in any of the runtime's per-kind physics functions or in
collisionHalfHeightForObject — every one of those falls through to its generic default
case for card-holder, which is why the physics table above shows five "(default)" values
for this kind, more than any other.
Holder behavior is driven by metadata, not by the kind. A holder captures a card or deck
dropped within a scale-derived planar radius and stamps metadata.holderId on it; what makes an
entity act as a holder at all is metadata.cardHolder === true, so any kind can be one and
card-holder is simply the stock shape for it.
⚠ A holder no longer confers a seat's ownership by itself. It used to: a holder that had
drifted inside a seat's zone stamped every card it captured with that seat, competing with — and
quietly overriding — the seat's own hand zone. That implicit fallback was removed. What remains
is an explicit opt-in: set metadata.holderOwnerSeat and the holder is treated as that
seat's rack, cards included, exactly as before. With neither, seat membership comes only from
the seat's hand zone. A holder published before that opt-in existed is promoted on load —
its own ownerSeat is copied into metadata.holderOwnerSeat once, so an existing mod's rack
keeps gating who may take cards out of it. The promotion never overwrites a value you wrote,
including an explicit null. See
Player Zones and seat templates
for when to reach for which.
Reachable actions: lift, rotate, lock/unlock, flick, delete — identical to
custom and token.
Button#
A pressable control: a coloured cap sitting in a frame, with optional text or an image on its
top face. Pressing it dips the cap, plays a sound and raises the press action — which a
table or mod script observes as
onPressed.
Two presets ship it: Button (rectangular) and Round Button. They are the SAME kind —
shape is configuration, not a separate type — so everything below applies to both.
Configuration#
Everything about a button lives in metadata.button, validated by buttonConfigSchema
(packages/shared/src/tableButtons.ts). It is metadata rather than object-state fields on
purpose: metadata already travels through the schema, the snapshot delta, migrations and
persistence with no threading, and a button needs a dozen knobs, none of which the server
ever queries.
Every field has a default, and a field the schema rejects (a travel below its minimum, a
color that is not #rrggbb) is dropped on its own and takes that default; the rest of the
configuration is kept. Nothing reports the dropped field, so a button that ignores one setting
is worth checking against the ranges in buttonConfigSchema.
| Field | Default | What it does |
|---|---|---|
shape |
"rect" |
"rect" or "round". Round uses width as the diameter and ignores depth. |
width / depth / height |
0.34 / 0.24 / 0.075 | The cap's footprint and how tall it stands, in table units (1 unit = 1 ft). |
travel |
0.032 | How far the cap sinks on a press. Clamped to 80% of height at render time. |
pressSeconds |
0.11 | Duration of the dip-and-return. |
colors |
see below | cap, capPressed, frame, base, text. |
frame |
on, 0.028 / 0.026 | The bezel: enabled, thickness, height. |
face |
{ kind: "none" } |
none, { kind: "text", text, size, bold }, or { kind: "image", texturePath, inset }. |
eventName |
"button-press" |
The name a press reports to scripts. |
capPressed is optional: leave it out and the runtime darkens cap by 22% for the held
state, which is usually what you want and always readable.
An image face is a repo-relative path resolved through the same AssetResolver as every
other asset, so it works local-first in the editor and from GitHub for remote peers. A
text face is drawn to a canvas locally and never crosses the wire — the same rule prop
surfaces follow.
Geometry#
The button is built from primitives at runtime, not from a model.glb. That is deliberate:
it is fully described by the numbers you are already editing, so it is correct the instant it
spawns, resizes live as you drag those numbers, and has no asset that can 404 (unlike most
prop presets, which render as placeholder boxes when their model file is absent). The stack,
bottom to top, is plinth → frame → cap → face, with the cap the only part that moves.
The object's scale IS buttonOuterFootprint(config) and every child is a fraction of it,
so there is exactly one place that decides how big a button is.
Pressing#
Click it. The press claims the pointer before the grab path — the same way a prop-surface button does — so pushing a button never also starts dragging it.
A press is an ordinary press object action, which means it is host-authoritative and
replicated like any other mutation: a peer's click sends an intent, the host applies it, and
every client animates its own cap. The cap dip is local cosmetics and starts immediately
on click, because feedback that waits for a round trip feels broken.
A locked button is still pressable. Both presets ship locked because locking is how a
control stays put — a stray drag sliding the End Turn button across the table is never what
anyone meant — so isObjectActionAllowedForTarget exempts press from the locked gate.
Unlock it in the inspector to reposition it.
Reachable actions: press, lift, rotate, lock/unlock, flick, delete.
Sound#
The press sound rides the ordinary sound path: the press object action raises the press
runtime event, which OBJECT_SOUND_EVENT_MAP.button binds to the press sound action. For a
plastic (the default) or generic button that resolves to the bundled sharp click
(counter.land) rather than the place thud, which read as the button being dropped. To give
one button its own click, set a per-object override in soundSetOverrides — the same mechanism
every other kind uses, so there is no button-specific sound API to learn.
Table#
Furniture the game is played on — a dining table, a card table with a felt top, a glass coffee table — placed as an entity inside a scene. The author-facing name is Table.
Not the same thing as a table pack. A table pack
is the surface a whole game sits on: it is assigned to a scene, it is not an entity, and it never
appears in the Hierarchy's Entities folder. A table entity is an ordinary scene entity that
happens to be furniture — a side table beside the play area, a second table in a room, or the
table itself when you would rather place it than assign a pack. Both carry a surface material,
and both colour the sound of what lands on them the same way.
- It is always an authored model — legs, rails, a recessed top — so its suggested collision
shape is
"auto"(built from the model) rather than a box. The6 × 0.2 × 4default scale and#6b4a32colour above are only the placeholder slab drawn while (or if) the model never loads. - Physics. The runtime's per-kind functions have no
tablecase, so every value in the physics table above is the generic default. The editor's suggestion (defaultObjectPhysicsForKind) is a static body with friction 0.8 and no bounce. - Static by kind, and locked from the Model editor. A
tableis the one kind the runtime makes static on the strength of its kind alone: with nophysics.bodyTypeit spawns static even when unlocked, so it never topples under its own legs. Static is not the same as unmovable, though —lockedis what stops a player dragging it. Setting a model's Type to Table in the Model editor writeslocked: trueandbodyType: "static"into its sidecar (unless you had already set either), so a table placed from it is fixed; a table spawned by a script should passlocked: trueitself. (Aboard, by contrast, is dynamic until locked — see RIGIDBODY.) - It is a surface. A scripted deal or draw into a zone that sits over a table lands the card on the table's top, exactly as it would on a board, rather than on the pack's play-surface plane underneath.
- It is never lifted out of a board. The host's check that moves a piece authored inside a board up onto its floor (see Board) skips tables, so a table overlapping a board's footprint stays where you put it.
- It survives a blank reset. Starting a blank table keeps every
tableentity (and every lockedboard) and clears the rest — the furniture is not a piece of the game. - Sound. Default material
wood.OBJECT_SOUND_EVENT_MAP.tablebindsreleaseandsettletoplace,falltofallandtoppletotopple— the board's set withoutboard-clear, because a table is set down and in principle knocked over, never swept. Its own sound matters far less than its Surface: every piece that lands on it is heard through that material, so a felt-topped table muffles a die and a glass one makes it ring. See Sound material § Struck-surface tone. - Scripting. A table script's
refObjectis aTableFurnitureObject, which adds nothing toObjectHandle; a table's starter script opens onglobalEvents.onObjectDropped.
Reachable actions: lift, rotate, lock/unlock, delete. Not flick — the same exception
as board — and none of the container, card, die or button actions.
Coin#
A coin — a flat piece that does everything a token does, and can also be tossed.
Its Type in the Inspector's PIECE panel reads Coin, and its default label is Coin.
- The built-in coins are coins. The five built-in coin presets —
coin,coin-1,coin-2,coin-5andcoin-10— spawn as kindcoin. - Your own coin model is a coin too. Set an imported model's Type to Coin (in the Inspector's PIECE panel, or the Model editor's Type for its sidecar) and it tosses exactly like a built-in one. Nothing about tossing depends on the preset.
- Older saves are upgraded on load. Before this kind existed, the built-in coins were
tokens.migrateTableSnapshotrewrites a savedtokenwhosemetadata.standardPresetVariantis one of the five built-in coin variants (BUILTIN_COIN_PRESET_VARIANTS) tocoin, and the runtime applies the same rewrite when it spawns an entity, so an already-publishedsetup.jsonholding a coin token loads as a coin too. The rewrite is idempotent and does not change the snapshot's schema version. Atokenthat is not one of those built-in variants — including a coin-shaped model you imported as a token — stays a token; change its Type to Coin to make it toss. - Physics, stacking and printed faces are a token's. The runtime treats
tokenandcoinas the same flat piece (isFlatPieceKind): the same physics row above, the same disc collider, the same stacking, and the samemetadata.tokenShapeand printed-face keys (tokenFaceImage,tokenFaceBackImage,tokenFaceFit— see Printed faces). - Defaults that differ from a token's: sound material
metal(a token's isplastic), colour#c9a227, and a default scale of 0.08187 × 0.01575 × 0.08187 ft — the built-in coin's real size. - Sound.
OBJECT_SOUND_EVENT_MAP.coinis the token's set —grab→pickup,release→drop,settleandcollide→place,fall→fall,topple→topple. A toss has no clip of its own.
Flipping a coin#
A coin offers Flip — turn over 180° in place — by default. It is flat by definition, so it
does not consult its shape the way a token does: flippable absent or true means it flips,
and only an explicit flippable: false (the Inspector's ▸ ) turns Flip off.
Flip works exactly as it does for a token: it changes the rotation and
nothing else.
Tossing a coin#
Every coin also offers Flip Coin, the toss action. In the context menu it reads Flip
Coin; the touch rail and the VR object menu shorten it to Toss. toss is different from
Flip: Flip turns the piece over in place, while a toss throws the coin straight up 6 to 12 in,
spinning end over end about a random horizontal axis with a slight sideways drift, and lets
physics decide which side lands up. The table's global speed limit caps the highest tosses at
about 11.5 in. The coin makes no sound of its own going up; you hear it land through its
ordinary settle and collide sounds. Nothing reports heads or tails. Read the coin's orientation
after it settles if your game needs the result.
The test is the kind and nothing else: isTossableCoin(target) is target.kind === "coin". A
locked coin does not toss. The host refuses a toss on a locked coin, or on any entity that
is not a coin, on every path — its own menus and an AI agent included — with no log line and no
movement. A coin parented to another entity is held in place and is not thrown. Players, and AI
agents through table_object_action, can toss a coin. Table scripts and mods cannot request it;
a table script observes it as "toss" on onObjectAction / onAction, and a coin's own script
through CoinObject.onTossed. See
Object actions.
The touch multi-select bar offers it for a selection made only of coins, and tosses every one of them, the way an all-die selection rolls every die; a locked coin in the selection is refused.
- Scripting. A coin script's
refObjectis aCoinObject, whose one addition isonTossed; a coin's starter script opens on it.
Reachable actions: lift, rotate, lock/unlock, flick, delete, flip (unless
flippable: false) and toss. No container actions, roll, combine, or reveal-*.
See also#
- Object actions — the full kind × action gating matrix.
- Object state — every
TableObjectStatefield, kind-agnostic. - Standard presets — the ready-made definitions built on these kinds.
- Action vocabularies — the three action vocabularies (engine/table-script/mod), a different axis from this page's per-kind gating.
ObjectKind— the eleven kinds the table-script declaration names.- Runtime sound events — the sound events these kinds emit.
SoundMaterial— the materials behind each kind's default sound, and how a surface colours what lands on it.- Mod scripting API —
TableObjectState.kind, reading a kind from a mod. ObjectHandle—ObjectData.kind, reading it from a table script.- Types —
SpawnObjectOptions.kind, choosing a kind at spawn.
