@threenative/core 0.3.6 → 0.3.8
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/playtest.ts
CHANGED
|
@@ -23,6 +23,7 @@ import type { EntitySnapshot } from "./entities.js";
|
|
|
23
23
|
import type { IGameObservationContribution, IGamePluginHooks, IGamePluginRuntime } from "./game.js";
|
|
24
24
|
import { GEOMETRY_CAPTURE_CAPABILITY } from "./geometry-capture.js";
|
|
25
25
|
import { PIPELINE_CENSUS_CAPABILITY } from "./pipeline-census.js";
|
|
26
|
+
import { discardEngineCountsSinceLastFrame } from "./profiling/FrameCounters.js";
|
|
26
27
|
import { readRenderChainObservation } from "./render/chain.js";
|
|
27
28
|
import type { ICtx } from "./scene.js";
|
|
28
29
|
import { CORE_VERSION } from "./version.js";
|
|
@@ -156,11 +157,21 @@ export function playtest<
|
|
|
156
157
|
...(runtime?.startupCompileSettled === undefined
|
|
157
158
|
? {}
|
|
158
159
|
: { compileSettled: runtime.startupCompileSettled() }),
|
|
160
|
+
...(runtime?.startupRevealed === undefined
|
|
161
|
+
? {}
|
|
162
|
+
: { revealed: runtime.startupRevealed() }),
|
|
159
163
|
// Wall-clock milestones, so a scenario asserts startup time as an observation instead
|
|
160
164
|
// of reading it off a console marker after the fact.
|
|
161
165
|
...(runtime?.startupTimeline === undefined
|
|
162
166
|
? {}
|
|
163
167
|
: { timeline: runtime.startupTimeline() }),
|
|
168
|
+
// What the reveal waited for that the spawn camera does not show, once the reveal ran.
|
|
169
|
+
...((offscreen) =>
|
|
170
|
+
offscreen === undefined
|
|
171
|
+
? {}
|
|
172
|
+
: {
|
|
173
|
+
offscreenBytes: { ...offscreen, top: offscreen.top.map((file) => ({ ...file })) },
|
|
174
|
+
})(runtime?.startupOffscreenBytes?.()),
|
|
164
175
|
}),
|
|
165
176
|
};
|
|
166
177
|
const installation = installThreePlaytestBridge(bridgeOptions);
|
|
@@ -227,7 +238,12 @@ export function playtest<
|
|
|
227
238
|
if (!wallClock) runtime?.freezeClock?.();
|
|
228
239
|
}
|
|
229
240
|
dispose = installation.dispose;
|
|
230
|
-
attached = holdUntilAttached(
|
|
241
|
+
attached = holdUntilAttached(
|
|
242
|
+
installation.bridge,
|
|
243
|
+
options,
|
|
244
|
+
() => startSceneEntered,
|
|
245
|
+
runtime?.startSceneLoaded,
|
|
246
|
+
);
|
|
231
247
|
const cleanup = () => {
|
|
232
248
|
if (!clockDisposed && clockRuntime?._setClockMode !== undefined)
|
|
233
249
|
clockControl._setClockMode("fixed-step");
|
|
@@ -378,6 +394,7 @@ function holdUntilAttached(
|
|
|
378
394
|
bridge: IPlaytestBridgeV1,
|
|
379
395
|
options: IPlaytestOptions,
|
|
380
396
|
startSceneEntered: () => Promise<void> | undefined,
|
|
397
|
+
startSceneLoaded?: () => Promise<void>,
|
|
381
398
|
): Promise<void> | undefined {
|
|
382
399
|
if (!shouldHoldUntilAttached(options)) return undefined;
|
|
383
400
|
const timeoutMs = options.attachTimeoutMs ?? PLAYTEST_ATTACH_TIMEOUT_MS;
|
|
@@ -413,6 +430,9 @@ function holdUntilAttached(
|
|
|
413
430
|
if (applySetup !== undefined) {
|
|
414
431
|
bridge.applySetup = async (request) => {
|
|
415
432
|
try {
|
|
433
|
+
// Setup names entities the start scene's load() registers; an async load is still
|
|
434
|
+
// pending when the runner first attaches.
|
|
435
|
+
await startSceneLoaded?.();
|
|
416
436
|
const confirmation = await applySetup(request);
|
|
417
437
|
release();
|
|
418
438
|
return confirmation;
|
|
@@ -451,9 +471,16 @@ function installRuntimeChannels(
|
|
|
451
471
|
);
|
|
452
472
|
const sample = bridge.sample;
|
|
453
473
|
bridge.sample = (request) =>
|
|
454
|
-
Promise.resolve(sample(request)).then((snapshot) =>
|
|
455
|
-
|
|
456
|
-
|
|
474
|
+
Promise.resolve(sample(request)).then(async (snapshot) => {
|
|
475
|
+
const observed = await addRuntimeObservations(
|
|
476
|
+
snapshot,
|
|
477
|
+
request,
|
|
478
|
+
runtime?.observations.contributions() ?? [],
|
|
479
|
+
);
|
|
480
|
+
// An observation walks the scene for entity `debug()`; the next frame is not billed for it.
|
|
481
|
+
discardEngineCountsSinceLastFrame();
|
|
482
|
+
return observed;
|
|
483
|
+
});
|
|
457
484
|
}
|
|
458
485
|
function addRuntimeCapabilities(
|
|
459
486
|
description: IPlaytestBridgeDescription,
|
|
@@ -518,9 +545,9 @@ function bridgeEntities<TState extends Record<string, unknown>, TPhysics>(
|
|
|
518
545
|
}
|
|
519
546
|
function entityObject(entity: object | undefined): ThreeObject3D | undefined {
|
|
520
547
|
if (entity instanceof Object3D) return entity;
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
548
|
+
// A game's own entity class usually exposes its root as `mesh`, `object` or `group`.
|
|
549
|
+
const roots = entity as { group?: unknown; mesh?: unknown; object?: unknown } | undefined;
|
|
550
|
+
const candidate = roots?.mesh ?? roots?.object ?? roots?.group;
|
|
524
551
|
return candidate instanceof Object3D ? candidate : undefined;
|
|
525
552
|
}
|
|
526
553
|
function gameplayObservations<TState extends Record<string, unknown>, TPhysics>(
|
|
@@ -599,6 +626,7 @@ function strideObservation(value: unknown): IPlaytestStrideObservation | undefin
|
|
|
599
626
|
return {
|
|
600
627
|
clipGroundSpeed: report.clipGroundSpeed as number,
|
|
601
628
|
groundSpeed: report.groundSpeed as number,
|
|
629
|
+
...(typeof report.inPlace === "boolean" ? { inPlace: report.inPlace } : {}),
|
|
602
630
|
overridden: report.overridden as boolean,
|
|
603
631
|
rate: report.rate as number,
|
|
604
632
|
synced: report.synced as boolean,
|
|
@@ -760,7 +788,8 @@ function objectGraphValues(root: object | undefined): object[] {
|
|
|
760
788
|
if (value === null || typeof value !== "object" || visited.has(value)) return;
|
|
761
789
|
visited.add(value);
|
|
762
790
|
values.push(value);
|
|
763
|
-
|
|
791
|
+
// Numeric storage is leaf data, not a container of contact adapters.
|
|
792
|
+
if (depth >= 4 || value instanceof Object3D || ArrayBuffer.isView(value)) return;
|
|
764
793
|
for (const child of Object.values(value)) visit(child, depth + 1);
|
|
765
794
|
};
|
|
766
795
|
visit(root, 0);
|
|
@@ -808,6 +837,7 @@ function stateResources<TState extends Record<string, unknown>, TPhysics>(
|
|
|
808
837
|
// Where every asset was actually served from, on every target and not only in a browser
|
|
809
838
|
// console log: a game whose manifest never loaded runs on the uncompiled source directory
|
|
810
839
|
// and looks healthy, and without this nothing observable says so.
|
|
840
|
+
["assetCache", assetCacheReport(ctx.assets)],
|
|
811
841
|
["assets", assetResolutions(ctx.assets)],
|
|
812
842
|
...(runtime?.frameCounts === undefined
|
|
813
843
|
? []
|
|
@@ -817,6 +847,22 @@ function stateResources<TState extends Record<string, unknown>, TPhysics>(
|
|
|
817
847
|
};
|
|
818
848
|
}
|
|
819
849
|
|
|
850
|
+
/** The cache counters and switches, without the action; observations are data. */
|
|
851
|
+
function assetCacheReport(assets: IAssetLoader): Record<string, JsonValue> {
|
|
852
|
+
const cache = assets.cache;
|
|
853
|
+
return {
|
|
854
|
+
enabled: cache.enabled,
|
|
855
|
+
persisted: cache.persisted,
|
|
856
|
+
hits: cache.hits,
|
|
857
|
+
misses: cache.misses,
|
|
858
|
+
bytesOnDisk: cache.bytesOnDisk,
|
|
859
|
+
bytesTotal: cache.bytesTotal,
|
|
860
|
+
filling: cache.filling,
|
|
861
|
+
backgroundFill: cache.backgroundFill,
|
|
862
|
+
...(cache.reason === undefined ? {} : { reason: cache.reason }),
|
|
863
|
+
};
|
|
864
|
+
}
|
|
865
|
+
|
|
820
866
|
/**
|
|
821
867
|
* The asset loader's `resolved` ledger, nested on the dots of each logical path.
|
|
822
868
|
*
|
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import { countDebug, debugRequested, isContentScaled } from "./debug-telemetry.js";
|
|
2
|
+
|
|
1
3
|
/**
|
|
2
4
|
* Host-boundary counters, default-off, on the frame budget's own record.
|
|
3
5
|
*
|
|
@@ -35,6 +37,21 @@ export interface IFrameCounters {
|
|
|
35
37
|
readonly gpuBytes?: number;
|
|
36
38
|
readonly hostCalls?: number;
|
|
37
39
|
readonly jsAllocBytes?: number;
|
|
40
|
+
/**
|
|
41
|
+
* JS->Wasm crossings this frame, from the web back end's own count (`createCrossingReader`).
|
|
42
|
+
* Absent on a host whose back end keeps no such count.
|
|
43
|
+
*/
|
|
44
|
+
readonly bridgeCrossings?: number;
|
|
45
|
+
/** Transforms the game moved this frame (the owned engine's `markLocalTransformDirty` calls; PRD-771). */
|
|
46
|
+
readonly dirtyTransforms?: number;
|
|
47
|
+
/** Shadow casters the virtual atlas judged moving this frame, each one invalidating its pages (PRD-771). */
|
|
48
|
+
readonly castersMoving?: number;
|
|
49
|
+
/**
|
|
50
|
+
* This frame's engine work counts by name (`createEngineCounterReader`): the web back end's and the
|
|
51
|
+
* engine's own totals, and `globalThis.__tnEngineCost`, differenced per frame. Absent unless a
|
|
52
|
+
* playtest asked for them.
|
|
53
|
+
*/
|
|
54
|
+
readonly engine?: Readonly<Record<string, number>>;
|
|
38
55
|
/** The loop's fixed-step count at the frame's end; absent when the caller did not feed one. */
|
|
39
56
|
readonly simulationTick?: number;
|
|
40
57
|
}
|
|
@@ -58,6 +75,18 @@ const SKIP: Record<string, true> = {
|
|
|
58
75
|
removeEventListener: true,
|
|
59
76
|
};
|
|
60
77
|
|
|
78
|
+
const GPU_COUNTERS: Readonly<Record<string, string>> = {
|
|
79
|
+
createBuffer: "gpuBufferCreates",
|
|
80
|
+
createTexture: "gpuTextureCreates",
|
|
81
|
+
createBindGroup: "gpuBindGroupCreates",
|
|
82
|
+
createRenderPipeline: "gpuPipelineCompiles",
|
|
83
|
+
createRenderPipelineAsync: "gpuPipelineCompiles",
|
|
84
|
+
mapAsync: "gpuReadbackMaps",
|
|
85
|
+
submit: "gpuQueueSubmits",
|
|
86
|
+
resolveQuerySet: "gpuQueryResolves",
|
|
87
|
+
beginRenderPass: "gpuRenderPasses",
|
|
88
|
+
};
|
|
89
|
+
|
|
61
90
|
/**
|
|
62
91
|
* Every function-valued method name on an object and its prototype chain.
|
|
63
92
|
*
|
|
@@ -116,6 +145,7 @@ export function counterDeviceOf(raw: unknown): unknown {
|
|
|
116
145
|
* allocation. Install once per renderer; `read` returns the counts since the previous `read`.
|
|
117
146
|
*/
|
|
118
147
|
export class FrameCounters {
|
|
148
|
+
readonly #debug = debugRequested();
|
|
119
149
|
#hostCalls = 0;
|
|
120
150
|
#gpuBytes = 0;
|
|
121
151
|
#lastHeapBytes: number | undefined;
|
|
@@ -125,9 +155,15 @@ export class FrameCounters {
|
|
|
125
155
|
private constructor(device: ICounterDevice) {
|
|
126
156
|
// A new encoder per pass, so an encoder's methods are wrapped the first time it is seen rather
|
|
127
157
|
// than once at install: a wrapper installed on one encoder would miss every later pass.
|
|
128
|
-
this.#wrap(
|
|
129
|
-
|
|
130
|
-
|
|
158
|
+
this.#wrap(
|
|
159
|
+
device,
|
|
160
|
+
this.#debug ? methodNames(device) : ["createCommandEncoder", "createRenderBundleEncoder"],
|
|
161
|
+
(name, result) => {
|
|
162
|
+
if (typeof result !== "object" || result === null) return;
|
|
163
|
+
if (name.endsWith("Encoder")) this.#wrapEncoder(result);
|
|
164
|
+
if (this.#debug && name === "createBuffer") this.#wrap(result, ["mapAsync"], undefined);
|
|
165
|
+
},
|
|
166
|
+
);
|
|
131
167
|
const queue = device.queue;
|
|
132
168
|
if (typeof queue === "object" && queue !== null)
|
|
133
169
|
this.#wrap(queue, methodNames(queue), undefined);
|
|
@@ -160,6 +196,7 @@ export class FrameCounters {
|
|
|
160
196
|
if (original === undefined) continue;
|
|
161
197
|
const wrapped = (...args: unknown[]): unknown => {
|
|
162
198
|
this.#hostCalls += 1;
|
|
199
|
+
const start = this.#debug ? performance.now() : undefined;
|
|
163
200
|
if (name === "writeBuffer") {
|
|
164
201
|
// `writeBuffer(buffer, offset, data, dataOffset, size)`; `size` defaults to the rest of
|
|
165
202
|
// the source, exactly as the spec says, so the count matches the bytes the driver sees.
|
|
@@ -173,16 +210,33 @@ export class FrameCounters {
|
|
|
173
210
|
typeof data.byteLength === "number"
|
|
174
211
|
? data.byteLength
|
|
175
212
|
: 0;
|
|
176
|
-
|
|
213
|
+
const elementBytes =
|
|
214
|
+
ArrayBuffer.isView(data) &&
|
|
215
|
+
"BYTES_PER_ELEMENT" in data &&
|
|
216
|
+
typeof data.BYTES_PER_ELEMENT === "number"
|
|
217
|
+
? data.BYTES_PER_ELEMENT
|
|
218
|
+
: 1;
|
|
219
|
+
this.#gpuBytes +=
|
|
220
|
+
size === undefined
|
|
221
|
+
? Math.max(0, available - dataOffset * elementBytes)
|
|
222
|
+
: size * elementBytes;
|
|
177
223
|
}
|
|
178
224
|
const result = original.apply(owner, args);
|
|
225
|
+
if (this.#debug) {
|
|
226
|
+
const field = GPU_COUNTERS[name];
|
|
227
|
+
if (field !== undefined) countDebug(field, 1, "gpu", `WebGPU.${name}`);
|
|
228
|
+
if (start !== undefined)
|
|
229
|
+
countDebug(`gpu.${name}Ms`, performance.now() - start, "gpu", `WebGPU.${name}`, "ms");
|
|
230
|
+
}
|
|
179
231
|
after?.(name, result);
|
|
180
232
|
return result;
|
|
181
233
|
};
|
|
182
234
|
try {
|
|
183
235
|
target[name] = wrapped;
|
|
236
|
+
const weak = new WeakRef(target);
|
|
184
237
|
this.#restore.push(() => {
|
|
185
|
-
|
|
238
|
+
const live = weak.deref();
|
|
239
|
+
if (live !== undefined) live[name] = original;
|
|
186
240
|
});
|
|
187
241
|
} catch {
|
|
188
242
|
// A native binding may expose a non-writable method. Losing that one from the count is a
|
|
@@ -204,6 +258,16 @@ export class FrameCounters {
|
|
|
204
258
|
if (heap !== undefined) {
|
|
205
259
|
const previous = this.#lastHeapBytes;
|
|
206
260
|
this.#lastHeapBytes = heap;
|
|
261
|
+
if (this.#debug) {
|
|
262
|
+
countDebug("jsHeapBytesSampled", heap, "memory", "performance.memory.usedJSHeapSize");
|
|
263
|
+
if (previous !== undefined)
|
|
264
|
+
countDebug(
|
|
265
|
+
heap >= previous ? "jsHeapGrowthBytes" : "jsHeapShrinkBytes",
|
|
266
|
+
Math.abs(heap - previous),
|
|
267
|
+
"memory",
|
|
268
|
+
"performance.memory.usedJSHeapSize",
|
|
269
|
+
);
|
|
270
|
+
}
|
|
207
271
|
if (previous !== undefined && heap >= previous)
|
|
208
272
|
return { ...counters, jsAllocBytes: heap - previous };
|
|
209
273
|
return counters;
|
|
@@ -229,3 +293,100 @@ function readHeapBytes(): number | undefined {
|
|
|
229
293
|
const used = perf?.memory?.usedJSHeapSize;
|
|
230
294
|
return typeof used === "number" && Number.isFinite(used) ? used : undefined;
|
|
231
295
|
}
|
|
296
|
+
|
|
297
|
+
/**
|
|
298
|
+
* The web back end's running count of JS->Wasm crossings, when the engine publishes one.
|
|
299
|
+
*
|
|
300
|
+
* `@threenative/three-native` installs `globalThis.__tnCrossingCount` (browser-entry.ts) and answers
|
|
301
|
+
* the total so far, so one frame's crossings are a difference of two reads. It is a different number
|
|
302
|
+
* from `hostCalls`: this counts the game's and the engine's calls into the engine's own ABI, which
|
|
303
|
+
* on the owned engine is a Wasm boundary on the game thread, and `hostCalls` counts WebGPU API calls.
|
|
304
|
+
* A host with no such back end (upstream three, the native player) answers `undefined`, and the
|
|
305
|
+
* field stays absent rather than reading zero.
|
|
306
|
+
*
|
|
307
|
+
* Per frame, not cumulative: the counter rides the frame budget's window, whose series are
|
|
308
|
+
* per-frame samples, and a cumulative total would climb with the window and say nothing about a frame.
|
|
309
|
+
*/
|
|
310
|
+
/** Set to `true` by a playtest that bounds engine counters (`engineCost`); three-native reads the same name. */
|
|
311
|
+
export const ENGINE_COST_KNOB = "__THREENATIVE_ENGINE_COST__";
|
|
312
|
+
|
|
313
|
+
interface IEngineCounterHost {
|
|
314
|
+
readonly __tnDebugSources?: Readonly<Record<string, { readonly unit?: string }>>;
|
|
315
|
+
readonly __THREENATIVE_ENGINE_COST__?: unknown;
|
|
316
|
+
/** The web back end's running totals by name (three-native browser-entry.ts). */
|
|
317
|
+
readonly __tnEngineCounters?: () => Readonly<Record<string, number>>;
|
|
318
|
+
/** Totals any module counts by name (`bag[name] = (bag[name] ?? 0) + 1`), on every engine. */
|
|
319
|
+
readonly __tnEngineCost?: Readonly<Record<string, number>>;
|
|
320
|
+
/** Installed by the reader while it is on: drops the counts since the last frame's read. */
|
|
321
|
+
__tnEngineCounterRebase?: () => void;
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
/**
|
|
325
|
+
* Leaves the work done since the last frame out of the next frame's engine counts. A caller that does
|
|
326
|
+
* work between frames which is not the game's (the playtest bridge answering an observation walks the
|
|
327
|
+
* scene for `debug()`) calls this when it is done; without it the next frame is billed for the walk
|
|
328
|
+
* and a bound on one frame's cost fails on a measurement of the harness, on a timing race.
|
|
329
|
+
*/
|
|
330
|
+
export function discardEngineCountsSinceLastFrame(
|
|
331
|
+
host: Pick<IEngineCounterHost, "__tnEngineCounterRebase"> = globalThis as IEngineCounterHost,
|
|
332
|
+
): void {
|
|
333
|
+
host.__tnEngineCounterRebase?.();
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
/**
|
|
337
|
+
* One reader for every engine work counter, so a playtest bounds them all from one surface,
|
|
338
|
+
* `TN_FRAME_BUDGET.counters.engine` (PRD-748's engine-cost row). Each source answers running totals;
|
|
339
|
+
* this answers one frame's difference per name. Off unless `ENGINE_COST_KNOB` is set, so a shipped
|
|
340
|
+
* frame pays nothing; the first read of a run is the baseline, not a frame.
|
|
341
|
+
*/
|
|
342
|
+
export function createEngineCounterReader(
|
|
343
|
+
host: IEngineCounterHost = globalThis as IEngineCounterHost,
|
|
344
|
+
): () => Record<string, number> | undefined {
|
|
345
|
+
const debug = debugRequested();
|
|
346
|
+
let last: Record<string, number> | undefined;
|
|
347
|
+
const read = (): Record<string, number> => ({
|
|
348
|
+
...host.__tnEngineCost,
|
|
349
|
+
...host.__tnEngineCounters?.(),
|
|
350
|
+
});
|
|
351
|
+
return () => {
|
|
352
|
+
if (!debug && host.__THREENATIVE_ENGINE_COST__ !== true) return undefined;
|
|
353
|
+
host.__tnEngineCounterRebase ??= () => {
|
|
354
|
+
if (last !== undefined) last = read();
|
|
355
|
+
};
|
|
356
|
+
const totals = read();
|
|
357
|
+
const previous = last;
|
|
358
|
+
last = totals;
|
|
359
|
+
if (previous === undefined) return undefined;
|
|
360
|
+
const frame: Record<string, number> = {};
|
|
361
|
+
// A name first counted this frame started from zero after the baseline.
|
|
362
|
+
for (const [name, total] of Object.entries(totals)) {
|
|
363
|
+
if (!Number.isFinite(total) || total < 0)
|
|
364
|
+
throw new Error(`TN_DEBUG: invalid ${name} counter.`);
|
|
365
|
+
// One name per asset URL or bridged property would add a ring per item the scene loads; the
|
|
366
|
+
// report ranks the run's largest ten of them instead (`isContentScaled`).
|
|
367
|
+
if (isContentScaled(name)) continue;
|
|
368
|
+
frame[name] =
|
|
369
|
+
debug && host.__tnDebugSources?.[name]?.unit === "gauge"
|
|
370
|
+
? total
|
|
371
|
+
: Math.max(0, total - (previous[name] ?? 0));
|
|
372
|
+
}
|
|
373
|
+
return frame;
|
|
374
|
+
};
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
export function createCrossingReader(
|
|
378
|
+
host: { readonly __tnCrossingCount?: () => number } = globalThis as {
|
|
379
|
+
readonly __tnCrossingCount?: () => number;
|
|
380
|
+
},
|
|
381
|
+
): () => number | undefined {
|
|
382
|
+
let last: number | undefined;
|
|
383
|
+
return () => {
|
|
384
|
+
if (typeof host.__tnCrossingCount !== "function") return undefined;
|
|
385
|
+
const total = host.__tnCrossingCount();
|
|
386
|
+
if (!Number.isFinite(total)) return undefined;
|
|
387
|
+
const previous = last;
|
|
388
|
+
last = total;
|
|
389
|
+
// The first read of a run is not a frame's worth of crossings: it is everything since boot.
|
|
390
|
+
return previous === undefined ? undefined : Math.max(0, total - previous);
|
|
391
|
+
};
|
|
392
|
+
}
|
|
@@ -0,0 +1,289 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where the main-thread frame goes, by stage (PRD-771).
|
|
3
|
+
*
|
|
4
|
+
* The frame budget's `render` phase wraps one synchronous `renderer.render()` call, and on the owned
|
|
5
|
+
* Wasm engine that call holds the scene walk, the draw plan, the encode, the post passes and the queue
|
|
6
|
+
* submit, all in C++. A phase that large with nothing named inside it is a question, not a measurement.
|
|
7
|
+
* This splits it with one clock read per boundary, so the split rides every window rather than a
|
|
8
|
+
* diagnostic flag:
|
|
9
|
+
*
|
|
10
|
+
* - the JS before the engine call (cull, `beforeRender`, reconcile, LOD, matrix walk) and after it;
|
|
11
|
+
* - the engine's own CPU stages, from the running totals the Wasm facade publishes in
|
|
12
|
+
* `renderer.info.engine.cpuMs` (three-native `gpu-stages.ts`), differenced per frame;
|
|
13
|
+
* - what is left of the call, named: JS inside `render()` around the Wasm call, and Wasm time no stage owns.
|
|
14
|
+
*
|
|
15
|
+
* The stages partition the render phase. `wasmOther` and `engineJs` are subtractions, published as
|
|
16
|
+
* stages (`wasmRendererGap` is what `Renderer::render` spends outside its plan and encode halves) so the unlocated time is a number and never a quiet category. On an engine that publishes no
|
|
17
|
+
* stage totals (upstream three), the whole call is `engineJs`.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
import type { IFrameCounters } from "./FrameCounters.js";
|
|
21
|
+
|
|
22
|
+
/** The stages of the render phase, in the order a frame spends them. They sum to the frame's `render` phase. */
|
|
23
|
+
export const RENDER_STAGES = [
|
|
24
|
+
"jsBefore",
|
|
25
|
+
"engineJs",
|
|
26
|
+
"wasmScene",
|
|
27
|
+
"wasmPlan",
|
|
28
|
+
"wasmCompute",
|
|
29
|
+
"wasmEncode",
|
|
30
|
+
"wasmPost",
|
|
31
|
+
"wasmSubmit",
|
|
32
|
+
"wasmPoll",
|
|
33
|
+
"wasmTail",
|
|
34
|
+
"wasmRendererGap",
|
|
35
|
+
"wasmDatabaseGap",
|
|
36
|
+
"wasmTargets",
|
|
37
|
+
"wasmOther",
|
|
38
|
+
"jsAfter",
|
|
39
|
+
] as const;
|
|
40
|
+
|
|
41
|
+
export type RenderStage = (typeof RENDER_STAGES)[number];
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Parts of a stage, published beside it and never added to the sum: `wasmPlan` holds all three, in the order the
|
|
45
|
+
* renderer runs them, and what is left of it is the rest of the prepare half.
|
|
46
|
+
*/
|
|
47
|
+
export const STAGE_PARTS = ["planVirtualPages", "planDraws", "planShadowLists"] as const;
|
|
48
|
+
|
|
49
|
+
export type StagePart = (typeof STAGE_PARTS)[number];
|
|
50
|
+
|
|
51
|
+
/** One frame's stages in milliseconds, reused across frames so the read allocates nothing. */
|
|
52
|
+
export type IFrameStageSample = Record<RenderStage | StagePart, number | undefined>;
|
|
53
|
+
|
|
54
|
+
/** The running totals the Wasm facade publishes (`renderer.info.engine.cpuMs`), in ms. */
|
|
55
|
+
export interface IEngineCpuTotals {
|
|
56
|
+
readonly cpuVirtualPagesMs: number;
|
|
57
|
+
readonly cpuPlanMs: number;
|
|
58
|
+
readonly cpuShadowBuildMs: number;
|
|
59
|
+
readonly cpuPrepareMs: number;
|
|
60
|
+
readonly cpuEncodeMs: number;
|
|
61
|
+
readonly cpuPostMs: number;
|
|
62
|
+
readonly cpuSceneMs: number;
|
|
63
|
+
readonly hostRenderMs: number;
|
|
64
|
+
readonly hostComputeMs: number;
|
|
65
|
+
readonly hostSubmitMs: number;
|
|
66
|
+
readonly hostPollMs: number;
|
|
67
|
+
readonly hostTailMs: number;
|
|
68
|
+
readonly rendererMs: number;
|
|
69
|
+
readonly hostDatabaseMs: number;
|
|
70
|
+
readonly hostTargetMs: number;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
const TOTAL_NAMES = [
|
|
74
|
+
"cpuVirtualPagesMs",
|
|
75
|
+
"cpuPlanMs",
|
|
76
|
+
"cpuShadowBuildMs",
|
|
77
|
+
"cpuPrepareMs",
|
|
78
|
+
"cpuEncodeMs",
|
|
79
|
+
"cpuPostMs",
|
|
80
|
+
"cpuSceneMs",
|
|
81
|
+
"hostRenderMs",
|
|
82
|
+
"hostComputeMs",
|
|
83
|
+
"hostSubmitMs",
|
|
84
|
+
"hostPollMs",
|
|
85
|
+
"hostTailMs",
|
|
86
|
+
"rendererMs",
|
|
87
|
+
"hostDatabaseMs",
|
|
88
|
+
"hostTargetMs",
|
|
89
|
+
] as const satisfies readonly (keyof IEngineCpuTotals)[];
|
|
90
|
+
|
|
91
|
+
/** A fresh sample with every stage at zero. */
|
|
92
|
+
export function emptyStageSample(): IFrameStageSample {
|
|
93
|
+
return {
|
|
94
|
+
engineJs: 0,
|
|
95
|
+
jsAfter: 0,
|
|
96
|
+
jsBefore: 0,
|
|
97
|
+
planDraws: 0,
|
|
98
|
+
planShadowLists: 0,
|
|
99
|
+
planVirtualPages: 0,
|
|
100
|
+
wasmCompute: 0,
|
|
101
|
+
wasmDatabaseGap: 0,
|
|
102
|
+
wasmEncode: 0,
|
|
103
|
+
wasmOther: 0,
|
|
104
|
+
wasmPlan: 0,
|
|
105
|
+
wasmPoll: 0,
|
|
106
|
+
wasmPost: 0,
|
|
107
|
+
wasmRendererGap: 0,
|
|
108
|
+
wasmScene: 0,
|
|
109
|
+
wasmSubmit: 0,
|
|
110
|
+
wasmTail: 0,
|
|
111
|
+
wasmTargets: 0,
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/** Every stage and part that only the engine's totals can fill. */
|
|
116
|
+
const UNMEASURED_WITHOUT_TOTALS = [
|
|
117
|
+
"wasmScene",
|
|
118
|
+
"wasmPlan",
|
|
119
|
+
"wasmCompute",
|
|
120
|
+
"wasmEncode",
|
|
121
|
+
"wasmPost",
|
|
122
|
+
"wasmSubmit",
|
|
123
|
+
"wasmPoll",
|
|
124
|
+
"wasmTail",
|
|
125
|
+
"wasmRendererGap",
|
|
126
|
+
"wasmDatabaseGap",
|
|
127
|
+
"wasmTargets",
|
|
128
|
+
"wasmOther",
|
|
129
|
+
"planVirtualPages",
|
|
130
|
+
"planDraws",
|
|
131
|
+
"planShadowLists",
|
|
132
|
+
] as const;
|
|
133
|
+
|
|
134
|
+
const positive = (value: number): number => (value > 0 ? value : 0);
|
|
135
|
+
|
|
136
|
+
interface IEngineCpuHost {
|
|
137
|
+
readonly info?: { readonly engine?: { readonly cpuMs?: Partial<IEngineCpuTotals> } };
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/**
|
|
141
|
+
* The reader `game.ts` calls once per rendered frame with the three JS timings of that frame. It returns the
|
|
142
|
+
* frame's stages (the same object every call) or `undefined` for the baseline read, so a run's first frame
|
|
143
|
+
* is not charged everything since boot.
|
|
144
|
+
*
|
|
145
|
+
* `renderer` is the raw renderer; one that publishes no stage totals gets the whole call as `engineJs`.
|
|
146
|
+
* Wasm time is wall time on the page's clock; the totals only ever grow, so a negative difference (a
|
|
147
|
+
* restarted engine) reads as zero rather than a negative stage.
|
|
148
|
+
*/
|
|
149
|
+
export function createStageReader(
|
|
150
|
+
renderer: () => unknown,
|
|
151
|
+
): (jsBefore: number, engineCall: number, jsAfter: number) => IFrameStageSample | undefined {
|
|
152
|
+
const sample = emptyStageSample();
|
|
153
|
+
const last = new Float64Array(TOTAL_NAMES.length);
|
|
154
|
+
let haveLast = false;
|
|
155
|
+
return (jsBefore, engineCall, jsAfter) => {
|
|
156
|
+
sample.jsBefore = positive(jsBefore);
|
|
157
|
+
sample.jsAfter = positive(jsAfter);
|
|
158
|
+
const totals = (renderer() as IEngineCpuHost | null | undefined)?.info?.engine?.cpuMs;
|
|
159
|
+
if (totals === undefined) {
|
|
160
|
+
// A stage the engine did not measure is absent, never zero: the window leaves it out and the sum skips it.
|
|
161
|
+
sample.engineJs = positive(engineCall);
|
|
162
|
+
for (const name of UNMEASURED_WITHOUT_TOTALS) sample[name] = undefined;
|
|
163
|
+
return sample;
|
|
164
|
+
}
|
|
165
|
+
let delta0 = 0;
|
|
166
|
+
const delta = (index: number): number => {
|
|
167
|
+
const total = totals[TOTAL_NAMES[index] as keyof IEngineCpuTotals] ?? 0;
|
|
168
|
+
const previous = last[index] ?? 0;
|
|
169
|
+
last[index] = total;
|
|
170
|
+
delta0 = positive(total - previous);
|
|
171
|
+
return delta0;
|
|
172
|
+
};
|
|
173
|
+
const virtualPages = delta(0);
|
|
174
|
+
const draws = delta(1);
|
|
175
|
+
const shadowLists = delta(2);
|
|
176
|
+
const prepare = delta(3);
|
|
177
|
+
const encode = delta(4);
|
|
178
|
+
const post = delta(5);
|
|
179
|
+
const scene = delta(6);
|
|
180
|
+
const host = delta(7);
|
|
181
|
+
const compute = delta(8);
|
|
182
|
+
const submit = delta(9);
|
|
183
|
+
const poll = delta(10);
|
|
184
|
+
const tail = delta(11);
|
|
185
|
+
const inRenderer = delta(12);
|
|
186
|
+
const inDatabase = delta(13);
|
|
187
|
+
const targets = delta(14);
|
|
188
|
+
if (!haveLast) {
|
|
189
|
+
haveLast = true;
|
|
190
|
+
return undefined;
|
|
191
|
+
}
|
|
192
|
+
const encodeOnly = positive(encode - post);
|
|
193
|
+
sample.wasmScene = scene;
|
|
194
|
+
sample.wasmPlan = prepare;
|
|
195
|
+
sample.wasmCompute = compute;
|
|
196
|
+
sample.wasmEncode = encodeOnly;
|
|
197
|
+
sample.wasmPost = post;
|
|
198
|
+
sample.wasmSubmit = submit;
|
|
199
|
+
sample.wasmPoll = poll;
|
|
200
|
+
sample.wasmTail = tail;
|
|
201
|
+
sample.wasmRendererGap = positive(inRenderer - prepare - encode);
|
|
202
|
+
sample.wasmDatabaseGap = positive(inDatabase - scene - inRenderer);
|
|
203
|
+
sample.wasmTargets = targets;
|
|
204
|
+
sample.planVirtualPages = virtualPages;
|
|
205
|
+
sample.planDraws = draws;
|
|
206
|
+
sample.planShadowLists = shadowLists;
|
|
207
|
+
sample.wasmOther = positive(host - (inDatabase + targets + compute + submit + poll + tail));
|
|
208
|
+
sample.engineJs = positive(engineCall - host);
|
|
209
|
+
return sample;
|
|
210
|
+
};
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
/**
|
|
214
|
+
* Whether this launch reads the stage meters. On unless the launch turns them off: `?tnStages=0` in the URL,
|
|
215
|
+
* `TN_STAGES=0` in a native host's environment, or `globalThis.__tnStages = false` before the game boots.
|
|
216
|
+
* Off, the frame reads no extra clock, the engine reads none around its stages, and the window carries no
|
|
217
|
+
* `stages`: the paired A/B that prices the meters runs one build with this switch alone.
|
|
218
|
+
*/
|
|
219
|
+
export function stageMetersRequested(): boolean {
|
|
220
|
+
const host = globalThis as { process?: { env?: Record<string, unknown> }; __tnStages?: unknown };
|
|
221
|
+
const fromEnv = host.process?.env?.TN_STAGES;
|
|
222
|
+
if (fromEnv === "0" || fromEnv === "false") return false;
|
|
223
|
+
const query = globalThis.location?.search;
|
|
224
|
+
if (typeof query === "string" && /[?&]tnStages=(?:0|false)(?:&|$)/u.test(query)) return false;
|
|
225
|
+
return host.__tnStages !== false;
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
interface IEngineWorkHost {
|
|
229
|
+
readonly info?: {
|
|
230
|
+
readonly engine?: {
|
|
231
|
+
readonly work?: {
|
|
232
|
+
readonly dirtyTransforms?: number;
|
|
233
|
+
readonly castersMoving?: number;
|
|
234
|
+
readonly queueWriteBytes?: number;
|
|
235
|
+
};
|
|
236
|
+
};
|
|
237
|
+
};
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
/**
|
|
241
|
+
* The frame's work counts beside its stages (PRD-771), as `IFrameCounters` fields: transforms moved, shadow
|
|
242
|
+
* casters judged moving, bytes the GPU queue took (`gpuBytes`, buffer writes only), the engine ABI calls
|
|
243
|
+
* (`hostCalls`, which on the owned engine are the bridge crossings the caller passes in) and the JS heap the
|
|
244
|
+
* frame grew (`jsAllocBytes`, from `performance.memory`; a frame the collector ran in reads 0, so it is a floor).
|
|
245
|
+
* The first read is the baseline. A count the engine does not publish stays absent, never zero.
|
|
246
|
+
*/
|
|
247
|
+
export function createWorkReader(
|
|
248
|
+
renderer: () => unknown,
|
|
249
|
+
): (
|
|
250
|
+
crossings: number | undefined,
|
|
251
|
+
) =>
|
|
252
|
+
| Pick<
|
|
253
|
+
IFrameCounters,
|
|
254
|
+
"castersMoving" | "dirtyTransforms" | "gpuBytes" | "hostCalls" | "jsAllocBytes"
|
|
255
|
+
>
|
|
256
|
+
| undefined {
|
|
257
|
+
let last: { dirty: number; moving: number; bytes: number } | undefined;
|
|
258
|
+
let heap: number | undefined;
|
|
259
|
+
return (crossings) => {
|
|
260
|
+
const work = (renderer() as IEngineWorkHost | null | undefined)?.info?.engine?.work;
|
|
261
|
+
const memory = (globalThis.performance as { memory?: { usedJSHeapSize?: unknown } } | undefined)
|
|
262
|
+
?.memory?.usedJSHeapSize;
|
|
263
|
+
const used = typeof memory === "number" && Number.isFinite(memory) ? memory : undefined;
|
|
264
|
+
const grown = used === undefined || heap === undefined ? undefined : positive(used - heap);
|
|
265
|
+
heap = used;
|
|
266
|
+
if (
|
|
267
|
+
work === undefined ||
|
|
268
|
+
typeof work.dirtyTransforms !== "number" ||
|
|
269
|
+
typeof work.castersMoving !== "number" ||
|
|
270
|
+
typeof work.queueWriteBytes !== "number"
|
|
271
|
+
)
|
|
272
|
+
return undefined;
|
|
273
|
+
const now = {
|
|
274
|
+
dirty: work.dirtyTransforms,
|
|
275
|
+
moving: work.castersMoving,
|
|
276
|
+
bytes: work.queueWriteBytes,
|
|
277
|
+
};
|
|
278
|
+
const previous = last;
|
|
279
|
+
last = now;
|
|
280
|
+
if (previous === undefined) return undefined;
|
|
281
|
+
return {
|
|
282
|
+
castersMoving: positive(now.moving - previous.moving),
|
|
283
|
+
dirtyTransforms: positive(now.dirty - previous.dirty),
|
|
284
|
+
gpuBytes: positive(now.bytes - previous.bytes),
|
|
285
|
+
...(crossings === undefined ? {} : { hostCalls: crossings }),
|
|
286
|
+
...(grown === undefined ? {} : { jsAllocBytes: grown }),
|
|
287
|
+
};
|
|
288
|
+
};
|
|
289
|
+
}
|