# SoundAction

> The 18 logical interactions that can emit a sound, which entity kinds bind each one, and why this list is not the object-action list.

- Source: https://diceytable.com/docs/reference/enums/sound-action
- Last verified: 2026-10-06

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`](https://diceytable.com/docs/scripting-api/api#apiplaysound) and
[`api.setObjectSound`](https://diceytable.com/docs/scripting-api/api#apisetobjectsound) both take.

**18 values**, declared as `soundActionSchema` in `packages/shared/src/soundSets.ts`.

**This is not [`TableObjectAction`](https://diceytable.com/docs/reference/enums/table-object-action).** The two unions overlap in
exactly three spellings — `shuffle`, `roll` and `press` — 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`. `toss` has no sound of its own either: a tossed coin is heard only when it lands, through
its ordinary settle and collide sounds. 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`, `coin`, `board`, `card-holder`, `custom`, `button`, `table` | `playSound` · `setObjectSound` · `ModSoundSet.action` |
| `pickup` | A piece being lifted off the surface. | `card`, `deck`, `die`, `token`, `coin`, `custom`, `button` | the same three |
| `drop` | A piece being released to fall. | `die`, `token`, `coin`, `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 |
| `press` | A control actuating — a button being pressed. Not a `place`: a press is a switch, and the place thud read as the button being dropped. A `plastic` or `generic` press borrows the `counter-land` click. | `button` | the engine and both declaration files |

**Three of the 18 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](https://diceytable.com/docs/reference/known-limitations#three-sound-actions-are-mod-only) 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 twelve that genuinely fire on their own today are `place`, `pickup`, `drop`, `shuffle`, `roll`, `fall`,
`topple`, `withdraw`, `return-to-box`, `box-pickup`, `box-place` and `press`.

**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](https://diceytable.com/docs/reference/enums/sound-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](https://diceytable.com/docs/reference/enums/runtime-sound-event) table, then resolves the pair
(the entity's [material](https://diceytable.com/docs/reference/enums/sound-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

- [SoundMaterial](https://diceytable.com/docs/reference/enums/sound-material) — the other half of the pair.
- [Runtime sound events](https://diceytable.com/docs/reference/enums/runtime-sound-event) — the 16 moments and their per-kind bindings.
- [`api.playSound`](https://diceytable.com/docs/scripting-api/api#apiplaysound) — the three semantic forms.
- [`api.setObjectSound`](https://diceytable.com/docs/scripting-api/api#apisetobjectsound) — per-entity, per-action overrides.
- [TableObjectAction (engine)](https://diceytable.com/docs/reference/enums/table-object-action) — the unrelated list with four look-alike names.
