@bendyline/molen-client 0.0.2 → 0.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -0
- package/dist/assets-Bp0ox8YY.d.mts +59 -0
- package/dist/audio.d.mts +526 -0
- package/dist/audio.mjs +1740 -0
- package/dist/camera-track.d.mts +1 -1
- package/dist/index.d.mts +19 -167
- package/dist/index.mjs +725 -482
- package/dist/input-CD-dHuv0.d.mts +120 -0
- package/dist/input-CfbIm1MS.mjs +361 -0
- package/dist/markers.d.mts +127 -0
- package/dist/markers.mjs +308 -0
- package/dist/navigation.d.mts +529 -0
- package/dist/navigation.mjs +1402 -0
- package/dist/{renderer-B3pd4N-J.d.mts → renderer-DfWc3MFM.d.mts} +111 -5
- package/dist/vehicles.d.mts +14 -2
- package/dist/vehicles.mjs +82 -25
- package/dist/webgpu-driver-Bt2mvZk9.mjs +165 -0
- package/dist/webgpu-sky-reflections-CymGEes-.mjs +22 -0
- package/package.json +17 -4
- package/dist/webgpu-driver-DXsRuz8j.mjs +0 -75
package/README.md
CHANGED
|
@@ -67,6 +67,9 @@ probe — a pinned backend is what makes a captured frame reproducible.
|
|
|
67
67
|
| `./vite` | `molenScripts()` — a Vite plugin that type-strips `*.ts?raw` scene scripts so the browser never sees TypeScript |
|
|
68
68
|
| `./vehicles` | `createVehicleVisual`, `createParkedVehicleBatch`, `vehicleCameraPose` — car visuals and cockpit/chase views, the render half of `@bendyline/molen-kernel/vehicles` |
|
|
69
69
|
| `./aircraft` | `createAircraftVisual`, `aircraftCameraPose` — animated airframe and instrumented cockpit, the render half of `@bendyline/molen-kernel/aircraft` |
|
|
70
|
+
| `./navigation` | `OrbitController`, `FlyController`, `WalkController` + `WalkCollision`, `FollowController`, `NavigationInputSource` (keys, gamepad, pointer gestures) and `createTouchJoystick` — camera navigation for `createViewer` hosts |
|
|
71
|
+
| `./markers` | `createMarkerLayer`, `composeMarkerImage`, `projectWorldToScreen` — screen-sized, ground-snapped, pickable world markers such as photo pins |
|
|
72
|
+
| `./audio` | `createAudioLayer`, `AudioDirector`, `WebAudioBackend`, `loadPackSoundbanks`, `attachAutoplayUnlock` — plays sound banks and a scene's `audioEnvironment`/`audioSource`/`audioZone` rules and `molen.audio.*` events; three-free at runtime, so the director also runs in Node |
|
|
70
73
|
|
|
71
74
|
Renderables are data, not three.js objects: primitives and glTF assets described by a
|
|
72
75
|
`renderable` component, with materials resolved from `palette:`, `matgraph:` and `pixelgrid:`
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import * as THREE from "three";
|
|
2
|
+
import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
|
|
3
|
+
|
|
4
|
+
//#region src/assets.d.ts
|
|
5
|
+
/**
|
|
6
|
+
* Resolves asset refs to bytes. Refs are project asset ids ("crate"); refs containing "/" or
|
|
7
|
+
* starting with "./" / "http(s):" pass through as URLs, so manifest-less demos stay trivial.
|
|
8
|
+
*/
|
|
9
|
+
interface AssetProvider {
|
|
10
|
+
load(ref: string): Promise<ArrayBuffer>;
|
|
11
|
+
loadText(ref: string): Promise<string>;
|
|
12
|
+
}
|
|
13
|
+
interface UrlAssetProviderOptions {
|
|
14
|
+
/**
|
|
15
|
+
* Packed runtime variant to prefer for convention-resolved ids (e.g. "ktx2" from
|
|
16
|
+
* `molen asset pack`): assets/<id>/model.<variant>.glb is tried first and model.glb is the
|
|
17
|
+
* fallback when the variant is not served. Index-mapped and URL-ish refs are used as given.
|
|
18
|
+
*/
|
|
19
|
+
variant?: string;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* URL-backed provider: asset ids resolve through an id -> URL index (from the project manifest's
|
|
23
|
+
* assets record, mapped to served model URLs); URL-ish refs resolve against baseUrl.
|
|
24
|
+
*/
|
|
25
|
+
declare function createUrlAssetProvider(baseUrl: string, index?: Record<string, string>, options?: UrlAssetProviderOptions): AssetProvider;
|
|
26
|
+
interface LoadedGltf {
|
|
27
|
+
scene: THREE.Group;
|
|
28
|
+
clips: THREE.AnimationClip[];
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Parse each glTF ref once; hand out per-entity instances (SkeletonUtils.clone so skinned
|
|
32
|
+
* meshes work while geometry/textures stay shared). `whenIdle()` resolves when no loads are
|
|
33
|
+
* pending — the capture path awaits it before its single deterministic frame.
|
|
34
|
+
*/
|
|
35
|
+
declare class AssetCache {
|
|
36
|
+
private readonly provider;
|
|
37
|
+
/** Owned by the cache: `dispose()` tears down its Draco/KTX2 decoder worker pools. */
|
|
38
|
+
private readonly loader;
|
|
39
|
+
private readonly loads;
|
|
40
|
+
private readonly bases;
|
|
41
|
+
private readonly disposedGeometries;
|
|
42
|
+
private readonly disposedMaterials;
|
|
43
|
+
private pending;
|
|
44
|
+
private idleResolvers;
|
|
45
|
+
private disposed;
|
|
46
|
+
constructor(provider: AssetProvider, loader: GLTFLoader);
|
|
47
|
+
/** Register an external async task (e.g. a material bake) so whenIdle() waits for it. */
|
|
48
|
+
track<T>(p: Promise<T>): Promise<T>;
|
|
49
|
+
private base;
|
|
50
|
+
/** A fresh instance of the (sub-)scene for one entity. */
|
|
51
|
+
instance(ref: string, node?: string): Promise<LoadedGltf>;
|
|
52
|
+
/** Resolves once every load kicked off so far has settled. */
|
|
53
|
+
whenIdle(): Promise<void>;
|
|
54
|
+
clear(): void;
|
|
55
|
+
dispose(): void;
|
|
56
|
+
private disposeLoaded;
|
|
57
|
+
}
|
|
58
|
+
//#endregion
|
|
59
|
+
export { createUrlAssetProvider as a, UrlAssetProviderOptions as i, AssetProvider as n, LoadedGltf as r, AssetCache as t };
|
package/dist/audio.d.mts
ADDED
|
@@ -0,0 +1,526 @@
|
|
|
1
|
+
import { n as AssetProvider } from "./assets-Bp0ox8YY.mjs";
|
|
2
|
+
import { AudioEnvironmentData, AudioScalar, AudioWhen, EngineEvent, EntityId, JsonObject, SoundEntry, SoundbankDoc, WeatherData } from "@bendyline/molen-schema";
|
|
3
|
+
|
|
4
|
+
//#region src/audio/types.d.ts
|
|
5
|
+
type AudioVec3 = [number, number, number];
|
|
6
|
+
/** Where the ears are, in world space (render origin already added back). */
|
|
7
|
+
interface AudioListenerState {
|
|
8
|
+
position: AudioVec3;
|
|
9
|
+
/** Unit look direction. */
|
|
10
|
+
forward: AudioVec3;
|
|
11
|
+
/** Unit up direction. */
|
|
12
|
+
up: AudioVec3;
|
|
13
|
+
/** World velocity (m/s); when absent the director measures it between updates. */
|
|
14
|
+
velocity?: AudioVec3;
|
|
15
|
+
/** Speed (m/s); overrides the measured value. */
|
|
16
|
+
speed?: number;
|
|
17
|
+
/** Host navigation mode: walk, drive, fly, orbit, pilot… (the `listener.mode` signal). */
|
|
18
|
+
mode?: string;
|
|
19
|
+
/** false suppresses footsteps; undefined counts as grounded. */
|
|
20
|
+
grounded?: boolean;
|
|
21
|
+
/** Surface under the listener (grass, concrete, wood…), selects footstep sounds. */
|
|
22
|
+
surface?: string;
|
|
23
|
+
/** true when the listener is inside a building. */
|
|
24
|
+
indoors?: boolean;
|
|
25
|
+
/**
|
|
26
|
+
* Height above the ground under the listener (m); the `listener.heightAboveGround` signal. Hosts
|
|
27
|
+
* with terrain report it so ground-level ambience (birds, traffic) fades as the listener rises.
|
|
28
|
+
*/
|
|
29
|
+
heightAboveGround?: number;
|
|
30
|
+
}
|
|
31
|
+
/** Sky state the director reads (a subset of the client's SkyFrame). */
|
|
32
|
+
interface AudioSkySignals {
|
|
33
|
+
sunDirection?: AudioVec3;
|
|
34
|
+
daylight: number;
|
|
35
|
+
starVisibility?: number;
|
|
36
|
+
}
|
|
37
|
+
/** World-level signals: weather, sky and anything else the host wants to expose as `host.*`. */
|
|
38
|
+
interface AudioEnvironmentSignals {
|
|
39
|
+
weather?: WeatherData;
|
|
40
|
+
sky?: AudioSkySignals;
|
|
41
|
+
host?: Record<string, AudioScalar | undefined>;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* The structural slice of an entity store the director reads. Implemented over a Worker-linked
|
|
45
|
+
* `MolenClient` (`entitySourceFromClient`) and over a main-thread kernel `World`
|
|
46
|
+
* (`entitySourceFromWorld`); a kernel-less viewer passes none.
|
|
47
|
+
*/
|
|
48
|
+
interface AudioEntitySource {
|
|
49
|
+
readonly tick: number | undefined;
|
|
50
|
+
readonly tickRate?: number;
|
|
51
|
+
/** Every entity carrying `component`, with that component's (read-only) data. */
|
|
52
|
+
each(component: string): Iterable<[EntityId, JsonObject]>;
|
|
53
|
+
get(id: EntityId, component: string): JsonObject | undefined;
|
|
54
|
+
/** Subscribe to every engine event; returns an unsubscribe. */
|
|
55
|
+
onEvent?(cb: (event: EngineEvent, tick: number) => void): () => void;
|
|
56
|
+
}
|
|
57
|
+
interface DirectorInput {
|
|
58
|
+
/** Wall-clock milliseconds (performance.now in browsers; simulated time headlessly). */
|
|
59
|
+
nowMs: number;
|
|
60
|
+
listener?: Partial<AudioListenerState>;
|
|
61
|
+
source?: AudioEntitySource;
|
|
62
|
+
signals?: AudioEnvironmentSignals;
|
|
63
|
+
}
|
|
64
|
+
interface VoiceSpatial {
|
|
65
|
+
position: AudioVec3;
|
|
66
|
+
refDistance: number;
|
|
67
|
+
maxDistance: number;
|
|
68
|
+
rolloff: number;
|
|
69
|
+
model: "linear" | "inverse" | "exponential";
|
|
70
|
+
}
|
|
71
|
+
/** The director's output: a diff the backend applies. */
|
|
72
|
+
type VoiceCommand = {
|
|
73
|
+
op: "start";
|
|
74
|
+
voice: string;
|
|
75
|
+
sound: string; /** Asset ref for `AssetProvider.load` (bank base + clip path). */
|
|
76
|
+
ref: string;
|
|
77
|
+
loop: boolean;
|
|
78
|
+
loopStart?: number;
|
|
79
|
+
loopEnd?: number;
|
|
80
|
+
gain: number;
|
|
81
|
+
pitch: number;
|
|
82
|
+
bus: string;
|
|
83
|
+
spatial?: VoiceSpatial;
|
|
84
|
+
fadeInS?: number;
|
|
85
|
+
} | {
|
|
86
|
+
op: "set";
|
|
87
|
+
voice: string;
|
|
88
|
+
gain?: number;
|
|
89
|
+
pitch?: number;
|
|
90
|
+
position?: AudioVec3;
|
|
91
|
+
rampS?: number;
|
|
92
|
+
} | {
|
|
93
|
+
op: "stop";
|
|
94
|
+
voice: string;
|
|
95
|
+
fadeS?: number;
|
|
96
|
+
} | {
|
|
97
|
+
op: "listener";
|
|
98
|
+
position: AudioVec3;
|
|
99
|
+
forward: AudioVec3;
|
|
100
|
+
up: AudioVec3;
|
|
101
|
+
} | {
|
|
102
|
+
op: "bus";
|
|
103
|
+
bus: string;
|
|
104
|
+
gain: number;
|
|
105
|
+
};
|
|
106
|
+
interface AudioBackendStats {
|
|
107
|
+
voices: number;
|
|
108
|
+
decoded: number;
|
|
109
|
+
pending: number;
|
|
110
|
+
state: "running" | "suspended" | "closed" | "headless";
|
|
111
|
+
}
|
|
112
|
+
/** Realizes voice commands. `WebAudioBackend` plays them; `createRecordingBackend` logs them. */
|
|
113
|
+
interface AudioBackend {
|
|
114
|
+
apply(commands: readonly VoiceCommand[]): void;
|
|
115
|
+
/** Resume audio output; browsers require a user gesture first. */
|
|
116
|
+
unlock(): Promise<void>;
|
|
117
|
+
readonly unlocked: boolean;
|
|
118
|
+
/** Pause/resume output without losing voices (page hidden, game paused). */
|
|
119
|
+
setSuspended?(suspended: boolean): void;
|
|
120
|
+
/** Decode clips ahead of first use. */
|
|
121
|
+
preload?(refs: readonly string[]): Promise<void>;
|
|
122
|
+
stats(): AudioBackendStats;
|
|
123
|
+
dispose(): void;
|
|
124
|
+
}
|
|
125
|
+
//#endregion
|
|
126
|
+
//#region src/audio/adapters.d.ts
|
|
127
|
+
/** The slice of a Worker-linked `MolenClient` the audio layer reads. */
|
|
128
|
+
interface AudioClientLike {
|
|
129
|
+
readonly tick: number | undefined;
|
|
130
|
+
entities(): EntityId[];
|
|
131
|
+
get(id: EntityId, component: string): JsonObject | undefined;
|
|
132
|
+
onEvent(type: string, cb: (event: EngineEvent, tick: number) => void): () => void;
|
|
133
|
+
}
|
|
134
|
+
/**
|
|
135
|
+
* Entity source over a kernel-linked client. Reads are memoized per mirrored tick, because
|
|
136
|
+
* `client.get` returns a detached copy and the mirror only changes when a new tick arrives.
|
|
137
|
+
*/
|
|
138
|
+
declare function entitySourceFromClient(client: AudioClientLike, opts?: {
|
|
139
|
+
tickRate?: number;
|
|
140
|
+
}): AudioEntitySource;
|
|
141
|
+
/** The slice of a main-thread kernel `World` the audio layer reads (structural, no import). */
|
|
142
|
+
interface AudioWorldLike {
|
|
143
|
+
readonly tick: number;
|
|
144
|
+
readonly tickRate: number;
|
|
145
|
+
query(component: {
|
|
146
|
+
readonly name: string;
|
|
147
|
+
}): Iterable<[EntityId, ...JsonObject[]]>;
|
|
148
|
+
get(id: EntityId, component: {
|
|
149
|
+
readonly name: string;
|
|
150
|
+
}): unknown;
|
|
151
|
+
on(type: string, handler: (event: EngineEvent, ctx: {
|
|
152
|
+
tick: number;
|
|
153
|
+
}) => void): () => void;
|
|
154
|
+
}
|
|
155
|
+
/** Entity source over a main-thread `World` (EarthVehicles, headless tooling). */
|
|
156
|
+
declare function entitySourceFromWorld(world: AudioWorldLike): AudioEntitySource;
|
|
157
|
+
//#endregion
|
|
158
|
+
//#region src/audio/bank.d.ts
|
|
159
|
+
/** A bank document plus where its clip paths resolve (e.g. `pack:molen.sounds/`, `sounds/`). */
|
|
160
|
+
interface SoundbankInput {
|
|
161
|
+
doc: SoundbankDoc;
|
|
162
|
+
/** Prefix joined to every clip path; default none (clips are provider refs as written). */
|
|
163
|
+
base?: string;
|
|
164
|
+
}
|
|
165
|
+
interface ResolvedSound {
|
|
166
|
+
id: string;
|
|
167
|
+
entry: SoundEntry;
|
|
168
|
+
/** Clip refs ready for `AssetProvider.load`. */
|
|
169
|
+
refs: readonly string[];
|
|
170
|
+
/** Id of the bank that supplied this sound (later banks override earlier ones). */
|
|
171
|
+
bank: string;
|
|
172
|
+
}
|
|
173
|
+
interface SoundBank {
|
|
174
|
+
resolve(id: string): ResolvedSound | undefined;
|
|
175
|
+
ids(): readonly string[];
|
|
176
|
+
}
|
|
177
|
+
/** Merge banks; a later bank's sound replaces an earlier one with the same id (reskinning). */
|
|
178
|
+
declare function mergeSoundbanks(inputs: readonly (SoundbankDoc | SoundbankInput)[]): SoundBank;
|
|
179
|
+
/** 32-bit string/number hash (FNV-1a + fmix32); deterministic across hosts. */
|
|
180
|
+
declare function hash32(...parts: (string | number)[]): number;
|
|
181
|
+
/** Deterministic [0, 1) from any key parts. */
|
|
182
|
+
declare function unitRandom(...parts: (string | number)[]): number;
|
|
183
|
+
//#endregion
|
|
184
|
+
//#region src/audio/director.d.ts
|
|
185
|
+
interface AudioDirectorOptions {
|
|
186
|
+
bank: SoundBank;
|
|
187
|
+
/** Host soundscape rules; a scene's audioEnvironment entity overrides these key by key. */
|
|
188
|
+
environment?: AudioEnvironmentData;
|
|
189
|
+
/** Concurrent one-shot budget; the oldest is cut when exceeded. Default 16. */
|
|
190
|
+
maxOneShots?: number;
|
|
191
|
+
/** Seed mixed into clip/pitch variation. */
|
|
192
|
+
seed?: string | number;
|
|
193
|
+
/** Called once per distinct warning (unknown sound ids, unknown signals). */
|
|
194
|
+
onWarning?: (message: string) => void;
|
|
195
|
+
}
|
|
196
|
+
/** A persistent voice the director is keeping alive. */
|
|
197
|
+
interface VoiceSnapshot {
|
|
198
|
+
key: string;
|
|
199
|
+
voice: string;
|
|
200
|
+
sound: string;
|
|
201
|
+
bus: string;
|
|
202
|
+
gain: number;
|
|
203
|
+
pitch: number;
|
|
204
|
+
loop: boolean;
|
|
205
|
+
position?: AudioVec3;
|
|
206
|
+
entity?: EntityId;
|
|
207
|
+
}
|
|
208
|
+
declare class AudioDirector {
|
|
209
|
+
private bank;
|
|
210
|
+
private hostEnvironment;
|
|
211
|
+
private readonly maxOneShots;
|
|
212
|
+
private readonly seed;
|
|
213
|
+
private readonly onWarning;
|
|
214
|
+
private readonly live;
|
|
215
|
+
private readonly oneShots;
|
|
216
|
+
private readonly scriptLoops;
|
|
217
|
+
private readonly stopFades;
|
|
218
|
+
private readonly gates;
|
|
219
|
+
private readonly motion;
|
|
220
|
+
private readonly firedOnce;
|
|
221
|
+
private readonly startTickFired;
|
|
222
|
+
private readonly triggers;
|
|
223
|
+
private readonly lastFire;
|
|
224
|
+
private readonly lastClip;
|
|
225
|
+
private readonly busGains;
|
|
226
|
+
private readonly events;
|
|
227
|
+
private readonly warned;
|
|
228
|
+
private readonly warningList;
|
|
229
|
+
private readonly checked;
|
|
230
|
+
private musicState;
|
|
231
|
+
private musicOverride;
|
|
232
|
+
private listenerState;
|
|
233
|
+
private footAcc;
|
|
234
|
+
private footLast;
|
|
235
|
+
private startMs;
|
|
236
|
+
private lastNow;
|
|
237
|
+
private frame;
|
|
238
|
+
private serial;
|
|
239
|
+
private hostHandles;
|
|
240
|
+
constructor(opts: AudioDirectorOptions);
|
|
241
|
+
setBank(bank: SoundBank): void;
|
|
242
|
+
setEnvironment(environment: AudioEnvironmentData | undefined): void;
|
|
243
|
+
/** Queue an engine event (`audio.play|stop|music` or a type mapped under `events`). */
|
|
244
|
+
handleEvent(event: EngineEvent, tick?: number): void;
|
|
245
|
+
/** Host-side one-shot or loop (UI clicks, host-owned engines). Returns a handle for `stop`. */
|
|
246
|
+
play(sound: string, opts?: {
|
|
247
|
+
entity?: EntityId;
|
|
248
|
+
position?: AudioVec3;
|
|
249
|
+
gain?: number;
|
|
250
|
+
pitch?: number;
|
|
251
|
+
bus?: string;
|
|
252
|
+
loop?: boolean;
|
|
253
|
+
}): string;
|
|
254
|
+
stop(target: string | {
|
|
255
|
+
entity?: EntityId;
|
|
256
|
+
sound?: string;
|
|
257
|
+
}, fadeS?: number): void;
|
|
258
|
+
music(playlist: string | string[] | null, opts?: {
|
|
259
|
+
crossfadeS?: number;
|
|
260
|
+
}): void;
|
|
261
|
+
/** Persistent voices currently alive (loops, ambience, zones, music). */
|
|
262
|
+
voices(): VoiceSnapshot[];
|
|
263
|
+
warnings(): readonly string[];
|
|
264
|
+
/** Stop everything (fading) and forget all state except warnings. */
|
|
265
|
+
reset(fadeS?: number): VoiceCommand[];
|
|
266
|
+
update(input: DirectorInput): VoiceCommand[];
|
|
267
|
+
private measureListener;
|
|
268
|
+
private measureEntities;
|
|
269
|
+
private environmentFor;
|
|
270
|
+
private entityPos;
|
|
271
|
+
private warn;
|
|
272
|
+
private sound;
|
|
273
|
+
private checkSignals;
|
|
274
|
+
private gate;
|
|
275
|
+
/** A drive's value: the product of its bindings' curves (1 when there is none). */
|
|
276
|
+
private bound;
|
|
277
|
+
/** The smoothing time of the first binding that sets one. */
|
|
278
|
+
private smoothing;
|
|
279
|
+
private spatialFor;
|
|
280
|
+
private pickClip;
|
|
281
|
+
private basePitch;
|
|
282
|
+
private fireOneShot;
|
|
283
|
+
private pruneOneShots;
|
|
284
|
+
private syncBuses;
|
|
285
|
+
private collectAmbience;
|
|
286
|
+
private collectZones;
|
|
287
|
+
private collectSources;
|
|
288
|
+
private collectScriptLoops;
|
|
289
|
+
private resolveAt;
|
|
290
|
+
private processEvents;
|
|
291
|
+
private footsteps;
|
|
292
|
+
private updateMusic;
|
|
293
|
+
private reconcile;
|
|
294
|
+
}
|
|
295
|
+
//#endregion
|
|
296
|
+
//#region src/audio/listener.d.ts
|
|
297
|
+
/** Anything with a three.js-style world matrix (column-major 4×4 `elements`). */
|
|
298
|
+
interface AudioCameraLike {
|
|
299
|
+
readonly matrixWorld: {
|
|
300
|
+
readonly elements: ArrayLike<number>;
|
|
301
|
+
};
|
|
302
|
+
}
|
|
303
|
+
/**
|
|
304
|
+
* Listener pose from a render camera. The renderer keeps the camera near the origin (floating
|
|
305
|
+
* origin); pass `renderer.getWorldOrigin()` so the listener sits in the same world space as
|
|
306
|
+
* entity transforms. Reads the matrix only, so it needs no three.js import.
|
|
307
|
+
*/
|
|
308
|
+
declare function listenerFromCamera(camera: AudioCameraLike, worldOrigin?: ArrayLike<number>): Pick<AudioListenerState, "position" | "forward" | "up">;
|
|
309
|
+
//#endregion
|
|
310
|
+
//#region src/audio/layer.d.ts
|
|
311
|
+
/** The renderer slice the layer reads: camera pose, world origin, sky and weather state. */
|
|
312
|
+
interface AudioRendererLike {
|
|
313
|
+
readonly camera: AudioCameraLike;
|
|
314
|
+
getWorldOrigin(): ArrayLike<number>;
|
|
315
|
+
readonly sky?: {
|
|
316
|
+
readonly frame?: AudioSkySignals;
|
|
317
|
+
} | undefined;
|
|
318
|
+
readonly weather?: {
|
|
319
|
+
readonly data?: WeatherData;
|
|
320
|
+
} | undefined;
|
|
321
|
+
}
|
|
322
|
+
interface AudioLayerOptions {
|
|
323
|
+
/** Sound banks, earliest first; later banks override sounds with the same id. */
|
|
324
|
+
banks: readonly (SoundbankDoc | SoundbankInput)[];
|
|
325
|
+
/** Loads clip bytes; required for the default Web Audio backend. */
|
|
326
|
+
provider?: AssetProvider;
|
|
327
|
+
/** Default: Web Audio when available (and a provider is given), else a silent recorder. */
|
|
328
|
+
backend?: AudioBackend;
|
|
329
|
+
/** Host soundscape rules; a scene's audioEnvironment entity overrides them key by key. */
|
|
330
|
+
environment?: AudioEnvironmentData;
|
|
331
|
+
/** Listener from this camera and sky/weather signals from this renderer, when given. */
|
|
332
|
+
renderer?: AudioRendererLike;
|
|
333
|
+
/** Extra signals merged over the renderer's each update (e.g. `host.landcover`). */
|
|
334
|
+
signals?: () => AudioEnvironmentSignals | undefined;
|
|
335
|
+
/** Master volume 0–1 (default 1) and mute. */
|
|
336
|
+
volume?: number;
|
|
337
|
+
muted?: boolean;
|
|
338
|
+
/** Suspend output while the page is hidden; default true. */
|
|
339
|
+
suspendWhenHidden?: boolean;
|
|
340
|
+
maxOneShots?: number;
|
|
341
|
+
seed?: string | number;
|
|
342
|
+
onWarning?: (message: string) => void;
|
|
343
|
+
}
|
|
344
|
+
interface AudioLayerStats {
|
|
345
|
+
voices: number;
|
|
346
|
+
warnings: number;
|
|
347
|
+
backend: AudioBackendStats;
|
|
348
|
+
}
|
|
349
|
+
interface AudioLayer {
|
|
350
|
+
readonly director: AudioDirector;
|
|
351
|
+
readonly backend: AudioBackend;
|
|
352
|
+
readonly volume: number;
|
|
353
|
+
readonly muted: boolean;
|
|
354
|
+
readonly unlocked: boolean;
|
|
355
|
+
/** Advance one frame: resolve rules against the listener and signals, then play the diff. */
|
|
356
|
+
update(nowMs: number, listener?: Partial<AudioListenerState>, signals?: AudioEnvironmentSignals): void;
|
|
357
|
+
/** Read entities and events from a Worker-linked client (game samples). */
|
|
358
|
+
attachClient(client: AudioClientLike, opts?: {
|
|
359
|
+
tickRate?: number;
|
|
360
|
+
}): () => void;
|
|
361
|
+
/** Read entities and events from a main-thread kernel World (vehicles, aircraft). */
|
|
362
|
+
attachWorld(world: AudioWorldLike): () => void;
|
|
363
|
+
/** Plug in any entity source; undefined detaches. */
|
|
364
|
+
setSource(source: AudioEntitySource | undefined): void;
|
|
365
|
+
play(sound: string, opts?: {
|
|
366
|
+
entity?: EntityId;
|
|
367
|
+
position?: AudioVec3;
|
|
368
|
+
gain?: number;
|
|
369
|
+
pitch?: number;
|
|
370
|
+
bus?: string;
|
|
371
|
+
loop?: boolean;
|
|
372
|
+
}): string;
|
|
373
|
+
stop(target: string | {
|
|
374
|
+
entity?: EntityId;
|
|
375
|
+
sound?: string;
|
|
376
|
+
}, fadeS?: number): void;
|
|
377
|
+
music(playlist: string | string[] | null, opts?: {
|
|
378
|
+
crossfadeS?: number;
|
|
379
|
+
}): void;
|
|
380
|
+
setVolume(volume: number): void;
|
|
381
|
+
setMuted(muted: boolean): void;
|
|
382
|
+
/** Host-side bus trim, multiplied with the environment's bus gain. */
|
|
383
|
+
setBusGain(bus: string, gain: number): void;
|
|
384
|
+
setEnvironment(environment: AudioEnvironmentData | undefined): void;
|
|
385
|
+
setBanks(banks: readonly (SoundbankDoc | SoundbankInput)[]): void;
|
|
386
|
+
unlock(): Promise<void>;
|
|
387
|
+
setSuspended(suspended: boolean): void;
|
|
388
|
+
stats(): AudioLayerStats;
|
|
389
|
+
dispose(): void;
|
|
390
|
+
}
|
|
391
|
+
/**
|
|
392
|
+
* The audio layer a host creates once and updates each frame. It owns the director (rules) and
|
|
393
|
+
* the backend (playback). Kernel-less viewers call `update` with listener state only; kernel hosts
|
|
394
|
+
* also `attachClient` or `attachWorld` so entity components and events reach the director.
|
|
395
|
+
*/
|
|
396
|
+
declare function createAudioLayer(opts: AudioLayerOptions): AudioLayer;
|
|
397
|
+
//#endregion
|
|
398
|
+
//#region src/audio/packs.d.ts
|
|
399
|
+
/** The slice of a `@bendyline/molen-pack` PackSet this needs (structural: no pack dependency). */
|
|
400
|
+
interface AudioPackSetLike {
|
|
401
|
+
provided(role: string): {
|
|
402
|
+
pack: {
|
|
403
|
+
readonly manifest: {
|
|
404
|
+
readonly id: string;
|
|
405
|
+
};
|
|
406
|
+
};
|
|
407
|
+
path: string;
|
|
408
|
+
}[];
|
|
409
|
+
readJson<T = unknown>(ref: string): Promise<T>;
|
|
410
|
+
}
|
|
411
|
+
/**
|
|
412
|
+
* Every `provides.soundbank` document in a pack set, validated, with clip refs rooted in its pack
|
|
413
|
+
* (`pack:<id>/<dir>/`), ready for `createAudioLayer({ banks, provider: set.assetProvider() })`.
|
|
414
|
+
* Invalid banks are reported through `onWarning` and skipped.
|
|
415
|
+
*/
|
|
416
|
+
declare function loadPackSoundbanks(set: AudioPackSetLike, onWarning?: (message: string) => void): Promise<SoundbankInput[]>;
|
|
417
|
+
//#endregion
|
|
418
|
+
//#region src/audio/recording-backend.d.ts
|
|
419
|
+
type StartCommand = Extract<VoiceCommand, {
|
|
420
|
+
op: "start";
|
|
421
|
+
}>;
|
|
422
|
+
interface RecordingBackend extends AudioBackend {
|
|
423
|
+
/** Every command applied, in order. */
|
|
424
|
+
readonly log: VoiceCommand[];
|
|
425
|
+
/** Looping voices currently started and not stopped. */
|
|
426
|
+
readonly active: ReadonlyMap<string, StartCommand>;
|
|
427
|
+
clear(): void;
|
|
428
|
+
}
|
|
429
|
+
/** A silent backend that records commands: tests, headless planning, and hosts without audio. */
|
|
430
|
+
declare function createRecordingBackend(opts?: {
|
|
431
|
+
unlocked?: boolean;
|
|
432
|
+
}): RecordingBackend;
|
|
433
|
+
//#endregion
|
|
434
|
+
//#region src/audio/signals.d.ts
|
|
435
|
+
type SignalValue = AudioScalar | undefined;
|
|
436
|
+
/** Per-entity motion the director measures from transforms (the `self.*` signals). */
|
|
437
|
+
interface EntityMotion {
|
|
438
|
+
pos: [number, number, number];
|
|
439
|
+
speed: number;
|
|
440
|
+
distance: number;
|
|
441
|
+
}
|
|
442
|
+
interface SignalContext {
|
|
443
|
+
listener: AudioListenerState & {
|
|
444
|
+
speed: number;
|
|
445
|
+
distance: number;
|
|
446
|
+
};
|
|
447
|
+
signals: AudioEnvironmentSignals;
|
|
448
|
+
source: AudioEntitySource | undefined;
|
|
449
|
+
/** The entity `<component>.<field>` and `self.*` paths resolve on. */
|
|
450
|
+
entity: EntityId | undefined;
|
|
451
|
+
motion: ReadonlyMap<EntityId, EntityMotion>;
|
|
452
|
+
/** Entities someone is mounted in (a `mounted` component names them): `self.occupied`. */
|
|
453
|
+
occupied: ReadonlySet<EntityId>;
|
|
454
|
+
seconds: number;
|
|
455
|
+
}
|
|
456
|
+
/** Resolve a signal path to a scalar, or undefined when it has no value here. */
|
|
457
|
+
declare function resolveSignal(path: string, ctx: SignalContext): SignalValue;
|
|
458
|
+
/** Every condition must hold (AND). `active` widens numeric ranges (hysteresis). */
|
|
459
|
+
declare function evalWhen(when: AudioWhen | undefined, ctx: SignalContext, active?: boolean): boolean;
|
|
460
|
+
/** Piecewise-linear lookup over [input, output] points, clamped at both ends. */
|
|
461
|
+
declare function curve(points: readonly (readonly [number, number])[], x: number): number;
|
|
462
|
+
/** Rising/falling edge gate: a rule turns on after `enterMs` true and off after `exitMs` false. */
|
|
463
|
+
declare class Gate {
|
|
464
|
+
private readonly enterMs;
|
|
465
|
+
private readonly exitMs;
|
|
466
|
+
active: boolean;
|
|
467
|
+
private started;
|
|
468
|
+
private since;
|
|
469
|
+
constructor(enterMs?: number, exitMs?: number);
|
|
470
|
+
update(raw: boolean, nowMs: number): boolean;
|
|
471
|
+
}
|
|
472
|
+
//#endregion
|
|
473
|
+
//#region src/audio/unlock.d.ts
|
|
474
|
+
/** Something that needs a user gesture before it can make sound. */
|
|
475
|
+
interface Unlockable {
|
|
476
|
+
unlock(): Promise<void>;
|
|
477
|
+
readonly unlocked: boolean;
|
|
478
|
+
}
|
|
479
|
+
/**
|
|
480
|
+
* Browsers start audio suspended until the page gets a gesture. Resume on the first pointer,
|
|
481
|
+
* key or touch on `target` (default the window); returns a detach function.
|
|
482
|
+
*/
|
|
483
|
+
declare function attachAutoplayUnlock(audio: Unlockable, target?: EventTarget | undefined): () => void;
|
|
484
|
+
//#endregion
|
|
485
|
+
//#region src/audio/web-audio-backend.d.ts
|
|
486
|
+
interface WebAudioBackendOptions {
|
|
487
|
+
/** Loads clip bytes by ref (a pack set's `assetProvider()`, or `createUrlAssetProvider`). */
|
|
488
|
+
provider: AssetProvider;
|
|
489
|
+
/** Supply a context (tests, shared graphs); default a new interactive AudioContext. */
|
|
490
|
+
context?: AudioContext;
|
|
491
|
+
/** Drop a one-shot whose clip is still decoding this many seconds after it was requested. */
|
|
492
|
+
staleOneShotS?: number;
|
|
493
|
+
onError?: (message: string) => void;
|
|
494
|
+
}
|
|
495
|
+
/** Plays director commands through Web Audio: buses, panners, looped buffers, fades. */
|
|
496
|
+
declare class WebAudioBackend implements AudioBackend {
|
|
497
|
+
readonly context: AudioContext;
|
|
498
|
+
private readonly provider;
|
|
499
|
+
private readonly staleS;
|
|
500
|
+
private readonly onError;
|
|
501
|
+
private readonly master;
|
|
502
|
+
private readonly buses;
|
|
503
|
+
private readonly buffers;
|
|
504
|
+
private readonly voices;
|
|
505
|
+
private decoded;
|
|
506
|
+
private pending;
|
|
507
|
+
private hostSuspended;
|
|
508
|
+
private disposed;
|
|
509
|
+
constructor(opts: WebAudioBackendOptions);
|
|
510
|
+
get unlocked(): boolean;
|
|
511
|
+
unlock(): Promise<void>;
|
|
512
|
+
setSuspended(suspended: boolean): void;
|
|
513
|
+
preload(refs: readonly string[]): Promise<void>;
|
|
514
|
+
stats(): AudioBackendStats;
|
|
515
|
+
apply(commands: readonly VoiceCommand[]): void;
|
|
516
|
+
dispose(): void;
|
|
517
|
+
private bus;
|
|
518
|
+
private load;
|
|
519
|
+
private start;
|
|
520
|
+
private set;
|
|
521
|
+
private stop;
|
|
522
|
+
private cleanup;
|
|
523
|
+
private setListener;
|
|
524
|
+
}
|
|
525
|
+
//#endregion
|
|
526
|
+
export { type AudioBackend, type AudioBackendStats, type AudioCameraLike, type AudioClientLike, AudioDirector, type AudioDirectorOptions, type AudioEntitySource, type AudioEnvironmentSignals, type AudioLayer, type AudioLayerOptions, type AudioLayerStats, type AudioListenerState, type AudioPackSetLike, type AudioRendererLike, type AudioSkySignals, type AudioVec3, type AudioWorldLike, type DirectorInput, type EntityMotion, Gate, type RecordingBackend, type ResolvedSound, type SignalContext, type SignalValue, type SoundBank, type SoundbankInput, type Unlockable, type VoiceCommand, type VoiceSnapshot, type VoiceSpatial, WebAudioBackend, type WebAudioBackendOptions, attachAutoplayUnlock, createAudioLayer, createRecordingBackend, curve, entitySourceFromClient, entitySourceFromWorld, evalWhen, hash32, listenerFromCamera, loadPackSoundbanks, mergeSoundbanks, resolveSignal, unitRandom };
|