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#
- A per-action override on the entity —
soundSetOverrides[action], set byapi.setObjectSoundor authored in the editor. - The entity's own
materialfield. - 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(woodwhen absent); - a board, a placed
tableor any other entity → that entity'smaterial, 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
tablekind. - PIECE — setting an entity's Surface in the editor.
