Change the sound FX parameters of a sound while it plays #315

Until now a value handed to a sound FX counted from the start of the
voice only. An engine whose pitch follows the speed, or a loop that
gets quieter, could not be built. Every play of Play sound now gives
out the number of its voice, and a new node lets the knobs of that one
voice glide to new values while it plays.

- Play sound has a new output voice: the number of this one play, or 0
  where nothing was played. Kept in a Number variable it reaches the
  voice from another event. Two plays of one sound are two voices.
- New action node Set sound FX parameters (exec, voice, fx params).
  It reaches exactly the voice it is given, a detached one too. A
  voice that has ended, or voice 0, is not reached.
- AudioSink.play returns the voice number and takes the plan and the
  values (FxVoice) instead of a finished chain. AudioSink.tune takes a
  voice number and new values. A name the voice's FX does not have is
  left out, one not given keeps its value.
- SoundLibrary hands out the number at once, before the bytes are
  there, and never twice. A voice still waiting for its bytes starts
  with the values handed in meanwhile.
- Every knob of a voice moves with setTargetAtTime (30 ms time
  constant). A knob whose value did not change is not sent again, so a
  tune every frame costs next to nothing.
- A pitch on a playing voice glides by playbackRate. A new WSOLA copy
  in the middle of a sound is not worked out, so the voice gets shorter
  or longer while it is moved. On a loop that is not heard.
- fxChainOf now gives a chain whose shape depends on the plan alone.
  A stage fed by a parameter stays at 0 dB, and a Mix fed by a
  parameter keeps both ways. A typed-in 0 or Mix at 0/1 is still left
  out by the compiler.
- Every way of a voice has a source of its own, also at the same
  pitch, so each can glide on its own. The pitched copy is shared.
- The tab keeps the numbers of what it plays, so moving a parameter
  field is heard at once.
- Test hook __gm.sound.levels(file) reads the knobs of every voice of
  a file, oldest first, and stats() counts the voices tuned.

Tests:
- soundfx.test.ts: 29 tests (+2 for the node in a running world: the
  voice of the first of two plays of one sound, and a play that played
  nothing)
- sound-library.test.ts: 15 tests (+3: glide, reach by number,
  pending voice)
- node-catalog.test.ts: 370 tests (+2, Play sound checks its voice)
- sounds + keep-on-scene-load: 31 tests, unchanged
- Counter-test: a tune that reaches every voice of the same file makes
  the reach test fail.
- e2e 34 (melektaus-atx): ALL PASSED - 30 checks (+1). In Chrome two
  looping voices of one sound start at depth 7. The one whose number
  sits in a variable glides to 0.7938 (2^(-4/12) = 0.7937), the other
  stays at 1. Both gains stay at 0.5012.
- The gate ran before voices got a number (CHECK EXIT 0, 241 files,
  3658 tests), not after.

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

src/runtime/systems/behaviorContext.ts

@@ -16,7 +16,7 @@ import { hasRenderLayer } from '../../core/properties/PropertySchema';
 import { resolveAssetProps } from '../../core/properties/resolve';
 import { loopsOf, volumeOf } from '../../core/properties/sounds';
 import { soundFxBuildFor } from '../../core/soundfx/compile';
-import { DRY, fxChainOf, type FxParams } from '../../core/soundfx/nodes';
+import { DRY_VOICE, type FxParams } from '../../core/soundfx/nodes';
 import type { Entity } from '../Entity';
 import { PhysicsSystem } from '../physics/PhysicsSystem';
 import type { World } from '../World';
@@ -172,6 +172,7 @@ export function behaviorContext(
       const file = assetId === '' ? '' : soundFileOf(project, assetId);
       if (assetId === '' || file) run.audio.stop(file);
     },
+    tuneSound: (voice, fxParams) => run.audio.tune(voice, fxParams),
     spawn: (assetId, position, parent) => world.spawn(assetId, position, resolve(parent) ?? null),
     addJoint: (assetId, owner, connected, at) => {
       const on = resolve(owner);
@@ -218,7 +219,7 @@ export function behaviorContext(
  * node's, and its loop flag unless the node overrules it either way. The asset is what a sound
  * *is* – a node that says nothing therefore plays it as the project describes it. An FX asset that
  * does not compile plays the sound dry: a broken effect should not silence the game. Its parameters
- * take the values handed in, the others their defaults.
+ * take the values handed in, the others their defaults. Returns the number of the voice, 0 for none.
  */
 function playSound(
   { project, audio }: ContextSources,
@@ -228,14 +229,20 @@ function playSound(
   owner: string,
   fxId: string,
   fxParams: FxParams,
-): void {
+): number {
   const asset = findAssetOf(project, assetId, 'sound');
-  if (!asset?.file) return;
+  if (!asset?.file) return 0;
   const props = resolveAssetProps(project, asset);
   const level = Math.max(0, Math.min(1, volumeOf(props) * volume));
   const fx = fxId ? findAssetOf(project, fxId, 'soundfx') : undefined;
   const plan = fx && soundFxBuildFor(fx).compiled;
-  audio.play(asset.file, level, loop ?? loopsOf(props), owner, plan ? fxChainOf(plan, fxParams) : DRY);
+  return audio.play(
+    asset.file,
+    level,
+    loop ?? loopsOf(props),
+    owner,
+    plan ? { plan, params: fxParams } : DRY_VOICE,
+  );
 }
 
 /** Where a ray of that length ends; where it has no direction, where it starts. */