GameSample

Open in new tab

Methods

.define(tag, registry)
.timeoutCallback()
.triggerCallback(name, event)
.play(stateOverride)
Play this sample immediately.
.subscribe(context, callback)

Defines a synthesised sound or vibration effect. Place it directly inside <game-shell> for automatic triggering, or call .play() manually.

<game-sample> observes shell triggers and the muted, vibration, roundScores, rounds, and scoreOrder signals.

Attributes

name
string — An identifier for manual lookup or .play(). Not required for trigger-based playback.
trigger
string -- The auto-trigger name that causes this sample to play. See the trigger table in GameSample. Multiple samples can share the same trigger -- all matching samples play simultaneously. Combined with when-* condition attributes, you can play different sounds depending on the player's score, trophies, difficulty, and more. 
<!-- Modest resolve for scores under 20 -->
<game-sample
  trigger="complete"
  when-max-score="19"
  type="marimba"
  notes="392:0,523:0.13"
  gain="0.35"
></game-sample>

<!-- Fanfare for perfect score -->
<game-sample
  trigger="complete"
  when-min-score="20"
  type="marimba"
  notes="262:0,330:0.10,392:0.20,523:0.32,659:0.48"
  gain="0.45"
></game-sample>
type
"marimba" | "beep" | "sine" | "noise" — The synthesis engine to use. Defaults to "marimba".
  • marimba — Additive sine-wave partials (fundamental + 2nd + 4th harmonic) with an exponential decay envelope. Produces a warm, mallet-like tone.
  • beep — Square wave with a short exponential decay. Produces a sharp, retro game-style tone.
  • sine — Sine wave with a short exponential decay. Produces a soft, clean tone.
  • noise — Filtered white noise burst. Ignores the notes attribute. Useful for error sounds, percussive hits, or static effects.
gain
number — Volume level from 0 to 1. Defaults to 0.35.
duration
number — Note duration in seconds. Defaults depend on the synth type: 0.5 for marimba, 0.08 for beep, 0.02 for noise.
notes
string — When scale is not set, a comma-separated list of freq:when pairs defining the notes to play. Each pair specifies a frequency in hertz and a start time offset in seconds. 
notes="523:0,659:0.08,784:0.16"

This plays three notes: 523 Hz at time 0, 659 Hz at 0.08s, and 784 Hz at 0.16s — producing an ascending arpeggio. Ignored for type="noise".

When scale is set, notes is repurposed as the maximum number of notes to play in the adaptive arpeggio (default: 5).

scale
"pentatonic" | "major" | "minor" | "chromatic" — When set, the sample generates a score-proportional arpeggio instead of playing fixed notes. The number of notes and base frequency scale with how well the player did on the last round.

Available scales (semitone offsets from root):

Scale Intervals
pentatonic 0, 2, 4, 7, 9, 12, 14, 16, 19, 21
major 0, 2, 4, 5, 7, 9, 11, 12, 14, 16
minor 0, 2, 3, 5, 7, 8, 10, 12, 14, 15
chromatic 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 
<!-- Score-proportional pentatonic jingle on pass -->
<game-sample
  trigger="pass"
  scale="pentatonic"
  notes="5"
  scale-root="220"
  gain="0.3"
>
</game-sample>

A low score plays 1 note at a low pitch. A high score plays up to 5 ascending notes at a higher pitch. The jingle adapts to reflect how well the round went.

scale-root
number — Root frequency in hertz for scale-based playback. Defaults to 220 (A3). The base frequency rises from this value toward an octave higher as the score proportion increases.
scale-spacing
number — Time in seconds between notes in a scale arpeggio. Defaults to 0.1.
vibrate
"auto" | "off" | pattern — Controls haptic feedback via the Vibration API. Defaults to "auto".
  • auto (default, or attribute absent) — Derives a vibration pattern from the note timing. Each note onset becomes a 15ms buzz; the gaps between notes become pauses. For type="noise", a single buzz matching the noise duration. For scale samples, the pattern matches the computed note count and spacing. This means every sample automatically vibrates in sync with its audio.
  • off — No haptic feedback.
  • Explicit pattern — A comma-separated list of milliseconds passed directly to navigator.vibrate(). Alternating vibrate/pause durations per the Web Vibration API.
<!-- Default: vibration mirrors the note timing -->
<game-sample trigger="pass" type="beep" notes="880:0" gain="0.2"> </game-sample>

<!-- Explicit celebration pattern -->
<game-sample
  trigger="complete"
  type="marimba"
  notes="523:0,659:0.12,784:0.24"
  vibrate="15,40,15,40,25"
>
</game-sample>

<!-- No vibration (e.g. ambient/subtle sounds) -->
<game-sample
  trigger="start"
  type="marimba"
  notes="523:0,659:0.08,784:0.16"
  gain="0.3"
  vibrate="off"
>
</game-sample>

Feature detection is built in — if navigator.vibrate is unavailable, the attribute is ignored. The shell's vibration signal acts as the global toggle.

Methods

.play(state?)
Play this sample immediately. Creates an AudioContext (or reuses the shared one) and schedules the synthesised notes.

Parameters:

  • state -- object (optional) -- Override for roundScores, rounds, and scoreOrder. When omitted, scale samples read current shell signals.
document.querySelector('game-sample[name="ding"]').play();

Usage

<!-- A three-note ascending chime -->
<game-sample
  name="chime"
  type="marimba"
  notes="523:0,659:0.1,784:0.2"
  gain="0.3"
>
</game-sample>

<!-- A short error buzz -->
<game-sample name="error" type="noise" gain="0.4" duration="0.03">
</game-sample>

<!-- A retro coin-collect beep -->
<game-sample
  name="coin"
  type="beep"
  notes="988:0,1319:0.06"
  gain="0.2"
  duration="0.05"
>
</game-sample>