Dicey Table

Enums and Constants

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.

On this page5 sections

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 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 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 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 BiquadFilterNodes 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 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 — the other half of the pair, and which actions a surface colours.
  • Runtime sound events — the moments that select an action, per kind.
  • api.playSound — playing one without changing anything.
  • api.setObjectSound — changing an entity's sound permanently.
  • Object kinds — the per-kind defaults in their wider context, and the table kind.
  • PIECE — setting an entity's Surface in the editor.

Did this page answer your question?