@adatechnology/game-audio 0.7.0 → 0.9.0

package/dist/{locale-CJfDpWnI.d.ts → locale-YHyJwN2P.d.ts}

@@ -1,340 +1,119 @@
+import { B as BusId, q as SampleEnvironment, p as SampleCrossover, F as Falloff, c as SampleSound, t as SampleTier, h as BuildOrder, C as Curve, b as SoundRecipe, S as SoundRegistry, a as SoundBank } from './bank-Dsj1VAht.js';
 import { Vec3, DeferredQueue, TestableModule } from '@adatechnology/game-contracts';
 
-/**
- * Sound recipes are data. A recipe says which nodes a sound has and which numbers drive them; ranges are drawn when the sound is planned, in
- * the order the fields are written (see `planSound`), so a recipe ported from a team routine draws its random numbers in the routine's order.
- */
-declare const BUS_IDS: readonly ["weapons", "voices", "world", "ambience", "weather", "ui"];
-type BusId = (typeof BUS_IDS)[number];
-/** A named number: from `PlayOptions.params` or the recipe's `vars`, times `scale`, plus `add`. */
-type ParamRef = {
-    readonly param: string;
-    readonly scale?: number;
-    readonly add?: number;
-};
-/** A number, a `[min, max]` drawn uniformly (`min + random × (max − min)`), or a named number. */
-type Range = number | readonly [min: number, max: number] | ParamRef;
-/** Seconds from the layer start: a range, the layer `'duration'`, or `'0.6d'` (0.6 × the layer duration). */
-type Time = Range | 'duration' | `${number}d`;
-type Curve = 'linear' | 'exp';
-/**
- * How an AudioParam moves:
- * - `{ set }` assigns `.value`;
- * - `{ set, to, curve, over }` assigns `.value`, then ramps to `to` at `over`;
- * - `{ from }` calls `setValueAtTime(from)` at the start; with `to`, `curve` and `over` it then ramps to `to` (`'from'` is the value drawn for `from`: the art scene ramps a tone back to its own start when it gives no end).
- */
-type Automation = {
-    readonly set: Range;
-    readonly to?: Range | 'from';
-    readonly curve?: Curve;
-    readonly over?: Time;
-} | {
-    readonly from: Range;
-    readonly to?: Range | 'from';
-    readonly curve?: Curve;
-    readonly over?: Time;
-};
-/**
- * One gain point: time (seconds, or `'0.6d'`), value and how it is reached (`set` = `setValueAtTime`, or a ramp). The value is multiplied by the
- * layer level (volume, distance and layer gain) except when the fourth item is `'fixed'` (the floor a ramp falls to, such as 0.001).
- */
-type EnvelopePoint = readonly [time: number | `${number}d`, value: number, curve: 'set' | Curve] | readonly [time: number | `${number}d`, value: number, curve: 'set' | Curve, fixed: 'fixed'];
-type Envelope = readonly EnvelopePoint[];
-type FilterSpec = {
-    readonly type: BiquadFilterType;
-    readonly frequency: Automation;
-    readonly q?: Range;
-    /** The BiquadFilter gain (shelf and peaking types). */
-    readonly gain?: Range;
-    /** A gain node after the filter, for a parallel bank where each band has its own level (the game's scream formants). */
-    readonly level?: Range;
-};
-type FilterBank = {
-    readonly mode: 'serial' | 'parallel';
-    readonly bank: readonly FilterSpec[];
-};
-/** An LFO. `depth` is absolute, or a factor of the source start frequency. With `base`, gain modulation goes through its own gain stage (the game rotor). */
-type Modulator = {
-    readonly target: 'gain' | 'frequency';
-    /** Left out, the oscillator keeps its default (sine) and no type is set. */
-    readonly wave?: OscillatorType;
-    readonly rate: Range;
-    readonly depth: Range | {
-        readonly scaleOf: 'frequency';
-        readonly factor: number;
-    };
-    readonly base?: number;
-};
-/**
- * Noise from the engine's seeded buffer. `offset` is where playback starts in it: `'random'` (random × `offsetScale`, default 1), `'fit'`
- * (random × (buffer length − duration)) or seconds. `loop` sets the source to loop (the art scene sets it on every noise source).
- */
-type NoiseSource = {
-    readonly kind: 'noise';
-    readonly offset?: 'random' | 'fit' | number;
-    readonly offsetScale?: number;
-    readonly loop?: boolean;
-};
-type OscSource = {
-    readonly kind: 'osc';
-    readonly wave: OscillatorType;
-    readonly frequency: Automation;
-};
-/** The art scene's `voice`: an oscillator with vibrato through formant bands, plus a band of breath noise, summed and boosted. */
-type FormantVoiceSource = {
-    readonly kind: 'formant_voice';
-    readonly wave: OscillatorType;
-    readonly frequency: Automation;
-    /** Vibrato rate, and depth as a factor of the start frequency. */
-    readonly vibrato: {
-        readonly rate: Range;
-        readonly depth: number;
-    };
-    readonly formants: readonly {
-        readonly frequency: Range;
-        readonly q: number;
-    }[];
-    readonly breath: {
-        readonly frequency: Range;
-        readonly q: number;
-        readonly gain: Range;
-    };
-    readonly mix: number;
-};
-type LayerSource = NoiseSource | OscSource | FormantVoiceSource;
-type Layer = {
-    /** Start, seconds after the sound starts. */
-    readonly at?: Range;
-    /** Overrides the recipe duration for this layer. */
-    readonly duration?: Range;
-    /** Seconds the source keeps running after the duration (the `+ 0.05` of the team routines). Default: the recipe's, else 0.05. */
-    readonly tail?: number;
-    /** The layer played `count` times, `spacing` seconds apart (the game's animal calls). */
-    readonly repeat?: {
-        readonly count: number;
-        readonly spacing: number;
-    };
-    /** Layer level before distance. Default 1. */
-    readonly gain?: Range;
-    /** Send to the reverb, 0..1 or more (the art scene uses up to 1.2). */
-    readonly wet?: number;
-    readonly source: LayerSource;
-    readonly filters?: FilterBank;
-    readonly modulators?: readonly Modulator[];
-    readonly envelope: Envelope;
+/** Where the ears are. `yaw` turns around y like a three.js camera: the right ear points at `(cos yaw, 0, −sin yaw)`. */
+type Listener = {
+    readonly position: Vec3;
+    readonly yaw: number;
 };
+type DistanceMode = 'xz' | '3d';
+declare const DEFAULT_LISTENER: Listener;
+/** The art scene clamps the pan to ±0.85 and never divides by less than 2 m (cena L1319). */
+declare const PAN_LIMIT = 0.85;
+declare const PAN_MIN_DISTANCE = 2;
+/** Distance from the listener: on the ground (`xz`, the teams' choice) or in 3D. */
+declare function listenerDistance(listener: Listener, position: Vec3, mode?: DistanceMode): number;
+/** The art scene's `panFor`: the side the sound is on, −0.85 (left) to 0.85 (right). No HRTF, for cost. */
+declare function panFor(listener: Listener, position: Vec3): number;
+
 /**
- * Distance falloff of a sound's level:
- * - `inverse_square`: `volume / (1 + d² × k)`; `cutoffK` also divides every lowpass cutoff by `1 + d × cutoffK` (the game's muffling);
- * - `linear`: `max(0, 1 − d / range)`, silent at or below `minGain`;
- * - `none`: no distance.
- * `scale` multiplies the level (the game's boom is 1.4 at the source), and below `minGain` the sound is not played.
+ * Sounds made of recorded files (`.ogg`), as data. A `SampleSound` lists the takes of each layer: `close` (the sound as heard near, the only one
+ * required), `far` (the same event heard from far away: a muffled bang with its echo) and the tail of the place it happens in (`indoor` / `outdoor`).
+ * `planSample` decides, from a seeded stream, which take plays (round-robin: never the same take twice in a row), the pitch (± a fraction), how the
+ * near and far layers cross over with the distance, the level, the pan and the distance lowpass. It is pure, so it runs in Node and in tests; the
+ * WebAudio layer (`realizeSample`) plays the plan from decoded buffers.
  */
-type Falloff = {
-    readonly model: 'inverse_square';
-    readonly k: number;
-    readonly minGain?: number;
-    readonly cutoffK?: number;
-    readonly scale?: number;
-} | {
-    readonly model: 'linear';
-    readonly range: number;
-    readonly minGain?: number;
-    readonly scale?: number;
-} | {
-    readonly model: 'none';
+
+declare const SAMPLE_ENVIRONMENTS: readonly ["indoor", "outdoor"];
+/** The role of a layer in a plan. */
+type SampleLayerRole = 'close' | 'far' | 'tail';
+declare const DEFAULT_SAMPLE_FALLOFF: Falloff;
+declare const DEFAULT_CROSSOVER: SampleCrossover;
+declare const DEFAULT_SAMPLE_PITCH = 0.04;
+declare const DEFAULT_TAIL_GAIN = 0.6;
+declare const DEFAULT_SAMPLE_CUTOFF_K = 0.01;
+/** The open lowpass: at or above it the realizer leaves the filter out. */
+declare const OPEN_CUTOFF = 20000;
+/** A layer quieter than this is left out of the plan. */
+declare const LAYER_FLOOR = 0.001;
+/** One file to play: which take, at what level (already times the sound level), rate and start. */
+type PlannedSampleLayer = {
+    readonly role: SampleLayerRole;
+    readonly url: string;
+    /** Index of the take in its list. */
+    readonly take: number;
+    readonly gain: number;
+    readonly rate: number;
+    readonly at: number;
+    /** Seconds into the file (the take's trim). */
+    readonly offset?: number;
+    /** Seconds of the file played (the take's trim). */
+    readonly duration?: number;
 };
-/**
- * The order the realizer creates and wires the nodes in. Each one is the order of the team routine it reproduces, so the trace of the SDK
- * matches the trace of the team code node for node:
- * - `layered` (default): the art scene's `sNoise`, `sTone` and `voice`; every layer has its own output stage (distance gain, pan, reverb send);
- * - `burst`: the game's `sfx` (jogo L62089);
- * - `scream`: the game's `grito` (L62128);
- * - `groan`: the game's `voz` (L62143);
- * - `boom`: the game's `boom` (L68278);
- * - `static`: the game's `chiado` (L69998);
- * - `chord`: the game's `buzina` (L70272);
- * - `calls`: the game's `bichoSom` (L66625);
- * - `siren`: the art scene's `siren` (L1369);
- * - `weapon`: the weapon audio of the kit (`weapons-three`): per layer a filtered noise burst or an oscillator, then its own gain, chained to the bus.
- * Every order but `layered` puts the level into the envelope and connects straight to the bus.
- */
-declare const BUILD_ORDERS: readonly ["layered", "burst", "scream", "groan", "boom", "static", "chord", "calls", "siren", "weapon"];
-type BuildOrder = (typeof BUILD_ORDERS)[number];
-type SoundRecipe = {
+type SamplePlan = {
+    readonly kind: 'sample';
     readonly id: string;
     readonly bus: BusId;
-    readonly order?: BuildOrder;
-    /** Named numbers drawn first, in the order written; layers read them with `{ param }`. */
-    readonly vars?: Readonly<Record<string, Range>>;
-    readonly duration?: Range;
-    readonly tail?: number;
-    readonly layers: readonly Layer[];
-    readonly falloff?: Falloff;
-    /** Stereo pan from the listener (the art scene's `panFor`). Only the `layered` order has an output stage to pan. */
-    readonly pan?: boolean;
-    /** Voice group for the limiter (`undead_voice`...). */
+    readonly level: number;
+    readonly distance: number;
+    readonly pan?: number;
+    /** Lowpass cutoff in Hz (`OPEN_CUTOFF` = no filter). */
+    readonly cutoff: number;
+    /** Playback rate of every layer (the pitch drawn for this play). */
+    readonly rate: number;
+    readonly environment: SampleEnvironment;
+    /** The tier played (`undefined` without tiers or intensity). */
+    readonly tier?: string;
+    /** 0 = all near, 1 = all far. */
+    readonly farMix: number;
+    readonly layers: readonly PlannedSampleLayer[];
+    readonly priority: number;
     readonly group?: string;
-    /** Limiter priority; default from the bus (weapons > voices > world > ambience). */
-    readonly priority?: number;
-    /**
-     * The team routine creates nodes before it checks the level (the game's `bichoSom` creates its gain and filter first): a silent sound is kept as
-     * a plan with `silent: true` so the realizer repeats those nodes. Off by default.
-     */
-    readonly keepSilent?: boolean;
-    /** Where the numbers come from: `"jogo:L62128"`, `"cena:L1342"`, or `"sdk"` for values the kit chose. */
-    readonly sources: readonly string[];
 };
-/**
- * The order the loop realizer creates the nodes in:
- * - `game_loop`: the game's `loopSet` (L62109): gain and filter first, nodes created the first time the volume passes `startAbove`, gain from 0;
- * - `chain_loop`: the art scene's loops in `initAudio` (L1314–1316): source, filters, gain at its starting volume, created when the loop opens.
- */
-type LoopOrder = 'game_loop' | 'chain_loop';
-type LoopRecipe = {
-    readonly id: string;
-    readonly bus: BusId;
-    readonly order?: LoopOrder;
-    /** An oscillator loop may leave the frequency out: it starts at the default and `set({ frequency })` glides it (the game's motor). */
-    readonly source: (NoiseSource & {
-        readonly loop: true;
-    }) | {
-        readonly kind: 'osc';
-        readonly wave: OscillatorType;
-        readonly frequency?: Automation;
-        readonly loop: true;
-    };
-    readonly filters?: FilterBank;
-    readonly modulators?: readonly Modulator[];
-    /** `setTargetAtTime` time constants (jogo L62125–62126: 0.15 for the volume, 0.08 for the frequency). */
-    readonly smoothing?: {
-        readonly volume: number;
-        readonly frequency: number;
-    };
-    /** Nodes are created the first time the volume reaches this (jogo L62112: 0.002). */
-    readonly startAbove?: number;
-    /** Volume the gain starts at when the loop opens (`chain_loop`). */
+/** The last take each sound layer played (`<id>/<role>` → index), so the next play never repeats it. Keep one per engine or channel. */
+type SampleMemory = Map<string, number>;
+type SamplePlanInput = {
+    readonly random: () => number;
+    readonly listener?: Listener;
+    readonly distanceMode?: DistanceMode;
+    readonly position?: Vec3;
+    /** Metres; overrides `position` for the distance (not for the pan). */
+    readonly distance?: number;
     readonly volume?: number;
-    /**
-     * Distance falloff of the loop, applied each time `set` gives a `position` (an engine, a fire, a skid heard from where it is). Left out, the loop is
-     * heard at the listener, as the team loops are. `cutoffK` also lowers the first filter's cutoff with the distance, as it does for one-shots.
-     */
-    readonly falloff?: Falloff;
-    /** Stereo pan from the listener, from the `position` of each `set` (a panner after the gain). Off by default. */
-    readonly pan?: boolean;
-    readonly sources: readonly string[];
+    /** Default `outdoor`. */
+    readonly environment?: SampleEnvironment;
+    /** 0 (clear) to 1 (behind a wall): lowers the level and closes the lowpass. */
+    readonly occlusion?: number;
+    /** Round-robin memory; without it each plan is drawn on its own (and may repeat). */
+    readonly memory?: SampleMemory;
+    /** Limiter priority when the sound has none. */
+    readonly priority?: number;
+    /** 0 (light) to 1 (heavy): picks the tier (see `SampleTier`). */
+    readonly intensity?: number;
 };
 /**
- * One id that plays one of several recipes (the takes of a footstep, of a punch): `play(id)` draws a variant, never the one it played last time (unless
- * `repeat`), and plays it at a rate drawn from `rate` (1.04 is 4% higher and 4% shorter; see `retunePlan`), so ten footsteps never sound like one.
+ * Round-robin without repeat: a take drawn among all but the last one played. With one take it is always 0; without `last` any take may come.
+ * One random number per call.
  */
-type SoundSet = {
-    readonly id: string;
-    /** Recipe ids, at least one. */
-    readonly variants: readonly string[];
-    /** `[min, max]` of the playback rate (pitch and speed together). Default `[1, 1]`. */
-    readonly rate?: readonly [min: number, max: number];
-    /** Allow the same variant twice in a row (default false). */
-    readonly repeat?: boolean;
-};
-type SoundBank = {
-    readonly id: string;
-    readonly sounds?: readonly SoundRecipe[];
-    readonly loops?: readonly LoopRecipe[];
-    readonly sets?: readonly SoundSet[];
-    /** Sounds played from recorded files (see `sample.ts`). A sample and a recipe may share an id: the sample plays once its files are loaded. */
-    readonly samples?: readonly SampleSound[];
-};
-/** One take: a file and its own trim (linear gain, default 1). */
-type SampleRef = {
-    readonly url: string;
-    readonly gain?: number;
-};
-/** Where a sound happens: a closed room rings short and dense, the open field long and thin. */
-type SampleEnvironment = 'indoor' | 'outdoor';
-/** Where the near take hands over to the far one: all near up to `from` metres, all far from `to`, an equal-power crossfade between. */
-type SampleCrossover = {
-    readonly from: number;
-    readonly to: number;
-};
-type SampleTail = {
-    readonly indoor?: readonly SampleRef[];
-    readonly outdoor?: readonly SampleRef[];
-    /** Level of the tail against the dry take (default 0.6). */
-    readonly gain?: number;
-    /** Seconds after the start (default 0: the tail file carries its own pre-delay). */
-    readonly at?: number;
+declare function pickTake(count: number, last: number | undefined, random: () => number): number;
+/** 0 at or below `from`, 1 at or beyond `to`, linear between. */
+declare function farMixAt(crossover: SampleCrossover, distance: number): number;
+/** Equal-power gains of the near and far layers for a far mix (so the crossover has no dip in loudness). */
+declare function crossGains(farMix: number): {
+    readonly close: number;
+    readonly far: number;
 };
+/** The distance lowpass, closed further behind a wall (an occluded sound loses its highs first). */
+declare function sampleCutoff(cutoffK: number, distance: number, occlusion?: number): number;
+/** Every file a sound may play (to load before its first play). */
+declare function sampleUrls(sound: SampleSound): string[];
+/** The tier for an intensity: the last whose `from` is at or below it. */
+declare function tierFor(sound: SampleSound, intensity: number | undefined): SampleTier | undefined;
 /**
- * A set of takes for a strength of the action (criterion C7: a light blow, a heavy one, a car at 10 or 60 km/h): from `from` (0..1) up, these takes
- * replace `close` and `far`. The tier played is the last one whose `from` is at or below `PlayOptions.intensity`.
+ * The plan of one play, or `null` when the sound is too far to be heard. Random numbers, in order: the pitch, the near take, the far take, the
+ * tail take (each drawn only when that layer has more than zero takes and is heard).
  */
-type SampleTier = {
-    readonly name: string;
-    readonly from: number;
-    readonly close: readonly SampleRef[];
-    readonly far?: readonly SampleRef[];
-};
-type SampleSound = {
-    readonly id: string;
-    readonly bus: BusId;
-    /** The takes heard near; at least one (the criteria ask four for a sound heard all the time). */
-    readonly close: readonly SampleRef[];
-    /** The takes heard far; without them the near take plays at every distance (muffled by the lowpass). */
-    readonly far?: readonly SampleRef[];
-    /** Takes by strength (light, medium, heavy), in rising `from`; without `intensity` the near takes above play. */
-    readonly tiers?: readonly SampleTier[];
-    /** Default `{ from: 30, to: 80 }`. */
-    readonly crossover?: SampleCrossover;
-    readonly tail?: SampleTail;
-    /** ± fraction of the playback rate drawn per play (default 0.04: ±4 %, inside the 3–5 % of the criteria). 0 plays every take at its pitch. */
-    readonly pitch?: number;
-    /** Level of the sound (default 1). */
-    readonly gain?: number;
-    /** Default `{ model: 'inverse_square', k: 0.002, minGain: 0.002 }`: a recorded take already sounds near or far, so the curve is gentler than a recipe's. */
-    readonly falloff?: Falloff;
-    /** The lowpass cutoff is `20000 / (1 + d × cutoffK)` Hz (default 0.01: 10 kHz at 100 m). 0 turns the distance lowpass off. */
-    readonly cutoffK?: number;
-    /** Stereo pan from the listener (default true). */
-    readonly pan?: boolean;
-    readonly group?: string;
-    readonly priority?: number;
-    /**
-     * At most `voices` plays of this sound ring at once: a new one fades the oldest out in `fade` seconds (default 0.03) at its own start. Rapid fire
-     * then stays shot by shot instead of a wall of overlapping takes (criterion C9). Without it every play rings to its end.
-     */
-    readonly choke?: {
-        readonly voices: number;
-        readonly fade?: number;
-    };
-    /**
-     * A continuous sound (fire, rain, an engine idling) that `engine.loop(id)` plays: the near takes chained without a seam, each crossed into the next
-     * in `crossfade` seconds (default 0.25, equal power), never the same take twice in a row. While the files load, the recipe loop of `fallback`
-     * (or of the same id) plays. `play(id)` still plays one take as a one-shot.
-     */
-    readonly loop?: boolean | {
-        readonly crossfade?: number;
-    };
-    /** A recipe id the engine plays while the files are not loaded yet (or failed): the synthesized sound stays as the fallback. */
-    readonly fallback?: string;
-    /** Where each file came from: `"freesound:123456 autor CC0"`, or `"sdk"` for files the kit made. */
-    readonly sources: readonly string[];
-};
-
-/** Where the ears are. `yaw` turns around y like a three.js camera: the right ear points at `(cos yaw, 0, −sin yaw)`. */
-type Listener = {
-    readonly position: Vec3;
-    readonly yaw: number;
-};
-type DistanceMode = 'xz' | '3d';
-declare const DEFAULT_LISTENER: Listener;
-/** The art scene clamps the pan to ±0.85 and never divides by less than 2 m (cena L1319). */
-declare const PAN_LIMIT = 0.85;
-declare const PAN_MIN_DISTANCE = 2;
-/** Distance from the listener: on the ground (`xz`, the teams' choice) or in 3D. */
-declare function listenerDistance(listener: Listener, position: Vec3, mode?: DistanceMode): number;
-/** The art scene's `panFor`: the side the sound is on, −0.85 (left) to 0.85 (right). No HRTF, for cost. */
-declare function panFor(listener: Listener, position: Vec3): number;
+declare function planSample(sound: SampleSound, input: SamplePlanInput): SamplePlan | null;
 
 /** How an AudioParam moves, with every number resolved and every time in seconds from the layer start. */
 type PlannedAutomation = {
@@ -448,101 +227,6 @@ type PlanInput = {
  */
 declare function planSound(recipe: SoundRecipe, input?: PlanInput): SoundPlan | null;
 
-/**
- * Sounds made of recorded files (`.ogg`), as data. A `SampleSound` lists the takes of each layer: `close` (the sound as heard near, the only one
- * required), `far` (the same event heard from far away: a muffled bang with its echo) and the tail of the place it happens in (`indoor` / `outdoor`).
- * `planSample` decides, from a seeded stream, which take plays (round-robin: never the same take twice in a row), the pitch (± a fraction), how the
- * near and far layers cross over with the distance, the level, the pan and the distance lowpass. It is pure, so it runs in Node and in tests; the
- * WebAudio layer (`realizeSample`) plays the plan from decoded buffers.
- */
-
-declare const SAMPLE_ENVIRONMENTS: readonly ["indoor", "outdoor"];
-/** The role of a layer in a plan. */
-type SampleLayerRole = 'close' | 'far' | 'tail';
-declare const DEFAULT_SAMPLE_FALLOFF: Falloff;
-declare const DEFAULT_CROSSOVER: SampleCrossover;
-declare const DEFAULT_SAMPLE_PITCH = 0.04;
-declare const DEFAULT_TAIL_GAIN = 0.6;
-declare const DEFAULT_SAMPLE_CUTOFF_K = 0.01;
-/** The open lowpass: at or above it the realizer leaves the filter out. */
-declare const OPEN_CUTOFF = 20000;
-/** A layer quieter than this is left out of the plan. */
-declare const LAYER_FLOOR = 0.001;
-/** One file to play: which take, at what level (already times the sound level), rate and start. */
-type PlannedSampleLayer = {
-    readonly role: SampleLayerRole;
-    readonly url: string;
-    /** Index of the take in its list. */
-    readonly take: number;
-    readonly gain: number;
-    readonly rate: number;
-    readonly at: number;
-};
-type SamplePlan = {
-    readonly kind: 'sample';
-    readonly id: string;
-    readonly bus: BusId;
-    readonly level: number;
-    readonly distance: number;
-    readonly pan?: number;
-    /** Lowpass cutoff in Hz (`OPEN_CUTOFF` = no filter). */
-    readonly cutoff: number;
-    /** Playback rate of every layer (the pitch drawn for this play). */
-    readonly rate: number;
-    readonly environment: SampleEnvironment;
-    /** The tier played (`undefined` without tiers or intensity). */
-    readonly tier?: string;
-    /** 0 = all near, 1 = all far. */
-    readonly farMix: number;
-    readonly layers: readonly PlannedSampleLayer[];
-    readonly priority: number;
-    readonly group?: string;
-};
-/** The last take each sound layer played (`<id>/<role>` → index), so the next play never repeats it. Keep one per engine or channel. */
-type SampleMemory = Map<string, number>;
-type SamplePlanInput = {
-    readonly random: () => number;
-    readonly listener?: Listener;
-    readonly distanceMode?: DistanceMode;
-    readonly position?: Vec3;
-    /** Metres; overrides `position` for the distance (not for the pan). */
-    readonly distance?: number;
-    readonly volume?: number;
-    /** Default `outdoor`. */
-    readonly environment?: SampleEnvironment;
-    /** 0 (clear) to 1 (behind a wall): lowers the level and closes the lowpass. */
-    readonly occlusion?: number;
-    /** Round-robin memory; without it each plan is drawn on its own (and may repeat). */
-    readonly memory?: SampleMemory;
-    /** Limiter priority when the sound has none. */
-    readonly priority?: number;
-    /** 0 (light) to 1 (heavy): picks the tier (see `SampleTier`). */
-    readonly intensity?: number;
-};
-/**
- * Round-robin without repeat: a take drawn among all but the last one played. With one take it is always 0; without `last` any take may come.
- * One random number per call.
- */
-declare function pickTake(count: number, last: number | undefined, random: () => number): number;
-/** 0 at or below `from`, 1 at or beyond `to`, linear between. */
-declare function farMixAt(crossover: SampleCrossover, distance: number): number;
-/** Equal-power gains of the near and far layers for a far mix (so the crossover has no dip in loudness). */
-declare function crossGains(farMix: number): {
-    readonly close: number;
-    readonly far: number;
-};
-/** The distance lowpass, closed further behind a wall (an occluded sound loses its highs first). */
-declare function sampleCutoff(cutoffK: number, distance: number, occlusion?: number): number;
-/** Every file a sound may play (to load before its first play). */
-declare function sampleUrls(sound: SampleSound): string[];
-/** The tier for an intensity: the last whose `from` is at or below it. */
-declare function tierFor(sound: SampleSound, intensity: number | undefined): SampleTier | undefined;
-/**
- * The plan of one play, or `null` when the sound is too far to be heard. Random numbers, in order: the pitch, the near take, the far take, the
- * tail take (each drawn only when that layer has more than zero takes and is heard).
- */
-declare function planSample(sound: SampleSound, input: SamplePlanInput): SamplePlan | null;
-
 /**
  * Decoded sample buffers by url. Files load once (concurrent asks share the same promise), decode on the engine's context and stay until `clear`.
  * The bytes come from a `SampleLoader`: `fetch` by default, or anything else (a single-file page passes the files inlined as base64).
@@ -624,29 +308,6 @@ declare function resolveMix(mix: string | MixProfile, profiles?: Readonly<Record
 /** The gain a bus plays at: 0 when muted, its gain (default 1) otherwise. */
 declare function busGain(setting: BusSetting | undefined): number;
 
-type DeepPartial<TValue> = TValue extends readonly unknown[] ? TValue : TValue extends object ? {
-    readonly [Key in keyof TValue]?: DeepPartial<TValue[Key]>;
-} : TValue;
-/** Every sound and loop the engine knows, by id. Banks register in order; a later bank replaces an earlier recipe with the same id. */
-type SoundRegistry = {
-    register(bank: SoundBank): void;
-    /** Merged into the recipe by id (objects merge, arrays such as `layers` are replaced); an unknown id is ignored. */
-    patch(id: string, patch: DeepPartial<SoundRecipe> | DeepPartial<LoopRecipe> | DeepPartial<SampleSound>): void;
-    remove(id: string): void;
-    sound(id: string): SoundRecipe | undefined;
-    loop(id: string): LoopRecipe | undefined;
-    /** The set an id names (`SoundBank.sets`), if any; a recipe with the same id wins in `play`. */
-    set(id: string): SoundSet | undefined;
-    sample(id: string): SampleSound | undefined;
-    soundIds(): string[];
-    setIds(): string[];
-    loopIds(): string[];
-    sampleIds(): string[];
-    /** Which bank each id came from. */
-    bankOf(id: string): string | undefined;
-};
-declare function createSoundRegistry(banks?: readonly SoundBank[]): SoundRegistry;
-
 /**
  * Rules for a group of voices (`undead_voice`...). A request passes when every rule passes:
  * - `maxConcurrent`: at most this many of the group play at once (`steal` replaces the group's oldest instead of refusing);
@@ -859,7 +520,10 @@ type AudioEngine = {
     plan(id: string, options?: PlayOptions): SoundPlan | null;
     /** Pure: the plan a sample sound would play with (no round-robin memory), from `options.seed` or the engine seed. */
     planSample(id: string, options?: PlayOptions): SamplePlan | null;
-    /** Loads the files of these sample sounds (default all registered). Creates the context; resolves when every file is decoded or failed. */
+    /**
+     * Loads the files of these sample sounds (default all registered). Creates the context; resolves when every file is decoded or failed. An id named
+     * here that has no files yet (its manifest not registered) loads as soon as a bank that resolves it registers.
+     */
     loadSamples(ids?: readonly string[]): Promise<SampleLoadReport>;
     /** `ready` when every file of the sound is decoded. */
     sampleStatus(id: string): SampleStatus;
@@ -1124,6 +788,10 @@ type UserSoundPick = {
     /** 0–10: how well the files fit the sound (rate, clipping, band). */
     readonly score: number;
     readonly loop?: boolean;
+    /** Who made the files, when the pack is not the list's `author`. */
+    readonly author?: string;
+    /** Their licence, when not the list's `license`. */
+    readonly license?: string;
 };
 type UserSoundPicks = {
     readonly version: 1;
@@ -1247,4 +915,4 @@ type AudioBenchText = {
 };
 declare const audioBenchTextOf: (locale: string) => AudioBenchText;
 
-export { type FormantVoiceSource as $, type AudioLoopHandle as A, type BusId as B, CRITERIA as C, CRITERIA_TARGETS as D, type CriterionId as E, type Falloff as F, type CriterionResult as G, type Curve as H, DEFAULT_CROSSOVER as I, DEFAULT_LISTENER as J, DEFAULT_MAX_VOICES as K, type LoopRecipe as L, type MixProfile as M, DEFAULT_MIX as N, DEFAULT_SAMPLE_CUTOFF_K as O, type ParamRef as P, DEFAULT_SAMPLE_FALLOFF as Q, type Range as R, type SampleSound as S, DEFAULT_SAMPLE_PITCH as T, DEFAULT_TAIL_GAIN as U, type DeepPartial as V, type DistanceMode as W, type Envelope as X, type EnvelopePoint as Y, type FilterBank as Z, type FilterSpec as _, type SampleLoader as a, type UserSampleBankOptions as a$, KIT_SAMPLES_BANK as a0, LAYER_FLOOR as a1, type LayerSource as a2, type Listener as a3, type LoadUserSamplesOptions as a4, type LoopOrder as a5, type LoopSet as a6, MIX_PROFILES as a7, type MeasureOptions as a8, type Modulator as a9, type SampleLayerRole as aA, type SampleLoadReport as aB, type SampleMemory as aC, type SampleOptions as aD, type SamplePlanInput as aE, type SampleRef as aF, type SampleStatus as aG, type SampleStore as aH, type SampleTail as aI, type SampleTier as aJ, type SdkLicense as aK, type SfxBlow as aL, type SfxCategory as aM, type SfxEntry as aN, type SfxFileEntry as aO, type SfxLayer as aP, type SfxManifestLike as aQ, type SfxManifestSound as aR, type SfxMaterial as aS, type SfxPriority as aT, type SfxState as aU, type SoundRegistry as aV, type SoundSource as aW, type StartQueueOptions as aX, type Time as aY, USER_SAMPLES_BANK as aZ, USER_SOUND_PREFIX as a_, type NoiseSource as aa, OPEN_CUTOFF as ab, type OscSource as ac, PAN_LIMIT as ad, PAN_MIN_DISTANCE as ae, type PlanInput as af, type PlannedAutomation as ag, type PlannedEnvelopePoint as ah, type PlannedFilter as ai, type PlannedLayer as aj, type PlannedModulator as ak, type PlannedSampleLayer as al, type PlannedSource as am, type PlayOptions as an, SAMPLE_ENVIRONMENTS as ao, SDK_LICENSES as ap, SFX_BLOWS as aq, SFX_CATALOG as ar, SFX_CATEGORIES as as, SFX_IMPACTS as at, SFX_LAYERS as au, SFX_MATERIALS as av, SFX_TIERS as aw, type SampleBankOptions as ax, type SampleCrossover as ay, type SampleEnvironment as az, type SfxManifest as b, type UserSampleBankResult as b0, type UserSfxFile as b1, type UserSfxManifest as b2, type UserSfxSound as b3, type UserSoundPick as b4, type UserSoundPicks as b5, type UserSoundRole as b6, VOICE_GROUPS as b7, type VoiceDecision as b8, type VoiceGroup as b9, pickTake as bA, planSample as bB, planSound as bC, recordOutput as bD, resolveMix as bE, sampleBankFromManifest as bF, sampleCutoff as bG, sampleUrls as bH, sfxState as bI, soundSourceOf as bJ, splitTier as bK, tierFor as bL, userSampleBank as bM, type VoiceHandle as ba, type VoiceManager as bb, type VoiceManagerOptions as bc, type VoiceRefusal as bd, type VoiceRequest as be, type VoiceStartEvent as bf, type VoiceStats as bg, audioBenchTextOf as bh, busGain as bi, busPriority as bj, createAudioEngine as bk, createAudioTestModule as bl, createSampleStore as bm, createSoundRegistry as bn, createVoiceManager as bo, crossGains as bp, farMixAt as bq, fetchLoader as br, impactSoundId as bs, inlineLoader as bt, limiterCurve as bu, listenerDistance as bv, loadUserSamples as bw, measureCriteria as bx, panFor as by, parseSfxName as bz, type SoundBank as c, type SampleDefaults as d, type SoundRecipe as e, type Layer as f, type SoundSet as g, type SoundPlan as h, type SamplePlan as i, type LoopEntry as j, type AudioEngine as k, type ActionCheck as l, type AudioBenchText as m, type AudioChannel as n, type AudioEngineOptions as o, type AudioScenarioLike as p, type AudioStats as q, type AudioTestModule as r, type AudioTestModuleOptions as s, type Automation as t, BENCH_BANK as u, BUILD_ORDERS as v, BUS_IDS as w, BUS_PRIORITY as x, type BuildOrder as y, type BusSetting as z };
+export { SDK_LICENSES as $, type AudioEngine as A, BENCH_BANK as B, CRITERIA as C, type DistanceMode as D, DEFAULT_TAIL_GAIN as E, LAYER_FLOOR as F, type LoadUserSamplesOptions as G, type LoopSet as H, MIX_PROFILES as I, type MeasureOptions as J, KIT_SAMPLES_BANK as K, type LoopEntry as L, type MixProfile as M, PAN_MIN_DISTANCE as N, OPEN_CUTOFF as O, PAN_LIMIT as P, type PlanInput as Q, type PlannedAutomation as R, type SampleLoader as S, type PlannedEnvelopePoint as T, type PlannedFilter as U, type PlannedLayer as V, type PlannedModulator as W, type PlannedSampleLayer as X, type PlannedSource as Y, type PlayOptions as Z, SAMPLE_ENVIRONMENTS as _, type SfxManifest as a, measureCriteria as a$, SFX_BLOWS as a0, SFX_CATALOG as a1, SFX_CATEGORIES as a2, SFX_IMPACTS as a3, SFX_LAYERS as a4, SFX_MATERIALS as a5, SFX_TIERS as a6, type SampleBankOptions as a7, type SampleLayerRole as a8, type SampleLoadReport as a9, type UserSoundPicks as aA, type UserSoundRole as aB, VOICE_GROUPS as aC, type VoiceDecision as aD, type VoiceGroup as aE, type VoiceHandle as aF, type VoiceManager as aG, type VoiceManagerOptions as aH, type VoiceRefusal as aI, type VoiceRequest as aJ, type VoiceStartEvent as aK, type VoiceStats as aL, audioBenchTextOf as aM, busGain as aN, busPriority as aO, createAudioEngine as aP, createAudioTestModule as aQ, createSampleStore as aR, createVoiceManager as aS, crossGains as aT, farMixAt as aU, fetchLoader as aV, impactSoundId as aW, inlineLoader as aX, limiterCurve as aY, listenerDistance as aZ, loadUserSamples as a_, type SampleMemory as aa, type SampleOptions as ab, type SamplePlanInput as ac, type SampleStatus as ad, type SampleStore as ae, type SdkLicense as af, type SfxBlow as ag, type SfxCategory as ah, type SfxEntry as ai, type SfxFileEntry as aj, type SfxLayer as ak, type SfxManifestLike as al, type SfxManifestSound as am, type SfxMaterial as an, type SfxPriority as ao, type SfxState as ap, type SoundSource as aq, type StartQueueOptions as ar, USER_SAMPLES_BANK as as, USER_SOUND_PREFIX as at, type UserSampleBankOptions as au, type UserSampleBankResult as av, type UserSfxFile as aw, type UserSfxManifest as ax, type UserSfxSound as ay, type UserSoundPick as az, type SampleDefaults as b, panFor as b0, parseSfxName as b1, pickTake as b2, planSample as b3, planSound as b4, recordOutput as b5, resolveMix as b6, sampleBankFromManifest as b7, sampleCutoff as b8, sampleUrls as b9, sfxState as ba, soundSourceOf as bb, splitTier as bc, tierFor as bd, userSampleBank as be, type SoundPlan as c, type SamplePlan as d, type AudioLoopHandle as e, type Listener as f, type ActionCheck as g, type AudioBenchText as h, type AudioChannel as i, type AudioEngineOptions as j, type AudioScenarioLike as k, type AudioStats as l, type AudioTestModule as m, type AudioTestModuleOptions as n, BUS_PRIORITY as o, type BusSetting as p, CRITERIA_TARGETS as q, type CriterionId as r, type CriterionResult as s, DEFAULT_CROSSOVER as t, DEFAULT_LISTENER as u, DEFAULT_MAX_VOICES as v, DEFAULT_MIX as w, DEFAULT_SAMPLE_CUTOFF_K as x, DEFAULT_SAMPLE_FALLOFF as y, DEFAULT_SAMPLE_PITCH as z };

package/dist/testing.d.ts

@@ -1,6 +1,7 @@
-import { aL as SfxBlow, aS as SfxMaterial, az as SampleEnvironment, aU as SfxState, E as CriterionId, aW as SoundSource, p as AudioScenarioLike, k as AudioEngine, G as CriterionResult, bf as VoiceStartEvent, ba as VoiceHandle, c as SoundBank, a as SampleLoader, aN as SfxEntry, l as ActionCheck } from './locale-CJfDpWnI.js';
-export { m as AudioBenchText, r as AudioTestModule, s as AudioTestModuleOptions, u as BENCH_BANK, bh as audioBenchTextOf, bl as createAudioTestModule } from './locale-CJfDpWnI.js';
+import { ag as SfxBlow, an as SfxMaterial, ap as SfxState, r as CriterionId, aq as SoundSource, k as AudioScenarioLike, A as AudioEngine, s as CriterionResult, aK as VoiceStartEvent, aF as VoiceHandle, S as SampleLoader, ai as SfxEntry, g as ActionCheck } from './locale-YHyJwN2P.js';
+export { h as AudioBenchText, m as AudioTestModule, n as AudioTestModuleOptions, B as BENCH_BANK, aM as audioBenchTextOf, aQ as createAudioTestModule } from './locale-YHyJwN2P.js';
 import { TestableModule } from '@adatechnology/game-contracts';
+import { q as SampleEnvironment, a as SoundBank } from './bank-Dsj1VAht.js';
 
 type Strength = 'light' | 'medium' | 'heavy';
 type SoundCheckText = {
@@ -15,9 +16,9 @@ type SoundCheckText = {
     readonly strengths: Readonly<Record<Strength, string>>;
     readonly states: Readonly<Record<SfxState, string>>;
     readonly criteria: Readonly<Record<CriterionId, string>>;
-    readonly metrics: Readonly<Record<'source' | 'chosen' | 'matrix' | 'last' | 'ab' | 'blind' | 'verdicts' | 'state' | 'count', string>>;
+    readonly metrics: Readonly<Record<'source' | 'chosen' | 'matrix' | 'last' | 'ab' | 'blind' | 'verdicts' | 'state' | 'count' | 'unlicensed', string>>;
     readonly run: Readonly<Record<'idle' | 'measuring' | 'done' | 'failed' | 'recording' | 'recorded', string>>;
-    readonly words: Readonly<Record<'none' | 'hidden' | 'prefers' | 'approved', string>>;
+    readonly words: Readonly<Record<'none' | 'hidden' | 'prefers' | 'approved' | 'local_file' | 'sdk_file' | 'synth', string>>;
     /** Where the voice came from: the kit's file, the owner's file, the synthesized recipe. */
     readonly sources: Readonly<Record<SoundSource, string>>;
     readonly probe: string;