Dicey Table

SoundAction

A sound action is a logical interaction that can make a noise. It is the other half of the material × action pair the engine resolves into a licensed clip, and it is what api.playSound and api.setObjectSound both take.

17 values, declared as soundActionSchema in packages/shared/src/soundSets.ts.

This is not TableObjectAction. The two unions overlap in exactly two spellings — shuffle and roll — and even those mean different things: a sound action is a noise, an object action is a change to the table. draw and deal are object actions with no sound action of the same name; they map to withdraw. Passing a sound action to api.objectAction throws, and passing an object action to api.setObjectSound is dropped with a diagnostic.

The values#

The Kinds that bind it column is the per-kind runtime map: which entity kinds have a moment that selects this action on their own. Every value can be named explicitly by a mod for any entity, whatever that column says.

Value The interaction Kinds that bind it Where you can name it
place A piece being set down gently. card, deck, die, token, board, card-holder, custom playSound · setObjectSound · ModSoundSet.action
pickup A piece being lifted off the surface. card, deck, die, token, custom the same three
drop A piece being released to fall. die, token, custom the same three
slide A piece being dragged across the surface. A continuous, looping set. — the same three
shuffle A deck being shuffled. card, deck the same three
roll A die tumbling. die (from both the roll and its collisions) the same three
fall A piece landing after a real descent — faster than 2.5 ft/s straight down, about a 6 in drop. every kind the same three
topple A piece coming to rest still spinning hard (over 6 rad/s) — it went over rather than being set down. every kind the same three
withdraw A card being pulled out of a deck or a hand. card, deck (both draw and deal) the same three
collect Several pieces being gathered up. die the same three
return-to-box A card or deck being absorbed into a deck (drop one onto another). deck the same three
board-clear A board being swept clear. board the same three
box-pickup A box or bag being lifted. bag the same three
box-place A box or bag being set down. bag the same three
bag-rummage A hand searching inside a bag. A continuous, looping set. bag the same three
counter-land A small counter landing on a surface. — the same three
counter-fall A small counter falling. — the same three

Three of the 17 are mod-only: slide, counter-land and counter-fall are in the taxonomy but no kind's runtime map binds them, so nothing at the table triggers them on its own. A mod can still name them with api.playSound. This is deliberate, not an oversight — see Known limitations for why each one is left where it is.

Three more are bound and still never play — and they are not blocked on the same thing, which matters if you are deciding whether to play one yourself:

Value Why it is silent
bag-rummage The gesture exists: shaking a held bag is detected today (analyzeShake → dispatchShakeGesture) and, since shuffle became deck-only, does nothing with it. What is missing is the protocol — bag-rummage is a looping set (loop: true), soundEventSchema carries no loop flag and there is no stop message, so a peer would play a loop-mastered clip as a one-shot. It is the same wall slide hit, and the two need one decision, not two.
collect There is no such operation. Nothing in the runtime gathers or collects a group of dice — a multi-select drag and the bunching path are different gestures. The clip set (dice.collect) exists and resolves; the moment does not.
board-clear There is no such operation either. The table has no "sweep the board" action; deleting everything on a board is the nearest thing and is not the same gesture. Note also that the default board material is wood, and only cardboard.board-clear is in the catalog — so even with a trigger, a default board would resolve to nothing.

The eleven that genuinely fire on their own today are place, pickup, drop, shuffle, roll, fall, topple, withdraw, return-to-box, box-pickup and box-place.

A binding is not a promise of noise. fall and topple are bound for every kind, but the clip catalog only carries wood.fall, wood.topple and plastic.topple. When a kind binds an action and the entity's material has no clip for it, the landing falls back to the ordinary place sound rather than going silent. So a wooden token topples audibly, a plastic die topples audibly, and a card does not — even though all three bind it.

How an action becomes a clip#

The runtime notices a moment — a grab, a settle, a collision — maps it to a sound action through the per-kind runtime sound event table, then resolves the pair (the entity's material, this action) into a licensed clip set and picks one variant at random. A mod skips the first step by naming the action itself.

See also#