@threenative/core 0.3.11 → 0.3.13
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 +1 -1
- package/capabilities.json +1988 -204
- package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
- package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
- package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
- package/dist/chunk-4SRAQFTU.js +133 -0
- package/dist/chunk-CFGTPFUH.js +231 -0
- package/dist/chunk-DIPIJICH.js +8916 -0
- package/dist/chunk-EEABDLUC.js +2237 -0
- package/dist/chunk-EFWZWLPY.js +1895 -0
- package/dist/chunk-GXY7B3JG.js +46 -0
- package/dist/chunk-GYUZJQ7U.js +280 -0
- package/dist/chunk-H4J6IAJE.js +504 -0
- package/dist/chunk-KIRUKTBQ.js +187 -0
- package/dist/chunk-QWJEMUUT.js +94 -0
- package/dist/chunk-SV4QVUTQ.js +31 -0
- package/dist/chunk-U4YHUKKL.js +615 -0
- package/dist/chunk-VP43GIWW.js +18 -0
- package/dist/chunk-XDTZ4QMO.js +160 -0
- package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
- package/dist/{game-DzMcitDO.d.ts → game-k8K3hZai.d.ts} +85 -9
- package/dist/hot.d.ts +5 -4
- package/dist/hot.js +5 -52
- package/dist/index.d.ts +633 -1351
- package/dist/index.js +12873 -23068
- package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-DPTzeCcD.d.ts} +35 -3
- package/dist/playtest.d.ts +5 -4
- package/dist/playtest.js +25 -75
- package/dist/quality-BYqKGAwo.d.ts +868 -0
- package/dist/react-css.js +1 -215
- package/dist/react.d.ts +3 -2
- package/dist/render-environment.d.ts +170 -0
- package/dist/render-environment.js +352 -0
- package/dist/{renderer-rZm0hVqq.d.ts → renderer-BtOSseYf.d.ts} +42 -35
- package/dist/spells/index.d.ts +643 -0
- package/dist/spells/index.js +1558 -0
- package/dist/spells/ultra/index.d.ts +1600 -0
- package/dist/spells/ultra/index.js +6804 -0
- package/dist/terrain-jobs-worker.js +1 -123
- package/dist/two-sided-foliage-W523J3UM.js +1 -0
- package/dist/ui-layer.js +6 -384
- package/dist/worker.js +13 -43
- package/dist/world.d.ts +988 -268
- package/dist/world.js +17464 -18290
- package/mcp/animation-server.mjs +1 -1
- package/mcp/animation.mjs +2 -3
- package/mcp/engine-server.mjs +245 -52
- package/mcp/servers.mjs +10 -3
- package/mcp/terrain.mjs +8 -0
- package/package.json +19 -7
- package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
- package/patches/three@0.187.0.patch +2004 -407
- package/src/animation-batch.ts +193 -0
- package/src/animation-layers.ts +7 -3
- package/src/animation.ts +209 -29
- package/src/asset-cache.ts +3 -3
- package/src/asset-memo.ts +202 -0
- package/src/assets.ts +437 -125
- package/src/auto-batch.ts +190 -44
- package/src/card-lod.ts +152 -0
- package/src/compressed-texture-preparation.ts +1008 -0
- package/src/compute-driven.ts +1 -1
- package/src/config.ts +8 -0
- package/src/debug.ts +103 -22
- package/src/dev-global.ts +54 -0
- package/src/engine-hooks.ts +37 -0
- package/src/frame-budget.ts +50 -23
- package/src/game-boot-phase.ts +269 -0
- package/src/game-dev-tools.ts +86 -0
- package/src/game-frame-loop.ts +958 -0
- package/src/game-renderer-metrics.ts +77 -0
- package/src/game-startup.ts +1076 -0
- package/src/game-ui.ts +84 -0
- package/src/game-validate.ts +70 -0
- package/src/game.ts +198 -2264
- package/src/gamepad-mappings.ts +269 -0
- package/src/generated/console-markers.ts +13 -0
- package/src/geometry-capture.ts +28 -4
- package/src/gpu-readings.ts +98 -0
- package/src/gpu-scene-bvh.ts +149 -36
- package/src/hot.ts +4 -7
- package/src/index.ts +141 -9
- package/src/input.ts +237 -25
- package/src/instanced-batch-lod.ts +3 -8
- package/src/interpolation.ts +171 -40
- package/src/launch-diagnostics.ts +22 -12
- package/src/look/ao-admission.ts +25 -0
- package/src/look/auto-exposure.ts +5 -16
- package/src/look/default-tone-mapping.ts +41 -5
- package/src/look/filmic-tone-mapping.ts +15 -13
- package/src/look/local-exposure.ts +2 -7
- package/src/look/look-diagnostics.ts +3 -3
- package/src/look/quad-pass.ts +21 -0
- package/src/look/quality.ts +14 -5
- package/src/look/unreal-bloom.ts +4 -13
- package/src/look/world-environment.ts +113 -103
- package/src/loop.ts +29 -0
- package/src/merge-parts.ts +20 -24
- package/src/model-lod.ts +139 -17
- package/src/particle-kinds.ts +515 -0
- package/src/particle-significance.ts +12 -0
- package/src/particles.ts +19 -10
- package/src/picking.ts +17 -3
- package/src/platform.ts +23 -4
- package/src/playtest.ts +27 -1
- package/src/profiling/FrameStages.ts +5 -6
- package/src/profiling/Spans.ts +3 -17
- package/src/profiling/debug-telemetry.ts +2 -6
- package/src/profiling/render-list-validate.ts +6 -15
- package/src/projection-apply.ts +4 -1
- package/src/projection-marker.ts +2 -1
- package/src/projection-plan.ts +9 -6
- package/src/quiet-markers.ts +3 -10
- package/src/render/cpu-bvh.ts +100 -0
- package/src/render/depth-pyramid.ts +6 -14
- package/src/render/environment/environmentContribution.ts +202 -0
- package/src/render/environment/environmentRadiance.ts +44 -0
- package/src/render/environment/environmentSampleCache.ts +56 -0
- package/src/render/environment/environmentSampling.ts +201 -0
- package/src/render/environment/environmentSnapshot.ts +71 -0
- package/src/render/environment/gate.ts +57 -0
- package/src/render/mesh-pool.ts +4 -20
- package/src/render/probe-trace.ts +872 -0
- package/src/render/probe-volume.ts +780 -34
- package/src/render/radiance-cache.ts +17 -0
- package/src/render/resolution-subrect.ts +2 -0
- package/src/render/rough-diffuse.ts +46 -12
- package/src/render/soft-shadow.ts +27 -12
- package/src/render/virtual-shadow-adaptive.ts +55 -0
- package/src/render/virtual-shadow-casters.ts +175 -0
- package/src/render/virtual-shadow-layers.ts +76 -0
- package/src/render/virtual-shadow-level.ts +224 -0
- package/src/render/virtual-shadow-markers.ts +193 -0
- package/src/render/virtual-shadow-options.ts +370 -0
- package/src/render/virtual-shadow-pages.ts +5 -0
- package/src/render/virtual-shadow-partial.ts +13 -0
- package/src/render/virtual-shadow.ts +231 -1008
- package/src/render/world-impostor-surface.ts +402 -40
- package/src/render/world-impostor.ts +5 -2
- package/src/render-camera-cull.ts +98 -3
- package/src/render-environment.ts +41 -0
- package/src/render-pass-budget.ts +34 -7
- package/src/renderProjection.ts +22 -0
- package/src/renderer-config.ts +36 -0
- package/src/renderer-facts.ts +37 -0
- package/src/renderer.ts +144 -65
- package/src/resolution-scaler.ts +3 -2
- package/src/scene-entry-inspectors.ts +61 -0
- package/src/snow-field.ts +2 -1
- package/src/spells/cast-pool.ts +361 -0
- package/src/spells/index.ts +177 -0
- package/src/spells/mechanisms.ts +295 -0
- package/src/spells/reaction-field.ts +415 -0
- package/src/spells/spell-lights.ts +139 -0
- package/src/spells/spell-world.ts +187 -0
- package/src/spells/spell.ts +397 -0
- package/src/spells/spells.ts +283 -0
- package/src/spells/ultra/engine/camera.ts +184 -0
- package/src/spells/ultra/engine/quality.ts +96 -0
- package/src/spells/ultra/index.ts +52 -0
- package/src/spells/ultra/main.ts +305 -0
- package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
- package/src/spells/ultra/spells/cast.ts +233 -0
- package/src/spells/ultra/spells/fire.ts +1267 -0
- package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
- package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
- package/src/spells/ultra/vfx/FxTarget.ts +61 -0
- package/src/spells/ultra/vfx/GroundField.ts +1399 -0
- package/src/spells/ultra/vfx/Particles.ts +1475 -0
- package/src/spells/ultra/vfx/Ribbons.ts +645 -0
- package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
- package/src/spells/ultra/vfx/Volumes.ts +489 -0
- package/src/spells/ultra/vfx/common.ts +1195 -0
- package/src/spells/ultra/vfx/noise.ts +441 -0
- package/src/startup-offscreen-bytes.ts +78 -0
- package/src/startup-readiness.ts +128 -34
- package/src/static-transform.ts +25 -19
- package/src/streamed-textures.ts +112 -0
- package/src/streaming.ts +68 -4
- package/src/texture-streaming.ts +331 -0
- package/src/version.ts +1 -1
- package/src/warmup.ts +56 -8
- package/src/water-surface.ts +9 -3
- package/src/worker.ts +12 -2
- package/src/world-bundle-safety.ts +446 -0
- package/src/world-cell-batches.ts +1178 -0
- package/src/world-cell-chunks.ts +1128 -0
- package/src/world-cell-data.ts +995 -0
- package/src/world-cell-impostors.ts +1461 -0
- package/src/world-cell-lod-bias.ts +151 -0
- package/src/world-cell-models.ts +1074 -0
- package/src/world-cell-options.ts +177 -0
- package/src/world-cell-placements.ts +798 -0
- package/src/world-cell-prewarm.ts +592 -0
- package/src/world-cell-readiness.ts +357 -0
- package/src/world-cell-records.ts +401 -0
- package/src/world-cell-render-bundles.ts +459 -0
- package/src/world-cell-render-gpu-dress.ts +710 -0
- package/src/world-cell-render-main-cull.ts +540 -0
- package/src/world-cell-render-shadow-claims.ts +198 -0
- package/src/world-cell-render-util.ts +259 -0
- package/src/world-cell-render.ts +1501 -0
- package/src/world-cell-residency.ts +754 -0
- package/src/world-cell-stale.ts +238 -0
- package/src/world-cells.ts +1335 -10418
- package/src/world-chunk-shadow.ts +308 -0
- package/src/world-collar.ts +315 -0
- package/src/world-gpu-flags.ts +131 -0
- package/src/world-gpu-readback.ts +881 -0
- package/src/world-gpu-reference.ts +524 -0
- package/src/world-gpu-scene.ts +256 -2286
- package/src/world-gpu-shadow.ts +203 -0
- package/src/world-gpu-types.ts +409 -0
- package/src/world-gpu-validation.ts +518 -0
- package/src/world-heightfield.ts +802 -0
- package/src/world-load-limiter.ts +111 -0
- package/src/world-model-sections.ts +80 -0
- package/src/world-noise.ts +241 -0
- package/src/world-package.ts +42 -0
- package/src/world-region.ts +1 -1
- package/src/world-river-ribbon.ts +282 -0
- package/src/world-root-frame.ts +39 -0
- package/src/world-shore-field.ts +91 -0
- package/src/world-static-pose.ts +163 -0
- package/src/world-surface-sampler.ts +48 -0
- package/src/world-terrain-splat.ts +361 -153
- package/src/world-tile-budget.ts +249 -0
- package/src/world-tile-geometry.ts +469 -0
- package/src/world-tile-lod.ts +408 -0
- package/src/world-tile-observation.ts +566 -0
- package/src/world-tile-stitch.ts +166 -0
- package/src/world-tiles.ts +247 -1755
- package/src/world-validate.ts +6 -14
- package/src/world-warm.ts +51 -0
- package/src/world-water-bodies.ts +359 -0
- package/src/world.ts +48 -741
package/src/compute-driven.ts
CHANGED
|
@@ -113,7 +113,7 @@ export class ComputeDrivenRegistry {
|
|
|
113
113
|
): void {
|
|
114
114
|
const simulatedSeconds =
|
|
115
115
|
simulation === undefined ? undefined : simulation.tick() * simulation.step;
|
|
116
|
-
if (camera !== undefined) {
|
|
116
|
+
if (camera !== undefined && !this.#significance.idle) {
|
|
117
117
|
const candidates: IBudgetCandidate[] = [];
|
|
118
118
|
for (const { object, driven } of this.#entries.values()) {
|
|
119
119
|
if (
|
package/src/config.ts
CHANGED
|
@@ -336,6 +336,14 @@ export interface IThreeNativeConfig {
|
|
|
336
336
|
readonly orientation?: ThreeNativeOrientation;
|
|
337
337
|
readonly fullscreen?: boolean;
|
|
338
338
|
readonly keepScreenOn?: boolean;
|
|
339
|
+
/**
|
|
340
|
+
* CPU priority of a shipped native game (PRD-859). `"game"`, the default, raises the game, render
|
|
341
|
+
* and present threads above other programs and lowers the game's own background work (shader
|
|
342
|
+
* compiles, workers, the HUD processes), through the route each OS allows without admin rights.
|
|
343
|
+
* `"normal"` keeps the OS default. The player reports what the OS applied on its
|
|
344
|
+
* `TN_PROCESS_PRIORITY` line. The browser owns scheduling, so a web build ignores it.
|
|
345
|
+
*/
|
|
346
|
+
readonly priority?: "game" | "normal";
|
|
339
347
|
/**
|
|
340
348
|
* Maximum native presentation rate in frames per second. Left out, it follows the display's own
|
|
341
349
|
* refresh rate capped at 120 on desktop and web, and stays 60 on mobile where the ceiling is
|
package/src/debug.ts
CHANGED
|
@@ -3,18 +3,112 @@
|
|
|
3
3
|
*
|
|
4
4
|
* Two questions an agent answers differently in every game, both of which cost a rewrite: how do I
|
|
5
5
|
* turn this on for one run without changing the code, and how does a capture script reach the object
|
|
6
|
-
* it wants to look at. The answers here are one function each,
|
|
7
|
-
* looks.
|
|
6
|
+
* it wants to look at. The answers here are one function each, neither decides how anything looks.
|
|
8
7
|
*/
|
|
9
8
|
|
|
10
|
-
|
|
11
|
-
const HOST_KEY = "__THREENATIVE__";
|
|
9
|
+
import { devGlobal, publishDevGlobal } from "./dev-global.js";
|
|
12
10
|
|
|
13
11
|
/** `freeCam` → `FREE_CAM`. A name a developer typed becomes a name a shell can set. */
|
|
14
12
|
function envName(name: string): string {
|
|
15
13
|
return `TN_DEBUG_${name.replace(/([a-z0-9])([A-Z])/gu, "$1_$2").toUpperCase()}`;
|
|
16
14
|
}
|
|
17
15
|
|
|
16
|
+
/**
|
|
17
|
+
* The three seams a launch has, named once. A native host sets the environment variable, a browser
|
|
18
|
+
* page asks with the query parameter, and a test or capture harness sets the global before boot.
|
|
19
|
+
*/
|
|
20
|
+
export interface ILaunchFlagSpec {
|
|
21
|
+
/** Environment variable a native host sets, e.g. `TN_TERRAIN_VALIDATE`. */
|
|
22
|
+
readonly environment: string;
|
|
23
|
+
/** Query parameter a browser asks with, e.g. `tnTerrainValidate`. */
|
|
24
|
+
readonly query: string;
|
|
25
|
+
/** Global a test or harness sets before the game boots, e.g. `__tnTerrainValidate`. */
|
|
26
|
+
readonly global?: string;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* Every seam that named `flag`, in the order they are read: environment, query string, global.
|
|
31
|
+
*
|
|
32
|
+
* An empty environment variable is skipped — a shell that exports a name with no value did not ask
|
|
33
|
+
* for anything — while an empty value on any other seam means the seam named the flag and had no
|
|
34
|
+
* value to give, which is a URL's way of saying yes.
|
|
35
|
+
*/
|
|
36
|
+
function readLaunchSeams(spec: ILaunchFlagSpec, search?: string): readonly string[] {
|
|
37
|
+
const values: string[] = [];
|
|
38
|
+
if (spec.environment.length > 0) {
|
|
39
|
+
const env = envValue(spec.environment);
|
|
40
|
+
if (env !== undefined && env !== "") values.push(env);
|
|
41
|
+
}
|
|
42
|
+
const query = search ?? globalThis.location?.search;
|
|
43
|
+
if (typeof query === "string") {
|
|
44
|
+
const fromQuery = new URLSearchParams(query).get(spec.query);
|
|
45
|
+
if (fromQuery !== null) values.push(fromQuery);
|
|
46
|
+
}
|
|
47
|
+
if (spec.global !== undefined) {
|
|
48
|
+
const fromGlobal: unknown = (globalThis as Record<string, unknown>)[spec.global];
|
|
49
|
+
if (typeof fromGlobal === "string") values.push(fromGlobal);
|
|
50
|
+
else if (typeof fromGlobal === "number") values.push(String(fromGlobal));
|
|
51
|
+
else if (typeof fromGlobal === "boolean") values.push(fromGlobal ? "true" : "false");
|
|
52
|
+
}
|
|
53
|
+
return values;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** `0` and `false` are the only two spellings of off; a named-but-empty value is on. */
|
|
57
|
+
function isOff(value: string): boolean {
|
|
58
|
+
return value === "0" || value === "false";
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Whether this launch asked for a flag, on one rule for every subsystem.
|
|
63
|
+
*
|
|
64
|
+
* `askedFor` says which answer the caller cares about: an opt-in switch (`"on"`, the default) is off
|
|
65
|
+
* when no seam asked for it, and an opt-out switch (`"off"`) is on unless some seam asked it off.
|
|
66
|
+
* Every seam that names the flag is heard, so a global a test sets is not lost behind an environment
|
|
67
|
+
* variable that happens to disagree; what changes from the sixteen hand-written readers this
|
|
68
|
+
* replaces is the vocabulary, not the seams: `0` and `false` are off and everything else is on.
|
|
69
|
+
*
|
|
70
|
+
* `search` is the query string to read, for a caller that already read the URL once at setup.
|
|
71
|
+
*
|
|
72
|
+
* @situation read one of the engine's launch switches the same way every subsystem does
|
|
73
|
+
* @example const validate = readLaunchFlag({ environment: "TN_TERRAIN_VALIDATE", query: "tnTerrainValidate" });
|
|
74
|
+
* @constraint `0` and `false` are off; a named-but-empty value is on; an empty variable is unset
|
|
75
|
+
*/
|
|
76
|
+
export function readLaunchFlag(
|
|
77
|
+
spec: ILaunchFlagSpec,
|
|
78
|
+
askedFor: "on" | "off" = "on",
|
|
79
|
+
search?: string,
|
|
80
|
+
): boolean {
|
|
81
|
+
const values = readLaunchSeams(spec, search);
|
|
82
|
+
return askedFor === "off"
|
|
83
|
+
? values.some((value) => isOff(value))
|
|
84
|
+
: values.some((value) => !isOff(value));
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* The text this launch gave a flag, or `undefined` when no seam named it.
|
|
89
|
+
*
|
|
90
|
+
* For switches whose value is not a yes or no — an occlusion mode, a numeric override — the caller
|
|
91
|
+
* parses. An empty string means a seam named the flag with no value.
|
|
92
|
+
*
|
|
93
|
+
* @situation read a launch override whose value is not a boolean
|
|
94
|
+
* @example const mode = readLaunchValue({ environment: "TN_OCCLUSION", query: "tnOcclusion" });
|
|
95
|
+
*/
|
|
96
|
+
export function readLaunchValue(spec: ILaunchFlagSpec): string | undefined {
|
|
97
|
+
return readLaunchSeams(spec)[0];
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* Every value this launch gave a flag, one per seam that named it, in the order they are read.
|
|
102
|
+
*
|
|
103
|
+
* For the switches whose answer is not a yes or a no — a tri-state, a table of spellings — the
|
|
104
|
+
* caller classifies the whole set rather than only the first seam's answer.
|
|
105
|
+
*
|
|
106
|
+
* @situation classify every value a launch gave one switch
|
|
107
|
+
*/
|
|
108
|
+
export function readLaunchValues(spec: ILaunchFlagSpec): readonly string[] {
|
|
109
|
+
return readLaunchSeams(spec);
|
|
110
|
+
}
|
|
111
|
+
|
|
18
112
|
/**
|
|
19
113
|
* `process.env` on a host that installed one, narrowed rather than asserted exactly as
|
|
20
114
|
* `isDevLaunch` does in `game.ts`: it exists on the native runtime and not in a browser bundle.
|
|
@@ -31,15 +125,10 @@ function envValue(name: string): string | undefined {
|
|
|
31
125
|
return typeof value === "string" ? value : undefined;
|
|
32
126
|
}
|
|
33
127
|
|
|
34
|
-
/** Not one of the two spellings of off. */
|
|
35
|
-
function isOn(value: string): boolean {
|
|
36
|
-
return value !== "0" && value !== "false";
|
|
37
|
-
}
|
|
38
|
-
|
|
39
128
|
/**
|
|
40
129
|
* A debug switch read from the URL, or from the environment on a native launch.
|
|
41
130
|
*
|
|
42
|
-
* @situation read a debug toggle from the URL
|
|
131
|
+
* @situation read a debug toggle from the URL, an environment variable or a harness global
|
|
43
132
|
*
|
|
44
133
|
* A browser asks with the query string — `?freeCam`, or `?freeCam=0` to force it off — and a native
|
|
45
134
|
* launch asks with `TN_DEBUG_FREE_CAM`, because a query string is not something a developer sets on
|
|
@@ -47,14 +136,7 @@ function isOn(value: string): boolean {
|
|
|
47
136
|
* "off" rather than quietly turning it back on.
|
|
48
137
|
*/
|
|
49
138
|
export function debugFlag(name: string): boolean {
|
|
50
|
-
|
|
51
|
-
// `?freeCam` is on, because the query string has no other way to say it.
|
|
52
|
-
const env = envValue(envName(name));
|
|
53
|
-
if (env !== undefined && env !== "" && isOn(env)) return true;
|
|
54
|
-
const search: unknown = globalThis.location?.search;
|
|
55
|
-
if (typeof search !== "string") return false;
|
|
56
|
-
const value = new URLSearchParams(search).get(name);
|
|
57
|
-
return value !== null && isOn(value);
|
|
139
|
+
return readLaunchFlag({ environment: envName(name), query: name });
|
|
58
140
|
}
|
|
59
141
|
|
|
60
142
|
/**
|
|
@@ -74,9 +156,8 @@ export function exposeDebug(name: string, value: unknown): void {
|
|
|
74
156
|
const isDev =
|
|
75
157
|
(import.meta as ImportMeta & { env?: Record<"DEV", boolean | undefined> }).env?.DEV === true;
|
|
76
158
|
if (!isDev) return;
|
|
77
|
-
const tools = (
|
|
78
|
-
const debug = tools.debug ?? {};
|
|
159
|
+
const tools = devGlobal(globalThis) ?? {};
|
|
160
|
+
const debug = (tools.debug as Record<string, unknown> | undefined) ?? {};
|
|
79
161
|
debug[name] = value;
|
|
80
|
-
|
|
81
|
-
Reflect.set(globalThis, HOST_KEY, tools);
|
|
162
|
+
publishDevGlobal("debug", debug, globalThis);
|
|
82
163
|
}
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one owner of `__THREENATIVE__`, the object every dev surface publishes under.
|
|
3
|
+
*
|
|
4
|
+
* Five places used to spell the key itself — the debug flag, hot reload, the game's dev tools, the
|
|
5
|
+
* UI overlay and the engine's export — so the global's name and its shape were written twice at
|
|
6
|
+
* least. The worker keeps its own mirror list: that list is a typed tuple its mirror machinery is
|
|
7
|
+
* built from, and moving it here changed what the worker host forwarded.
|
|
8
|
+
*
|
|
9
|
+
* Nothing here decides how anything looks: it is the seam a capture script, the console and the dev
|
|
10
|
+
* overlay reach the running game through.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
/** The property name a dev surface publishes under, on the window and on a worker's global. */
|
|
14
|
+
export const DEV_GLOBAL_KEY = "__THREENATIVE__";
|
|
15
|
+
|
|
16
|
+
/** What the game's own dev tools publish: a snapshot, and an armed geometry capture. */
|
|
17
|
+
export interface IDevTools {
|
|
18
|
+
snapshot(): import("./entities.js").EntitySnapshot;
|
|
19
|
+
/**
|
|
20
|
+
* Arms one per-object geometry capture for a development overlay. Absent until the game has a
|
|
21
|
+
* render loop; the overlay treats that as "not ready", never as an empty scene.
|
|
22
|
+
*/
|
|
23
|
+
geometry?(
|
|
24
|
+
request?: import("./geometry-capture.js").IGeometryCaptureRequest,
|
|
25
|
+
): Promise<import("./geometry-capture.js").IGeometryCaptureReport>;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** What a dev surface may publish under {@link DEV_GLOBAL_KEY}. */
|
|
29
|
+
export type DevGlobal = Partial<IDevTools> & Record<string, unknown>;
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* The global a host installed, or `undefined` outside a dev launch.
|
|
33
|
+
*
|
|
34
|
+
* `scope` is required on purpose: a default of `globalThis` would make an explicit `undefined` read
|
|
35
|
+
* the page's global, which is exactly the worker case a caller is asking about.
|
|
36
|
+
*/
|
|
37
|
+
export function devGlobal(scope: unknown): DevGlobal | undefined {
|
|
38
|
+
const value = (scope as Record<string, unknown> | undefined)?.[DEV_GLOBAL_KEY];
|
|
39
|
+
return typeof value === "object" && value !== null ? (value as DevGlobal) : undefined;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** Adds one member to the global, keeping whatever another surface already published. */
|
|
43
|
+
export function publishDevGlobal(name: string, value: unknown, scope: unknown): void {
|
|
44
|
+
const host = scope as Record<string, unknown> | undefined;
|
|
45
|
+
if (host === undefined) return;
|
|
46
|
+
// In place: a surface that published earlier keeps its identity, which is what lets a disposer
|
|
47
|
+
// check `devGlobal(host) === mine` and leave another surface's members alone.
|
|
48
|
+
const current = devGlobal(scope);
|
|
49
|
+
if (current !== undefined) {
|
|
50
|
+
current[name] = value;
|
|
51
|
+
return;
|
|
52
|
+
}
|
|
53
|
+
host[DEV_GLOBAL_KEY] = { [name]: value };
|
|
54
|
+
}
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import type { Matrix4, Object3D } from "three";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The method the owned engine puts on every `Object3D` to copy its world matrix into a caller's
|
|
5
|
+
* `Matrix4`. Plain three.js has no such method and reads `matrixWorld` instead.
|
|
6
|
+
*
|
|
7
|
+
* The engine defines this name in `runtime-native/src/engine/abi/bindings_scene.cpp` and probes it in
|
|
8
|
+
* `adapters/v8/math/entry.js`. `__tests__/engine-hooks.spec.ts` holds those two copies to this one,
|
|
9
|
+
* so a rename on either side fails a spec instead of silently taking every caller down the slow path.
|
|
10
|
+
*/
|
|
11
|
+
export const COPY_MATRIX_WORLD_HOOK = "__tnCopyMatrixWorld";
|
|
12
|
+
|
|
13
|
+
type CopyMatrixWorld = (target: Matrix4) => void;
|
|
14
|
+
|
|
15
|
+
/** An `Object3D` that may carry the engine's hook; the property is absent on plain three.js. */
|
|
16
|
+
type HookCarrier = Object3D & { readonly [COPY_MATRIX_WORLD_HOOK]?: unknown };
|
|
17
|
+
|
|
18
|
+
function hookOf(object: Object3D): CopyMatrixWorld | undefined {
|
|
19
|
+
const hook = (object as HookCarrier)[COPY_MATRIX_WORLD_HOOK];
|
|
20
|
+
return typeof hook === "function" ? (hook as CopyMatrixWorld) : undefined;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** Whether `object` belongs to the owned engine, which copies world matrices out instead of aliasing them. */
|
|
24
|
+
export function hasCopyMatrixWorldHook(object: Object3D): boolean {
|
|
25
|
+
return hookOf(object) !== undefined;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Copy `object`'s current world matrix into `target` through the engine's hook.
|
|
30
|
+
* @returns false when the object has no hook, so the caller reads `object.matrixWorld` itself
|
|
31
|
+
*/
|
|
32
|
+
export function copyMatrixWorld(object: Object3D, target: Matrix4): boolean {
|
|
33
|
+
const hook = hookOf(object);
|
|
34
|
+
if (hook === undefined) return false;
|
|
35
|
+
hook.call(object, target);
|
|
36
|
+
return true;
|
|
37
|
+
}
|
package/src/frame-budget.ts
CHANGED
|
@@ -21,6 +21,7 @@
|
|
|
21
21
|
* instead of skipping.
|
|
22
22
|
*/
|
|
23
23
|
|
|
24
|
+
import { CONSOLE_MARKER } from "./generated/console-markers.js";
|
|
24
25
|
import type { IFrameCounters } from "./profiling/FrameCounters.js";
|
|
25
26
|
import { type IFrameStageSample, RENDER_STAGES, STAGE_PARTS } from "./profiling/FrameStages.js";
|
|
26
27
|
import {
|
|
@@ -62,9 +63,9 @@ function requireTarget(target: ITargetFps): ITargetFps {
|
|
|
62
63
|
}
|
|
63
64
|
|
|
64
65
|
/** Marker printed once per report window. */
|
|
65
|
-
export const FRAME_BUDGET_MARKER =
|
|
66
|
+
export const FRAME_BUDGET_MARKER = CONSOLE_MARKER.frameBudget;
|
|
66
67
|
/** Marker printed the moment a gap between presented frames exceeds `hitchMs`. */
|
|
67
|
-
export const FRAME_HITCH_MARKER =
|
|
68
|
+
export const FRAME_HITCH_MARKER = CONSOLE_MARKER.frameHitch;
|
|
68
69
|
|
|
69
70
|
/**
|
|
70
71
|
* The named parts of one presented frame. They partition the frame: `hostGap` is the time before
|
|
@@ -486,10 +487,12 @@ export interface IFrameBudgetWindow {
|
|
|
486
487
|
export interface IFrameBudgetSimulation {
|
|
487
488
|
readonly tick: () => number;
|
|
488
489
|
readonly step: number;
|
|
490
|
+
/** False counts presented frames while the simulation has not advanced in the window. */
|
|
491
|
+
readonly clockFrozen?: boolean;
|
|
489
492
|
}
|
|
490
493
|
|
|
491
494
|
export interface IFrameBudgetOptions {
|
|
492
|
-
/** Simulation ticks per
|
|
495
|
+
/** Simulation ticks per window; presented frames without a clock or while a live one is held. Default 300. */
|
|
493
496
|
readonly reportEvery?: number;
|
|
494
497
|
/** Minimum measured rendered frames per report window. Default 1. */
|
|
495
498
|
readonly minFrames?: number;
|
|
@@ -766,6 +769,8 @@ export class FrameBudget {
|
|
|
766
769
|
/** The last drawn frame's timestamp; a declined frame leaves it, so the next drawn interval spans it. */
|
|
767
770
|
#lastDrawnTimestamp: number | undefined;
|
|
768
771
|
#lastFrameEnd: number | undefined;
|
|
772
|
+
#covered = false;
|
|
773
|
+
#windowCovered = false;
|
|
769
774
|
#framesInWindow = 0;
|
|
770
775
|
#hitchesInWindow = 0;
|
|
771
776
|
/** The target frame this window counts against, and its two counts; see `overTarget`. */
|
|
@@ -878,10 +883,22 @@ export class FrameBudget {
|
|
|
878
883
|
this.#taskObserver = undefined;
|
|
879
884
|
}
|
|
880
885
|
|
|
886
|
+
/** Marks the following frames as behind the presentation cover: no hot-call line for them. */
|
|
887
|
+
markCovered(): void {
|
|
888
|
+
this.#covered = true;
|
|
889
|
+
this.#windowCovered = true;
|
|
890
|
+
}
|
|
891
|
+
|
|
892
|
+
/** Marks the cover lifted: the next window that begins reports hot calls again. */
|
|
893
|
+
markRevealed(): void {
|
|
894
|
+
this.#covered = false;
|
|
895
|
+
}
|
|
896
|
+
|
|
881
897
|
beginFrame(timestampMs: number, nowMs: number): void {
|
|
882
898
|
if (this.#open)
|
|
883
899
|
throw new Error("FrameBudget.beginFrame called before the previous frame ended.");
|
|
884
900
|
this.#open = true;
|
|
901
|
+
if (this.#framesInWindow === 0) this.#windowCovered = this.#covered;
|
|
885
902
|
this.#windowStartTick ??= this.#simulation?.tick();
|
|
886
903
|
this.#frameStart = nowMs;
|
|
887
904
|
if (this.#firstFrameStart === undefined) this.#firstFrameStart = nowMs;
|
|
@@ -995,6 +1012,7 @@ export class FrameBudget {
|
|
|
995
1012
|
`Frame budget gpu frame must be a non-negative integer, received ${String(frame)}.`,
|
|
996
1013
|
);
|
|
997
1014
|
}
|
|
1015
|
+
// A repeated frame id is the previous resolve still in flight, not a new measurement.
|
|
998
1016
|
if (frame === this.#lastGpuFrame) {
|
|
999
1017
|
this.#gpuStaleThisFrame = true;
|
|
1000
1018
|
return;
|
|
@@ -1111,8 +1129,9 @@ export class FrameBudget {
|
|
|
1111
1129
|
}
|
|
1112
1130
|
|
|
1113
1131
|
/**
|
|
1114
|
-
* Closes the frame and returns its phase split, or `undefined` when
|
|
1115
|
-
*
|
|
1132
|
+
* Closes the frame and returns its phase split, or `undefined` when `wantSample` is false. A hitch
|
|
1133
|
+
* still returns its split — `loop.ts` feeds it to the per-frame diagnostics — and the window meters
|
|
1134
|
+
* below are what exclude it: a 27-second startup stall is not a frame time and must not enter a
|
|
1116
1135
|
* percentile anybody is asked to act on.
|
|
1117
1136
|
*
|
|
1118
1137
|
* `wantSample` is false when the caller is going to discard the split, which is the default
|
|
@@ -1138,6 +1157,20 @@ export class FrameBudget {
|
|
|
1138
1157
|
: 0;
|
|
1139
1158
|
if (drawn) this.#lastDrawnTimestamp = this.#frameTimestamp;
|
|
1140
1159
|
|
|
1160
|
+
const update = Math.max(0, simulationEnd - this.#frameStart);
|
|
1161
|
+
const tail = Math.max(0, nowMs - simulationEnd);
|
|
1162
|
+
const residual = Math.max(0, tail - this.#renderMs - this.#overlayMs - this.#uiMs);
|
|
1163
|
+
const sample: IFramePhaseSample | undefined = wantSample
|
|
1164
|
+
? {
|
|
1165
|
+
hostGap: round(this.#hostGap),
|
|
1166
|
+
overlay: round(this.#overlayMs),
|
|
1167
|
+
render: round(this.#renderMs),
|
|
1168
|
+
residual: round(residual),
|
|
1169
|
+
ui: round(this.#uiMs),
|
|
1170
|
+
update: round(update),
|
|
1171
|
+
}
|
|
1172
|
+
: undefined;
|
|
1173
|
+
|
|
1141
1174
|
const isHitch = this.#presentedDelta >= this.hitchMs;
|
|
1142
1175
|
if (isHitch) {
|
|
1143
1176
|
// The gap is excluded, so the next drawn interval must not start before it.
|
|
@@ -1153,22 +1186,10 @@ export class FrameBudget {
|
|
|
1153
1186
|
})}`,
|
|
1154
1187
|
);
|
|
1155
1188
|
this.#maybeReport();
|
|
1156
|
-
|
|
1189
|
+
// Exclude the present gap from windows; diagnostics still need the measured callback phases.
|
|
1190
|
+
return sample;
|
|
1157
1191
|
}
|
|
1158
1192
|
|
|
1159
|
-
const update = Math.max(0, simulationEnd - this.#frameStart);
|
|
1160
|
-
const tail = Math.max(0, nowMs - simulationEnd);
|
|
1161
|
-
const residual = Math.max(0, tail - this.#renderMs - this.#overlayMs - this.#uiMs);
|
|
1162
|
-
const sample: IFramePhaseSample | undefined = wantSample
|
|
1163
|
-
? {
|
|
1164
|
-
hostGap: round(this.#hostGap),
|
|
1165
|
-
overlay: round(this.#overlayMs),
|
|
1166
|
-
render: round(this.#renderMs),
|
|
1167
|
-
residual: round(residual),
|
|
1168
|
-
ui: round(this.#uiMs),
|
|
1169
|
-
update: round(update),
|
|
1170
|
-
}
|
|
1171
|
-
: undefined;
|
|
1172
1193
|
this.#frame.push(frameMs);
|
|
1173
1194
|
this.#substeps.push(this.#substepCount);
|
|
1174
1195
|
// The first frame has no predecessor, so it has neither an interval nor a host gap; pushing a
|
|
@@ -1572,17 +1593,23 @@ export class FrameBudget {
|
|
|
1572
1593
|
}
|
|
1573
1594
|
|
|
1574
1595
|
#maybeReport(): void {
|
|
1575
|
-
//
|
|
1576
|
-
|
|
1596
|
+
// A window counts simulation ticks, so the first one spans startup plus `reportEvery` ticks of
|
|
1597
|
+
// play. A live clock whose simulation has not advanced in this window counts presented frames,
|
|
1598
|
+
// so a held game still reports.
|
|
1599
|
+
const ticks =
|
|
1577
1600
|
this.#simulation === undefined
|
|
1578
|
-
?
|
|
1601
|
+
? 0
|
|
1579
1602
|
: this.#simulation.tick() - (this.#windowStartTick ?? this.#simulation.tick());
|
|
1603
|
+
const elapsed =
|
|
1604
|
+
this.#simulation === undefined || (this.#simulation.clockFrozen === false && ticks === 0)
|
|
1605
|
+
? this.#framesInWindow
|
|
1606
|
+
: ticks;
|
|
1580
1607
|
if (elapsed < this.reportEvery || this.#framesInWindow < this.minFrames) return;
|
|
1581
1608
|
const completed = this.window();
|
|
1582
1609
|
this.#report(`${FRAME_BUDGET_MARKER}:${JSON.stringify(completed)}`);
|
|
1583
1610
|
if (this.#debug) {
|
|
1584
1611
|
this.#report(formatDebugReport(completed));
|
|
1585
|
-
const hotCalls = debugHotCalls(completed);
|
|
1612
|
+
const hotCalls = this.#windowCovered ? undefined : debugHotCalls(completed);
|
|
1586
1613
|
if (hotCalls !== undefined) this.#report(hotCalls);
|
|
1587
1614
|
}
|
|
1588
1615
|
this.#windowIndex += 1;
|