GameSequencer

Methods

.effectCallback({ scene })

.start()

.stop()

.define(tag, registry)

.subscribe(context, callback)

A musical sequencer that plays during gameplay. Automatically starts when the game enters the playing or between state and stops when it leaves both (or when audio is muted). This means the sequencer continues playing through round transitions, providing uninterrupted audio across the play loop. Supports two modes via the mode attribute:

• sequence (default) — Loops a note pattern at a BPM that ramps from start-bpm to end-bpm over the timer duration, creating a sense of mounting urgency.
• hum — Plays a rising sine oscillator that glides from root to end-freq, with an initial silent period controlled by silent-fraction.

Attributes

notes

string — A comma-separated list of semitone offsets from the root frequency. Use null or empty entries for rests. The pattern loops continuously.

notes="0,4,7,12,7,4"

This defines a major arpeggio pattern: root, major third, fifth, octave, fifth, major third.

root

number — Root frequency in hertz. Defaults to 261.63 (middle C). All semitone offsets in notes are calculated relative to this frequency.

start-bpm

number — Starting tempo in beats per minute. Defaults to 72.

end-bpm

number — Target tempo in beats per minute. Defaults to 160. The sequencer ramps from start-bpm to end-bpm over the timer duration using an ease-in curve — the tempo increases slowly at first, then accelerates rapidly in the final third.

gain

number — Volume level from 0 to 1. Defaults to 0.07. Keep this low so the sequencer sits in the background.

type

string — Synth type for the notes. Defaults to "marimba". Uses the same additive sine partial engine as GameSample.

mode

"sequence" | "hum" — Playback mode. Defaults to "sequence". In "hum" mode the notes, start-bpm, end-bpm, and type attributes are ignored; a continuous oscillator rises from root to end-freq instead.

end-freq

number — Target frequency in hertz for hum mode. The oscillator glides from root to this value over the timer duration. Defaults to 220. Has no effect in sequence mode.

silent-fraction

number — Fraction of the total timer duration that stays silent at the start of hum mode (0–1). Defaults to 0.25 (first 25% is silent). Has no effect in sequence mode.

Methods

.start()

Start the sequencer manually. Reads the <game-timer> duration from the nearest shell to calculate the BPM ramp duration. Normally called automatically when the game enters the playing or between state.

.stop()

Stop the sequencer. Called automatically when the game leaves both the playing and between states (e.g. entering result or paused).

Timer Integration

The sequencer reads the duration attribute from the first <game-timer> inside the same <game-shell> to determine how long the BPM ramp lasts. If no timer is found, it defaults to 10 seconds.

BPM Ramp Curve

The tempo does not increase linearly. An ease-in curve is applied:

• First 60% of the timer — gentle acceleration (tempo reaches roughly 40% of the way from start to end BPM).
• Final 40% of the timer — rapid acceleration to the target BPM.

This means the player feels comfortable at first, with tension building sharply as time runs out.

Signal Access

Mute Awareness

The sequencer checks the <game-audio> element's muted attribute before starting. If audio is muted, the sequencer stays stopped even during playing/between scenes. When the sound preference is toggled (via --toggle-mute or the preferences panel), the sequencer reacts immediately -- stopping if muted, resuming if unmuted and the game is in a playing state.

Usage

<game-sequencer
  notes="0,4,7,12,7,4"
  root="261.63"
  start-bpm="72"
  end-bpm="160"
  gain="0.07"
></game-sequencer>

A minor-key tension pattern:

<game-sequencer
  notes="0,3,7,null,12,7,3,null"
  root="220"
  start-bpm="80"
  end-bpm="180"
  gain="0.06"
></game-sequencer>