GameAudio

Methods

.play(name, state): Manually play a named sample by its `name` attribute.
.timeoutCallback(event)
.triggerCallback(triggerName, event)
.define(tag, registry)
.subscribe(context, callback)

A declarative audio container that automatically plays synthesised sound effects in response to game state transitions. Place <game-sample> children inside it to define the sounds, then let the component handle triggering.

Attributes

vibration

boolean — Global vibration toggle for all child <game-sample> elements. Absent by default (haptic feedback disabled). Add the attribute to enable haptic feedback for all samples (subject to their individual vibrate setting).

<!-- Vibration enabled -->
<game-audio vibration>
  <!-- Vibration disabled (default) -->
  <game-audio></game-audio
></game-audio>

Auto-wired by <game-preferences> when the vibration key is toggled.

muted

boolean — When present, all sample playback is suppressed. Auto-wired by `` when the `sound` key is toggled.

volume

number — Master volume multiplier applied to all child <game-sample> playback. Defaults to 1. Auto-wired by `` when the `volume` key is adjusted.

Auto-Triggers

<game-audio> observes game signals and fires samples based on state transitions. Each trigger name matches the trigger attribute on a <game-sample> child:

Trigger Name	Fires When
`start`	Game transitions to `playing` from `ready` or `result`
`round`	Every transition to `playing` (including between rounds)
`pass`	Round passed (enters `between` with `lastRoundPassed` true)
`fail`	Round failed (enters `between` with `lastRoundPassed` false, and no timeout trigger)
`timeout`	Round failed due to timeout (enters `between` with feedback containing "time" and a `<game-sample trigger="timeout">` exists)
`complete`	Game enters the `result` state
`tier-up`	The `difficulty.tierIndex` increased since the last state update

DOM Event Triggers

In addition to state-transition triggers, samples can fire on DOM events during gameplay. These triggers are only active while the game is in the playing state -- they are automatically bound when play starts and unbound when it ends.

Trigger Name	Fires When
`input`	A `game-tile-input` event bubbles up (from `<game-tile-input>` on each keystroke)
`countdown`	A whole-second tick from `<game-timer>` (`game-timer-countdown` event); combine with `value="3"` etc. to target specific seconds
`keydown`	Any `keydown` event on the shell
`keyup`	Any `keyup` event on the shell
`click`	Any `click` event on the shell
`pointerdown`	Any `pointerdown` event on the shell
`pointerup`	Any `pointerup` event on the shell

<!-- Keypress click sound for tile input -->
<game-sample trigger="input" type="noise" gain="0.15" duration="0.025">
</game-sample>

<!-- Click feedback for mouse/touch games -->
<game-sample
  trigger="pointerdown"
  type="beep"
  notes="600:0"
  gain="0.1"
  duration="0.03"
>
</game-sample>

If no <game-sample> matches a trigger, nothing plays -- so you only need to define the sounds you care about.

Instance Methods

.play(name, state?)

Manually play a named sample. Looks up a child <game-sample name="..."> and calls its .play(state) method. Pass state if the sample uses the scale attribute and you want score-proportional playback.

const audio = document.querySelector("game-audio");
audio.play("bonus"); // plays <game-sample name="bonus">

Signal Access

Signal	Usage
Shell signals	Reads `scene`, `lastRoundPassed`, `lastFeedback`, and `difficulty` signals to detect triggers

Usage

<game-audio>
  <game-sample
    trigger="start"
    type="marimba"
    notes="523:0,659:0.08,784:0.16"
    gain="0.3"
  >
  </game-sample>
  <game-sample
    trigger="pass"
    type="beep"
    notes="880:0"
    gain="0.2"
    duration="0.06"
  >
  </game-sample>
  <game-sample trigger="fail" type="noise" gain="0.3" duration="0.04">
  </game-sample>
  <game-sample trigger="timeout" type="beep" notes="220:0,180:0.1" gain="0.25">
  </game-sample>
  <game-sample
    trigger="complete"
    type="marimba"
    notes="523:0,659:0.12,784:0.24,1047:0.36"
    gain="0.35"
  >
  </game-sample>
  <game-sample
    trigger="tier-up"
    type="marimba"
    notes="659:0,784:0.06,1047:0.12"
    gain="0.3"
  >
  </game-sample>
</game-audio>

You can also trigger samples by name from your game logic:

<game-audio>
  <game-sample name="bonus" type="marimba" notes="1047:0,1319:0.05" gain="0.25">
  </game-sample>
  <game-sample trigger="pass" type="beep" notes="880:0" gain="0.2">
  </game-sample>
</game-audio>

// In your game component:
document.querySelector("game-audio").play("bonus");