# Sound sets

> The five sound enums (12 materials, 18 actions, 16 runtime events, 3 counts, 2 intensities), a mod's soundSets, and how a SoundRef stays license-safe.

- Source: https://diceytable.com/docs/mods/reference/sound-sets
- Last verified: 2026-09-29

DiceyTable's built-in sound effects are licensed for embedded gameplay use only — the EULA forbids exposing
them as an addressable clip library (see [Object actions](https://diceytable.com/docs/mods/reference/object-actions) for the
parallel gating pattern on the *physical* side of the table). Every mod- and script-facing surface reflects
that: nothing in this reference names a clip id, a file, or an internal catalog key. A sound is always
requested **semantically** — by material and action — or as one of the mod's own uploaded files.

## The five enums

Five small enums, all declared in `packages/shared/src/soundSets.ts`, combine to select a clip. Three
already have their own full reference page; this page owns the two that don't, plus the parts of the system
that combine all five.

| Enum | Values | What it is | Full reference |
|---|---:|---|---|
| `SoundMaterial` | 12 | The physical surface a piece is made of — and what a piece landing on it is heard through. | [SoundMaterial](https://diceytable.com/docs/reference/enums/sound-material) |
| `SoundAction` | 18 | The logical interaction that emits a sound. | [SoundAction](https://diceytable.com/docs/reference/enums/sound-action) |
| `RuntimeSoundEvent` | 16 | The physics/interaction moment the table notices on its own. | [RuntimeSoundEvent](https://diceytable.com/docs/reference/enums/runtime-sound-event) |
| `SoundCount` | 3 | How many pieces the action involves. | below |
| `SoundIntensity` | 2 | Soft vs. hard impact. | below |

### `SoundCount` — 3 values

`single` · `double` · `multi`. Only meaningful for **roll** sounds: `resolveBuiltinSetId` looks up
`roll.<surface>.<count>` first and falls back to `roll.<surface>.single` if the exact count has no dedicated
variant. Nothing sets this from object state directly — the runtime derives it from how many dice are
rolling together in one gesture at the moment of the roll.

### `SoundIntensity` — 2 values

`gentle` · `firm`. An optional modifier on **place**-type impacts (dropping a piece softly onto the table
vs. slamming it down); the runtime derives it from the impact velocity at the moment of collision. Most
`(material, action)` pairs have no `firm` variant, in which case the resolver falls back to the plain
`material.action` set — a `firm` drop and a `gentle` drop sound the same unless a dedicated variant exists.

The generated field tables for all five enums — including the full `SoundMaterial`, `SoundAction` and
`RuntimeSoundEvent` value lists — are appended below; their individual reference pages linked above go
deeper on each one's per-kind bindings and defaults.

## How a material becomes a clip: `resolveBuiltinSetId`

The runtime's `resolveBuiltinSetId(material, action, { count?, intensity?, surface? })` is the one function
that turns a semantic request into an internal catalog key, and it is worth understanding conceptually even
though the catalog itself is not part of the mod-facing contract (see the licensing note above — this
reference does not enumerate it). In order:

1. **`material === "silent"`** resolves to nothing, always — the sentinel opt-out.
   **`felt`, `cloth`, `glass` and `stone`** have no recordings, so they are swapped for the recorded material
   they borrow from (`SOUND_MATERIAL_CLIP_SOURCE`: `felt`/`cloth` → `cardboard`, `glass`/`stone` → `tile`)
   before any lookup.
2. **`roll`** keys off the **struck surface** (`opts.surface` — what the die is landing on, probed by the
   runtime) and `opts.count`, not the rolling piece's own material — a plastic die thrown onto a cardboard box
   sounds like cardboard, not plastic. There are two recorded roll surfaces: `felt`, `cloth`, `card` and
   `cardboard` use the cardboard take, everything else (and no surface at all) the wood take.
3. **`slide`** keys off the sliding piece's own material, falling back to `wood` if that material has no
   slide variant.
4. Every other action tries, in order: `material.action.intensity` (if an intensity was given), then
   `material.action`, then — for `plastic` only — a `dice.action` alternative, then `generic.action` as the
   last resort.
5. Nothing matching, at any step: the sound is silently dropped. This is not an error condition — an
   unusual `(material, action)` combination (e.g. `board` + `roll`) legitimately has no built-in set.

The clip is then **coloured by the surface it was struck on**: the runtime probes what lies under the sounding
entity (a board, a placed `table`, the table pack's play surface) and, for impact actions only, runs the voice
through that material's filter — felt muffles, glass rings, wood and cardboard are left alone. The table of
tones and the rules for what counts as underneath are on
[SoundMaterial § Struck-surface tone](https://diceytable.com/docs/reference/enums/sound-material#struck-surface-tone).

## What binds a `RuntimeSoundEvent` to a `SoundAction`

`OBJECT_SOUND_EVENT_MAP` (`packages/shared/src/soundSets.ts`) is the per-kind table that decides which
`SoundAction` plays for each `RuntimeSoundEvent` — a `card`'s `grab` plays `pickup`, a `bag`'s `grab` plays
`box-pickup`. The full table, one row per event, lives on
[RuntimeSoundEvent](https://diceytable.com/docs/reference/enums/runtime-sound-event) rather than being duplicated here.

**A binding here means "this kind has this moment", not "this kind always makes a noise then."** Whether
anything is audible is settled a step later, when the action is resolved against the entity's material — so
every kind binds `topple`, but only `wood` and `plastic` have a topple clip, and the rest quietly fall back to
their ordinary `place`. Binding broadly and resolving narrowly is deliberate, because this map is also what
the loading screen walks to decide which clips to **preload**. An action the runtime can trigger but that is
missing from this map is fetched cold on first use, and if it decodes too late it is dropped — so the first
one you hear is silence. That is why `fall` and `topple` are in the map even though the runtime, not the map,
decides when they happen.

**15 of the 18 sound actions have a binding; 12 of them actually fire today.** `slide`, `counter-land` and
`counter-fall` are bound to nothing at all — a mod-only vocabulary, deliberately, and the reasons are on
[Known limitations](https://diceytable.com/docs/reference/known-limitations#three-sound-actions-are-mod-only). Separately, `collect`,
`board-clear` and `bag-rummage` *are* in the map and still never play — but for **two different reasons**, and
the difference decides whether waiting is worth anything:

- **`bag-rummage` — the moment exists, the protocol does not.** Shaking a held bag is already a detected
  gesture, and since `shuffle` became deck-only it does nothing. What blocks the sound is that `bag-rummage` is
  a **looping** set: `soundEventSchema` has no loop flag and there is no stop message, so a peer would play a
  loop-mastered clip as a one-shot. `slide` is stuck behind the identical wall, and the two are one decision.
- **`collect` and `board-clear` — the operation does not exist.** There is no gather-the-dice and no
  sweep-the-board gesture anywhere in the runtime, so there is nothing to bind a sound to. These are
  speculative bindings for features that were never built, not sounds waiting on plumbing.

Do not assume a bound action is an audible one; if your game needs a rummage or a board sweep, play it yourself
with `api.playSound`.

Every kind also has a **default material** it assumes when an entity has no `material` field set —
`DEFAULT_SOUND_MATERIAL_BY_KIND`, reproduced on [SoundMaterial](https://diceytable.com/docs/reference/enums/sound-material) and on
[Object kinds](https://diceytable.com/docs/mods/reference/object-kinds#physics-defaults-at-a-glance)'s physics table (same values,
different page, kept in sync by hand — flag a mismatch as a doc bug if you find one, not a data bug).

## `SoundRef` — the license-safe pointer

A `SoundRef` (`packages/shared/src/soundSets.ts`) is how *anything* outside the runtime — a mod, an entity's
`soundSetOverrides`, the editor's sound-override panel — names a sound. It is a two-shape discriminated
union and nothing else is representable:

| Shape | Meaning |
|---|---|
| `{ kind: "builtin", material }` | Semantic: the engine resolves `material` × whatever action is being played internally. No `SoundSetId`, clip file or path is ever present. |
| `{ kind: "mod", modId, name }` | A sound the named mod declared in its own manifest `soundSets`. The host enforces `modId` matches the calling mod and `name` is one it actually declared — a mod cannot point at another mod's sound. |

`api.setObjectSound(objectId, action, ref)` is the mod-facing way to set one, permanently, in an entity's
`soundSetOverrides`; see [its reference page](https://diceytable.com/docs/scripting-api/api#apisetobjectsound) for the full
parameter treatment and the ownership-check rejection message.

## A mod's own sounds: `soundSets` in the manifest

A mod that ships its own audio — a game-specific sound effect no built-in material captures — declares each
one as a `ModSoundSet` in the manifest's `soundSets` array (max **64** entries; see
[Manifest reference § `soundSets`](https://diceytable.com/docs/mods/manifest/reference#soundsets) for the field-level schema and a
worked JSON example). The generated `ModSoundSet` field table is appended below.

Once declared, a mod plays its own sound with `api.playSound({ modSound: "<name>" })`
([reference](https://diceytable.com/docs/scripting-api/api#apiplaysound)) or attaches it permanently to an entity with
`api.setObjectSound(objectId, action, { kind: "mod", modId: manifest.id, name: "<name>" })`. Both reject a
`name` the mod never declared, or a `modId` that isn't the calling mod's own.

## See also

- [`api.playSound`](https://diceytable.com/docs/scripting-api/api#apiplaysound) — a one-shot sound, ephemeral and never persisted.
- [`api.setObjectSound`](https://diceytable.com/docs/scripting-api/api#apisetobjectsound) — a permanent per-entity, per-action override.
- [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) — the per-kind default sound material.
- [Manifest reference](https://diceytable.com/docs/mods/manifest/reference) — the `soundSets` field in the wider manifest schema.
- [Known limitations](https://diceytable.com/docs/reference/known-limitations) — documented gaps across both script surfaces.

## `modSoundSetSchema`

Exported from `@diceytable/shared` as `modSoundSetSchema`. 5 fields across 1 table.

| Field | Type | Required | Default | Min / Max | Pattern | Rule | Description |
|---|---|---|---|---|---|---|---|
| `name` | `string` | **yes** | — | 1–80 chars | `^[a-z0-9][a-z0-9._-]*$` | — | — |
| `variants` | `string[]` | **yes** | — | 1–16 items; each 1–180 chars | — | — | — |
| `material` | `soundMaterialSchema` | no | — | — | — | — | — |
| `action` | `soundActionSchema` | no | — | — | — | — | — |
| `loop` | `boolean` | no | — | — | — | — | — |

### `name`

The logical name a mod's own script and `soundSetOverrides` refer to it by — `api.playSound({ modSound:
"<name>" })` and `{ kind: "mod", modId, name }`. Scoped to the declaring mod; another mod's script cannot
reference it by name even if it knows it.

### `variants`

Repo-relative asset paths (subject to the same [18-extension allowlist](https://diceytable.com/docs/mods/files/assets) as any
other declared asset — in practice `.mp3`/`.ogg`/`.wav`). One is chosen at random per play, the same
variant-rotation model the built-in catalog uses.

### `material`

Optional semantic tag for your own bookkeeping — does **not** blend this sound with the built-in catalog or
let anything resolve to it automatically. A mod's sound only ever plays when named explicitly by `modSound`
or a `{ kind: "mod" }` ref.

### `action`

Optional semantic tag, same caveat as `material` above — informational only, not a hook into the runtime's
own event → action bindings.

### `loop`

Marks this as a continuous sound (a rummage, a slide) rather than a one-shot. A mod still has to pass
`loop: true` again on the `playSound`/`setObjectSound` call that uses it — declaring it here does not make
every play of this sound loop automatically.

## `soundMaterialSchema`

12 values. The physical material an object sounds like. `silent` is the opt-out sentinel.

| Value |
|---|
| `wood` |
| `cardboard` |
| `metal` |
| `plastic` |
| `card` |
| `tile` |
| `felt` |
| `cloth` |
| `glass` |
| `stone` |
| `generic` |
| `silent` |

Full treatment, including the per-kind default table and the "where a material comes from" precedence
order, lives on [SoundMaterial](https://diceytable.com/docs/reference/enums/sound-material) — this table is the raw value list for
quick reference alongside the other four sound enums.

## `soundActionSchema`

18 values. The logical interaction that emits a sound. A superset of the gameplay `TableObjectAction` union.

| Value |
|---|
| `place` |
| `pickup` |
| `drop` |
| `slide` |
| `shuffle` |
| `roll` |
| `fall` |
| `topple` |
| `withdraw` |
| `collect` |
| `return-to-box` |
| `board-clear` |
| `box-pickup` |
| `box-place` |
| `bag-rummage` |
| `counter-land` |
| `counter-fall` |
| `press` |

Full treatment lives on [SoundAction](https://diceytable.com/docs/reference/enums/sound-action). It is a **separate vocabulary**
from the 27-value gameplay `TableObjectAction` union on
[Object actions](https://diceytable.com/docs/mods/reference/object-actions) — neither a subset nor a superset of it. A sound action
names *why a sound plays*; an object action names *a thing the engine did to an entity*. The two lists share
exactly three spellings, `roll`, `shuffle` and `press`. Every other value here (`place`, `pickup`, `drop`, `slide`,
`fall`, `topple`, `withdraw`, `collect`, `return-to-box`, `board-clear`, `box-pickup`, `box-place`,
`bag-rummage`, `counter-land`, `counter-fall`) has no object action of the same name, and the twenty-four other
object actions (`toss` among them) have no sound action of the same name. Passing one where the other belongs fails loudly:
`api.objectAction` throws on a sound action, and `api.setObjectSound` drops an object action with a
diagnostic.

## `runtimeSoundEventSchema`

16 values. Runtime moments that can emit a sound; mapped to a sound action per object kind.

| Value |
|---|
| `grab` |
| `release` |
| `settle` |
| `fall` |
| `topple` |
| `collide` |
| `roll` |
| `shuffle` |
| `flip` |
| `deal` |
| `draw` |
| `insert` |
| `collect` |
| `board-clear` |
| `rummage` |
| `press` |

Full treatment, including the per-kind event → action binding table, lives on
[RuntimeSoundEvent](https://diceytable.com/docs/reference/enums/runtime-sound-event). Not part of any script surface — a mod never
names one of these directly.

## `soundCountSchema`

3 values. How many pieces the action involves — selects single/double/multi clip variants.

| Value |
|---|
| `single` |
| `double` |
| `multi` |

Only meaningful on a `roll` sound; see "How a material becomes a clip" above for exactly how
`resolveBuiltinSetId` uses it.

## `soundIntensitySchema`

2 values. Soft vs hard impact. Also derived from impact velocity at runtime.

| Value |
|---|
| `gentle` |
| `firm` |

Derived from impact velocity at runtime — nothing on the mod or table-script surface sets this directly. See
"How a material becomes a clip" above.
