# RuntimeSoundEvent

> The 16 runtime moments that can emit a sound, the sound action each one maps to for every entity kind, and which moments a mod can trigger itself.

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

A **runtime sound event** is a moment the table notices: a piece was grabbed, a piece came to rest, two
pieces collided. The runtime maps each moment to a [sound action](https://diceytable.com/docs/reference/enums/sound-action) using
a per-kind table, then resolves that action against the entity's
[material](https://diceytable.com/docs/reference/enums/sound-material) to pick a clip.

**16 values**, declared as `runtimeSoundEventSchema` in `packages/shared/src/soundSets.ts`.

This enum is **not part of any script surface**. A mod never names a runtime sound event: it names a sound
action directly with [`api.playSound`](https://diceytable.com/docs/scripting-api/api#apiplaysound). The list is here because it
is what decides, without you doing anything, what your pieces sound like — and because a mod that plays its
own sound on top of one of these gets two sounds.

## The values

| Value | The moment | Kinds that bind it, and the action it plays | Reachable from a script |
|---|---|---|---|
| `grab` | A piece is picked up. | `card`→`pickup` · `deck`→`pickup` · `die`→`pickup` · `token`→`pickup` · `coin`→`pickup` · `custom`→`pickup` · `button`→`pickup` · `bag`→`box-pickup` | no — the table raises it |
| `release` | A piece is let go. | `card`→`place` · `deck`→`place` · `die`→`drop` · `token`→`drop` · `coin`→`drop` · `custom`→`drop` · `board`→`place` · `bag`→`box-place` · `card-holder`→`place` · `button`→`place` · `table`→`place` | no |
| `settle` | A piece stops moving. | `card`→`place` · `deck`→`place` · `die`→`place` · `token`→`place` · `coin`→`place` · `custom`→`place` · `board`→`place` · `bag`→`box-place` · `card-holder`→`place` · `button`→`place` · `table`→`place` | no |
| `fall` | A piece stops moving after a real descent: over 2.5 ft/s straight down, roughly a 6 in drop. | every kind→`fall` | no |
| `topple` | A piece stops moving while still spinning over 6 rad/s — it went over rather than being placed. | every kind→`topple` | no |
| `collide` | A piece strikes something. | `die`→`roll` · `token`→`place` · `coin`→`place` · `custom`→`place` · `button`→`place` | no |
| `roll` | A die is thrown. | `die`→`roll` | indirectly: `api.objectAction(id, "roll")` |
| `shuffle` | A deck is shuffled. | `card`→`shuffle` · `deck`→`shuffle` | indirectly: `api.objectAction(id, "shuffle")` |
| `flip` | A card is turned over. | `card`→`place` | indirectly: `api.objectAction(id, "flip")` |
| `deal` | Cards are dealt out. | `card`→`withdraw` · `deck`→`withdraw` | indirectly: `api.objectAction(id, "deal")` |
| `draw` | A card is taken off a pile. | `card`→`withdraw` · `deck`→`withdraw` | indirectly: `api.objectAction(id, "draw")` |
| `insert` | A card or deck is absorbed into a deck — drop one onto another. Plays on the surviving deck. | `deck`→`return-to-box` | indirectly: `api.objectAction(id, "combine")` |
| `collect` | Several pieces are gathered up. **Never raised** — no such operation exists. | `die`→`collect` | no |
| `board-clear` | A board is swept clear. **Never raised** — no such operation exists. | `board`→`board-clear` | no |
| `rummage` | A hand searches inside a bag. **Never raised** — the gesture exists, the loop protocol does not. | `bag`→`bag-rummage` | no |
| `press` | A button is pressed. Raised by the `press` object action, not by physics. | `button`→`press` | no — neither script surface can request `press`; a player clicks the button |

A kind with no binding for a moment makes no sound at that moment. `board` binds no `grab`, which is why a
board is quiet when picked up and a bag is not. A `table` binds no `grab` either, for the same reason.

**Three of the 16 have a binding and are never raised, for two different reasons.** `rummage` is the one that
is nearly there: shaking a held bag is already detected (`analyzeShake` → `dispatchShakeGesture`) and, now that
`shuffle` is deck-only, does nothing — but `bag-rummage` is a looping set and the `sound-event` protocol has no
loop flag and no stop message, the same wall that keeps `slide` unbound. `collect` and `board-clear` are a
different case entirely: the table has **no gather-the-dice and no sweep-the-board operation at all**, so there
is no moment to raise. Their clip sets still preload. If your game needs one of these, play it yourself with
[`api.playSound`](https://diceytable.com/docs/scripting-api/api#apiplaysound).

**`settle`, `fall` and `topple` are the same moment, resolved once.** A body's moving→rest transition picks
exactly one of the three — `fall` first, then `topple`, then the ordinary `settle` — so a landing never plays
two clips, and binding the two new ones cannot make a settling pile any noisier than it was. A candidate is
taken only if the kind binds it *and* the entity's [material](https://diceytable.com/docs/reference/enums/sound-material) resolves a
clip for it; the catalog carries `wood.fall`, `wood.topple` and `plastic.topple` and nothing else in that
family, so most entities keep their `place`. The choice lives in
`apps/web/src/playcanvas/audio/settleSoundAction.ts` if you want to read the thresholds.

## How this affects a mod

**Do not duplicate what the table already plays.** Calling `api.playSound` in an
[`onCardDrawn`](https://diceytable.com/docs/scripting-api/hooks-and-capabilities#modhookeventmaponcarddrawn) handler adds a
second sound on top of the `draw` → `withdraw` the runtime already played. Use `playSound` for moments the
table has no concept of — a bid accepted, a round scored — and let the physical ones alone.

**To change what a moment sounds like, change the entity, not the moment.** There is no way to remap a
runtime event. What you can do is override the action it resolves to, per entity, with
[`api.setObjectSound(objectId, action, ref)`](https://diceytable.com/docs/scripting-api/api#apisetobjectsound) — so a coin that
should clink when it lands gets a `metal` override on `place`, and every `settle` and `release` on that
coin picks it up.

**Sounds are ephemeral.** They ride the unreliable channel, are never persisted, and never appear in a
snapshot. Do not treat a sound as evidence that anything happened.

## See also

- [SoundAction](https://diceytable.com/docs/reference/enums/sound-action) — the 18 actions this table maps into, and the three no moment binds.
- [SoundMaterial](https://diceytable.com/docs/reference/enums/sound-material) — what resolves an action to a clip.
- [`api.setObjectSound`](https://diceytable.com/docs/scripting-api/api#apisetobjectsound) — overriding one action on one entity.
- [`api.playSound`](https://diceytable.com/docs/scripting-api/api#apiplaysound) — a one-shot that changes nothing.
- [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) — the kinds in the second column.
