@bendyline/molen-client 0.0.1
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/LICENSE +21 -0
- package/NOTICE.md +11 -0
- package/README.md +95 -0
- package/dist/aircraft.d.mts +23 -0
- package/dist/aircraft.mjs +99 -0
- package/dist/camera-track.d.mts +20 -0
- package/dist/camera-track.mjs +102 -0
- package/dist/index.d.mts +1000 -0
- package/dist/index.mjs +4579 -0
- package/dist/math-ev_jEkRe.mjs +42 -0
- package/dist/model-signals-DVlLyP-w.d.mts +17 -0
- package/dist/model-signals-Gw1COJfo.mjs +53 -0
- package/dist/renderer-B3pd4N-J.d.mts +446 -0
- package/dist/vehicle-interior-0o-8QV_-.d.mts +31 -0
- package/dist/vehicle-interior-DZT0HmWC.mjs +12 -0
- package/dist/vehicles.d.mts +17 -0
- package/dist/vehicles.mjs +174 -0
- package/dist/vite.d.mts +24 -0
- package/dist/vite.mjs +57 -0
- package/dist/webgpu-driver-DXsRuz8j.mjs +75 -0
- package/dist/webgpu-frame-timer-Xnuq1Hld.mjs +97 -0
- package/dist/webgpu-scene-optimizer-D6e9ZJQM.mjs +319 -0
- package/package.json +85 -0
package/dist/index.d.mts
ADDED
|
@@ -0,0 +1,1000 @@
|
|
|
1
|
+
import { i as readModelSignals, n as ModelSignals, r as createModelSignalVisual, t as ModelSignalVisual } from "./model-signals-DVlLyP-w.mjs";
|
|
2
|
+
import { C as skyTimeMs, D as FrameAdmissionOptions, E as AdmissionSample, O as FrameAdmissionQueue, S as evaluateEarthSky, T as AdmissionOptions, _ as SkyVisual, a as RendererBackendPreference, b as CelestialPosition, c as TopDownOrtho, d as GpuFrameTimer, f as GpuFrameTimerOptions, g as SkyStar, h as SkyFrame, i as RendererBackend, k as SceneAdmission, l as nextWorldOrigin, m as WeatherVisual, n as CameraPose, o as RendererOptions, p as createGpuFrameTimer, r as Renderer, s as ThreeRenderer, t as AutoWorldOriginOptions, u as orthoFrustum, v as SkyVisualOptions, w as starDirection, x as EarthSkyState, y as defaultSkyPalette } from "./renderer-B3pd4N-J.mjs";
|
|
3
|
+
import { Command, ControlAction, CustomSkyData, Delta, DiagMessage, EarthObserver, EarthSkyData, EngineEvent, EntityId, GamepadAxisBinding, InputProfile, JsonObject, JsonValue, Keyframe, MessageLink, ModelSignalSpec, Quat, ResolvedWeather, SceneCamera, SceneInput, SceneManifest, SkyAppearance, SkyBodyData, SkyData, SkyData as SkyData$1, SkyPalette, SkyTime, Vec3, WeatherData, WeatherProfile, resolveWeather, weatherProfile } from "@bendyline/molen-schema";
|
|
4
|
+
import * as THREE from "three";
|
|
5
|
+
import { Intersection, Object3D } from "three";
|
|
6
|
+
import { BakedMaterial, MaterialBaker } from "@bendyline/molen-materials";
|
|
7
|
+
import { GLTFLoader, GLTFLoader as GLTFLoader$1 } from "three/addons/loaders/GLTFLoader.js";
|
|
8
|
+
import { WebGPURenderer } from "three/webgpu";
|
|
9
|
+
|
|
10
|
+
//#region src/adaptive-quality.d.ts
|
|
11
|
+
interface AdaptiveQualityOptions {
|
|
12
|
+
/** Integer detail levels increase with quality. The host maps them to its own budgets. */
|
|
13
|
+
minLevel?: number;
|
|
14
|
+
maxLevel?: number;
|
|
15
|
+
initialLevel?: number;
|
|
16
|
+
targetFrameMs?: number;
|
|
17
|
+
/** Measurements are evaluated in windows; frame samples alone never change quality. */
|
|
18
|
+
evaluationIntervalMs?: number;
|
|
19
|
+
warmupMs?: number;
|
|
20
|
+
/** Sustained overload before stepping down; memory pressure bypasses this delay. */
|
|
21
|
+
decreaseDelayMs?: number;
|
|
22
|
+
/** Stable headroom before probing one higher level. Failed probes increase this delay. */
|
|
23
|
+
increaseDelayMs?: number;
|
|
24
|
+
cooldownMs?: number;
|
|
25
|
+
/** An isolated longer interval is treated as a pause; repeated ones remain overload. */
|
|
26
|
+
pauseFrameMs?: number;
|
|
27
|
+
}
|
|
28
|
+
interface AdaptiveQualitySample {
|
|
29
|
+
/** False while hidden, suspended, or deliberately not rendering. Resets measurement history. */
|
|
30
|
+
active?: boolean;
|
|
31
|
+
/** Loading may lower detail under sustained overload, but never authorizes an upgrade. */
|
|
32
|
+
loading?: boolean;
|
|
33
|
+
/** Optional measured work, excluding waiting for the next animation frame. */
|
|
34
|
+
cpuFrameMs?: number;
|
|
35
|
+
/** Supply only a completed, valid asynchronous GPU timing query. */
|
|
36
|
+
gpuFrameMs?: number;
|
|
37
|
+
/** Estimated resident working set / memory budget. Values above one lower detail. */
|
|
38
|
+
memoryPressure?: number;
|
|
39
|
+
}
|
|
40
|
+
type AdaptiveQualityReason = "frame-time" | "memory-pressure" | "headroom" | "manual";
|
|
41
|
+
interface AdaptiveQualityChange {
|
|
42
|
+
previousLevel: number;
|
|
43
|
+
level: number;
|
|
44
|
+
reason: AdaptiveQualityReason;
|
|
45
|
+
}
|
|
46
|
+
interface AdaptiveQualityStats {
|
|
47
|
+
level: number;
|
|
48
|
+
targetFrameMs: number;
|
|
49
|
+
/** Exponentially smoothed, trimmed frame time; undefined before the first complete window. */
|
|
50
|
+
smoothedFrameMs: number | undefined;
|
|
51
|
+
p90FrameMs: number | undefined;
|
|
52
|
+
slowFrameRatio: number;
|
|
53
|
+
/** Valid samples in the most recently completed measurement window. */
|
|
54
|
+
samples: number;
|
|
55
|
+
changes: number;
|
|
56
|
+
recoveryDelayMs: number;
|
|
57
|
+
reason: AdaptiveQualityReason | undefined;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Rendering-only feedback controller; does not change simulation state or depend on a browser.
|
|
61
|
+
* Lower quickly, recover slowly, and probe with backoff instead of oscillating between tiers.
|
|
62
|
+
* Hosts should apply a change atomically to resolution, screen-space error, and residency.
|
|
63
|
+
*/
|
|
64
|
+
declare class AdaptiveQualityController {
|
|
65
|
+
private minLevel;
|
|
66
|
+
private maxLevel;
|
|
67
|
+
private level;
|
|
68
|
+
private readonly targetFrameMs;
|
|
69
|
+
private readonly evaluationIntervalMs;
|
|
70
|
+
private readonly warmupMs;
|
|
71
|
+
private readonly decreaseDelayMs;
|
|
72
|
+
private readonly increaseDelayMs;
|
|
73
|
+
private readonly cooldownMs;
|
|
74
|
+
private readonly pauseFrameMs;
|
|
75
|
+
private readonly frames;
|
|
76
|
+
private frameCursor;
|
|
77
|
+
private clockMs;
|
|
78
|
+
private windowMs;
|
|
79
|
+
private warmupElapsedMs;
|
|
80
|
+
private lastChangeMs;
|
|
81
|
+
private overloadMs;
|
|
82
|
+
private headroomMs;
|
|
83
|
+
private loading;
|
|
84
|
+
private cpuTotalMs;
|
|
85
|
+
private cpuSamples;
|
|
86
|
+
private gpuTotalMs;
|
|
87
|
+
private gpuSamples;
|
|
88
|
+
private memoryTotal;
|
|
89
|
+
private memorySamples;
|
|
90
|
+
private previousPause;
|
|
91
|
+
private smoothedFrameMs;
|
|
92
|
+
private p90FrameMs;
|
|
93
|
+
private slowFrameRatio;
|
|
94
|
+
private samples;
|
|
95
|
+
private changes;
|
|
96
|
+
private reason;
|
|
97
|
+
private recoveryMultiplier;
|
|
98
|
+
private lastUpgradeMs;
|
|
99
|
+
constructor(options?: AdaptiveQualityOptions);
|
|
100
|
+
/** No allocation in the usual per-frame path. A change object is returned only on a step. */
|
|
101
|
+
sample(frameMs: number, sample?: AdaptiveQualitySample): AdaptiveQualityChange | undefined;
|
|
102
|
+
getStats(): AdaptiveQualityStats;
|
|
103
|
+
/** Set a manual tier or restart automatic adaptation without carrying stale timing samples. */
|
|
104
|
+
setLevel(level: number): AdaptiveQualityChange | undefined;
|
|
105
|
+
/** Change a user/device ceiling and floor; an out-of-bounds current level is clamped. */
|
|
106
|
+
setBounds(minLevel: number, maxLevel: number): AdaptiveQualityChange | undefined;
|
|
107
|
+
private evaluate;
|
|
108
|
+
private change;
|
|
109
|
+
private resetWindow;
|
|
110
|
+
private resetMeasurements;
|
|
111
|
+
}
|
|
112
|
+
//#endregion
|
|
113
|
+
//#region src/assets.d.ts
|
|
114
|
+
/**
|
|
115
|
+
* Resolves asset refs to bytes. Refs are project asset ids ("crate"); refs containing "/" or
|
|
116
|
+
* starting with "./" / "http(s):" pass through as URLs, so manifest-less demos stay trivial.
|
|
117
|
+
*/
|
|
118
|
+
interface AssetProvider {
|
|
119
|
+
load(ref: string): Promise<ArrayBuffer>;
|
|
120
|
+
loadText(ref: string): Promise<string>;
|
|
121
|
+
}
|
|
122
|
+
interface UrlAssetProviderOptions {
|
|
123
|
+
/**
|
|
124
|
+
* Packed runtime variant to prefer for convention-resolved ids (e.g. "ktx2" from
|
|
125
|
+
* `molen asset pack`): assets/<id>/model.<variant>.glb is tried first and model.glb is the
|
|
126
|
+
* fallback when the variant is not served. Index-mapped and URL-ish refs are used as given.
|
|
127
|
+
*/
|
|
128
|
+
variant?: string;
|
|
129
|
+
}
|
|
130
|
+
/**
|
|
131
|
+
* URL-backed provider: asset ids resolve through an id -> URL index (from the project manifest's
|
|
132
|
+
* assets record, mapped to served model URLs); URL-ish refs resolve against baseUrl.
|
|
133
|
+
*/
|
|
134
|
+
declare function createUrlAssetProvider(baseUrl: string, index?: Record<string, string>, options?: UrlAssetProviderOptions): AssetProvider;
|
|
135
|
+
interface LoadedGltf {
|
|
136
|
+
scene: THREE.Group;
|
|
137
|
+
clips: THREE.AnimationClip[];
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* Parse each glTF ref once; hand out per-entity instances (SkeletonUtils.clone so skinned
|
|
141
|
+
* meshes work while geometry/textures stay shared). `whenIdle()` resolves when no loads are
|
|
142
|
+
* pending — the capture path awaits it before its single deterministic frame.
|
|
143
|
+
*/
|
|
144
|
+
declare class AssetCache {
|
|
145
|
+
private readonly provider;
|
|
146
|
+
/** Owned by the cache: `dispose()` tears down its Draco/KTX2 decoder worker pools. */
|
|
147
|
+
private readonly loader;
|
|
148
|
+
private readonly loads;
|
|
149
|
+
private readonly bases;
|
|
150
|
+
private readonly disposedGeometries;
|
|
151
|
+
private readonly disposedMaterials;
|
|
152
|
+
private pending;
|
|
153
|
+
private idleResolvers;
|
|
154
|
+
private disposed;
|
|
155
|
+
constructor(provider: AssetProvider, loader: GLTFLoader);
|
|
156
|
+
/** Register an external async task (e.g. a material bake) so whenIdle() waits for it. */
|
|
157
|
+
track<T>(p: Promise<T>): Promise<T>;
|
|
158
|
+
private base;
|
|
159
|
+
/** A fresh instance of the (sub-)scene for one entity. */
|
|
160
|
+
instance(ref: string, node?: string): Promise<LoadedGltf>;
|
|
161
|
+
/** Resolves once every load kicked off so far has settled. */
|
|
162
|
+
whenIdle(): Promise<void>;
|
|
163
|
+
clear(): void;
|
|
164
|
+
dispose(): void;
|
|
165
|
+
private disposeLoaded;
|
|
166
|
+
}
|
|
167
|
+
//#endregion
|
|
168
|
+
//#region src/interpolation.d.ts
|
|
169
|
+
interface InterpTransform {
|
|
170
|
+
pos: Vec3;
|
|
171
|
+
rot: Quat;
|
|
172
|
+
scale?: Vec3;
|
|
173
|
+
/** When true, the renderer snaps to this transform instead of interpolating into it. */
|
|
174
|
+
teleport?: boolean;
|
|
175
|
+
}
|
|
176
|
+
/**
|
|
177
|
+
* Holds a small ring of recent per-tick transform snapshots and samples interpolated
|
|
178
|
+
* transforms ~delayTicks behind the latest tick. Never extrapolates: clamps to the latest
|
|
179
|
+
* known transform when ahead of the buffer.
|
|
180
|
+
*/
|
|
181
|
+
declare class InterpolationBuffer {
|
|
182
|
+
readonly tickRate: number;
|
|
183
|
+
private snaps;
|
|
184
|
+
private readonly baseline;
|
|
185
|
+
private readonly current;
|
|
186
|
+
private readonly active;
|
|
187
|
+
private visited;
|
|
188
|
+
private readonly capacity;
|
|
189
|
+
readonly delayTicks: number;
|
|
190
|
+
private readonly tickMs;
|
|
191
|
+
/** Smoothed local time (ms) that tick 0 would have arrived at — the render clock's anchor. */
|
|
192
|
+
private clockOffsetMs;
|
|
193
|
+
/** The last tick handed out, so a frame sequence never steps backwards. */
|
|
194
|
+
private lastRenderTick;
|
|
195
|
+
constructor(tickRate: number, opts?: {
|
|
196
|
+
capacity?: number;
|
|
197
|
+
delayTicks?: number;
|
|
198
|
+
});
|
|
199
|
+
/** Record the transforms present at a kernel tick. recvMs is the local receive time. */
|
|
200
|
+
push(tick: number, transforms: Map<EntityId, InterpTransform>, recvMs: number): void;
|
|
201
|
+
/** Record a contiguous sparse update. Unmentioned entities keep their previous transform. */
|
|
202
|
+
pushDelta(tick: number, changes: Map<EntityId, InterpTransform | undefined>, recvMs: number): void;
|
|
203
|
+
private at;
|
|
204
|
+
/** Visit only changed/interpolating entities; send the final pose once before retiring it. */
|
|
205
|
+
sampleActive(nowMs: number, apply: (id: EntityId, transform: InterpTransform) => void): void;
|
|
206
|
+
/** Reapply a static pose after a render/light binding changes without a transform delta. */
|
|
207
|
+
activate(id: EntityId): void;
|
|
208
|
+
get lastSampleVisited(): number;
|
|
209
|
+
get latestTick(): number | undefined;
|
|
210
|
+
/** Number of snapshots currently held (≤ capacity). */
|
|
211
|
+
get size(): number;
|
|
212
|
+
/**
|
|
213
|
+
* Fold one arrival into the smoothed clock offset. Anchoring on the newest arrival instead (the
|
|
214
|
+
* old `latest.tick + (now - latest.recvMs)`) makes every stall a visible rewind: a delta that
|
|
215
|
+
* lands 12 ms late moves the render tick ~0.3 ticks *backwards* and every moving entity reverses.
|
|
216
|
+
*/
|
|
217
|
+
private trackClock;
|
|
218
|
+
/**
|
|
219
|
+
* Estimate the render tick for a wall-clock time from the smoothed clock, minus the delay.
|
|
220
|
+
* Never runs ahead of the newest tick held (sampling clamps there anyway) and never steps
|
|
221
|
+
* backwards between calls, so a late delta cannot reverse motion mid-flight.
|
|
222
|
+
*/
|
|
223
|
+
estimateRenderTick(nowMs: number): number | undefined;
|
|
224
|
+
/** Sample an entity's interpolated transform at an explicit render tick (the tested core). */
|
|
225
|
+
sampleAt(renderTick: number, id: EntityId): InterpTransform | undefined;
|
|
226
|
+
/** Sample for a wall-clock time using the estimated render tick. */
|
|
227
|
+
sample(nowMs: number, id: EntityId): InterpTransform | undefined;
|
|
228
|
+
/** Ids present in the most recent snapshot. */
|
|
229
|
+
latestIds(): EntityId[];
|
|
230
|
+
clear(): void;
|
|
231
|
+
}
|
|
232
|
+
//#endregion
|
|
233
|
+
//#region src/sync.d.ts
|
|
234
|
+
/** The render contract component (docs-src/schemas/components.md, `renderable`). */
|
|
235
|
+
interface Renderable {
|
|
236
|
+
kind: "primitive" | "gltf" | (string & {});
|
|
237
|
+
ref: string;
|
|
238
|
+
materialRef?: string;
|
|
239
|
+
primitive?: {
|
|
240
|
+
size?: Vec3;
|
|
241
|
+
};
|
|
242
|
+
/** gltf: named sub-node to instance (default: the whole scene). */
|
|
243
|
+
node?: string;
|
|
244
|
+
visible?: boolean;
|
|
245
|
+
shadows?: {
|
|
246
|
+
cast?: boolean;
|
|
247
|
+
receive?: boolean;
|
|
248
|
+
};
|
|
249
|
+
/** gltf clip playback; clip time derives deterministically from startTick in captures. */
|
|
250
|
+
animation?: {
|
|
251
|
+
clip: string;
|
|
252
|
+
speed?: number;
|
|
253
|
+
loop?: "repeat" | "once" | "pingpong";
|
|
254
|
+
paused?: boolean; /** Simulation tick held while paused (default startTick). */
|
|
255
|
+
pausedAtTick?: number;
|
|
256
|
+
startTick?: number;
|
|
257
|
+
};
|
|
258
|
+
}
|
|
259
|
+
/** A light source component at the entity transform (mirrors the schema `light` component). */
|
|
260
|
+
interface LightData {
|
|
261
|
+
type: "directional" | "point" | "spot";
|
|
262
|
+
color?: string;
|
|
263
|
+
intensity?: number;
|
|
264
|
+
range?: number;
|
|
265
|
+
angleDeg?: number;
|
|
266
|
+
penumbra?: number;
|
|
267
|
+
castShadow?: boolean;
|
|
268
|
+
}
|
|
269
|
+
/** A backend that owns actual scene-graph objects (three.js, or a mock in tests). */
|
|
270
|
+
interface SceneBackend {
|
|
271
|
+
create(id: EntityId, renderable: Renderable): void;
|
|
272
|
+
updateRenderable(id: EntityId, renderable: Renderable): void;
|
|
273
|
+
destroy(id: EntityId): void;
|
|
274
|
+
setTransform(id: EntityId, transform: InterpTransform): void;
|
|
275
|
+
setModelSignals?(id: EntityId, spec: ModelSignalSpec | undefined, signals: ModelSignals): void;
|
|
276
|
+
/** Optional light surface (per-entity `light` components). */
|
|
277
|
+
createLight?(id: EntityId, light: LightData): void;
|
|
278
|
+
updateLight?(id: EntityId, light: LightData): void;
|
|
279
|
+
destroyLight?(id: EntityId): void;
|
|
280
|
+
/** Optional environment surface (the singleton `environment` component, or undefined). */
|
|
281
|
+
setEnvironment?(env: Record<string, unknown> | undefined): void;
|
|
282
|
+
/** Physical and visual weather singleton; independent of environment/sky configuration. */
|
|
283
|
+
setWeather?(weather: Record<string, unknown> | undefined): void;
|
|
284
|
+
}
|
|
285
|
+
/**
|
|
286
|
+
* Maintains a client-side mirror of kernel entities and reconciles renderable bindings against
|
|
287
|
+
* a SceneBackend (create / updateRenderable / destroy). Pure aside from the backend calls, so
|
|
288
|
+
* it is unit-testable with a mock backend.
|
|
289
|
+
*
|
|
290
|
+
* Reconciliation is incremental: a delta marks the ids it touched dirty and `reconcile` visits
|
|
291
|
+
* only those (a keyframe forces a full pass), so a 1000-entity scene with one moving entity
|
|
292
|
+
* serializes one renderable per message, not a thousand.
|
|
293
|
+
*/
|
|
294
|
+
declare class SceneMirror {
|
|
295
|
+
private readonly mirror;
|
|
296
|
+
private readonly bound;
|
|
297
|
+
private readonly boundLights;
|
|
298
|
+
private boundEnvironment;
|
|
299
|
+
private environmentOwner;
|
|
300
|
+
private boundWeather;
|
|
301
|
+
private weatherOwner;
|
|
302
|
+
private currentTick;
|
|
303
|
+
/** Ids touched since the last reconcile (spawned/changed/removedComponents/destroyed). */
|
|
304
|
+
private readonly dirty;
|
|
305
|
+
/** Set by a keyframe: the next reconcile must visit everything. */
|
|
306
|
+
private full;
|
|
307
|
+
private visited;
|
|
308
|
+
applyKeyframe(keyframe: Keyframe): void;
|
|
309
|
+
/** Apply only a contiguous delta; false means the caller must request a fresh keyframe. */
|
|
310
|
+
applyDelta(delta: Delta): boolean;
|
|
311
|
+
/** Extract the transforms present in the mirror (for the interpolation buffer). */
|
|
312
|
+
transforms(): Map<EntityId, InterpTransform>;
|
|
313
|
+
/** Extract only transform changes (including removals), before reconciliation clears dirty ids. */
|
|
314
|
+
transformChanges(delta: Delta): Map<EntityId, InterpTransform | undefined>;
|
|
315
|
+
/** How many entity ids the last `reconcile` examined (all of them after a keyframe). */
|
|
316
|
+
get lastReconcileVisited(): number;
|
|
317
|
+
/** Create/update/destroy backend objects so they match the mirror's renderables. */
|
|
318
|
+
reconcile(backend: SceneBackend): void;
|
|
319
|
+
/** Bring one id's renderable binding in line with the mirror (absent entity -> destroy). */
|
|
320
|
+
private reconcileRenderable;
|
|
321
|
+
private reconcileLights;
|
|
322
|
+
private reconcileLight;
|
|
323
|
+
private reconcileEnvironment;
|
|
324
|
+
private reconcileWeather;
|
|
325
|
+
/** Did this batch of dirty ids touch the current owner, or introduce another `environment`? */
|
|
326
|
+
private environmentTouched;
|
|
327
|
+
boundIds(): EntityId[];
|
|
328
|
+
get tick(): number | undefined;
|
|
329
|
+
has(id: EntityId): boolean;
|
|
330
|
+
/** A detached copy of one component of a mirrored entity (undefined when absent). */
|
|
331
|
+
get(id: EntityId, component: string): JsonObject | undefined;
|
|
332
|
+
/**
|
|
333
|
+
* The stored component object (no copy) for renderers that sample every frame: treat it as
|
|
334
|
+
* frozen. Its identity changes exactly when a delta or keyframe replaced it.
|
|
335
|
+
*/
|
|
336
|
+
peek(id: EntityId, component: string): JsonObject | undefined;
|
|
337
|
+
/** Every mirrored entity id, in creation order. */
|
|
338
|
+
entities(): EntityId[];
|
|
339
|
+
/** The component names an entity currently carries. */
|
|
340
|
+
components(id: EntityId): string[];
|
|
341
|
+
}
|
|
342
|
+
//#endregion
|
|
343
|
+
//#region src/client-core.d.ts
|
|
344
|
+
type Unsubscribe = () => void;
|
|
345
|
+
/**
|
|
346
|
+
* A failure the page has to see. `link` is the kernel side going away or misbehaving (an uncaught
|
|
347
|
+
* throw in the Worker, a script that fails to load, an undeserializable message); `frame` is an
|
|
348
|
+
* exception out of the client's own render frame. Both also reach `onDiag` as a `ClientDiagCode`
|
|
349
|
+
* diagnostic, so a page that only wired diagnostics still learns its kernel is dead.
|
|
350
|
+
*/
|
|
351
|
+
interface ClientError {
|
|
352
|
+
source: "link" | "frame";
|
|
353
|
+
/** Human-readable summary, already including the underlying message where one was available. */
|
|
354
|
+
message: string;
|
|
355
|
+
/** The `ErrorEvent`/`MessageEvent` or thrown value behind it, when there was one. */
|
|
356
|
+
cause?: unknown;
|
|
357
|
+
}
|
|
358
|
+
/** Diag codes the client synthesizes for failures the kernel cannot report (it is the casualty). */
|
|
359
|
+
type ClientDiagCode = "link-error" | "frame-error";
|
|
360
|
+
interface ClientCoreOptions {
|
|
361
|
+
link: MessageLink;
|
|
362
|
+
backend: SceneBackend;
|
|
363
|
+
interpolationDelayTicks?: number;
|
|
364
|
+
/** Wall clock in ms (default performance.now / Date.now); injectable for tests. */
|
|
365
|
+
now?: () => number;
|
|
366
|
+
}
|
|
367
|
+
interface ClientCore {
|
|
368
|
+
readonly mirror: SceneMirror;
|
|
369
|
+
/** The interpolation buffer, once the first keyframe/ready message fixed the tick rate. */
|
|
370
|
+
readonly buffer: InterpolationBuffer | undefined;
|
|
371
|
+
/** The latest kernel tick applied to the mirror. */
|
|
372
|
+
readonly tick: number | undefined;
|
|
373
|
+
/** Subscribe to kernel events by type, or `'*'` for all. Exact-type handlers run first. */
|
|
374
|
+
onEvent(type: string, cb: (event: EngineEvent, tick: number) => void): Unsubscribe;
|
|
375
|
+
/**
|
|
376
|
+
* Subscribe to kernel diagnostics (tick overruns, rejected commands, protocol errors). Codes the
|
|
377
|
+
* client does not know are delivered as they arrive rather than dropped, so a newer kernel's
|
|
378
|
+
* diagnostics reach an older page.
|
|
379
|
+
*/
|
|
380
|
+
onDiag(cb: (diag: DiagMessage) => void): Unsubscribe;
|
|
381
|
+
/**
|
|
382
|
+
* Subscribe to client-side failures: a dead or throwing kernel link, and frame-loop exceptions.
|
|
383
|
+
* Without this a crashed Worker is invisible — the page keeps rendering its last pose while
|
|
384
|
+
* every `command()` posts into nothing.
|
|
385
|
+
*/
|
|
386
|
+
onError(cb: (error: ClientError) => void): Unsubscribe;
|
|
387
|
+
/** Push a failure through the error + diag channels (the frame loop and custom backends use it). */
|
|
388
|
+
reportError(error: ClientError): void;
|
|
389
|
+
/** Read a component of a mirrored entity (a detached copy). */
|
|
390
|
+
get(id: EntityId, component: string): JsonObject | undefined;
|
|
391
|
+
/** Every mirrored entity id (creation order). */
|
|
392
|
+
entities(): EntityId[];
|
|
393
|
+
/** Sample every interpolated transform for `nowMs` into the backend (or any consumer). */
|
|
394
|
+
sampleTransforms(nowMs: number, apply: (id: EntityId, t: InterpTransform) => void): void;
|
|
395
|
+
sendCommand(command: Command): void;
|
|
396
|
+
/** Send a command by type + payload; the envelope is filled (`seq`, `source: 'local'`). */
|
|
397
|
+
command(type: string, payload?: JsonValue): void;
|
|
398
|
+
/**
|
|
399
|
+
* Drive the kernel's scheduler: `pause`, `resume`, `step` a fixed number of ticks, `set-rate`,
|
|
400
|
+
* or `request-keyframe`. Pairs with the host's `startPaused` option — a page that boots paused
|
|
401
|
+
* resumes once its assets are in, so nothing simulates behind a loading screen.
|
|
402
|
+
*/
|
|
403
|
+
control(action: ControlAction): void;
|
|
404
|
+
/** Unhook the link and clear the buffer. */
|
|
405
|
+
dispose(): void;
|
|
406
|
+
}
|
|
407
|
+
/** The envelope `command()` fills: local source, kernel re-stamps tick 0 to next tick. */
|
|
408
|
+
declare function localCommand(seq: number, type: string, payload: Command["payload"]): Command;
|
|
409
|
+
declare function createClientCore(opts: ClientCoreOptions): ClientCore;
|
|
410
|
+
//#endregion
|
|
411
|
+
//#region src/input.d.ts
|
|
412
|
+
type Unsubscribe$2 = () => void;
|
|
413
|
+
interface InputBindings {
|
|
414
|
+
bindings: Record<string, string>;
|
|
415
|
+
}
|
|
416
|
+
/** Resolve a key or Mouse<button> code to its bound action. */
|
|
417
|
+
declare function resolveAction(bindings: Record<string, string>, code: string): string | undefined;
|
|
418
|
+
/** Structural Gamepad API snapshot; also usable by custom device adapters and tests. */
|
|
419
|
+
interface InputGamepad {
|
|
420
|
+
id: string;
|
|
421
|
+
index: number;
|
|
422
|
+
connected: boolean;
|
|
423
|
+
mapping: string;
|
|
424
|
+
axes: readonly number[];
|
|
425
|
+
buttons: readonly {
|
|
426
|
+
pressed: boolean;
|
|
427
|
+
value: number;
|
|
428
|
+
}[];
|
|
429
|
+
}
|
|
430
|
+
type EventTargetLike = {
|
|
431
|
+
addEventListener(type: string, listener: (ev: unknown) => void): void;
|
|
432
|
+
removeEventListener(type: string, listener: (ev: unknown) => void): void;
|
|
433
|
+
};
|
|
434
|
+
interface InputMapOptions extends InputProfile {
|
|
435
|
+
profiles?: Record<string, InputProfile>;
|
|
436
|
+
profile?: string;
|
|
437
|
+
/** Event source (usually window); injectable for tests. */
|
|
438
|
+
target?: EventTargetLike;
|
|
439
|
+
/** Defaults to navigator.getGamepads. Inject an adapter for other browser facilities. */
|
|
440
|
+
getGamepads?: () => readonly (InputGamepad | null)[];
|
|
441
|
+
}
|
|
442
|
+
/** Calibrate and shape a raw axis. Invalid/non-finite hardware readings are neutral. */
|
|
443
|
+
declare function normalizeInputAxis(raw: number, binding: GamepadAxisBinding): number;
|
|
444
|
+
/**
|
|
445
|
+
* Keyboard/mouse + browser controllers mapped to numeric named actions. Call update() each
|
|
446
|
+
* frame (applyInputRules does this on its poller). Profiles are complete replacements.
|
|
447
|
+
*/
|
|
448
|
+
declare class InputMap {
|
|
449
|
+
private base;
|
|
450
|
+
private readonly profiles;
|
|
451
|
+
private current;
|
|
452
|
+
private readonly keys;
|
|
453
|
+
private readonly blockedKeys;
|
|
454
|
+
private readonly blockedButtons;
|
|
455
|
+
private baselineButtons;
|
|
456
|
+
private values;
|
|
457
|
+
private padValues;
|
|
458
|
+
private pads;
|
|
459
|
+
private enabled;
|
|
460
|
+
private disposed;
|
|
461
|
+
private focused;
|
|
462
|
+
private suspensions;
|
|
463
|
+
private revision;
|
|
464
|
+
private readonly pressHandlers;
|
|
465
|
+
private readonly releaseHandlers;
|
|
466
|
+
private readonly changeHandlers;
|
|
467
|
+
private readonly resetHandlers;
|
|
468
|
+
private readonly profileHandlers;
|
|
469
|
+
private readonly target;
|
|
470
|
+
private readonly provider;
|
|
471
|
+
private readonly listeners;
|
|
472
|
+
private status;
|
|
473
|
+
constructor(opts: InputMapOptions);
|
|
474
|
+
private get accepting();
|
|
475
|
+
private get profile();
|
|
476
|
+
get activeProfile(): string | undefined;
|
|
477
|
+
get gamepadStatus(): "available" | "unavailable" | "blocked";
|
|
478
|
+
profileNames(): string[];
|
|
479
|
+
/** Detached, serializable copy for custom editors and host-managed persistence. */
|
|
480
|
+
getProfile(...selection: [name?: string]): InputProfile;
|
|
481
|
+
/** Atomically validate and replace bindings; no held button becomes a new action. */
|
|
482
|
+
defineProfile(name: string | undefined, profile: InputProfile): void;
|
|
483
|
+
/** Undefined selects the root bindings. Held keys/buttons must be released before reuse. */
|
|
484
|
+
setProfile(name: string | undefined): void;
|
|
485
|
+
/** Snapshot of all detected devices and raw values, suitable for an axis/button inspector. */
|
|
486
|
+
devices(): InputGamepad[];
|
|
487
|
+
/** Poll fresh browser objects; unplugging or losing permission releases affected controls. */
|
|
488
|
+
update(): void;
|
|
489
|
+
/** Suspend while editing a form/menu; device discovery continues during update(). */
|
|
490
|
+
setEnabled(enabled: boolean): void;
|
|
491
|
+
/** Temporarily suppress gameplay while a remapping UI is open; returned release is idempotent. */
|
|
492
|
+
suspend(): Unsubscribe$2;
|
|
493
|
+
private attach;
|
|
494
|
+
press(code: string): void;
|
|
495
|
+
release(code: string): void;
|
|
496
|
+
/** Numeric action value; strongest absolute contribution wins, keyboard wins ties. */
|
|
497
|
+
value(action: string): number;
|
|
498
|
+
isActive(action: string): boolean;
|
|
499
|
+
activeActions(): Set<string>;
|
|
500
|
+
private contribute;
|
|
501
|
+
private recompute;
|
|
502
|
+
private commit;
|
|
503
|
+
/** Release actions immediately; suppress held physical buttons until released. */
|
|
504
|
+
reset(): void;
|
|
505
|
+
private subscribe;
|
|
506
|
+
onPress(action: string, handler: (action: string) => void): Unsubscribe$2;
|
|
507
|
+
onRelease(action: string, handler: (action: string) => void): Unsubscribe$2;
|
|
508
|
+
/** Action values changed (including neutralization on reset/profile switch). */
|
|
509
|
+
onChange(handler: () => void): Unsubscribe$2;
|
|
510
|
+
/** Explicit neutralization on reset, focus loss, suspension or profile replacement. */
|
|
511
|
+
onReset(handler: () => void): Unsubscribe$2;
|
|
512
|
+
/** Profile selection or definitions changed. */
|
|
513
|
+
onProfilesChanged(handler: () => void): Unsubscribe$2;
|
|
514
|
+
dispose(): void;
|
|
515
|
+
}
|
|
516
|
+
//#endregion
|
|
517
|
+
//#region src/three/materials.d.ts
|
|
518
|
+
/** Upload a BakedMaterial's slots onto a MeshStandardMaterial. */
|
|
519
|
+
declare function materialFromBaked(baked: BakedMaterial): THREE.MeshStandardMaterial;
|
|
520
|
+
/**
|
|
521
|
+
* Resolves materialRef strings to three.js materials. Sync for `palette:`; doc-backed refs
|
|
522
|
+
* (`matgraph:`/`pixelgrid:`) load + bake asynchronously. Every ref string maps to ONE cached
|
|
523
|
+
* material shared by all entities using it; `acquire*`/`release` refcount those so a material
|
|
524
|
+
* (and its textures) is disposed exactly when its last user lets go.
|
|
525
|
+
*/
|
|
526
|
+
declare class MaterialResolver {
|
|
527
|
+
private readonly provider;
|
|
528
|
+
private readonly baker;
|
|
529
|
+
private readonly cache;
|
|
530
|
+
/** Reverse map: cached material -> its cache key (for release). */
|
|
531
|
+
private readonly keyOf;
|
|
532
|
+
private readonly refs;
|
|
533
|
+
private disposed;
|
|
534
|
+
private readonly disposedMaterials;
|
|
535
|
+
/** An optional caller-owned worker baker keeps procedural rasterization off the UI thread. */
|
|
536
|
+
constructor(provider?: AssetProvider | undefined, baker?: MaterialBaker | undefined);
|
|
537
|
+
/** Sync resolution: palette refs (and the shared grey fallback for unknown/absent refs). */
|
|
538
|
+
resolveSync(materialRef: string | undefined): THREE.Material;
|
|
539
|
+
/** Is this a doc-backed ref that resolves asynchronously? */
|
|
540
|
+
isAsync(materialRef: string | undefined): boolean;
|
|
541
|
+
/**
|
|
542
|
+
* Async resolution for doc-backed refs; falls back to grey (with one warning) when the doc
|
|
543
|
+
* is missing/invalid so a bad ref never blanks the scene.
|
|
544
|
+
*/
|
|
545
|
+
resolve(materialRef: string): Promise<THREE.Material>;
|
|
546
|
+
/** `resolveSync` plus one reference; pair with `release`. */
|
|
547
|
+
acquireSync(materialRef: string | undefined): THREE.Material;
|
|
548
|
+
/** `resolve` plus one reference; pair with `release`. */
|
|
549
|
+
acquire(materialRef: string): Promise<THREE.Material>;
|
|
550
|
+
/**
|
|
551
|
+
* Drop one reference; at zero the material (and its textures) is disposed and evicted from
|
|
552
|
+
* the cache. Materials not handed out by `acquire*` are ignored.
|
|
553
|
+
*/
|
|
554
|
+
release(material: THREE.Material): void;
|
|
555
|
+
private retain;
|
|
556
|
+
private remember;
|
|
557
|
+
private bake;
|
|
558
|
+
dispose(): void;
|
|
559
|
+
private disposeMaterial;
|
|
560
|
+
}
|
|
561
|
+
//#endregion
|
|
562
|
+
//#region src/three/kinds.d.ts
|
|
563
|
+
/**
|
|
564
|
+
* Custom renderable kinds: a capability client half (figures, ...) registers how entities with
|
|
565
|
+
* `renderable.kind === '<kind>'` become three.js objects. The backend keeps ownership of the
|
|
566
|
+
* entity object (naming, world-root placement, interpolated transforms, visibility, shadows,
|
|
567
|
+
* capture barriers) and hands the kind a handle per entity for everything else.
|
|
568
|
+
*/
|
|
569
|
+
/** Read-only view of the client's mirrored components, without per-frame cloning. */
|
|
570
|
+
interface MirrorReader {
|
|
571
|
+
readonly tick: number | undefined;
|
|
572
|
+
/**
|
|
573
|
+
* The stored component object, not a copy: treat it as frozen. Its identity changes exactly
|
|
574
|
+
* when a delta or keyframe replaced it, so `peek(...) !== last` is a free change test.
|
|
575
|
+
*/
|
|
576
|
+
peek(id: EntityId, component: string): JsonObject | undefined;
|
|
577
|
+
}
|
|
578
|
+
/** What the live frame loop knows about an entity when it samples its pose. */
|
|
579
|
+
interface KindView {
|
|
580
|
+
/** Distance from the camera to the entity origin, meters. */
|
|
581
|
+
distance: number;
|
|
582
|
+
inView: boolean;
|
|
583
|
+
/** Whether any mesh of the entity casts shadows (never throttled). */
|
|
584
|
+
shadows: boolean;
|
|
585
|
+
/** The configured near/far animation distance. */
|
|
586
|
+
distantDistance: number;
|
|
587
|
+
}
|
|
588
|
+
interface KindContext {
|
|
589
|
+
/** The world root the entity object lives under (floating origin included). */
|
|
590
|
+
readonly scene: THREE.Object3D;
|
|
591
|
+
readonly renderer: Renderer | undefined;
|
|
592
|
+
readonly assets: AssetCache | undefined;
|
|
593
|
+
readonly materials: MaterialResolver;
|
|
594
|
+
/** Mirrored components (bound once the client connects; undefined in bare viewers). */
|
|
595
|
+
readonly mirror: MirrorReader | undefined;
|
|
596
|
+
/** Register async work the capture barrier (`client.ready()`) must wait for. */
|
|
597
|
+
track<T>(promise: Promise<T>): Promise<T>;
|
|
598
|
+
warn(message: string): void;
|
|
599
|
+
}
|
|
600
|
+
interface KindHandle {
|
|
601
|
+
/** The entity's root object; the backend names it, adds it to the scene and drives its transform. */
|
|
602
|
+
readonly object: THREE.Object3D;
|
|
603
|
+
/** The renderable changed without changing identity. */
|
|
604
|
+
update(renderable: Renderable): void;
|
|
605
|
+
/**
|
|
606
|
+
* Sample the entity's pose at a simulation tick (fractional on the live path). `view` is
|
|
607
|
+
* undefined on the capture path: exact tick, full detail, no throttling.
|
|
608
|
+
*/
|
|
609
|
+
setTick?(tick: number, tickRate: number, view: KindView | undefined): void;
|
|
610
|
+
dispose(): void;
|
|
611
|
+
}
|
|
612
|
+
interface RenderableKind {
|
|
613
|
+
readonly kind: string;
|
|
614
|
+
/** The identity part of a renderable: a change rebuilds the object, otherwise `update` runs. */
|
|
615
|
+
identity(renderable: Renderable): string;
|
|
616
|
+
create(id: EntityId, renderable: Renderable, ctx: KindContext): KindHandle;
|
|
617
|
+
/** Release kind-level shared resources (geometry caches, materials). */
|
|
618
|
+
dispose?(): void;
|
|
619
|
+
}
|
|
620
|
+
//#endregion
|
|
621
|
+
//#region src/three/static-batches.d.ts
|
|
622
|
+
interface StaticBatchOptions {
|
|
623
|
+
cellSize?: number;
|
|
624
|
+
minInstances?: number;
|
|
625
|
+
}
|
|
626
|
+
//#endregion
|
|
627
|
+
//#region src/three/backend.d.ts
|
|
628
|
+
interface SceneOptimizationOptions {
|
|
629
|
+
shaderWarmup?: boolean;
|
|
630
|
+
staticInstancing?: boolean | StaticBatchOptions;
|
|
631
|
+
/** Live-only pose throttling. Captures continue to sample exact simulation ticks. */
|
|
632
|
+
animation?: {
|
|
633
|
+
distantDistance?: number;
|
|
634
|
+
distantHz?: number;
|
|
635
|
+
hiddenHz?: number;
|
|
636
|
+
} | false;
|
|
637
|
+
/** Local lights beyond this count are ranked by influence; unlimited by default. */
|
|
638
|
+
maxLocalLights?: number;
|
|
639
|
+
}
|
|
640
|
+
/** Deterministic clip time from kernel tick (the capture path's animation contract). */
|
|
641
|
+
declare function computeClipTime(anim: NonNullable<Renderable["animation"]>, tick: number, tickRate: number, durationSec: number): number;
|
|
642
|
+
/** three.js implementation of the SceneBackend: primitives + async glTF instances + lights. */
|
|
643
|
+
declare class ThreeSceneBackend implements SceneBackend {
|
|
644
|
+
private readonly scene;
|
|
645
|
+
private readonly assets;
|
|
646
|
+
private readonly renderer;
|
|
647
|
+
private readonly materials;
|
|
648
|
+
private readonly optimization;
|
|
649
|
+
private readonly batches;
|
|
650
|
+
private readonly batchDirty;
|
|
651
|
+
private readonly dynamic;
|
|
652
|
+
private readonly escaped;
|
|
653
|
+
private readonly transformed;
|
|
654
|
+
private readonly animations;
|
|
655
|
+
private readonly lastPoseTick;
|
|
656
|
+
private readonly frustum;
|
|
657
|
+
private readonly viewProjection;
|
|
658
|
+
private animationTick;
|
|
659
|
+
private animationTickRate;
|
|
660
|
+
private readonly objects;
|
|
661
|
+
private readonly gltf;
|
|
662
|
+
private readonly modelSignals;
|
|
663
|
+
private readonly identities;
|
|
664
|
+
private readonly lights;
|
|
665
|
+
/** Refcounted primitive geometry, keyed by `geometryKey`; disposed when the count hits 0. */
|
|
666
|
+
private readonly geometries;
|
|
667
|
+
private readonly entityGeometry;
|
|
668
|
+
/** The one resolver-owned material each entity currently holds a reference on. */
|
|
669
|
+
private readonly entityMaterial;
|
|
670
|
+
private readonly entityMaterialRef;
|
|
671
|
+
/** Bumps on every material assignment/destroy so a late bake never overwrites a newer one. */
|
|
672
|
+
private readonly materialEpoch;
|
|
673
|
+
private epochSeq;
|
|
674
|
+
private warnedNoAssets;
|
|
675
|
+
/** Custom renderable kinds and the per-entity handles they created. */
|
|
676
|
+
private readonly kinds;
|
|
677
|
+
private readonly handles;
|
|
678
|
+
private readonly warnedKinds;
|
|
679
|
+
private mirror;
|
|
680
|
+
/** Async work registered by kinds that the capture barrier waits for. */
|
|
681
|
+
private readonly pending;
|
|
682
|
+
constructor(scene: THREE.Object3D, assets?: AssetCache | undefined, renderer?: Renderer | undefined, materials?: MaterialResolver, optimization?: SceneOptimizationOptions);
|
|
683
|
+
/** Register a custom renderable kind (capability client halves). Core kinds cannot be replaced. */
|
|
684
|
+
registerKind(kind: RenderableKind): void;
|
|
685
|
+
/** Give custom kinds read access to the mirrored components (no per-frame cloning). */
|
|
686
|
+
bindMirror(reader: MirrorReader): void;
|
|
687
|
+
private identityOf;
|
|
688
|
+
private kindContext;
|
|
689
|
+
private createKind;
|
|
690
|
+
/** Apply a resolved material to every mesh under an object. */
|
|
691
|
+
private static dressMeshes;
|
|
692
|
+
private acquireGeometry;
|
|
693
|
+
private releaseGeometry;
|
|
694
|
+
/** Hand an already-acquired material to an entity, releasing whatever it held before. */
|
|
695
|
+
private assignMaterial;
|
|
696
|
+
private releaseMaterial;
|
|
697
|
+
/**
|
|
698
|
+
* Resolve `materialRef` onto `target`: the sync material (palette, or the shared grey
|
|
699
|
+
* placeholder) immediately, then the baked one once an async ref finishes. Refcounts are
|
|
700
|
+
* balanced at every step so shared placeholders are never disposed out from under others.
|
|
701
|
+
*/
|
|
702
|
+
private bindMaterial;
|
|
703
|
+
private static applyShadows;
|
|
704
|
+
create(id: EntityId, renderable: Renderable): void;
|
|
705
|
+
private createGltf;
|
|
706
|
+
private applyAnimation;
|
|
707
|
+
updateRenderable(id: EntityId, renderable: Renderable): void;
|
|
708
|
+
/** Latest mirrored values are retained while the model loads. No simulation state is changed. */
|
|
709
|
+
setModelSignals(id: EntityId, spec: ModelSignalSpec | undefined, signals: ModelSignals): void;
|
|
710
|
+
private bindModelSignals;
|
|
711
|
+
private applyModelSignals;
|
|
712
|
+
destroy(id: EntityId): void;
|
|
713
|
+
setTransform(id: EntityId, t: InterpTransform): void;
|
|
714
|
+
/** Per-entity `light` components (directional/spot aim at the origin by default). */
|
|
715
|
+
createLight(id: EntityId, data: LightData): void;
|
|
716
|
+
updateLight(id: EntityId, data: LightData): void;
|
|
717
|
+
destroyLight(id: EntityId): void;
|
|
718
|
+
/** The singleton `environment` component; undefined restores the default rig. */
|
|
719
|
+
setEnvironment(env: Record<string, unknown> | undefined): void;
|
|
720
|
+
setWeather(weather: Record<string, unknown> | undefined): void;
|
|
721
|
+
/** Standalone preview clock; connected clients use setAnimationTick with the kernel clock. */
|
|
722
|
+
tickAnimations(dtSec: number): void;
|
|
723
|
+
private poseAnimation;
|
|
724
|
+
/** Live and capture poses use the same simulation tick and no wall-clock accumulation. */
|
|
725
|
+
setAnimationTick(tick: number, tickRate: number): void;
|
|
726
|
+
/** Flush static membership only when bindings change; world-origin shifts move the common root. */
|
|
727
|
+
prepareFrame(): void;
|
|
728
|
+
whenReady(): Promise<void>;
|
|
729
|
+
/** Exact tick-derived poses on return to view; invisible shadow casters are never skipped. */
|
|
730
|
+
updateLiveAnimations(tick: number, tickRate: number, camera: THREE.Camera): void;
|
|
731
|
+
private updateLocalLights;
|
|
732
|
+
entityForIntersection(hit: THREE.Intersection): EntityId | undefined;
|
|
733
|
+
count(): number;
|
|
734
|
+
dispose(): void;
|
|
735
|
+
/**
|
|
736
|
+
* Escape hatch: the raw three.js object for an entity (undefined if not created), for advanced
|
|
737
|
+
* effects the wrapper doesn't cover. Unstable — you own whatever you mutate, and the backend may
|
|
738
|
+
* recreate the object when the renderable changes.
|
|
739
|
+
*/
|
|
740
|
+
getObject(id: EntityId): THREE.Object3D | undefined;
|
|
741
|
+
/** The three.js world root this backend writes into (escape hatch for custom objects/lights). */
|
|
742
|
+
get threeScene(): THREE.Object3D;
|
|
743
|
+
}
|
|
744
|
+
//#endregion
|
|
745
|
+
//#region src/three/loaders.d.ts
|
|
746
|
+
interface DecoderConfig {
|
|
747
|
+
/** Hosted Draco decoder dir (e.g. "/decoders/draco/"); omit if assets are meshopt-canonical. */
|
|
748
|
+
dracoDecoderPath?: string;
|
|
749
|
+
/** Hosted Basis transcoder dir for KTX2 textures; omit when not using KTX2. */
|
|
750
|
+
ktx2TranscoderPath?: string;
|
|
751
|
+
}
|
|
752
|
+
/**
|
|
753
|
+
* A GLTFLoader with the meshopt decoder always attached (its WASM is inlined — zero hosting),
|
|
754
|
+
* plus optional Draco/KTX2 support when decoder paths are configured. Canonical GLBs from
|
|
755
|
+
* `molen asset import` are quantize+meshopt only, so most apps never configure paths.
|
|
756
|
+
*/
|
|
757
|
+
declare function createGltfLoader(renderer?: THREE.WebGLRenderer | WebGPURenderer, config?: DecoderConfig): GLTFLoader$1;
|
|
758
|
+
//#endregion
|
|
759
|
+
//#region src/client.d.ts
|
|
760
|
+
interface AssetOptions {
|
|
761
|
+
/** Base URL asset refs resolve against (default: the page origin). */
|
|
762
|
+
baseUrl?: string;
|
|
763
|
+
/** Asset id -> served URL index (from the project manifest); ids without an entry use the assets/<id>/model.glb convention. */
|
|
764
|
+
index?: Record<string, string>;
|
|
765
|
+
/**
|
|
766
|
+
* Packed runtime variant to prefer for convention-resolved ids (e.g. "ktx2"); pair it with
|
|
767
|
+
* `decoders.ktx2TranscoderPath`. Falls back to model.glb per asset when the variant is missing.
|
|
768
|
+
*/
|
|
769
|
+
variant?: string;
|
|
770
|
+
/** Bring-your-own provider (overrides baseUrl/index). */
|
|
771
|
+
provider?: AssetProvider;
|
|
772
|
+
}
|
|
773
|
+
interface ClientOptions extends RendererOptions {
|
|
774
|
+
sceneOptimization?: SceneOptimizationOptions;
|
|
775
|
+
/** Optional caller-owned worker pool for procedural textures. */
|
|
776
|
+
materialBaker?: MaterialBaker;
|
|
777
|
+
frameLoop?: "auto" | "manual";
|
|
778
|
+
/** Declarative camera; follow targets use the same interpolation as rendered entities. */
|
|
779
|
+
sceneCamera?: SceneCamera;
|
|
780
|
+
interpolationDelayTicks?: number;
|
|
781
|
+
/** Enable gltf renderables: where asset refs load from. */
|
|
782
|
+
assets?: AssetOptions;
|
|
783
|
+
/** Optional Draco/KTX2 decoder hosting (canonical imported assets need neither). */
|
|
784
|
+
decoders?: DecoderConfig;
|
|
785
|
+
/** Custom renderable kinds from capability client halves (e.g. figures). */
|
|
786
|
+
kinds?: RenderableKind[];
|
|
787
|
+
/**
|
|
788
|
+
* Cancels a mount in flight (`createClient`, `createSnapshotViewer`, `createViewer`,
|
|
789
|
+
* `mountExperience`): if it aborts while the GPU is initializing the
|
|
790
|
+
* factory rejects with an `AbortError` and nothing is left running. A host that unmounts mid-mount
|
|
791
|
+
* (React StrictMode's double-invoked effect) otherwise leaks a live client on the same canvas.
|
|
792
|
+
* Every factory is asynchronous, so every mount can be cancelled.
|
|
793
|
+
*/
|
|
794
|
+
signal?: AbortSignal;
|
|
795
|
+
}
|
|
796
|
+
interface MolenClient {
|
|
797
|
+
readonly renderer: Renderer;
|
|
798
|
+
/**
|
|
799
|
+
* The three.js scene backend driving this client (escape hatch: `getObject`, `threeScene`,
|
|
800
|
+
* `registerKind`). Unstable, like everything else you reach through it.
|
|
801
|
+
*/
|
|
802
|
+
readonly backend: ThreeSceneBackend;
|
|
803
|
+
/** The latest kernel tick applied (undefined before the first keyframe). */
|
|
804
|
+
readonly tick: number | undefined;
|
|
805
|
+
/** Override the declarative camera, disabling automatic follow tracking. */
|
|
806
|
+
setCamera(pose: CameraPose): void;
|
|
807
|
+
sendCommand(command: Command): void;
|
|
808
|
+
/**
|
|
809
|
+
* Send a command by type + payload; the client fills the envelope (`seq` auto-increments,
|
|
810
|
+
* `source: 'local'`, `tick: 0` — the kernel rewrites late ticks to the next tick).
|
|
811
|
+
*/
|
|
812
|
+
command(type: string, payload?: Command["payload"]): void;
|
|
813
|
+
/**
|
|
814
|
+
* Drive the kernel's scheduler: `{action: 'resume'}` after a `startPaused` host, `'pause'`,
|
|
815
|
+
* `'step'` a fixed number of ticks, `'set-rate'`, or `'request-keyframe'`. A page that boots
|
|
816
|
+
* its worker paused and resumes on `ready()` never simulates behind its own loading screen,
|
|
817
|
+
* and a test that steps instead of waiting is independent of wall-clock speed.
|
|
818
|
+
* No-op on a snapshot viewer, which has no kernel.
|
|
819
|
+
*/
|
|
820
|
+
control(action: ControlAction): void;
|
|
821
|
+
/**
|
|
822
|
+
* Subscribe to kernel events by type, or `'*'` for all (gameplay feedback: hits, pickups,
|
|
823
|
+
* win/lose, `command-rejected`). Handlers get the event and the tick it happened on.
|
|
824
|
+
*/
|
|
825
|
+
onEvent(type: string, cb: (event: EngineEvent, tick: number) => void): Unsubscribe;
|
|
826
|
+
/** Subscribe to kernel diagnostics (tick overruns, rejected commands, protocol errors). */
|
|
827
|
+
onDiag(cb: (diag: DiagMessage) => void): Unsubscribe;
|
|
828
|
+
/**
|
|
829
|
+
* Subscribe to client-side failures the kernel cannot report: the link died (`source: 'link'` —
|
|
830
|
+
* the Worker threw, failed to load, or sent an undeserializable message) or a render frame threw
|
|
831
|
+
* (`source: 'frame'`). Each also arrives on `onDiag` as `link-error` / `frame-error`.
|
|
832
|
+
*/
|
|
833
|
+
onError(cb: (error: ClientError) => void): Unsubscribe;
|
|
834
|
+
/** Read a component of a mirrored entity — a HUD's data source (a detached copy). */
|
|
835
|
+
get(id: EntityId, component: string): JsonObject | undefined;
|
|
836
|
+
/** Every mirrored entity id. */
|
|
837
|
+
entities(): EntityId[];
|
|
838
|
+
renderFrame(nowMs?: number): void;
|
|
839
|
+
/** Resolves when all pending asset loads have settled (capture/testing barrier). */
|
|
840
|
+
ready(): Promise<void>;
|
|
841
|
+
/** Number of bound scene objects (for stats/tests). */
|
|
842
|
+
objectCount(): number;
|
|
843
|
+
/** Resolve a Three ray hit to its entity, including static instanced meshes. */
|
|
844
|
+
entityForIntersection(hit: Intersection): EntityId | undefined;
|
|
845
|
+
/**
|
|
846
|
+
* Escape hatch: the raw three.js object for an entity (undefined when it has none yet). Taking it
|
|
847
|
+
* un-batches the entity from any static batch and marks it escaped, so edits you make stay
|
|
848
|
+
* visible — `renderer.worldRoot.getObjectByName(id)` skips that and hands back a hidden original.
|
|
849
|
+
*/
|
|
850
|
+
getObject(id: EntityId): Object3D | undefined;
|
|
851
|
+
dispose(): void;
|
|
852
|
+
}
|
|
853
|
+
/**
|
|
854
|
+
* Create a client bound to a kernel message link (Worker/MessagePort). The renderer-free core
|
|
855
|
+
* (`createClientCore`) applies keyframes/deltas into a scene mirror + interpolation buffer and
|
|
856
|
+
* dispatches events; this wraps it with the three.js backend and a frame loop.
|
|
857
|
+
*
|
|
858
|
+
* Asynchronous because selecting a graphics backend is: `backend` defaults to `'auto'`, which
|
|
859
|
+
* probes WebGPU and falls back to WebGL. Pass `backend: 'webgl'` to skip the probe — capture and
|
|
860
|
+
* golden paths do, because a pinned backend is what makes a frame byte-stable.
|
|
861
|
+
*/
|
|
862
|
+
declare function createClient(link: MessageLink, opts?: ClientOptions): Promise<MolenClient>;
|
|
863
|
+
/**
|
|
864
|
+
* Boot a client directly from a serialized keyframe with no live kernel — the capture page
|
|
865
|
+
* and replay viewer use this (docs-src/guide/three-surface.md). With gltf renderables, await
|
|
866
|
+
* `ready()` before the deterministic frame; clip poses derive from the keyframe tick.
|
|
867
|
+
*
|
|
868
|
+
* Like `createClient`, `backend` defaults to `'auto'`; pin `'webgl'` for a byte-stable frame.
|
|
869
|
+
*/
|
|
870
|
+
declare function createSnapshotViewer(keyframe: Keyframe, opts?: ClientOptions): Promise<MolenClient>;
|
|
871
|
+
/**
|
|
872
|
+
* Create a viewer with no kernel and no snapshot — just a renderer + camera over an empty
|
|
873
|
+
* scene. For client-side capabilities (terrain, custom three.js objects via `renderer.scene`).
|
|
874
|
+
*/
|
|
875
|
+
declare function createViewer(opts?: ClientOptions): Promise<MolenClient>;
|
|
876
|
+
interface MountExperienceOptions extends ClientOptions {
|
|
877
|
+
/** The kernel link (a Worker running KernelHost, or a MessagePort). Built by the host. */
|
|
878
|
+
link: MessageLink;
|
|
879
|
+
/** The validated scene manifest; its `camera` and `input` blocks are applied. */
|
|
880
|
+
scene: SceneManifest;
|
|
881
|
+
canvas: HTMLCanvasElement;
|
|
882
|
+
/** Where key/mouse events come from (default: window). */
|
|
883
|
+
inputTarget?: InputMapOptions["target"];
|
|
884
|
+
/** Controller/numeric input poll interval in ms (default 50). */
|
|
885
|
+
pollMs?: number;
|
|
886
|
+
/** Follow the canvas's client size on window resize (default true when `window` exists). */
|
|
887
|
+
autoResize?: boolean;
|
|
888
|
+
}
|
|
889
|
+
interface MountedExperience {
|
|
890
|
+
client: MolenClient;
|
|
891
|
+
/** The InputMap driving the scene's emit rules (undefined when the scene has no input block). */
|
|
892
|
+
input: InputMap | undefined;
|
|
893
|
+
dispose(): void;
|
|
894
|
+
}
|
|
895
|
+
/**
|
|
896
|
+
* The one-call browser mount: create the client on the link, apply the scene's `camera`, wire
|
|
897
|
+
* its `input` bindings + emit rules to `client.command`, and keep the renderer sized to the
|
|
898
|
+
* canvas. The kernel side is the host's `KernelHost` in a Worker built with `buildWorld` (which
|
|
899
|
+
* installs the same scene's scripts). Returns the client plus a disposer.
|
|
900
|
+
*
|
|
901
|
+
* This is the one entry point a page needs. It is asynchronous because `backend` defaults to
|
|
902
|
+
* `'auto'`, which probes WebGPU and falls back to WebGL; pass `backend: 'webgl'` to skip the probe.
|
|
903
|
+
*/
|
|
904
|
+
declare function mountExperience(opts: MountExperienceOptions): Promise<MountedExperience>;
|
|
905
|
+
//#endregion
|
|
906
|
+
//#region src/math.d.ts
|
|
907
|
+
declare function lerp3(a: Vec3, b: Vec3, t: number): Vec3;
|
|
908
|
+
/**
|
|
909
|
+
* Normalized linear quaternion interpolation along the shorter arc. Not a slerp: the angular
|
|
910
|
+
* rate is not constant across `t`, which is the right trade for interpolating between two
|
|
911
|
+
* consecutive simulation ticks (cheap, always returns a unit quaternion, no trig). A rotation
|
|
912
|
+
* large enough for the difference to read would have to turn most of the way around inside one
|
|
913
|
+
* tick.
|
|
914
|
+
*/
|
|
915
|
+
declare function nlerp4(a: Quat, b: Quat, t: number): Quat;
|
|
916
|
+
//#endregion
|
|
917
|
+
//#region src/scene-bindings.d.ts
|
|
918
|
+
type Unsubscribe$1 = () => void;
|
|
919
|
+
/** The renderer surface `applySceneCamera` needs (satisfied by `Renderer`). */
|
|
920
|
+
interface CameraTarget {
|
|
921
|
+
setCamera(pose: CameraPose): void;
|
|
922
|
+
setTopDownOrtho(opts: TopDownOrtho): void;
|
|
923
|
+
setFov(fovDeg: number): void;
|
|
924
|
+
}
|
|
925
|
+
/**
|
|
926
|
+
* Apply a scene's `camera` block. `fixed` and `free-fly` pose the perspective camera (free-fly
|
|
927
|
+
* applies its initial pose only; movement controls are the host's); `top-down-ortho` switches to
|
|
928
|
+
* the orthographic framing. Re-run after a resize to keep ortho framing (the Renderer already
|
|
929
|
+
* refits on setSize; callers with their own renderer may call this again).
|
|
930
|
+
*/
|
|
931
|
+
declare function applySceneCamera(camera: SceneCamera, renderer: CameraTarget, target?: InterpTransform): void;
|
|
932
|
+
interface InputRuleOptions {
|
|
933
|
+
/** How often controllers and numeric rules are polled (ms). Default 50. */
|
|
934
|
+
pollMs?: number;
|
|
935
|
+
/** Injectable timer (setInterval/clearInterval shape) for tests. */
|
|
936
|
+
timer?: {
|
|
937
|
+
set(fn: () => void, ms: number): unknown;
|
|
938
|
+
clear(handle: unknown): void;
|
|
939
|
+
};
|
|
940
|
+
}
|
|
941
|
+
/**
|
|
942
|
+
* Run a scene's `input.emit` rules against an InputMap: `press`/`release` rules emit on action
|
|
943
|
+
* edges; numeric rules share one controller poller that emits a scalar or [x, y] vector only
|
|
944
|
+
* when its value changes. Returns a disposer.
|
|
945
|
+
*/
|
|
946
|
+
declare function applyInputRules(input: SceneInput, inputMap: InputMap, emit: (type: string, payload: JsonObject) => void, opts?: InputRuleOptions): Unsubscribe$1;
|
|
947
|
+
/** Pure camera composition shared by live interpolation and deterministic snapshot viewers. */
|
|
948
|
+
declare function followCameraPose(camera: Extract<SceneCamera, {
|
|
949
|
+
mode: "follow";
|
|
950
|
+
}>, target: InterpTransform): CameraPose;
|
|
951
|
+
//#endregion
|
|
952
|
+
//#region src/sky/star-catalog.d.ts
|
|
953
|
+
/** One catalog row: J2000 right ascension and declination in degrees, magnitude, B-V. */
|
|
954
|
+
type StarCatalogRow = readonly [ra: number, dec: number, magnitude: number, bv: number];
|
|
955
|
+
/** Encode catalog rows as molen/stars@1 bytes. */
|
|
956
|
+
declare function encodeStarCatalog(rows: readonly StarCatalogRow[]): Uint8Array;
|
|
957
|
+
/** Decode molen/stars@1 bytes to catalog rows. */
|
|
958
|
+
declare function decodeStarCatalogRows(input: ArrayBuffer | Uint8Array): StarCatalogRow[];
|
|
959
|
+
/**
|
|
960
|
+
* Decode a molen/stars@1 catalog into sky stars (J2000 equatorial directions, the same frame the
|
|
961
|
+
* bundled catalog uses) for `SkyVisual.setStars` or `Renderer.setStarCatalog`.
|
|
962
|
+
*/
|
|
963
|
+
declare function decodeStarCatalog(input: ArrayBuffer | Uint8Array): SkyStar[];
|
|
964
|
+
//#endregion
|
|
965
|
+
//#region src/three/environment.d.ts
|
|
966
|
+
/** Mirrors the schema `environment` component (loose; all fields optional). */
|
|
967
|
+
interface EnvironmentData {
|
|
968
|
+
/** Earth or authored clear sky. Owns ambient/sun/moon lights when present. */
|
|
969
|
+
sky?: SkyData$1;
|
|
970
|
+
ambient?: {
|
|
971
|
+
sky?: string;
|
|
972
|
+
ground?: string;
|
|
973
|
+
intensity?: number;
|
|
974
|
+
};
|
|
975
|
+
sun?: {
|
|
976
|
+
direction?: [number, number, number];
|
|
977
|
+
color?: string;
|
|
978
|
+
intensity?: number;
|
|
979
|
+
castShadow?: boolean;
|
|
980
|
+
};
|
|
981
|
+
background?: string;
|
|
982
|
+
fog?: {
|
|
983
|
+
color: string;
|
|
984
|
+
near?: number;
|
|
985
|
+
far?: number;
|
|
986
|
+
};
|
|
987
|
+
toneMapping?: "none" | "aces" | "agx";
|
|
988
|
+
exposure?: number;
|
|
989
|
+
shadows?: "off" | "low" | "medium" | "high";
|
|
990
|
+
}
|
|
991
|
+
/** Exactly the rig the renderer always shipped — existing scenes render byte-identical. */
|
|
992
|
+
declare const defaultEnvironment: EnvironmentData;
|
|
993
|
+
/**
|
|
994
|
+
* Apply an environment onto the renderer + scene: replaces the ambient/sun rig, background,
|
|
995
|
+
* fog, tone mapping, exposure, and the shadow quality tier. Passing `defaultEnvironment`
|
|
996
|
+
* restores the stock rig; omitted fields fall back to it.
|
|
997
|
+
*/
|
|
998
|
+
declare function applyEnvironment(renderer: Renderer, env: EnvironmentData): void;
|
|
999
|
+
//#endregion
|
|
1000
|
+
export { type AdaptiveQualityChange, AdaptiveQualityController, type AdaptiveQualityOptions, type AdaptiveQualityReason, type AdaptiveQualitySample, type AdaptiveQualityStats, type AdmissionOptions, type AdmissionSample, AssetCache, type AssetOptions, type AssetProvider, type AutoWorldOriginOptions, type CameraPose, type CameraTarget, type CelestialPosition, type ClientCore, type ClientCoreOptions, type ClientDiagCode, type ClientError, type ClientOptions, type CustomSkyData, type DecoderConfig, type EarthObserver, type EarthSkyData, type EarthSkyState, type EnvironmentData, type FrameAdmissionOptions, FrameAdmissionQueue, type GpuFrameTimer, type GpuFrameTimerOptions, type InputBindings, type InputGamepad, InputMap, type InputMapOptions, type InputRuleOptions, type InterpTransform, InterpolationBuffer, type KindContext, type KindHandle, type KindView, type LightData, type LoadedGltf, MaterialResolver, type MirrorReader, type ModelSignalVisual, type ModelSignals, type MolenClient, type MountExperienceOptions, type MountedExperience, type Renderable, type RenderableKind, Renderer, type RendererBackend, type RendererBackendPreference, type RendererOptions, type ResolvedWeather, type SceneAdmission, type SceneBackend, SceneMirror, type SceneOptimizationOptions, type SkyAppearance, type SkyBodyData, type SkyData, type SkyFrame, type SkyPalette, type SkyStar, type SkyTime, SkyVisual, type SkyVisualOptions, type StarCatalogRow, type StaticBatchOptions, THREE, type ThreeRenderer, ThreeSceneBackend, type TopDownOrtho, type Unsubscribe, type UrlAssetProviderOptions, type WeatherData, type WeatherProfile, WeatherVisual, applyEnvironment, applyInputRules, applySceneCamera, computeClipTime, createClient, createClientCore, createGltfLoader, createGpuFrameTimer, createModelSignalVisual, createSnapshotViewer, createUrlAssetProvider, createViewer, decodeStarCatalog, decodeStarCatalogRows, defaultEnvironment, defaultSkyPalette, encodeStarCatalog, evaluateEarthSky, followCameraPose, lerp3, localCommand, materialFromBaked, mountExperience, nextWorldOrigin, nlerp4, normalizeInputAxis, orthoFrustum, readModelSignals, resolveAction, resolveWeather, skyTimeMs, starDirection, weatherProfile };
|