Dicey Table

Working with Decks

<!-- screenshot: editor/working/decks.png -->

This page is about using a deck once you've built one in the Deck editor — placing it, understanding what actually ends up on the table, and the one gotcha that catches almost everyone once. For building the deck asset itself (uploading card images, resolution presets, the back picker, sheet generation), see the Deck editor reference and the Building a deck workflow.

Placing a deck on the table#

A .deck.json asset in the explorer drags onto the viewport, or click-to-instantiates, the same as any other asset. Doing so spawns a standard deck-kind Scene Entity and bakes the deck definition's resolved card list into that entity's metadata.customDeck (buildCustomDeckObjectMetadata, called from instantiateDeckAsset in TableEditModeShell.tsx) — the entity's stackCount is set to the deck's card count including copies (customDeckTotalCards, not the number of distinct card images), and its display name to the deck's name. The deck's card and deck data models ride along in the same baked slice, so a script reading a placed deck — or a card drawn out of it — has them without touching the source asset. From there it behaves exactly like any other deck: the runtime windows each card's face out of the baked sheet, and every deck action (shuffle, draw, split, combine) works untouched.

⚠ Spawning copies the deck definition into the entity at that moment. It does not keep a live reference back to the .deck.json asset. If you go back into the Deck editor afterward and add a card, reorder, change the resolution, or regenerate the sheet, every deck object already placed on the table keeps the old baked copy — there is no code path that re-syncs an already-spawned deck's metadata.customDeck from its source asset. To pick up a change, delete the placed deck object and drag the asset onto the table again.

This is worth planning around: finish shaping a deck (all its cards, its back, its resolution) before you place your first copy of it in a scene with several tables or several identical decks, rather than placing early and iterating with placed copies already on the board.

When to use a deck vs. individual cards#

A deck asset is the right tool when you have many cards that share one back, one resolution, and one game-logic identity (a standard playing-card deck, a game's action-card deck). If you need a handful of unique cards with independent behavior — or cards that should keep updating as you tweak a shared asset without re-placing them — model them as individual card-kind entities instead; a deck's baked-snapshot model doesn't fit that use case.

Common mistakes#

  • Editing a deck asset and expecting placed decks to update. They won't — see above. Delete and re-place, or finish the deck design before placing your first copy.
  • Placing a deck before running Generate & Save at least once. An unresolved .deck.json has no baked sheet to spawn from; the editor refuses with "This deck has no valid definition yet — open it and Generate & Save first."
  • Expecting per-card behavior differences within one deck. A deck is one entity with a window into a shared sheet — cards inside it don't carry independent scripts or metadata the way standalone card entities can.

See also#