Play and stop a pattern from a behavior in the game #336

A pattern could only be heard in its tab. Songs come with #334, and
only then can #336 play them in a game. Until then a game plays a
single pattern, looped or once, through two new nodes.

- Play pattern plays the whole pattern through its instrument at its
  own tempo. The loop on the ruler is only for editing. Inputs are
  pattern, volume, loop (on by default) and detached. It gives out
  playback, 0 where there is no instrument or no note.
- Stop pattern stops one pattern, every pattern for none, or one
  playback by its number. Let ring lets notes with an Envelope fall
  away in their release.
- A playing is numbered and owned like a voice. Destroying the object,
  Stop sound with nothing named and the end of the run stop it. Stop
  sound with a voice takes a playback too.
- Each playing runs on a scheduler of its own (core/music/playbacks).
  It waits for its files first, and a stop that came earlier wins.
- The scheduler has an end for a sequence that does not loop. It stops
  waking there and is done once its last notes are.
- The worker clock moved to viewport/wake.ts, so SoundLibrary can use
  it without importing music.ts.

Tests:
- pattern-play.test.ts (new): 8 tests, node catalog +7 cases
- e2e 64 (melektaus-atx): ALL PASSED, 23 checks (+3)
- Gate (melektaus-atx): CHECK EXIT 0, 248 files, 3854 tests
- Counter-checks: no end in the scheduler, and no owner for the
  playing, each fail 1 test

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/runtime/systems/Audio.ts

@@ -1,4 +1,5 @@
 import type { EaseShare } from '../../core/model/animation';
+import type { SequencePlay } from '../../core/music/playbacks';
 import type { FxParams, FxPlan, FxVoice } from '../../core/soundfx/nodes';
 
 /**
@@ -34,6 +35,15 @@ export interface AudioSink {
     duration: number,
     timing?: NoteTiming,
   ): number;
+  /**
+   * Plays the notes of a pattern on the audio clock, each struck through `play.strike`. `name` stands
+   * for the pattern as a file does for a sound, and the number it gives back is one no voice has:
+   * `stopVoice` and `playing` take it like a voice's, `stopOwner` and stopping everything reach it.
+   * Returns 0 where nothing is going to play.
+   */
+  playSequence(name: string, play: SequencePlay, owner: string): number;
+  /** Stops every pattern of that name, `''` every pattern; with `letRing` its notes fall away in their release. */
+  stopSequence(name: string, letRing?: boolean): void;
   /**
    * The end of a note (#331): its ways that end with the note fade out, those that play through
    * go on. Nothing happens for a voice that is no note or not there.
@@ -59,7 +69,7 @@ export interface AudioSink {
    */
   tail(voice: number): number;
   /**
-   * Silences every voice of that file; `''` silences all of them. A voice is faded out in a few
+   * Silences every voice of that file; `''` silences all of them, patterns too. A voice is faded out in a few
    * milliseconds, its echoes with it – unless `letRing`, which stops the sound and lets them fade.
    */
   stop(file: string, letRing?: boolean): void;
@@ -81,6 +91,8 @@ export interface NoteTiming {
 export const SILENT_AUDIO: AudioSink = {
   play: () => 0,
   playNote: () => 0,
+  playSequence: () => 0,
+  stopSequence: () => {},
   release: () => {},
   tune: () => {},
   length: () => 0,

src/runtime/systems/behaviorContext.ts

@@ -19,6 +19,7 @@ import { soundFxBuildFor } from '../../core/soundfx/compile';
 import { instrumentBuildFor, instrumentSourcesOf } from '../../core/instrument/compile';
 import { VELOCITY_PARAM } from '../../core/instrument/nodes';
 import { heldNote } from '../../core/instrument/notes';
+import { patternInstrument, patternLength, patternSequence, patternTempo } from '../../core/music/pattern';
 import { DRY_VOICE, type FxParams } from '../../core/soundfx/nodes';
 import type { Entity } from '../Entity';
 import { PhysicsSystem } from '../physics/PhysicsSystem';
@@ -173,6 +174,10 @@ export function behaviorContext(
       playNote(run, instrumentId, { note, velocity, volume, duration }, detached ? '' : entity.id, params, {
         tempo,
       }),
+    playPattern: (patternId, volume, loop, detached) =>
+      playPattern(run, patternId, volume, loop, detached ? '' : entity.id),
+    stopPattern: (patternId, letRing) =>
+      run.audio.stopSequence(patternId && patternVoiceName(patternId), letRing),
     soundLength: (assetId) => {
       const file = soundFileOf(project, assetId);
       return file ? run.audio.length(file) : 0;
@@ -289,6 +294,52 @@ export function instrumentVoiceName(instrumentId: string): string {
   return `instrument:${instrumentId}`;
 }
 
+/**
+ * A pattern played by a game: its notes through its instrument at its tempo, the whole of it once or
+ * round and round – the loop set on its ruler is for editing. Its notes take the volume and the owner
+ * of the playing. Returns the number of the playing, 0 where there is no pattern or nothing to hear.
+ */
+function playPattern(
+  { project, audio }: Pick<ContextSources, 'project' | 'audio'>,
+  patternId: string,
+  volume: number,
+  loop: boolean,
+  owner: string,
+): number {
+  const asset = findAssetOf(project, patternId, 'pattern');
+  if (!asset) return 0;
+  const sequence = patternSequence(asset);
+  const instrument = findAssetOf(project, patternInstrument(asset.props), 'instrument');
+  if (!instrument || sequence.notes.length === 0) return 0;
+  const sources = instrumentSourcesOf(project);
+  const pitches = [...new Set(sequence.notes.map((n) => n.note))];
+  const level = Number.isFinite(volume) ? Math.max(0, Math.min(1, volume)) : 1;
+  return audio.playSequence(
+    patternVoiceName(patternId),
+    {
+      sequence,
+      tempo: patternTempo(asset.props),
+      length: patternLength(asset),
+      loop,
+      layers: pitches.flatMap((note) => instrumentBuildFor(instrument, note, sources).layers),
+      strike: ({ instrument: id, note, velocity, duration, at, tempo }) =>
+        playNote(
+          { project, audio },
+          id,
+          { note, velocity, volume: level, duration },
+          owner,
+          {},
+          { at, tempo },
+        ),
+    },
+    owner,
+  );
+}
+
+export function patternVoiceName(patternId: string): string {
+  return `pattern:${patternId}`;
+}
+
 /** Where a ray of that length ends; where it has no direction, where it starts. */
 function pointAlong(from: Vec2, direction: Vec2, length: number): Vec2 {
   const d = Math.hypot(direction.x, direction.y);