Working in the Editor
Player Zones, Seats and Seat Templates
Seat templates (linked, layout-detached, mirrored seats), seat-local +Z, seat dice and pieces, zone types and options, table zones, seat variables.
On this page19 sections
- The ten-seat model
- Seat templates
- Zone types
- Zone roles: play areas, discard piles and decks
- Who owns what a zone holds
- Table zones — the deck slot and the discard pile
- Privacy: what a hand zone actually hides
- Hand zone or card holder?
- Card holders owned by the seat template
- What happens at the table
- Dice owned by the seat template
- Starting-layout pieces
- Where rolled dice land
- The name label
- Recoloring a seat
- Seat layout — putting seats back on the table
- Deleting and restoring a seat
- Common mistakes
- See also
(open full size)The ten-seat model#
DiceyTable authors up to ten player-color seats — Red, Blue, Green, Yellow, Purple,
Orange, Pink, Cyan, White, Brown (PLAYER_SEAT_OPTIONS, packages/shared/src/protocol.ts) — under the
Hierarchy's Player Zones (N) folder. Each seat owns one seat group: a group transform
(position and rotation Y), one or more translucent zone boxes, and exactly one movable
name label. All of it is authored — you place it in the editor, and it lives in the scene
document, not on the wire (packages/shared/src/sceneEditor.ts).
In the editor, every seat group renders so you can author every one of them. At the live table, a seat's zones and label render only once a player claims that seat. That is not merely cosmetic: the rules a zone enforces are built from the zones that are visible, so an unclaimed seat's zones enforce nothing at all.
A new table starts with all ten seats: three along each long edge and two at each end. The zones are narrowed to fit, so neighbouring hand zones never overlap. A table authored when the palette had eight colors keeps its eight seats. White and Brown appear as buttons under ADD SEAT on the Player Zones folder. Add them, then use SEAT LAYOUT to re-space the ring for ten.
Seat templates#
Authoring ten seats by hand is ten times the work, and the angles come out subtly wrong. A seat template is one layout — a name label, typed zones and card-holder definitions, and optionally the seat's own dice, a starting layout of pieces and a dice tray — authored once and applied to as many seats as you like. Neither Tabletop Simulator nor Tabletop Playground has an equivalent; in both you duplicate a group of zones per seat and rotate each copy by hand.
A scene has at most one template, and every seat is in one of three states:
| State | What the seat stores | What it follows |
|---|---|---|
| Linked | Its group transform (position + rotation Y), its color, an optional per-seat label text, optional per-seat changes to the template's dice and pieces, and whether it is mirrored | Its zones, label geometry, card holders, starting pieces and dice tray are the template's |
| Layout detached | Everything a linked seat stores, plus its own world-space zones and name label | The template's card holders, starting pieces, dice tray and dice — with this seat's overrides — but not its layout |
| Detached | Everything — its own world-space zones, label and holders | Nothing; the template is ignored for it |
Layout detached is the middle ground for a seat whose board cannot be a rotated copy of the template's — an asymmetric mat, a seat with one extra zone — but whose player should still get the template's dice and pieces and keep their per-seat colours. Before it existed the only way to customise one seat's zones was a full detach, which also cut the seat off from the template's dice, pieces and holders.
A scene with no template has every seat detached, which is exactly the behaviour that existed before templates: nothing changes for an older mod.
Scale belongs to the template, structurally#
The template carries one uniform Scale. A linked seat has nowhere to store a scale — its
group transform is position and rotation Y only. "Every seat matches the template" is therefore
true by construction rather than by validation, and no player can end up with a bigger hand
area than another. A seat that genuinely needs its own size detaches; that is what detaching is
for.
Mirrored seats#
Some boards are not rotationally symmetric: on the Star Wars TCG mat both players' Space arenas sit on the same side of the table, so the far seat's layout is the near seat's reflected, not rotated. Tick Mirror on a bound seat and the template is reflected across that seat's own X axis before its group transform is applied — positions flip side and every yaw is negated — so both seats stay linked to one template and still match the art.
Mirroring reflects placement, never content. A mirrored hand still fills and overlaps
left-to-right from its own player's point of view (New cards go to and Card overlap keep their
meaning), area auto-arrange keeps its order, text is never mirror-written, and a piece's model is
not mirror-imaged — its pose is reflected (a piece turned 30° becomes one turned −30°). On a linked
seat Mirror reflects the zones and name label; on any bound seat it reflects the template's card
holders, pieces and dice tray. Zone ids and names are the same as on an unmirrored seat, so a
script that finds "Space" on every seat by name keeps working.
Seat-local space — the one thing you can get wrong silently#
Template geometry is authored in seat-local space: the origin is the seat's group pivot,
+Z points at the table centre, and units are world units (feet). Each linked seat's group
transform then places and turns that layout:
worldPosition = group.position + rotateY(group.rotationY) × (template.scale × M × localPosition)
worldRotationY = group.rotationY ± localRotationY
worldSize = template.scale × localSize
M flips local x (and the ± is −) only for a mirrored seat; otherwise it
is the identity.
Rotations here are degrees, everywhere — the group's, the zone's and the label's.
The practical consequence: author the layout as though the seat sits at the near edge of the
table looking away from you, with the hand area at small +Z and anything that belongs further
into the table at larger +Z. Get the sign wrong and every seat's layout points outward, away
from the table, in a way that looks deliberate until you claim a seat.
The five template actions#
All five live on the Player Zones folder's Inspector, except the seat's Binding (Linked, Layout detached, Fully detached) and Mirror, which are on the seat itself. See Player Zones Folder for the fields.
- Define — creates an empty template: one seat-local name label and one
Handzone. - Promote a seat to template… — copies one seat's zones and label into the template, converting world space to seat-local using that seat's group transform, and links that seat. It also offers to adopt the card holders standing inside that seat's zones as template holders. This is the ergonomic heart of the feature: build one player's area by hand until it looks right, then promote the lot.
- Apply to… — links the seats you tick and materializes the template onto them. You choose between keep each seat's current group transform and re-arrange the seats evenly around the table. Because applying can create and delete real card holders, the confirmation states the object delta plainly — "creates 12 card holders, updates 4, deletes 0".
- ▸ — freezes the template's current zones and name label onto that one seat, which then owns them, while the template keeps supplying its dice, dice tray, pieces and card holders. Nothing moves and nothing is released. Choosing it on a fully detached seat binds that seat again while keeping the zones it already has.
- ▸ — freezes the template's current geometry onto that one seat and drops the link entirely. Detaching is a visual no-op: nothing moves, and the seat keeps every card holder and piece it had (they simply stop being template-owned, so no later re-apply can remove them).
- ▸ — re-links a detached seat: its own zones are replaced by the template's (confirmed first when it has zones to lose).
- Clear Template — detaches every seat first, then removes the template. No object is ever deleted by clearing.
Every one of them goes through the ordinary scene-draft undo.
Editing a linked seat#
Select a linked seat and its Hierarchy row shows no children — there is nothing
seat-specific to select, because its layout is the template's. Its Inspector shows a
TEMPLATE LINK section badged LINKED, a GROUP TRANSFORM whose Scale is disabled and
badged 🔒 from template, and a LABEL TEXT override.
Dragging a zone gizmo while a linked seat is the template's preview seat edits the template: the committed world transform is converted back into seat-local space, and every linked seat moves in the same frame. That is the intended way to work — you are looking at one seat and editing all of them.
Zone types#
A zone box carries a type, and the type is what the zone does. Four types have behaviour today.
| Type | What it does |
|---|---|
Hand |
The seat's private hand area. An entity dropped here gets that seat as its owner, feeding the hand panel and the face-down redaction rules. A seat may have several, and their cards show as one hand. |
Area |
A play area or personal board. Gates who may interact with what is inside. Confers no hand membership. |
Hidden |
Conceals its contents from anyone not entitled to the seat, regardless of face-up or face-down. |
Scripting |
A geometry-only trigger volume. No engine rule of its own — it exists so a script can attach meaning to a region. |
Five more types — Reveal, Layout, Randomize, Fog of War and Drop — parse and render
but have no behaviour yet. They are in the schema so a scene authored on a newer client
still loads on an older one. Authoring one gives you an inert region and enter/leave events,
nothing more.
Enter and leave events fire for every type, Scripting included — see
globalEvents.onZoneEnter for table
scripts and onZoneEnter for mods. Scripting
is therefore best read as "a region that means something to my rules and nothing to the
engine", not as "the only type that raises events".
Several hand zones on one seat#
A seat (and the template) may define up to 8 Hand zones, as in Tabletop Simulator and
Tabletop Playground. Stud poker is the case they exist for: a small zone for the face-down
hole cards and a longer one beside it for the face-up board.
- One hand. A card in any of the seat's hand zones is in that seat's hand. The player's on-screen hand drawer shows every zone's cards as one hand, the primary zone's first.
- Deals fill the
Primaryzone first, then the seat's other hand zones in Hierarchy order, each up to its Max cards. TurningPrimaryon for one zone turns it off on the others. - Max cards steers, it never deletes. A card dropped into a full zone moves on to the next hand zone with room. If every zone is full, it stays where it was dropped.
- Cards entering is per zone. Set it to
Face upfor the board andKeep facing(orFace down) for the hole cards, and a stud deal comes out right with no script. - Privacy fails closed. A seat's face-down hand cards are public only when every one of its hand zones has Hide from other players off. Face-up cards are public either way.
The limit is enforced by the schema, not just the editor: a mod with more fails its
publish-time parse. Setting a ninth zone to Hand therefore silently demotes the oldest
hand zone to Area and posts a status-bar message naming it, using the row label the
Hierarchy shows. There is no dialog to dismiss, and the change undoes like any other.
Which way is "up": the arrow head#
In Edit Mode every zone shows an arrow head on its top edge, pointing away from the zone. It marks the edge the top of a card's art points at when the card is laid in the zone (a hand row, an area arrange, a tray), so you can see which way cards will read before you play-test. A tray fills from the opposite, bottom edge toward the arrow.
The top is the zone's own local +Z edge, and the zone's rotation is the only thing
that decides where it points. Where the zone sits on the table plays no part, and the rule is
the same for a seat zone and a table zone. Turn the zone and the arrow turns with it, along
with everything the zone lays out: 90° moves the top to a side edge, 180° flips it end for end.
A seat placed by the seat ring or by a seat template needs no attention. Seat-local +Z points
at the table centre, so such a seat's top is the edge on the far side from the player, and the
cards read the right way up for the player sitting there.
The box you see is the box that counts. At a rotation that is not a multiple of 90° — a seat on the curved end of an oval table — the area a zone owns and the row it lays out match the box as drawn.
Scenes authored before 2026-10-01. The top used to be re-pointed at the table centre whatever the zone's rotation. A zone turned to face away from the centre, or a table zone on the far half of the table, was therefore corrected automatically; it now lays its cards the way its arrow points. Turn the zone 180° to flip it. Separately, a zone at an angle that is not a multiple of 90° used to test "inside" and lay out its row against the mirror image of the drawn box, so pieces near its ends may now fall on the other side of the boundary.
Options every type has#
| Option | Effect |
|---|---|
| Name | The Hierarchy row label. An unnamed zone reads Zone 1, Zone 2, … — not its type name, so naming nothing never turns three untitled areas into three identical Area rows. The type is on the row already, as its type token. |
| Interaction | Anyone · Owner seat only · Blocked. Enforced on Area zones only, and offered on Area zones only — see the note below. |
| Show boundary | Everyone · Owner seat only. Who sees the zone outline. |
Tag filter (APPLIES TO) |
Gates occupancy itself. |
Tag filter is the option to reach for first. Its semantics copy Tabletop Simulator exactly:
no tags matches everything; one or more tags matches an entity sharing at least one of them.
An entity the filter rejects is not in the zone as far as any rule is concerned — it does not
get an owner from a Hand zone, it is not concealed by a Hidden zone, it raises no enter or
leave event, and it is absent from getZoneObjects. Reserved dt: platform tags are rejected
as filter entries; you filter on your own tags.
Interaction is an Area option. The positional interaction gate consults Area zones and
nothing else, so the Inspector offers the control on Area zones only. The schema still
accepts interaction on any type — a scene published while it was offered everywhere keeps
parsing, and its stored value is simply inert. To restrict who may act somewhere, draw an Area
zone there; a Hand or Hidden zone will not do it for you.
Options the type adds#
| Type | Option | Effect |
|---|---|---|
Hand |
Primary | The hand zone deals fill first. Turning it on turns it off on the seat's other hand zones. |
Hand |
Max cards | The most cards this zone holds before deals and dropped cards move on to the seat's next hand zone. 0 = no limit. |
Hand |
Shrink to fit | Once the row would overlap its cards more than Overlap before shrinking (60% by default), the cards shrink instead. See Shrink to fit. |
Hand |
Hide from other players | On (the default), this seat's face-down cards are private to it. Off, they are public — see below. |
Hand |
Cards entering | Keep facing, Face up or Face down: which side up a card turns when it is drawn, dealt or dropped into this hand. A face-up card in a hand is still private to its owner. (Replaces the old Cards face up checkbox; a hand that had it on shows Face up.) |
Hand |
Cards leaving | Keep facing, Face up or Face down: which side up a card turns when it is played from this hand onto the table. |
Hand |
Card overlap | Which neighbour a card is drawn over. Obeyed by the cards on the table and by the on-screen hand strip. |
Hand |
New cards go to | Which end a drawn or dealt card lands at while the player has their hand unsorted. |
Hand |
Sort methods | The orders a player can choose from by right-clicking their hand. See below. |
Hidden |
Hides | Everything conceals the whole entity; Card faces only neutralizes just the identity fields. |
Area |
Role | None, Play area, Discard pile or Deck: what the area is for. Drives the hand's Play menus and where a loaded deck lands. See Zone roles. |
Area |
Default play area | Shown when Role is Play area: where a plain Play sends a card. |
Area |
Cards placed here | Keep facing, Face up or Face down: which side up a card turns when it is played, sent, dropped or loaded into the area. Players can still flip it afterwards. |
Area |
Centre snap point | Adds a snap point at the zone's centre that follows the zone. |
Area |
Auto-arrange | Free, Stack, Row, Grid or Tray: how the pieces dropped inside are laid out. See below. |
Area |
Columns / Rows, Cell size, Gutter | The grid's shape and the row/grid slot spacing. |
Area |
Lanes, Piece rotation, Spacing, Infinite, Copies shown | The tray's shape and supply. See Trays. |
Area |
Shrink to fit, Overlap before shrinking, Grow grid by | Row, grid and tray: shrink the pieces rather than overflow. See Shrink to fit. |
Trays#
Tray stands pieces side by side in lanes that run from the zone's bottom edge toward its
top edge (the arrow head), the way chips stand in a rack. It takes cards, decks, tokens, dice
and custom models.
- Piece rotation turns every piece, in degrees about the zone's own axes: X runs across the
zone and Y points up. The default, 90° on X, stands a chip or a card on its edge. Set it to
0, 0, 0for pieces that should lie flat in a line. - Spacing is the gap between neighbours in a lane, in feet. A negative gap overlaps them, like chips leaning on each other.
- Lanes splits the zone's width into that many lanes. Lane 1 fills before lane 2.
- A lane that is too full closes up rather than spilling past the top edge, unless Shrink to fit is on, in which case the pieces shrink instead.
- Pieces at rest in a tray are held still (they are standing on edge, and the physics would otherwise topple them). Pick one up and it behaves like any other piece.
- Pieces are packed by the thickness they are drawn at, so chips with Spacing
0stand touching.
A tray's floor. A tray's pieces normally stand on the table under the zone. If the tray is a recess in the table model, lower the zone into it: a tray zone positioned below the table surface is taken as the floor of the recess, and its pieces stand at the zone's height. A zone at or above the surface still rests its pieces on the surface, so a zone left hovering never floats them. Moving, raising or lowering a tray zone re-lays its pieces at once.
Infinite turns the tray into a bottomless supply of ONE piece. Drop a single piece in and
the tray fills itself with copies of it: Copies shown of them, or as many as fit when that
is 0. Take one out and another appears in its place. Put one back and it returns to the
supply rather than overfilling the tray. A different piece dropped in is set down just
outside the tray's bottom edge, because an infinite tray holds one kind of piece only. Every
copy is a real entity, so keep Copies shown modest for big pieces.
In Edit Mode the copies an infinite tray shows are run-time copies: the scene holds only the
one piece that defines the tray, and the copies are not rows in the Hierarchy. Take a copy
out of the tray and it becomes an ordinary entity of the scene. It appears in the Hierarchy
with a full Inspector, it falls when the simulation goes Live, and the tray makes another copy
in its place.
Shrink to fit#
Shrink to fit is on Hand zones and on Area zones arranged as a row, grid or tray. Off,
a full zone does what it always did: a hand row and an area row close up with no limit, and a
grid stacks its surplus on the last cell. On:
- Pieces may overlap by up to Overlap before shrinking (a percentage of a piece). Past that,
every piece in the zone shrinks together so they all fit.
0shrinks as soon as neighbours would touch. A hand defaults to 60% because a hand is a fan. - A grid grows first: the 10th card in a 3 × 3 grid adds a column (or a row, per Grow grid by), then they alternate, and the pieces shrink to fit the larger grid.
- A piece picked up returns to its own size at once, and pieces grow back when the zone empties out again. Nothing below a fifth of full size.
The shrink is a real change to the piece's scale, so every player sees it and its collider
shrinks with it. The piece's own size is kept alongside (metadata.zoneFit), which is how it
gets exactly its old size back. A save taken mid-game restores the fitted pieces correctly.
Zones are two-dimensional: a footprint on the table plane with no height. There is deliberately no height field, because the occupancy test is a point-in-rotated-rectangle check that never reads one. An entity lifted high above a zone is still inside it, and a card resting on a board above a zone counts too. Every rule that reads zones agrees on that, which is the point. The zone's own height is read in exactly one place: it sets a sunken tray's floor, and never decides what is inside the zone.
Two Hidden zones overlapping is an AND, not a race. An entity inside seat A's and
seat B's Hidden zone is concealed from anyone not entitled to both — so neither A nor B
can read it, and only a viewer entitled to every owner (A's teammate who is also B's, or the
host) sees it. Hides resolves the same way: the strictest of the overlapping zones wins, so
one Everything zone makes the whole entity vanish even where the other says Card faces only. This matters most with a seat template, whose materialized zones sit on the table
perimeter at seat spacing — a generous template puts adjacent seats' zones within touching
distance of each other, and an entity that drifts into the seam belongs to both.
Zone roles: play areas, discard piles and decks#
An Area zone's Role tells the table what the area is for, so the players' card menus can
offer the right moves without a script:
- Play area. Right-clicking a card in your hand offers Play, which sends it to your default play area, and ▸ , which lists every play area you can use: your own seat's and the table's (unowned or yours), never another seat's. A card in a play area offers ▸ another play area, Back to hand or the Discard pile.
- Discard pile. Discard sends a card to your seat's discard pile, or to the table's when
your seat has none. At the table,
Xdoes the same for the hovered hand card or the selection.
Several pieces at once. Right-click any piece of a multi-selection and the zone rows move every selected piece, in the order they were selected; the row shows the count (for example Discard pile (3)). A piece the row does not apply to stays put: a token is never sent back to a hand, and a card already in the discard pile is not discarded again.
- Deck. When a player loads a deck, its main pile lands in their seat's
Deckarea. A deck with several piles (a sideboard, a second deck) sends each other pile to the seat's zone whose Name matches that pile's name; a pile with no match is laid out beside the deck as before.
Which area is the default. With exactly one play area, it is the default automatically. With several, the first one with Default play area on wins (in Hierarchy order: your seat's zones, then the table's). With several and none marked, there is no default: players see only ▸ and choose each time, so a card never lands somewhere they did not pick.
Facing is set on arrival only. A hand's Cards leaving and an area's Cards placed here
turn a card as it moves (a card played face down into a Face up area turns face up); after
that it is an ordinary card, and players can flip it. Keep facing leaves the card as it was.
The move is host-checked like a drag: the zone's Interaction rule still applies, so a card
cannot be sent into an area only its owner may use. AI agents make the same moves through
table_hand (play, to-zone, discard).
Who owns what a zone holds#
This section used to say the opposite, and the opposite was wrong. Stating it plainly:
- A
Handzone does confer ownership. Drop an entity inside one and the host stamps it with that seat, which is what makes it a hand card, what routes deals to it, and what feeds the face-down redaction rules. - An
Areazone does not. It gates interaction and nothing else. This is the fix for a real bug: before typed zones, dropping a card anywhere in any of a seat's boxes set the owning seat, so a discard pile counted as a hand card. A single-zone seat behaves identically before and after; a multi-zone seat gets the behaviour it always should have had. - A card holder no longer confers ownership by itself either — see Hand zone or card holder? below.
There is now exactly one writer of a seat's ownership: the seat's Hand zone (plus one
explicit opt-in on a holder). If an entity is not in a hand zone, it is not in anybody's hand.
Table zones — the deck slot and the discard pile#
A player zone is authored once per seat, which is right for a hand or a personal play area and wrong for everything a game has exactly one of. The Hierarchy's Table Zones (N) folder holds those: a deck location, a discard pile, a shared market row.
A table zone is the same box with the same options, with two differences:
- It is authored once, not eight times.
- It names its owner explicitly, because there is no seat above it to inherit one from.
Selecting a table zone row attaches the same transform gizmos a player zone gets: Move
writes Position, Rotate writes Rotation Y, and Scale writes Size X / Size Z
(clamped to the same 0.1–24 range the fields accept). The outline follows the drag live and the
new transform is written to the scene when you let go. The numbers in the TRANSFORM section
are world-space — a table zone has no seat to be local to.
Choosing an owner#
The Owner dropdown at the top of a table zone's ZONE section offers three kinds of answer:
| Owner | What it means |
|---|---|
| Table (no owner) | Nobody owns it. The right answer for a shared deck slot or discard pile. |
| A seat colour | That seat owns it whether or not anyone is sitting there. |
A seat variable ($activePlayer) |
Whichever seat the variable holds right now. |
Ownership is not cosmetic — it is what owner-seat-only interaction compares against, and what
a Hidden zone conceals from. An unowned Hidden zone therefore conceals its contents from
everyone, including the host. That is deliberate: an owner that could not be resolved must
never open a permission.
There is no Hand type on a table zone. A hand zone stamps its seat onto what is dropped in
it and is capped at one per seat; an owner that can move mid-game breaks both. Hands stay under
Player Zones.
Seat variables — ownership that follows the turn#
A seat variable is a named slot that holds a seat: activePlayer, dealer,
startingPlayer. Declare them in the SEAT VARIABLES section of the Table Zones folder's
Inspector, give one an optional starting seat, and bind a zone's owner to it.
One authored zone then covers the whole rotation. A script moves it:
await world.setSeatVariable("activePlayer", "blue");
const active = await world.getSeatVariable("activePlayer"); // "blue"
The zone's tint follows the new owner, an owner-seat-only rule starts admitting them, and a
Hidden zone starts concealing from everyone else — all in the same step.
Three things to know before you rely on it:
- Setting is host-only, like every other mutating script call. Table scripts already run on the authoritative peer, so this costs you nothing you had.
- Clearing is meaningful.
setSeatVariable(name, null)makes a bound zone unowned — not "still owned by whoever held it last". Between rounds that is usually what you want. - Deleting a variable leaves any zone that named it owned by the Table the next time the scene loads. The zone is not deleted and its geometry is untouched; only the binding goes.
Values live in the replicated snapshot, so every peer resolves the same owner the host does. A variable that is unset — or that a re-authored scene no longer declares — resolves to nobody.
Privacy: what a hand zone actually hides#
An author arriving from either competitor will expect something different from what DiceyTable does, so this is worth spelling out.
| Product | What is hidden in a player's private area |
|---|---|
| Tabletop Simulator | A hand zone's contents, regardless of face orientation (Hands.hiding = 1) — a face-up card in your hand is still secret. |
| Tabletop Playground | Face-up cards on an owned card holder. A face-down card there is public. |
| DiceyTable | Only face-down cards. A face-up card is public regardless of who owns it, because flipping it up is how a player chooses to show it. |
So if you want the Tabletop Simulator behaviour — contents concealed whichever way up they are
— a Hand zone is not it. Use a Hidden zone, which is exactly the rule that ignores
facing. Hidden is not an exotic extra type; it is the type that gives TTS-equivalent hand
privacy, and pairing a Hidden zone with the Hand zone is the normal way to build a hand area
for a game where holding a card face-up must not reveal it.
Teammates are always entitled to a seat's private information, unconditionally, on both competitors and here. There is no option to exclude them.
Sorting a hand#
A Hand zone can offer the player named sort methods. Each one points at a field and a
direction: either a built-in (Card name, Card ID) or one of the deck's own card fields
from the deck editor — so a game with a power or cost
field on its cards can offer "Power (high to low)" without any scripting.
The player picks one by right-clicking their own hand zone, and the choice is remembered for that game — it is stored on their account, so it follows them to a new room and a new device. It is their preference, not table state: it changes the order of their own hand only, and nobody else can see that order anyway.
Two options are always offered on top of whatever you author:
- Unsorted, where the player arranges the hand themselves by dragging cards sideways, and new cards land at the end you chose in New cards go to.
- Card name (A→Z), which is also the fallback.
That fallback is what makes this safe to change after publishing. If you remove a sort
method some players had chosen, they are not stuck and nothing errors — they simply get card
name order the next time they play, and can pick again. The same is true of a Default you
delete. Renaming a method keeps everyone's choice, because a method is identified by an id the
editor mints once, not by its name.
A card that has no value for the sorted field always sorts last, in both directions.
Turning a hand's privacy off#
Hide from other players on a Hand zone defaults to on, and on is everything described
above. Turning it off declares that seat's hand public: the host stops withholding those
cards' identities and every client draws their faces, so an open-hand game — a teaching table, a
solitaire layout, a bidding game where hands are revealed — needs no script to arrange it.
It is a privacy release, so it only ever adds visibility, and only to the one rule it names:
- It applies to cards owned by that seat — the ownership a
Handzone stamps — whether they are sitting in the zone, being dragged, or resting just outside it. Ownership is the fact, not proximity. - A
Hiddenzone still conceals. If a public hand overlaps one, theHiddenrule wins. - A card a script revealed to one team stays restricted to that team. An explicit reveal is a deliberate act and outranks a zone-wide default.
- Teammates are unaffected — they were always entitled, and still are.
- The seat's deck still keeps its order secret. Publishing a hand's card faces is not a licence to publish the order of a pile.
Off is authoring data, not a per-player toggle: it lives in the scene, applies to every session of the mod, and there is no in-game control to flip it back on mid-game.
There is no GM or see-all role#
Both competitors have one — Tabletop Simulator's Black seat and Tabletop Playground's per-slot
Game Master both see inside every hidden area. DiceyTable has no equivalent. A Hidden
zone conceals its contents from every viewer not entitled to the seat, and a spectator is not
entitled to anything. There is no exemption to grant a referee, a dealer or a dungeon master.
Do not build an RPG-style mod on Hidden zones expecting a GM to see through them. The gap is
recorded, but nothing in the redaction contract grants it today.
Cost: hidden information caps a table at ~4–6 remote peers#
A hidden zone is not itself expensive to replicate. Seat zones are authoring data — they live in the scene document and never cross the data channel at all. What is expensive is what a hidden zone causes. The moment one object needs redacting, the host can no longer send a single shared update to everybody: it drops out of delta replication entirely and sends each peer its own full, individually redacted copy of the table. That costs roughly 4.8 Mbps of sustained upload from the host, plus about 14 redact-and-serialise passes per second on the host's main thread, so a table holding hidden information caps out at around 4–6 remote peers (players other than the host) today — well below the seat count. The same ceiling applies to any face-down card or deck whether or not a hidden zone is involved; a hidden zone just makes it easy to reach deliberately.
An empty hidden zone is free. You only pay while objects are actually inside one — if no hidden zone is occupied, every update the host sends is byte-for-byte what it would have been without the zone. Authoring a hidden zone you fill only occasionally costs nothing the rest of the time.
Hand zone or card holder?#
Both are retained, and neither replaces the other. They answer different questions.
| Hand zone | Card holder | |
|---|---|---|
| What it is | A volume in seat-local space | A named pile location with physical presence |
| What it defines | Privacy and seat membership | Where a pile sits, and a proximity capture radius |
| Table geometry | None — an outline | Static furniture with a box collider |
| Where it lives | The scene document, per seat | The replicated snapshot, as an entity |
| Right for | "cards here are mine and private" | deal targets, per-player pile rows, discard piles, market rows, solitaire tableaus |
They compose, and composing them is the point. A card holder standing inside a hand zone is a private pile: the holder gives the cards a place to sit and a capture radius, and the zone around it makes them the seat's and hides the face-down ones. Neither primitive does both jobs, and you want both more often than not.
A holder no longer confers seat ownership by itself. It used to: a holder that had drifted
into a seat's area stamped every card it captured with that seat, quietly competing with the
zone rule. That implicit fallback is gone. What survives is the explicit opt-in — set
metadata.holderOwnerSeat on the holder and it is treated as that seat's rack, cards included,
exactly as before. A published mod that deliberately used a holder as a hand rack keeps working;
a holder that merely happened to sit in a seat's area stops making claims it never meant to.
Older saves are promoted, once, on load. A holder written before the opt-in existed can
carry a seat in ownerSeat and nothing in metadata. Loading a table copies that seat into
metadata.holderOwnerSeat, so the rack keeps gating who may take cards out of it instead of
silently becoming a free-for-all. The promotion runs once and never overwrites an answer you
gave: a holder you set to no seat stays seatless. If you want an old holder to stop
claiming a seat, clear metadata.holderOwnerSeat (and its ownerSeat) rather than expecting
the load to do it for you.
Capacity, spread and fan all belong on the holder or on the deferred Layout zone type, never
on the hand zone.
Card holders owned by the seat template#
A template can own card-holder definitions as well as zones, which is what makes "every
player has three tableau piles and a discard" authorable once. Add them from the Seat
Template panel's + Add menu alongside the zone types.
A holder definition is deliberately not an entity. It carries a stable holder id, a slug, a
kind, a seat-local position and rotation, an optional scale, and a small metadata payload — and
no world transform, no owning seat and no parent, because all three would be wrong for nine of
the ten seats. Applying the template turns each definition into a real entity per linked seat,
with a derived id and a derived unique slug ({label}-{seat}), and those entities appear under
Entities (N) like anything else.
Re-applying updates in place; it never duplicates. Generated holders carry a provenance marker, so a re-apply recomputes the ones it made, creates the ones that are missing, deletes the ones whose definition is gone — and never touches a card holder you placed yourself, even one standing squarely inside a seat's area.
Only that marker can get an entity deleted. A re-apply will adopt an entity whose id
happens to match a generated holder's — that is what lets a scene whose ids were rewritten on
import reconcile instead of duplicating — but it will never remove one on the strength of its
id alone. So an entity that arrives from an imported scene or a hand-written setup.json with
an id shaped like a template holder's is safe: worst case it is adopted, never silently
deleted.
⚠ Editing a generated holder directly is overwritten on the next re-apply. Selecting one
shows a read-only FROM SEAT TEMPLATE panel with an Edit Template button rather than the
usual entity Inspector, because a re-apply — on load, on save, or on any template edit —
recomputes the object wholesale from the definition and the seat's group transform. Edit the
template. If you want one seat's holder to differ from the rest, detach that seat.
What it costs#
Measured on the real materializer: about 0.4 KB and one static physics body per holder, so a four-holder template costs roughly 1.7 KB and four static bodies per claimed seat. Holders are static, so they cost broadphase only — no solver work. At the steady state below (holders exist only for claimed seats) a two-player table pays for eight holders, not forty.
What happens at the table#
The template is authoring state — there is no template affordance at /table, and no player or
spectator can edit one. But templated holders do appear and disappear at runtime, which is
player-visible and surprising the first time. Template pieces marked Only when seated do too,
with an extra rule that protects pieces in play. See
What happens to pieces at the table. The host, and only the host, decides:
- Claiming a seat spawns that seat's templated holders. This is what keeps a table authored on ten seats from being cluttered with eight unused racks.
- Explicitly leaving a seat removes them. That means choosing No color selected in the player menu, a host setting your seat to none, or Join as Spectator. Leaving a seat is remembered for as long as you stay connected: the table will not quietly sit you back down, and your racks will not reappear until you pick a seat again. Picking any seat — or coming back with Switch to Player — puts you back in the normal rotation and respawns them.
- A disconnect does not remove them. A network blip must not destroy someone's tableau, and the presence model genuinely cannot tell a ten-second drop from a deliberate leave. A disconnected player's rack is waiting when they come back.
- A seat that stops existing does not count as leaving it. If a scene load changes which
seats the table defines, players holding a seat that is gone are simply re-seated on the new
set; the
scene-loadedpass below is what fixes up the holders. - Host migration never removes a rack either. When a new host takes over it reconciles the claimed seats only, so it can create but never destroy — a rack left by an earlier disconnect survives the migration that disconnect may well have caused.
- Cards are never deleted. When a rack goes away its contents stay exactly where they were in world space and simply stop being "in" the holder. They are not teleported, scattered or removed, so a carefully arranged tableau survives a seat change intact. Re-claiming the seat respawns the rack and it picks the cards back up.
Save and load are deterministic in both directions: loading a scene reconciles every seat against who is actually sitting down, so a save made with two seats claimed and reloaded with none removes those holders — and still leaves every card on the table.
Dice owned by the seat template#
The game's manifest dice list holds the dice anyone
may roll. A template's DICE list holds the dice each seated player gets on top of those.
Use it for faction dice, or for "everyone has the same five d6, in their own colour". Author it
on the Seat Template panel, which
uses the same die slots as the Game panel's list.
At the table, a seated player's dice tray shows the game's dice first, then a Your seat's dice group. Each tile in that group is tagged Yours. A spectator, or a player without a seat, gets no seat dice.
A player can only roll their own seat's dice. A seat die is addressed as
seat:<entry key>, and the key is the same on every seat. The host does not trust the sender's
claimed seat. It resolves the key against the dice of the seat it has on record for the roller,
so the key always produces that roller's own look. A seat: key that no longer resolves (the
roller has left their seat, or the template dropped that die) is refused. It does not fall
back to the stock die, because that would still hand the roller a die they did not pick.
Seat dice go to every seated player, linked or detached. Detaching a seat is about its geometry, so a player at an asymmetric seat still rolls the game's faction dice. A detached seat has no Inspector section for per-seat dice. Any overrides it had while it was linked stay stored on the seat and still apply. Link it again to edit or reset them.
Changing a die for one seat#
A linked seat's Inspector has a DICE section with one row per template die. There are
two kinds of change, and they follow different rules on purpose:
- Same die, different colour. Set a Tint or drop a material. Only the colour changes: the seat keeps the template's model, and it follows the template if the template's model changes later. The template's Colour dice per seat button does this for every linked seat at once, using each seat's own colour.
- A different die. Drop a project model or another preset on the slot, or pick one in the row's Model list (which also lists the project's die designs). That replaces the whole look for that seat: model, tint and material. The template's tint and material were chosen for the template's model and are not carried onto the seat's own. You can also change a seat's Faces layout. If the seat was wearing the template's custom model, it gets the stock model of the new layout instead, because a custom model is only right for the layout it was modelled for.
The face layout always sets the numbers. A custom model has to be authored face-for-face in the
stock die's orientation. See dice[].model.
Starting-layout pieces#
A template's PIECES list is a player's starting layout: pieces every linked seat gets a
copy of, placed in seat-local space. Examples are a Chinese checkers point's ten marbles, or each
player's starting workers. Each linked seat's copy is a real entity with the id
seat-piece-{seat}-{pieceId} and a metadata.seatTemplatePiece provenance marker. The marker
records the seat, the piece, and the home position the piece was stamped at.
The quick way to author one is to lay the pieces out on the table next to any linked seat,
select them, and use Add N to seat layout in the Inspector's
SEAT LAYOUT section. The
selection is measured from the seat you pick and converted into template pieces. The originals
are then removed, and every linked seat, including that one, gets its own copy in the same
place relative to it.
Per seat, you can swap a piece for a different one (each player's own marble), recolour it, paint it with a material, or omit it. Colour pieces per seat on the template sets every seat's copies to that seat's colour in one click. Dropping a project model on a piece that is already a project model changes only its file, so the piece keeps its scale and physics. To do that for a whole group of pieces at once, use piece groups.
A piece keeps where it has been played. A holder is furniture and is recomputed wholesale on every re-apply. A piece is not. Re-applying the template keeps each existing piece's live position, rotation and face-up state, and re-applies only its look. The one exception is when the template moved the piece's home: an edit to the piece's Position or Rotation Y, the seat's group transform, or the template scale. Then the piece moves to the new home. Moving a generated piece by hand in the editor therefore moves that one seat's copy only. To change the layout for everyone, edit the template.
Detaching a seat, or clearing the template, keeps that seat's pieces as ordinary entities,
renamed piece-{seat}-{pieceId}. Nothing is deleted.
Piece groups: one model per player#
Pieces that are the same piece — same model, colour, material and scale — are grouped
automatically. Ten black marbles captured from one point show up in the Hierarchy as one
Marble Black (10) row under Seat Template. Expand it to see every piece. A piece that is
unlike every other piece stays a plain row.
Select the group row to edit all its pieces at once:
- Drop a model on the group's slot to change every piece's model on the template. Only the file changes. Scale, physics, tags and positions are kept.
- Model per seat and Material per seat let each seat use its own model file or material
for the whole group. Once one is on, the Inspector lists every linked seat. Drag that
player's marble onto their row and all ten of their marbles change. The seat's own
PIECESsection shows the same boxes.
Model per seat needs every piece in the group to be a project model on the same file (its
kind does not matter — a marble whose sidecar makes it a token qualifies). Material per
seat needs every piece to look the same. Turning either option off keeps what each seat set,
unused, so you can turn it back on without redoing the drops.
If some copies drifted apart — one picked up a material, another was rescaled — they stop
grouping together and both options grey out. The group's These are all the same piece
button gives every piece (and any piece in another group on the same model file) the first
piece's look, keeping each one's position. The group's piece buttons are numbered; ids like
marble-black-2 name pieces, not extra model files.
A seat's material replaces the model's own default material (the binding its sidecar got on import), so a black marble model painted red on the Red seat renders red.
A per-seat model changes the file and nothing else. So the pieces keep the template's scale and physics, which is the difference from swapping a single piece's whole definition. A single piece's swap on a seat still wins over its group's look.
Setting a group's name, an option or its model pins the group: each member records the group
id (seatTemplate.pieces[].group). A piece added later with the same look joins the pinned
group, so it gets each seat's model too.
What happens to pieces at the table#
The host decides, on the same edges that add and remove template card holders: claiming a seat, leaving one on purpose, a scene load, and host migration.
- A piece without Only when seated exists for every linked seat, whether anyone is sitting there or not.
- A piece with Only when seated appears when somebody claims that seat, at its home.
- When the player leaves the seat on purpose, the host removes that seat's gated pieces only while they still sit at their home spot (within 0.05 ft, measured horizontally). A piece a player has moved, or parented to something, is game state and stays on the table. If the seat is claimed again, the surviving piece is adopted by its id rather than duplicated.
- A disconnect removes nothing, for the same reason it keeps holders. A later scene load or host migration treats that seat as unclaimed and removes only its unmoved gated pieces.
- An existing piece is never moved or re-skinned by these passes. Its look is fixed when it is created.
In the editor every linked seat counts as occupied, so you always see the whole layout.
Where rolled dice land#
When a player rolls into the Tray, the dice land in a walled region in front of their seat.
The template's DICE TRAY section can replace the default region with an authored one: a
seat-local position, width, depth and rotation, scaled by the template scale. A tray that would
hang off the table is shrunk to fit and slid inboard, exactly like the default. Only linked seats
use the authored tray. A detached seat, or a player with no seat, gets the default.
Each player can show or hide the tray's outline from the dice tray popout. That setting affects only their own screen.
The name label#
Every seat group has exactly one label — position, box size, rotation Y, font size, and an
optional custom text. Left blank it falls back to the seat's stable id (seat-group-<index>) in
the editor and to the seated player's username at the live table; a seated player's name always
wins there, whatever text you authored.
On a linked seat the label's geometry and its shared text come from the template, so a
per-seat name lives in its own LABEL TEXT override field instead — the shared text would
otherwise be overwritten by the next materialization.
Recoloring a seat#
Select the seat group itself (not a zone or the label) for its Color picker: one of the eight standard colors, or Custom… for an arbitrary hex override. The override tints the zone boxes and the label frame, in the editor and at the table, claimed or not. A zone's type only modulates that colour — it never replaces it, because "whose area is this" is read at a glance far more often than "what kind of zone is this".
Because a recolored or relabeled seat can no longer be identified by its original color name, a
seat's identity is a stable, color-independent id (seat-group-<index>) that never changes.
The #seat-group tag targets every seat group at once; the stable id targets one
forever, however it has been recolored or relabeled.
Seat layout — putting seats back on the table#
Seat positions are derived from the table: its footprint, its ring layout (Edge for a
rectangle, Radial for a round or oval table) and how many seats it declares. Swap the table
and the seats do not follow on their own — a layout you authored is yours, and nothing moves it
without asking. The SEAT LAYOUT block on the Player Zones folder is where you put them back.
It names the table the seats are laid out on, its size, its ring layout and its seat count, so you can see at a glance that a game pinned to a round table still has its seats spread around a rectangle.
There are two strengths, and the difference matters:
| What it does | What it keeps | |
|---|---|---|
| Move seats onto this table's ring | Moves each seat's pivot, its first zone and its name label onto the new ring | Zone sizes, zone types, colours, custom label text, and every zone beyond the first — left exactly where you put them |
| Reset seats to this table's default | Rebuilds each seat as a fresh seat on this table: ring position, rotation, zone size and name-label geometry | Colours, custom label text and each seat's first zone type |
The first appears on its own as a warning whenever the seats stop matching the table — that is the one to take after you resize a table, because your authoring survives it intact.
The second is the one to take when the table changed shape. A hand zone stretched along a rectangle's long edge is still that shape on a circular table, and no amount of moving fixes it. Resetting also clears rotations you set by hand and deletes every zone beyond a seat's first — so it is an explicit action behind a button, never something that happens to you.
Neither touches your objects. A seat's card holders, and anything standing in its zones, stay exactly where they are.
Both show a before/after preview first: a row per seat with its position before and after, what the seat loses, and Apply or Cancel. Cancel is a real answer. Apply is one undo step (Ctrl+Z) — though undoing restores the old layout rather than re-opening the preview.
Seats beyond the table's seat count are removed. A table pack declares how many seats it lays out, and the ring for six seats is not the first six positions of the ring for eight — so lowering the count re-spaces the survivors as well. The preview names every seat it would remove, and a removed seat loses its zones, its label and its colour override.
Snap to table perimeter on a seat group and Apply to… → re-arrange evenly on the template use this same ring, on this same table. One seat or all of them, the answer to "where does this seat go" is the same.
Deleting and restoring a seat#
Delete Player Zone on a seat group removes its zones and label, but the seat slot itself stays available — re-add it later from the Player Zones folder's "Add seat" list, which shows every seat color not currently configured.
Common mistakes#
- Expecting an unclaimed seat's zone to work at the table. It is editor-only visibility by design, and the rules follow the visibility: an unclaimed seat renders nothing and enforces nothing. Not a bug if a zone you placed seems to "disappear" once you leave Edit Mode with nobody seated there.
- Assuming any zone makes something a hand card. Only a
Handzone does. If a discard pile stopped counting toward a player's hand, that is the fix, not a regression. - Expecting a hand zone to hide a face-up card. It does not — use a
Hiddenzone. - Expecting a spectator or a referee to see into a
Hiddenzone. Nobody does. There is no see-all role. - Editing a template-generated card holder in place. The next re-apply recomputes it. Edit the template, or detach that one seat.
- Authoring a template layout with
+Zpointing away from the table. Every seat will face outward.+Zpoints at the table centre. - Renaming a seat's label and expecting it to stick once someone sits down. A claimed seat's label always shows the player's username; your custom text only shows while the seat is empty.
- Swapping the table and expecting the seats to follow. They do not move on their own — open SEAT LAYOUT on the Player Zones folder and either re-derive the ring or reset the seats to the new table's default.
- Looking for an eleventh seat. The palette is fixed at ten (
PLAYER_SEAT_OPTIONS) — there is no way to author an eleventh color slot.
See also#
- Platform panels — every field on the Player Zones folder, the Seat Template, a seat group and a zone.
- The Hierarchy Panel — the
Seat Templaterow and thelinked/detachedbadges. - Glossary — Seat Template, linked, detached and the zone types, defined once.
- Tags and groups — the
#seat-grouptag and howGROUP EDITcan target every seat at once. - The Scene Model — Folders vs Tag Groups vs Entities.
- Setup JSON —
seatTemplateandseatZonesas they are stored. - Mod scripting API —
TableObjectDefinition.ownerSeatandTableHandState, seats as a mod sees them. - Mod hooks and capabilities —
onSeatChanged, and theonZoneEnter/onZoneLeavehooks these zones raise.
