# SoundMaterial

> The 12 materials that pick a piece's sound and colour whatever lands on them — each kind's default, the struck-surface tone, and how a mod names one.

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

A **material** is the physical surface a piece is made of. It is one half of the pair — material × action —
that the engine resolves into an actual licensed clip, and it is the only way a mod or a non-admin editor
user can name a first-party sound. Clip ids and file paths are never addressable.

It does a second job too: a material is also what a piece **lands on**. The same token placed on a felt
table and on a glass one sounds different, because the thing underneath colours the impact — see
[Struck-surface tone](https://diceytable.com/docs/reference/enums/sound-material#struck-surface-tone) below.

**12 values**, declared as `soundMaterialSchema` in `packages/shared/src/soundSets.ts`. Eleven of them make a
noise; `silent` is a sentinel that makes none.

## The values

The **Label** column is what the editor's Surface dropdowns show (`soundMaterialLabel`); the wire value is
what you write in a file or a script.

| Value | Label | What it sounds like | Clips it plays as a moving piece | Kinds that default to it |
|---|---|---|---|---|
| `wood` | Wood | Wooden tiles, meeples, board surfaces. | its own | `board`, `card-holder`, `table` |
| `cardboard` | Cardboard | Punchboard counters, chits, thick tokens. | its own | — |
| `metal` | Metal | Coins, metal miniatures, metal-cased dice. | its own | `coin` |
| `plastic` | Plastic | Injection-moulded pieces and standard dice. | its own | `die`, `token`, `button` |
| `card` | Card / paper | Paper card stock — the deck and hand sounds. | its own | `card`, `deck` |
| `tile` | Tile | Ceramic or heavy resin tiles; also the rummage sounds. | its own | `bag` |
| `felt` | Felt | A felt-covered piece or a baize table top. | `cardboard`'s | — |
| `cloth` | Cloth / leather | Fabric, leather, a playmat. | `cardboard`'s | — |
| `glass` | Glass | Glass beads and stones, a glass table top. | `tile`'s | — |
| `stone` | Stone / ceramic | Stone, marble, ceramic. | `tile`'s | — |
| `generic` | Generic | The catch-all. What `playSound({ event })` uses when you omit `material`. | its own | `custom` |
| `silent` | Silent | **A sentinel, not a sound.** An entity set to `silent` emits nothing. | none | — |

**`felt`, `cloth`, `glass` and `stone` have no recordings of their own.** The licensed pack was recorded with
pieces landing on wood and cardboard, so a *piece* made of one of them borrows the nearest recorded material's
clips (`SOUND_MATERIAL_CLIP_SOURCE`): a glass bead clacks like a ceramic tile, a felt-covered piece thuds like
cardboard. They earn their place as **surfaces**, where the tone below makes them sound like themselves.

Every kind has a default, so an entity with no `material` still sounds like something:
`card` → `card`, `deck` → `card`, `die` → `plastic`, `token` → `plastic`, `board` → `wood`, `bag` → `tile`,
`card-holder` → `wood`, `custom` → `generic`, `button` → `plastic`, `table` → `wood`, `coin` → `metal`.

## Where a material comes from, in order

1. A per-action override on the entity — `soundSetOverrides[action]`, set by
   [`api.setObjectSound`](https://diceytable.com/docs/scripting-api/api#apisetobjectsound) or authored in the editor.
2. The entity's own `material` field.
3. The per-kind default above.

`api.playSound({ event: { material, action } })` bypasses all three: it names a material directly for one
play and changes nothing about any entity.

A **table pack** has one more place a material lives: `tablePack.surfaceMaterial`, the material of its play
surface, set with the **Material** row of the Table Editor's
[Play Surface](https://diceytable.com/docs/editor/inspector/platform-panels#play-surface) inspector. It is only ever a *struck*
surface — nothing about the pack moves — and absent means `wood`.

## Struck-surface tone

When a piece meets something, the clip is picked from the **piece's** material as above, and then coloured by
the material of whatever is **underneath** it. A felt top swallows the click and leaves the thud; glass and
metal add a narrow resonant ring; tile and stone lift the highs. The effect is a gain, a pitch multiplier and
a short chain of Web Audio `BiquadFilterNode`s applied to that one voice (`surfaceToneFor` and
`SURFACE_TONES` in `soundSets.ts`, applied by the runtime's `SoundService`).

| Surface | Gain | Pitch | Filters | How it reads |
|---|--:|--:|---|---|
| `felt` | 0.5 | 0.93 | low-pass 1200 Hz | Muffled — the click is gone. |
| `cloth` | 0.72 | 0.97 | low-pass 2600 Hz | Softened. |
| `card` | 0.85 | 0.98 | low-pass 4000 Hz | Slightly dulled. |
| `plastic` | 1 | 1.02 | high shelf +2 dB above 3.5 kHz | A touch brighter. |
| `tile` | 1 | 1.04 | low shelf −3 dB, high shelf +4 dB | Hard and bright. |
| `stone` | 1 | 1.05 | low shelf −4 dB, peak +2 dB at 1.8 kHz, high shelf +5 dB | Hard, dense, bright. |
| `glass` | 0.95 | 1.08 | low shelf −5 dB, high shelf +7 dB, narrow peak +6 dB at 4.8 kHz | Rings. |
| `metal` | 1 | 1.03 | narrow peak +5 dB at 2.4 kHz, high shelf +3 dB | Rings, lower. |
| `wood`, `cardboard` | — | — | none | **Neutral.** Every clip was recorded on these, so filtering them would only move the sound away from the real thing. |
| `generic`, `silent`, nothing known | — | — | none | Neutral. |

**What is underneath.** Every peer, when it plays an entity's sound, casts a ray straight down from that
entity and takes the **highest** thing it hits:

- the table pack's play surface → the pack's `surfaceMaterial` (`wood` when absent);
- a board, a placed [`table`](https://diceytable.com/docs/mods/reference/object-kinds#table) or any other entity → that entity's
  `material`, or its kind's default;
- the room floor, or nothing within 6 ft → no tone.

So a die rolled onto a felt-topped board sitting on a glass table sounds like felt: the board is the highest
thing under it.

**Which sounds are coloured.** Only the ones that are a piece *meeting* a surface: `place`, `drop`, `fall`,
`topple`, `roll`, `slide`, `collect`, `counter-land`, `counter-fall` and `box-place`
(`SURFACE_AFFECTED_SOUND_ACTIONS`). Picking up, shuffling in the hand, drawing, dealing, rummaging and pressing
a button happen above or away from the table and keep their recorded sound.

**Rolls also change clip.** A die roll resolves against the struck surface rather than the die: over `felt`,
`cloth`, `card` or `cardboard` it uses the recorded *cardboard* roll (duller, fewer bounces), over anything
else the *wood* roll — and the tone is applied on top.

> **By design.** The surface is **probed on each peer, never sent.** Every peer already holds the same
> snapshot and the same table, and sound is not replicated state, so the `sound-event` message is unchanged and
> an older client that does not know a material simply hears it neutral. For the same reason a sound played
> at a **position** rather than on an entity — `api.playSound({ event, position })` — has nothing to probe
> under and is never coloured.

## What a mod can and cannot name

> **By design.** A `SoundRef` is either `{ kind: "builtin", material }` — semantic, resolved internally —
> or `{ kind: "mod", modId, name }`, pointing at a sound the mod declared in its own manifest. A first-party
> clip id, a `SoundSetId` and a file path are all unrepresentable in the type, and the host additionally
> refuses a `{ kind: "mod" }` ref naming another mod or a name this mod never declared. That is a licensing
> boundary — the first-party clips are not exposed as an addressable library — and it is not expected to
> change. Declare what you need in `manifest.soundSets` and reference it by name.

Both declaration files name all twelve, so `material: "felt"` type-checks in a mod script and a table
script alike.

## See also

- [SoundAction](https://diceytable.com/docs/reference/enums/sound-action) — the other half of the pair, and which actions a surface colours.
- [Runtime sound events](https://diceytable.com/docs/reference/enums/runtime-sound-event) — the moments that select an action, per kind.
- [`api.playSound`](https://diceytable.com/docs/scripting-api/api#apiplaysound) — playing one without changing anything.
- [`api.setObjectSound`](https://diceytable.com/docs/scripting-api/api#apisetobjectsound) — changing an entity's sound permanently.
- [Object kinds](https://diceytable.com/docs/mods/reference/object-kinds) — the per-kind defaults in their wider context, and the `table` kind.
- [PIECE](https://diceytable.com/docs/editor/inspector/piece) — setting an entity's Surface in the editor.
