@threenative/core 0.3.6 → 0.3.9
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 -5
- package/capabilities.json +739 -50
- package/dist/{assets-CqvE429w.d.ts → assets-YUbXa3-Y.d.ts} +101 -2
- package/dist/{canvas-layer-C1-5CviZ.d.ts → canvas-layer-vCtanIeB.d.ts} +1 -1
- package/dist/{game-Jz4Fdoeb.d.ts → game-cb99J-YE.d.ts} +100 -31
- package/dist/hot.d.ts +4 -4
- package/dist/hot.js +23 -5
- package/dist/index.d.ts +1742 -29
- package/dist/index.js +22443 -12423
- package/dist/{model-lod-BDAUYgsS.d.ts → model-lod-CTpZ6imz.d.ts} +1 -1
- package/dist/net.js +39 -12
- package/dist/playtest.d.ts +4 -4
- package/dist/playtest.js +48 -9
- package/dist/react-css.js +23 -0
- package/dist/react.d.ts +2 -2
- package/dist/{renderer-9yEo9hPa.d.ts → renderer-rZm0hVqq.d.ts} +178 -5
- package/dist/ui-layer.d.ts +11 -2
- package/dist/ui-layer.js +76 -4
- package/dist/worker.d.ts +36 -0
- package/dist/worker.js +1088 -0
- package/dist/world.d.ts +11 -3
- package/dist/world.js +1117 -197
- package/mcp/animation-server.mjs +265 -0
- package/mcp/animation.mjs +22 -0
- package/mcp/call.mjs +105 -0
- package/mcp/devtools.mjs +5 -0
- package/mcp/engine-server.mjs +713 -37
- package/mcp/launch.mjs +3 -2
- package/mcp/servers.d.mts +2 -0
- package/mcp/servers.mjs +33 -8
- package/package.json +12 -8
- package/patches/three@0.185.1-prd269-upgrade.patch +308 -0
- package/patches/three@0.185.1.patch +481 -272
- package/src/animation-packet-state.ts +88 -0
- package/src/animation-pose-packet.ts +537 -0
- package/src/animation.ts +779 -31
- package/src/asset-cache.ts +719 -0
- package/src/assets.ts +521 -152
- package/src/audio.ts +29 -3
- package/src/auto-batch.ts +792 -0
- package/src/config.ts +2 -0
- package/src/frame-budget.ts +268 -2
- package/src/game.ts +525 -105
- package/src/grounding.ts +7 -6
- package/src/hot.ts +19 -5
- package/src/index.ts +381 -6
- package/src/input.ts +21 -2
- package/src/interpolation.ts +19 -1
- package/src/launch-diagnostics.ts +7 -2
- package/src/look/ao-multibounce.ts +29 -0
- package/src/look/ao-reach.ts +39 -0
- package/src/look/auto-exposure.ts +264 -0
- package/src/look/default-tone-mapping.ts +44 -0
- package/src/look/exposure-graph.ts +208 -0
- package/src/look/exposure-readback.ts +97 -0
- package/src/look/exposure-settings.ts +132 -0
- package/src/look/filmic-tone-mapping.ts +852 -0
- package/src/look/gi-registry.ts +55 -0
- package/src/look/local-exposure.ts +507 -0
- package/src/look/look-diagnostics.ts +24 -0
- package/src/look/motion-blur.ts +42 -0
- package/src/look/quality.ts +309 -0
- package/src/look/reflection-trace.ts +344 -0
- package/src/look/unreal-bloom.ts +295 -0
- package/src/look/vignette.ts +14 -0
- package/src/look/world-environment.ts +2033 -0
- package/src/loop.ts +25 -1
- package/src/merge-parts.ts +25 -10
- package/src/model-lod.ts +14 -0
- package/src/net-session.ts +58 -14
- package/src/ocean/spectral.ts +41 -7
- package/src/picking.ts +72 -5
- package/src/platform.ts +29 -1
- package/src/playtest.ts +54 -8
- package/src/profiling/FrameCounters.ts +166 -5
- package/src/profiling/FrameStages.ts +289 -0
- package/src/profiling/Spans.ts +39 -25
- package/src/profiling/debug-telemetry.ts +312 -0
- package/src/profiling/scene-warning.ts +42 -6
- package/src/projection-apply.ts +11 -3
- package/src/projection-content.ts +189 -0
- package/src/projection-marker.ts +6 -2
- package/src/projection-plan.ts +279 -28
- package/src/projection-skinned.ts +620 -5
- package/src/projection-stability.ts +16 -0
- package/src/projection-uniform.ts +5 -1
- package/src/quiet-markers.ts +56 -0
- package/src/render/budget-ladder.ts +256 -0
- package/src/render/chain.ts +89 -7
- package/src/render/exposure-units.ts +59 -0
- package/src/render/frame-time-budget.ts +162 -0
- package/src/render/gi-budget.ts +231 -0
- package/src/render/gi-visualize.ts +49 -0
- package/src/render/material-key.ts +1 -0
- package/src/render/probe-volume.ts +196 -36
- package/src/render/rough-diffuse.ts +177 -0
- package/src/render/scene-trace.ts +532 -0
- package/src/render/shadow-filter-budget.ts +237 -0
- package/src/render/sky-capture.ts +194 -0
- package/src/render/soft-shadow.ts +607 -0
- package/src/render/surface-cache.ts +418 -0
- package/src/render/traced-reflections.ts +408 -0
- package/src/render/two-sided-foliage.ts +120 -0
- package/src/render/virtual-shadow-pages.ts +112 -12
- package/src/render/virtual-shadow.ts +386 -38
- package/src/render-camera-cull.ts +536 -31
- package/src/render-pass-budget.ts +140 -22
- package/src/renderProjection.ts +65 -9
- package/src/renderer-config.ts +3 -2
- package/src/renderer.ts +289 -14
- package/src/resolution-scaler.ts +65 -7
- package/src/skeletal-mesh.ts +4 -0
- package/src/snow-field.ts +46 -0
- package/src/softbody.ts +6 -5
- package/src/startup-offscreen-bytes.ts +168 -0
- package/src/startup-readiness.ts +137 -2
- package/src/ui-bridge.ts +38 -0
- package/src/ui-hit-regions.ts +6 -2
- package/src/ui-layer.ts +1 -0
- package/src/ui-state.ts +32 -3
- package/src/version.ts +1 -1
- package/src/viewport.ts +8 -5
- package/src/warmup.ts +76 -10
- package/src/worker-audio.ts +579 -0
- package/src/worker.ts +842 -0
- package/src/world-cells.ts +4 -1
- package/gpl/LICENSE.GPL +0 -117
- package/gpl/convert.py +0 -192
- package/gpl/fixtures/make_world_fixture.py +0 -184
- package/gpl/recipes/_common.py +0 -180
- package/gpl/recipes/bake_ao.py +0 -111
- package/gpl/recipes/decimate.py +0 -70
- package/gpl/recipes/export_world.py +0 -699
- package/gpl/recipes/retarget.py +0 -131
- package/gpl/recipes/unwrap.py +0 -71
- package/mcp/blender-server.mjs +0 -689
- package/mcp/blender.mjs +0 -26
package/src/snow-field.ts
CHANGED
|
@@ -94,6 +94,8 @@ const RECOVERED_COMPACTION = 0.008;
|
|
|
94
94
|
const WIND_EROSION = 0.00065;
|
|
95
95
|
/** Deposition burial rate per metre of fill. */
|
|
96
96
|
const DEPOSITION_BURIAL = 26;
|
|
97
|
+
/** Past this many separate windows a take is one box: a long drag must not grow the list. */
|
|
98
|
+
const MAX_UNTAKEN_WINDOWS = 32;
|
|
97
99
|
/** Hard ceiling on cells one contact may span, so a malformed extent fails instead of allocating. */
|
|
98
100
|
const MAX_CONTACT_CELLS = 1 << 20;
|
|
99
101
|
|
|
@@ -257,6 +259,7 @@ export class SnowField {
|
|
|
257
259
|
#version = 0;
|
|
258
260
|
#dirty: IHeightfieldRegionBounds | undefined;
|
|
259
261
|
#untaken: IHeightfieldRegionBounds | undefined;
|
|
262
|
+
#untakenWindows: IHeightfieldRegionBounds[] = [];
|
|
260
263
|
#scratch = new Float32Array(0);
|
|
261
264
|
|
|
262
265
|
constructor(options: ISnowFieldOptions) {
|
|
@@ -325,9 +328,23 @@ export class SnowField {
|
|
|
325
328
|
takeDirtyRegion(): IHeightfieldRegionBounds | undefined {
|
|
326
329
|
const region = this.#untaken;
|
|
327
330
|
this.#untaken = undefined;
|
|
331
|
+
this.#untakenWindows = [];
|
|
328
332
|
return region;
|
|
329
333
|
}
|
|
330
334
|
|
|
335
|
+
/**
|
|
336
|
+
* The windows written since the previous call, then forgotten. Windows that overlap or touch
|
|
337
|
+
* are one window, so two bodies a long way apart are two small windows, where
|
|
338
|
+
* `takeDirtyRegion` returns the large box around both. A renderer that uploads only what moved
|
|
339
|
+
* takes this. Like `takeDirtyRegion` it has one owner, and taking either one empties both.
|
|
340
|
+
*/
|
|
341
|
+
takeDirtyRegions(): readonly IHeightfieldRegionBounds[] {
|
|
342
|
+
const windows = this.#untakenWindows;
|
|
343
|
+
this.#untaken = undefined;
|
|
344
|
+
this.#untakenWindows = [];
|
|
345
|
+
return windows;
|
|
346
|
+
}
|
|
347
|
+
|
|
331
348
|
/** Bytes retained by the four snow channels and the base terrain copy. */
|
|
332
349
|
get memoryBytes(): number {
|
|
333
350
|
return (4 * this.#indent.length + this.#base.length) * Float32Array.BYTES_PER_ELEMENT;
|
|
@@ -739,6 +756,35 @@ export class SnowField {
|
|
|
739
756
|
this.field.updateHeights({ ...bounds, heights });
|
|
740
757
|
this.#dirty = { ...bounds };
|
|
741
758
|
this.#untaken = unionBounds(this.#untaken, bounds);
|
|
759
|
+
this.#untakenWindows = addWindow(this.#untakenWindows, bounds);
|
|
742
760
|
this.#version += 1;
|
|
743
761
|
}
|
|
744
762
|
}
|
|
763
|
+
|
|
764
|
+
/** Add `next` to `windows`, merging every window it overlaps or touches into one. */
|
|
765
|
+
function addWindow(
|
|
766
|
+
windows: readonly IHeightfieldRegionBounds[],
|
|
767
|
+
next: IHeightfieldRegionBounds,
|
|
768
|
+
): IHeightfieldRegionBounds[] {
|
|
769
|
+
let merged = next;
|
|
770
|
+
let rest = [...windows];
|
|
771
|
+
for (let again = true; again; ) {
|
|
772
|
+
again = false;
|
|
773
|
+
const keep: IHeightfieldRegionBounds[] = [];
|
|
774
|
+
for (const window of rest) {
|
|
775
|
+
const apart =
|
|
776
|
+
window.column > merged.column + merged.columns ||
|
|
777
|
+
merged.column > window.column + window.columns ||
|
|
778
|
+
window.row > merged.row + merged.rows ||
|
|
779
|
+
merged.row > window.row + window.rows;
|
|
780
|
+
if (apart) keep.push(window);
|
|
781
|
+
else {
|
|
782
|
+
merged = unionBounds(merged, window);
|
|
783
|
+
again = true;
|
|
784
|
+
}
|
|
785
|
+
}
|
|
786
|
+
rest = keep;
|
|
787
|
+
}
|
|
788
|
+
const all = [...rest, merged];
|
|
789
|
+
return all.length > MAX_UNTAKEN_WINDOWS ? [all.reduce((a, b) => unionBounds(a, b))] : all;
|
|
790
|
+
}
|
package/src/softbody.ts
CHANGED
|
@@ -196,10 +196,11 @@ function clothPass(options: {
|
|
|
196
196
|
const nextPosition = position.add(velocity.mul(options.halfStep)).toVar();
|
|
197
197
|
const collision = options.collision;
|
|
198
198
|
if (collision !== undefined) {
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
const
|
|
199
|
+
// Unrolled over the capacity: the owned engine reads a uniform array at a constant index only.
|
|
200
|
+
for (let box = 0; box < collision.capacity; box++) {
|
|
201
|
+
If(collision.count.greaterThan(box), () => {
|
|
202
|
+
const center = collision.bounds.element(box * 2).xyz;
|
|
203
|
+
const halfExtents = collision.bounds.element(box * 2 + 1).xyz;
|
|
203
204
|
const currentRelative = position.sub(center);
|
|
204
205
|
const relative = nextPosition.sub(center);
|
|
205
206
|
const withinX = relative.x.abs().lessThanEqual(halfExtents.x);
|
|
@@ -286,7 +287,7 @@ function clothPass(options: {
|
|
|
286
287
|
});
|
|
287
288
|
});
|
|
288
289
|
});
|
|
289
|
-
}
|
|
290
|
+
}
|
|
290
291
|
}
|
|
291
292
|
If(metadata.x.greaterThan(0), () => {
|
|
292
293
|
options.targetPositions
|
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
import { Box3, type Camera, Frustum, Matrix4, type Object3D } from "three";
|
|
2
|
+
import type { IResolvedAsset } from "./assets.js";
|
|
3
|
+
import { GEOMETRY_ASSET_KEY } from "./geometry-capture.js";
|
|
4
|
+
|
|
5
|
+
/** Why a file the reveal waited for shows nothing at the reveal. */
|
|
6
|
+
export type OffscreenReason = "hidden" | "not-placed" | "outside-view";
|
|
7
|
+
|
|
8
|
+
export interface IStartupOffscreenFile {
|
|
9
|
+
readonly bytes: number;
|
|
10
|
+
readonly path: string;
|
|
11
|
+
readonly reason: OffscreenReason;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* What the reveal waited for, split by whether the spawn camera shows it.
|
|
16
|
+
*
|
|
17
|
+
* Measured, never configured: nothing here is compared with a fixed size. `warn` is a ratio of two
|
|
18
|
+
* numbers from the same run (off-screen bytes against visible bytes), so no constant needs
|
|
19
|
+
* revisiting when links or games change.
|
|
20
|
+
*/
|
|
21
|
+
export interface IStartupOffscreenBytes {
|
|
22
|
+
/** Every sized byte the reveal waited for through `ctx.assets`. */
|
|
23
|
+
readonly awaitedBytes: number;
|
|
24
|
+
/** The fix, so a reader of one console line needs no other document. */
|
|
25
|
+
readonly fix: string;
|
|
26
|
+
/** Bytes of models with an object in view. */
|
|
27
|
+
readonly visibleBytes: number;
|
|
28
|
+
/** Bytes of models with no visible object in the frustum. */
|
|
29
|
+
readonly offscreenBytes: number;
|
|
30
|
+
/** Textures and audio: no scene object ties them to a view, so the engine does not guess. */
|
|
31
|
+
readonly unattributedBytes: number;
|
|
32
|
+
/** Awaited files whose size the manifest does not record, so they are in no byte count. */
|
|
33
|
+
readonly unsizedFiles: number;
|
|
34
|
+
/** The five largest off-screen files. */
|
|
35
|
+
readonly top: readonly IStartupOffscreenFile[];
|
|
36
|
+
/** Most of the wait bought nothing on screen: off-screen bytes exceed visible bytes. */
|
|
37
|
+
readonly warn: boolean;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
export const STARTUP_OFFSCREEN_BYTES_MARKER = "TN_STARTUP_OFFSCREEN_BYTES";
|
|
41
|
+
|
|
42
|
+
export const STARTUP_OFFSCREEN_FIX =
|
|
43
|
+
"Stream these files with WorldCells, or ctx.assets.prefetch them after the reveal, and keep " +
|
|
44
|
+
"awaiting everything the spawn camera sees. A not-placed file may also be geometry the game " +
|
|
45
|
+
"merged into a new buffer, which drops its provenance: check that before moving it.";
|
|
46
|
+
|
|
47
|
+
const TOP_FILES = 5;
|
|
48
|
+
|
|
49
|
+
function stampOf(userData: unknown): string | undefined {
|
|
50
|
+
const stamped = (userData as Record<string, unknown> | undefined)?.[GEOMETRY_ASSET_KEY];
|
|
51
|
+
return typeof stamped === "string" && stamped !== "" ? stamped : undefined;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* Which logical paths have an object in the scene, and whether any of them shows.
|
|
56
|
+
*
|
|
57
|
+
* A path is stamped on the model root and on every mesh geometry the loader returned, so an
|
|
58
|
+
* instanced batch built from a model's geometry keeps it even though the root never enters the
|
|
59
|
+
* scene. "Shows" means visible through the whole ancestry with world bounds in the frustum.
|
|
60
|
+
*/
|
|
61
|
+
function holders(root: Object3D, camera: Camera): Map<string, { shown: boolean; placed: boolean }> {
|
|
62
|
+
camera.updateWorldMatrix(true, false);
|
|
63
|
+
const frustum = new Frustum().setFromProjectionMatrix(
|
|
64
|
+
new Matrix4().multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse),
|
|
65
|
+
);
|
|
66
|
+
const found = new Map<string, { shown: boolean; placed: boolean }>();
|
|
67
|
+
const box = new Box3();
|
|
68
|
+
const visit = (object: Object3D, hidden: boolean): void => {
|
|
69
|
+
const isHidden = hidden || !object.visible;
|
|
70
|
+
const geometry = (object as Object3D & { geometry?: { userData?: unknown } }).geometry;
|
|
71
|
+
for (const path of new Set([stampOf(object.userData), stampOf(geometry?.userData)])) {
|
|
72
|
+
if (path === undefined) continue;
|
|
73
|
+
const entry = found.get(path) ?? { placed: false, shown: false };
|
|
74
|
+
found.set(path, entry);
|
|
75
|
+
if (isHidden) continue;
|
|
76
|
+
entry.placed = true;
|
|
77
|
+
if (!entry.shown && !box.setFromObject(object).isEmpty() && frustum.intersectsBox(box))
|
|
78
|
+
entry.shown = true;
|
|
79
|
+
}
|
|
80
|
+
for (const child of object.children) visit(child, isHidden);
|
|
81
|
+
};
|
|
82
|
+
visit(root, false);
|
|
83
|
+
return found;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* A one-off measurement walk, like the playtest observer's, under the same mark: three-native's
|
|
88
|
+
* bridge census then never bills its re-reads of every child to the game's frame.
|
|
89
|
+
*/
|
|
90
|
+
export function unbilled<T>(work: () => T): T {
|
|
91
|
+
const host = globalThis as { __tnPlaytestObserving?: number };
|
|
92
|
+
host.__tnPlaytestObserving = (host.__tnPlaytestObserving ?? 0) + 1;
|
|
93
|
+
try {
|
|
94
|
+
return work();
|
|
95
|
+
} finally {
|
|
96
|
+
host.__tnPlaytestObserving -= 1;
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* Split the bytes a reveal waited for into what the spawn camera shows and what it does not.
|
|
102
|
+
*
|
|
103
|
+
* `resolved` is `ctx.assets.resolved` at the reveal: every path that settled by then, with the
|
|
104
|
+
* kind and manifest size the loader recorded. A path with no stamp anywhere in `root` reads
|
|
105
|
+
* `not-placed`; a path stamped only under a hidden node reads `hidden`; otherwise a path whose
|
|
106
|
+
* bounds miss the frustum reads `outside-view`.
|
|
107
|
+
*/
|
|
108
|
+
export function measureStartupOffscreenBytes(
|
|
109
|
+
resolved: ReadonlyMap<string, IResolvedAsset>,
|
|
110
|
+
root: Object3D,
|
|
111
|
+
camera: Camera,
|
|
112
|
+
): IStartupOffscreenBytes {
|
|
113
|
+
const objects = unbilled(() => holders(root, camera));
|
|
114
|
+
let awaitedBytes = 0;
|
|
115
|
+
let visibleBytes = 0;
|
|
116
|
+
let unattributedBytes = 0;
|
|
117
|
+
let unsizedFiles = 0;
|
|
118
|
+
const offscreen: IStartupOffscreenFile[] = [];
|
|
119
|
+
// A load downloads its own file plus the shared images and lightmaps it names, and two models
|
|
120
|
+
// can share an image. Each url counts once: models in view first, so a file any visible model
|
|
121
|
+
// needs is visible, then textures and audio, then the models the camera does not show.
|
|
122
|
+
const counted = new Set<string>();
|
|
123
|
+
const take = (asset: IResolvedAsset): number => {
|
|
124
|
+
let bytes = 0;
|
|
125
|
+
for (const file of asset.files ?? [{ bytes: asset.bytes ?? 0, url: asset.url }]) {
|
|
126
|
+
if (counted.has(file.url)) continue;
|
|
127
|
+
counted.add(file.url);
|
|
128
|
+
bytes += file.bytes;
|
|
129
|
+
}
|
|
130
|
+
awaitedBytes += bytes;
|
|
131
|
+
return bytes;
|
|
132
|
+
};
|
|
133
|
+
const sized = [...resolved].filter(([, asset]) => {
|
|
134
|
+
if ((asset.bytes ?? 0) > 0) return true;
|
|
135
|
+
unsizedFiles += 1;
|
|
136
|
+
return false;
|
|
137
|
+
});
|
|
138
|
+
const rank = ([path, asset]: [string, IResolvedAsset]): number =>
|
|
139
|
+
asset.kind !== "model" ? 1 : objects.get(path)?.shown === true ? 0 : 2;
|
|
140
|
+
sized.sort((a, b) => rank(a) - rank(b));
|
|
141
|
+
for (const [path, asset] of sized) {
|
|
142
|
+
const bytes = take(asset);
|
|
143
|
+
if (asset.kind !== "model") {
|
|
144
|
+
unattributedBytes += bytes;
|
|
145
|
+
continue;
|
|
146
|
+
}
|
|
147
|
+
const holder = objects.get(path);
|
|
148
|
+
if (holder?.shown === true) visibleBytes += bytes;
|
|
149
|
+
else if (bytes > 0)
|
|
150
|
+
offscreen.push({
|
|
151
|
+
bytes,
|
|
152
|
+
path,
|
|
153
|
+
reason: holder === undefined ? "not-placed" : holder.placed ? "outside-view" : "hidden",
|
|
154
|
+
});
|
|
155
|
+
}
|
|
156
|
+
offscreen.sort((a, b) => b.bytes - a.bytes);
|
|
157
|
+
const offscreenBytes = offscreen.reduce((sum, file) => sum + file.bytes, 0);
|
|
158
|
+
return {
|
|
159
|
+
awaitedBytes,
|
|
160
|
+
fix: STARTUP_OFFSCREEN_FIX,
|
|
161
|
+
offscreenBytes,
|
|
162
|
+
top: offscreen.slice(0, TOP_FILES),
|
|
163
|
+
unattributedBytes,
|
|
164
|
+
unsizedFiles,
|
|
165
|
+
visibleBytes,
|
|
166
|
+
warn: offscreenBytes > visibleBytes,
|
|
167
|
+
};
|
|
168
|
+
}
|
package/src/startup-readiness.ts
CHANGED
|
@@ -1,5 +1,31 @@
|
|
|
1
1
|
export type StartupCompile = () => Promise<void> | void;
|
|
2
2
|
|
|
3
|
+
/**
|
|
4
|
+
* The renderer's own first-frame answer, with the inputs it is still short of so a launch that reached its
|
|
5
|
+
* deadline can name what never arrived instead of reporting a bare timeout.
|
|
6
|
+
*/
|
|
7
|
+
export interface IStartupImageState {
|
|
8
|
+
/** The renderer's answer: a world frame a player may see exists. */
|
|
9
|
+
readonly ready: boolean;
|
|
10
|
+
/** The exposure meter measured within tolerance of the target it owns. */
|
|
11
|
+
readonly exposureSettled: boolean;
|
|
12
|
+
/** Every active virtual shadow mapped its clip levels, and an ordinary world frame drew. */
|
|
13
|
+
readonly shadowInputsReady: boolean;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/** The answer of a renderer with nothing to wait for, and of a predicate that threw. */
|
|
17
|
+
const IMAGE_READY: IStartupImageState = {
|
|
18
|
+
exposureSettled: true,
|
|
19
|
+
ready: true,
|
|
20
|
+
shadowInputsReady: true,
|
|
21
|
+
};
|
|
22
|
+
/** A predicate that answers a plain `false` names no input: both are reported cold, which is its own answer. */
|
|
23
|
+
const IMAGE_COLD: IStartupImageState = {
|
|
24
|
+
exposureSettled: false,
|
|
25
|
+
ready: false,
|
|
26
|
+
shadowInputsReady: false,
|
|
27
|
+
};
|
|
28
|
+
|
|
3
29
|
export interface IStartupReadinessOptions {
|
|
4
30
|
/** Maximum wall-clock time spent waiting for first-use compilation. */
|
|
5
31
|
readonly compileBudgetMs?: number;
|
|
@@ -19,6 +45,20 @@ export interface IStartupReadinessOptions {
|
|
|
19
45
|
readonly stableWindowMs?: number;
|
|
20
46
|
/** Default ceiling on a single `hold()`, when the caller does not give one. */
|
|
21
47
|
readonly holdBudgetMs?: number;
|
|
48
|
+
/**
|
|
49
|
+
* Whether the renderer's own first real world frame exists. Read on every rendered frame, and required
|
|
50
|
+
* before readiness resolves, after the compile and stable-window budgets as well: those two timers answer
|
|
51
|
+
* what the *framework* cost, never that the picture behind the cover is the world. Absent means the caller
|
|
52
|
+
* has nothing to wait for (every renderer without the native presentation seam). A throwing predicate
|
|
53
|
+
* fails open, as a throwing hold does, so a broken read costs a frame the player did not see rather than a
|
|
54
|
+
* launch that never finishes.
|
|
55
|
+
*
|
|
56
|
+
* A predicate that says which input is still cold answers `IStartupImageState` instead of `false`; the
|
|
57
|
+
* deadline below prints that answer. One that never turns true — a black or unlit opening whose meter never
|
|
58
|
+
* measures, a sun that moves every frame and resets every shadow level, a target that keeps moving — costs
|
|
59
|
+
* `STARTUP_IMAGE_TIMEOUT_MS` of cover and then reveals, rather than costing the game its launch.
|
|
60
|
+
*/
|
|
61
|
+
readonly imageReady?: () => boolean | IStartupImageState;
|
|
22
62
|
/**
|
|
23
63
|
* Run after every hold settles and before readiness resolves.
|
|
24
64
|
*
|
|
@@ -71,6 +111,17 @@ export const STARTUP_STABLE_WINDOW_MS = 10_000;
|
|
|
71
111
|
* poorer-looking game and never a game that does not start.
|
|
72
112
|
*/
|
|
73
113
|
export const STARTUP_HOLD_BUDGET_MS = 45_000;
|
|
114
|
+
/**
|
|
115
|
+
* How long the renderer's own first-frame wait may outlast the frame window before the cover lifts anyway.
|
|
116
|
+
*
|
|
117
|
+
* It is the one wait a game cannot bound for itself, and real openings leave it outstanding for good: a menu or
|
|
118
|
+
* a space scene that is genuinely black, where the exposure meter never measures; a sun direction that changes
|
|
119
|
+
* every frame, where `atlas.cpp` resets every level and grants one per frame, so the atlas never reports ready;
|
|
120
|
+
* a meter target that keeps moving. Three seconds covers a healthy startup's cold frames many times over — the
|
|
121
|
+
* shadow pages map in the first few held frames and the meter settles soon after — and is short enough that such
|
|
122
|
+
* an opening is a launch that worked instead of a launch that hung.
|
|
123
|
+
*/
|
|
124
|
+
export const STARTUP_IMAGE_TIMEOUT_MS = 3_000;
|
|
74
125
|
|
|
75
126
|
/** One registered hold: the game's own launch work, and the bounded wait for it. */
|
|
76
127
|
interface IHold {
|
|
@@ -98,6 +149,10 @@ export class StartupReadiness {
|
|
|
98
149
|
readonly #holds = new Map<string, IHold>();
|
|
99
150
|
#holdBudgetMs: number;
|
|
100
151
|
#afterHolds: (() => Promise<void> | void) | undefined;
|
|
152
|
+
#imageReady: (() => boolean | IStartupImageState) | undefined;
|
|
153
|
+
#imageTimer: ReturnType<typeof setTimeout> | undefined;
|
|
154
|
+
#imageWaitedFrom = 0;
|
|
155
|
+
#imageTimedOut = false;
|
|
101
156
|
#compileTimer: ReturnType<typeof setTimeout> | undefined;
|
|
102
157
|
#windowTimer: ReturnType<typeof setTimeout> | undefined;
|
|
103
158
|
#resolveReady: () => void = () => undefined;
|
|
@@ -127,6 +182,7 @@ export class StartupReadiness {
|
|
|
127
182
|
"holdBudgetMs",
|
|
128
183
|
);
|
|
129
184
|
this.#afterHolds = options.afterHolds;
|
|
185
|
+
this.#imageReady = options.imageReady;
|
|
130
186
|
this.#readyPromise = new Promise<void>((resolve) => {
|
|
131
187
|
this.#resolveReady = resolve;
|
|
132
188
|
});
|
|
@@ -176,6 +232,15 @@ export class StartupReadiness {
|
|
|
176
232
|
return [...this.#holds.values()].filter((hold) => !hold.settled).map((hold) => hold.label);
|
|
177
233
|
}
|
|
178
234
|
|
|
235
|
+
/**
|
|
236
|
+
* The renderer's own wait, named for a stall report: the frame window is done and the first world frame is still
|
|
237
|
+
* cold. Empty before the frame window ends, after the deadline and once readiness resolves.
|
|
238
|
+
*/
|
|
239
|
+
get pendingImage(): readonly string[] {
|
|
240
|
+
if (this.#ready || !this.#frameWindowDone || this.#imageTimedOut) return [];
|
|
241
|
+
return this.#imageReadiness() ? [] : ["the renderer's first world frame"];
|
|
242
|
+
}
|
|
243
|
+
|
|
179
244
|
/** Completed units from active holds; settled holds freeze their count. Display progress is separate. */
|
|
180
245
|
get workProgress(): number {
|
|
181
246
|
let completed = 0;
|
|
@@ -285,6 +350,62 @@ export class StartupReadiness {
|
|
|
285
350
|
}
|
|
286
351
|
}
|
|
287
352
|
|
|
353
|
+
/**
|
|
354
|
+
* The renderer's answer changes only on a frame it drew, so it is polled on rendered frames and not by a
|
|
355
|
+
* timer: the compile and stable-window budgets must not release a picture the renderer says is cold. The
|
|
356
|
+
* deadline armed at the frame window is the one bound on that wait.
|
|
357
|
+
*/
|
|
358
|
+
#pollImage(): void {
|
|
359
|
+
if (this.#ready || this.#imageReady === undefined) return;
|
|
360
|
+
if (this.#imageReadiness()) this.#resolveIfComplete();
|
|
361
|
+
}
|
|
362
|
+
|
|
363
|
+
#imageReadiness(): boolean {
|
|
364
|
+
return this.#imageState().ready;
|
|
365
|
+
}
|
|
366
|
+
|
|
367
|
+
/** The renderer's answer as a state, failing open on a read that throws, like a throwing hold. */
|
|
368
|
+
#imageState(): IStartupImageState {
|
|
369
|
+
if (this.#imageReady === undefined) return IMAGE_READY;
|
|
370
|
+
try {
|
|
371
|
+
const answer = this.#imageReady();
|
|
372
|
+
return typeof answer === "boolean" ? (answer ? IMAGE_READY : IMAGE_COLD) : answer;
|
|
373
|
+
} catch {
|
|
374
|
+
return IMAGE_READY;
|
|
375
|
+
}
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
/**
|
|
379
|
+
* Bound the renderer's own wait, measured from the moment the framework's work ended.
|
|
380
|
+
*
|
|
381
|
+
* Everything else in a launch is bounded by its caller; this wait is not, so a game whose opening never
|
|
382
|
+
* satisfies it (`STARTUP_IMAGE_TIMEOUT_MS`) would keep its cover forever. Fails open like every other launch
|
|
383
|
+
* wait: the line names the input that never arrived, and the world shows.
|
|
384
|
+
*/
|
|
385
|
+
#armImageDeadline(): void {
|
|
386
|
+
if (this.#imageTimer !== undefined || this.#imageTimedOut) return;
|
|
387
|
+
this.#imageWaitedFrom = Date.now();
|
|
388
|
+
this.#imageTimer = setTimeout(() => {
|
|
389
|
+
this.#imageTimer = undefined;
|
|
390
|
+
if (this.#ready) return;
|
|
391
|
+
const state = this.#imageState();
|
|
392
|
+
// It arrived on its own inside the deadline: there is nothing to report.
|
|
393
|
+
if (state.ready) {
|
|
394
|
+
this.#resolveIfComplete();
|
|
395
|
+
return;
|
|
396
|
+
}
|
|
397
|
+
this.#imageTimedOut = true;
|
|
398
|
+
console.warn(
|
|
399
|
+
`TN_STARTUP_IMAGE_TIMEOUT ${JSON.stringify({
|
|
400
|
+
exposureSettled: state.exposureSettled === true,
|
|
401
|
+
shadowInputsReady: state.shadowInputsReady === true,
|
|
402
|
+
waitedMs: Date.now() - this.#imageWaitedFrom,
|
|
403
|
+
})}`,
|
|
404
|
+
);
|
|
405
|
+
this.#resolveIfComplete();
|
|
406
|
+
}, STARTUP_IMAGE_TIMEOUT_MS);
|
|
407
|
+
}
|
|
408
|
+
|
|
288
409
|
/** Begin the one-time first-use gate after the entered scene has been built. */
|
|
289
410
|
start(compile?: StartupCompile): void {
|
|
290
411
|
if (this.#started) return;
|
|
@@ -307,7 +428,10 @@ export class StartupReadiness {
|
|
|
307
428
|
|
|
308
429
|
/** Feed actual callback wall time, not requestAnimationFrame timestamp spacing. */
|
|
309
430
|
observe(frameMs: number): void {
|
|
310
|
-
if (!this.#ready)
|
|
431
|
+
if (!this.#ready) {
|
|
432
|
+
this.#pollHolds();
|
|
433
|
+
this.#pollImage();
|
|
434
|
+
}
|
|
311
435
|
if (!this.#started || this.#ready) return;
|
|
312
436
|
if (
|
|
313
437
|
this.#compileSettled &&
|
|
@@ -337,22 +461,33 @@ export class StartupReadiness {
|
|
|
337
461
|
}, this.#stableWindowMs);
|
|
338
462
|
}
|
|
339
463
|
|
|
340
|
-
/** The framework's own work is done. Whether the *world* is ready also depends on the holds. */
|
|
464
|
+
/** The framework's own work is done. Whether the *world* is ready also depends on the holds and the picture. */
|
|
341
465
|
#finishFrameWindow(): void {
|
|
342
466
|
if (this.#frameWindowDone) return;
|
|
343
467
|
this.#frameWindowDone = true;
|
|
344
468
|
if (this.#windowTimer !== undefined) clearTimeout(this.#windowTimer);
|
|
345
469
|
this.#windowTimer = undefined;
|
|
346
470
|
this.#resolveFrameworkReady();
|
|
471
|
+
if (!this.#imageReadiness()) this.#armImageDeadline();
|
|
347
472
|
this.#resolveIfComplete();
|
|
348
473
|
}
|
|
349
474
|
|
|
350
475
|
#resolveIfComplete(): void {
|
|
351
476
|
if (this.#ready || !this.#frameWindowDone) return;
|
|
352
477
|
for (const hold of this.#holds.values()) if (!hold.settled) return;
|
|
478
|
+
// Last, because it is the only wait that is not the caller's: a renderer that has not drawn a world a
|
|
479
|
+
// player may see yet keeps the cover, whatever the timers say — and no longer than its own deadline.
|
|
480
|
+
if (!this.#imageTimedOut && !this.#imageReadiness()) {
|
|
481
|
+
// A picture that was warm when the frame window closed can go cold before a game hold settles
|
|
482
|
+
// (a camera cut, a streamed tier): arm the deadline here too, or nothing bounds that wait.
|
|
483
|
+
this.#armImageDeadline();
|
|
484
|
+
return;
|
|
485
|
+
}
|
|
353
486
|
// Claim readiness before awaiting, so a hold that settles during `afterHolds` cannot re-enter
|
|
354
487
|
// and run it twice.
|
|
355
488
|
this.#ready = true;
|
|
489
|
+
if (this.#imageTimer !== undefined) clearTimeout(this.#imageTimer);
|
|
490
|
+
this.#imageTimer = undefined;
|
|
356
491
|
const afterHolds = this.#afterHolds;
|
|
357
492
|
// No holds means no second tier, which means the framework's own pass already saw the whole
|
|
358
493
|
// scene. Resolving synchronously there keeps every game that does not stream exactly as it was.
|
package/src/ui-bridge.ts
CHANGED
|
@@ -71,6 +71,13 @@ export const UI_INTENT_MESSAGE = "tn:intent";
|
|
|
71
71
|
* from it lies in exactly the sessions where somebody is trying to measure.
|
|
72
72
|
*/
|
|
73
73
|
export const UI_DEV_METRICS_MESSAGE = "tn:dev-metrics";
|
|
74
|
+
/**
|
|
75
|
+
* The startup phase the game end publishes: `covered` while the loading cover is up, `ready` from
|
|
76
|
+
* the frame the cover lifts. The UI realm cannot read `ctx.startup`, so this is how `useUiState`
|
|
77
|
+
* knows to return `undefined` until the player can see the page. A game that never sends it (an
|
|
78
|
+
* older core) reads as uncovered.
|
|
79
|
+
*/
|
|
80
|
+
export const UI_STARTUP_MESSAGE = "tn:startup";
|
|
74
81
|
/**
|
|
75
82
|
* The intent the UI layer sends once, when its tree has rendered and its rectangles are published.
|
|
76
83
|
*
|
|
@@ -270,6 +277,36 @@ function installInbound(scope: IScope, key: string, deliver: (frame: unknown) =>
|
|
|
270
277
|
};
|
|
271
278
|
}
|
|
272
279
|
|
|
280
|
+
const LOOPBACK_KEY = "__tnUiLoopback";
|
|
281
|
+
|
|
282
|
+
/**
|
|
283
|
+
* `?tnUiLoopback=1`: both ends stay in this realm but talk over a `MessageChannel`, so every
|
|
284
|
+
* frame arrives a task later, the hop a game in a worker adds (PRD-752). Installed once, as the
|
|
285
|
+
* host globals, by whichever end connects first; the game and the UI never know.
|
|
286
|
+
*/
|
|
287
|
+
function installLoopback(scope: IScope): void {
|
|
288
|
+
const search = (scope.location as { search?: unknown } | undefined)?.search;
|
|
289
|
+
if (typeof search !== "string" || new URLSearchParams(search).get("tnUiLoopback") !== "1") return;
|
|
290
|
+
if (scope[LOOPBACK_KEY] !== undefined) return;
|
|
291
|
+
const { port1: gamePort, port2: uiPort } = new MessageChannel();
|
|
292
|
+
const receive = (key: string) => (event: MessageEvent) =>
|
|
293
|
+
(scope[key] as ((frame: unknown) => void) | undefined)?.(event.data);
|
|
294
|
+
gamePort.onmessage = receive(UI_BRIDGE_GLOBALS.gameReceive);
|
|
295
|
+
uiPort.onmessage = receive(UI_BRIDGE_GLOBALS.uiReceive);
|
|
296
|
+
scope[UI_BRIDGE_GLOBALS.gamePost] = (frame: string) => gamePort.postMessage(frame);
|
|
297
|
+
scope[UI_BRIDGE_GLOBALS.uiHost] = { postMessage: (frame: string) => uiPort.postMessage(frame) };
|
|
298
|
+
scope.__tnUiOverlayAttached = () => true;
|
|
299
|
+
scope[LOOPBACK_KEY] = {
|
|
300
|
+
close() {
|
|
301
|
+
gamePort.close();
|
|
302
|
+
uiPort.close();
|
|
303
|
+
for (const key of [UI_BRIDGE_GLOBALS.gamePost, UI_BRIDGE_GLOBALS.uiHost, LOOPBACK_KEY])
|
|
304
|
+
scope[key] = undefined;
|
|
305
|
+
scope.__tnUiOverlayAttached = undefined;
|
|
306
|
+
},
|
|
307
|
+
};
|
|
308
|
+
}
|
|
309
|
+
|
|
273
310
|
/**
|
|
274
311
|
* Connect one end of the bridge.
|
|
275
312
|
*
|
|
@@ -286,6 +323,7 @@ export function connectUiBridge(options: IConnectOptions): IUiBridge {
|
|
|
286
323
|
throw new Error(`TN_UI_BRIDGE_END_INVALID: expected 'game' or 'ui', got '${String(end)}'.`);
|
|
287
324
|
}
|
|
288
325
|
const scope: IScope = options.scope ?? globalThis;
|
|
326
|
+
installLoopback(scope);
|
|
289
327
|
const listeners = new Set<(message: IUiMessage) => void>();
|
|
290
328
|
const deliver = (frame: unknown): void => {
|
|
291
329
|
const message = parseFrame(frame);
|
package/src/ui-hit-regions.ts
CHANGED
|
@@ -125,8 +125,12 @@ function quantize(value: number): number {
|
|
|
125
125
|
return Math.round(value * 1e5) / 1e5;
|
|
126
126
|
}
|
|
127
127
|
|
|
128
|
-
/**
|
|
129
|
-
|
|
128
|
+
/**
|
|
129
|
+
* Events that mean "something is moving and its published rect is now a frame behind".
|
|
130
|
+
* `transitionrun` is deliberately absent: a browser emits it as well as `transitionstart` for the
|
|
131
|
+
* same transition, and only that pair balances one `transitionend`/`transitioncancel`.
|
|
132
|
+
*/
|
|
133
|
+
const TRANSITION_START = ["transitionstart", "animationstart"] as const;
|
|
130
134
|
const TRANSITION_END = [
|
|
131
135
|
"transitionend",
|
|
132
136
|
"transitioncancel",
|
package/src/ui-layer.ts
CHANGED
package/src/ui-state.ts
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
|
+
import { countDebug, debugRequested, measureDebug } from "./profiling/debug-telemetry.js";
|
|
1
2
|
import {
|
|
2
3
|
GAME_STATE_MESSAGE,
|
|
3
4
|
type IUiBridge,
|
|
4
5
|
type IUiMessage,
|
|
5
6
|
UI_INTENT_MESSAGE,
|
|
7
|
+
UI_STARTUP_MESSAGE,
|
|
6
8
|
postUiState,
|
|
7
9
|
serializeUiState,
|
|
8
10
|
} from "./ui-bridge.js";
|
|
@@ -46,7 +48,9 @@ export interface IUiStatePublisher {
|
|
|
46
48
|
export interface IUiStateMirror<T> {
|
|
47
49
|
/** The last state the game published, or undefined before the first frame arrives. */
|
|
48
50
|
get(): T | undefined;
|
|
49
|
-
/**
|
|
51
|
+
/** True while the game reports its loading cover up; false before it says so and after it lifts. */
|
|
52
|
+
covered(): boolean;
|
|
53
|
+
/** Called after each accepted publication, and when the cover state changes. Returns an unsubscribe function. */
|
|
50
54
|
subscribe(listener: () => void): () => void;
|
|
51
55
|
/** Stop listening. */
|
|
52
56
|
stop(): void;
|
|
@@ -85,6 +89,13 @@ export function publishUiState<T>(
|
|
|
85
89
|
);
|
|
86
90
|
}
|
|
87
91
|
const schedule = options.schedule ?? microtask;
|
|
92
|
+
const debug = debugRequested();
|
|
93
|
+
const serialize = debug
|
|
94
|
+
? (state: T): string => {
|
|
95
|
+
countDebug("uiSerializations", 1, "ui", "publishUiState");
|
|
96
|
+
return measureDebug("uiSerialize", "ui", "publishUiState", () => serializeUiState(state));
|
|
97
|
+
}
|
|
98
|
+
: serializeUiState;
|
|
88
99
|
const read = (): T =>
|
|
89
100
|
store.getPublishedState === undefined ? store.getState() : store.getPublishedState();
|
|
90
101
|
let stopped = false;
|
|
@@ -94,12 +105,21 @@ export function publishUiState<T>(
|
|
|
94
105
|
const send = (state: T, frame: string): void => {
|
|
95
106
|
lastFrame = frame;
|
|
96
107
|
postUiState(bridge, state, frame);
|
|
108
|
+
if (debug) {
|
|
109
|
+
countDebug("uiMessages", 1, "ui", "publishUiState");
|
|
110
|
+
countDebug(
|
|
111
|
+
"uiMessageBytes",
|
|
112
|
+
new TextEncoder().encode(frame).byteLength,
|
|
113
|
+
"ui",
|
|
114
|
+
"publishUiState",
|
|
115
|
+
);
|
|
116
|
+
}
|
|
97
117
|
};
|
|
98
118
|
|
|
99
119
|
const publish = (): void => {
|
|
100
120
|
if (stopped) return;
|
|
101
121
|
const state = read();
|
|
102
|
-
send(state,
|
|
122
|
+
send(state, serialize(state));
|
|
103
123
|
};
|
|
104
124
|
|
|
105
125
|
const flush = (): void => {
|
|
@@ -112,7 +132,7 @@ export function publishUiState<T>(
|
|
|
112
132
|
// Skip a publication that would carry the bytes the UI already has. A store that writes the
|
|
113
133
|
// same value every tick is common and must not become a message per tick.
|
|
114
134
|
const state = read();
|
|
115
|
-
const frame =
|
|
135
|
+
const frame = serialize(state);
|
|
116
136
|
if (frame === lastFrame) return;
|
|
117
137
|
send(state, frame);
|
|
118
138
|
};
|
|
@@ -151,7 +171,15 @@ export function subscribeUiState<T>(bridge: IUiBridge): IUiStateMirror<T> {
|
|
|
151
171
|
}
|
|
152
172
|
const listeners = new Set<() => void>();
|
|
153
173
|
let current: T | undefined;
|
|
174
|
+
let covered = false;
|
|
154
175
|
const off = bridge.onMessage((message) => {
|
|
176
|
+
if (message.type === UI_STARTUP_MESSAGE) {
|
|
177
|
+
const next = message.phase !== "ready";
|
|
178
|
+
if (next === covered) return;
|
|
179
|
+
covered = next;
|
|
180
|
+
for (const listener of [...listeners]) listener();
|
|
181
|
+
return;
|
|
182
|
+
}
|
|
155
183
|
if (message.type !== GAME_STATE_MESSAGE) return;
|
|
156
184
|
const state = message.state;
|
|
157
185
|
if (typeof state !== "object" || state === null || Array.isArray(state)) {
|
|
@@ -162,6 +190,7 @@ export function subscribeUiState<T>(bridge: IUiBridge): IUiStateMirror<T> {
|
|
|
162
190
|
});
|
|
163
191
|
return {
|
|
164
192
|
get: () => current,
|
|
193
|
+
covered: () => covered,
|
|
165
194
|
subscribe(listener) {
|
|
166
195
|
listeners.add(listener);
|
|
167
196
|
return () => listeners.delete(listener);
|
package/src/version.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
// Generated by scripts/generate-version.mjs - do not edit. Source: package.json.
|
|
2
|
-
export const CORE_VERSION = "0.3.
|
|
2
|
+
export const CORE_VERSION = "0.3.9";
|