@threenative/core 0.3.11 → 0.3.12
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/capabilities.json +1096 -26
- package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
- package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-CWuFRT7G.d.ts} +1 -1
- package/dist/chunk-2Z44XSI2.js +35 -0
- package/dist/chunk-5O73CDMR.js +1849 -0
- package/dist/chunk-6KLNISRJ.js +153 -0
- package/dist/chunk-7UUT3TY5.js +133 -0
- package/dist/chunk-CFGTPFUH.js +231 -0
- package/dist/chunk-DBELTTTM.js +615 -0
- package/dist/chunk-GMHATRPW.js +7701 -0
- package/dist/chunk-GXY7B3JG.js +46 -0
- package/dist/chunk-KIRUKTBQ.js +187 -0
- package/dist/chunk-N5LRP4BR.js +220 -0
- package/dist/chunk-OKXUCASC.js +2238 -0
- package/dist/chunk-QWJEMUUT.js +94 -0
- package/dist/chunk-VAZM36TV.js +497 -0
- package/dist/{game-DzMcitDO.d.ts → game-D7pAzZUY.d.ts} +15 -3
- package/dist/hot.d.ts +3 -3
- package/dist/hot.js +2 -46
- package/dist/index.d.ts +329 -302
- package/dist/index.js +10566 -22552
- package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-B6BMqS1r.d.ts} +33 -3
- package/dist/playtest.d.ts +3 -3
- package/dist/playtest.js +24 -75
- package/dist/react-css.js +1 -215
- package/dist/react.d.ts +2 -2
- package/dist/{renderer-rZm0hVqq.d.ts → renderer-DvFVoAgj.d.ts} +13 -4
- 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 +5 -384
- package/dist/worker.js +4 -41
- package/dist/world.d.ts +725 -259
- package/dist/world.js +16714 -18284
- package/mcp/animation-server.mjs +1 -1
- package/mcp/animation.mjs +2 -3
- package/mcp/engine-server.mjs +142 -47
- package/mcp/servers.mjs +9 -2
- package/mcp/terrain.mjs +8 -0
- package/package.json +14 -6
- package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
- package/patches/three@0.187.0.patch +2004 -407
- package/src/assets.ts +9 -2
- package/src/card-lod.ts +152 -0
- package/src/compressed-texture-preparation.ts +1008 -0
- package/src/frame-budget.ts +31 -20
- package/src/game-dev-tools.ts +93 -0
- package/src/game-frame-loop.ts +995 -0
- package/src/game-renderer-metrics.ts +77 -0
- package/src/game-startup.ts +1001 -0
- package/src/game-validate.ts +70 -0
- package/src/game.ts +253 -1935
- package/src/index.ts +27 -2
- package/src/launch-diagnostics.ts +22 -12
- package/src/look/ao-admission.ts +24 -0
- package/src/look/filmic-tone-mapping.ts +15 -13
- package/src/look/look-diagnostics.ts +3 -3
- package/src/look/quality.ts +10 -5
- package/src/look/world-environment.ts +76 -9
- package/src/loop.ts +29 -0
- package/src/model-lod.ts +42 -3
- package/src/particle-kinds.ts +515 -0
- package/src/picking.ts +17 -3
- package/src/playtest.ts +27 -1
- package/src/projection-apply.ts +4 -1
- package/src/projection-plan.ts +9 -6
- package/src/render/mesh-pool.ts +1 -1
- 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.ts +213 -992
- package/src/render/world-impostor-surface.ts +293 -34
- package/src/render-pass-budget.ts +34 -7
- package/src/renderProjection.ts +22 -0
- package/src/renderer.ts +92 -37
- package/src/snow-field.ts +1 -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-readiness.ts +128 -34
- package/src/version.ts +1 -1
- package/src/warmup.ts +56 -8
- package/src/water-surface.ts +9 -3
- package/src/world-bundle-safety.ts +401 -0
- package/src/world-cell-batches.ts +1216 -0
- package/src/world-cell-chunks.ts +1132 -0
- package/src/world-cell-data.ts +995 -0
- package/src/world-cell-impostors.ts +1449 -0
- package/src/world-cell-lod-bias.ts +151 -0
- package/src/world-cell-models.ts +1074 -0
- package/src/world-cell-options.ts +189 -0
- package/src/world-cell-placements.ts +694 -0
- package/src/world-cell-prewarm.ts +557 -0
- package/src/world-cell-readiness.ts +357 -0
- package/src/world-cell-render-bundles.ts +459 -0
- package/src/world-cell-render-gpu-dress.ts +714 -0
- package/src/world-cell-render-main-cull.ts +484 -0
- package/src/world-cell-render-shadow-claims.ts +198 -0
- package/src/world-cell-render-util.ts +246 -0
- package/src/world-cell-render.ts +1493 -0
- package/src/world-cell-residency.ts +745 -0
- package/src/world-cells.ts +1318 -10418
- package/src/world-chunk-shadow.ts +308 -0
- package/src/world-collar.ts +315 -0
- package/src/world-gpu-flags.ts +163 -0
- package/src/world-gpu-readback.ts +881 -0
- package/src/world-gpu-reference.ts +510 -0
- package/src/world-gpu-scene.ts +214 -2264
- package/src/world-gpu-shadow.ts +190 -0
- package/src/world-gpu-types.ts +381 -0
- package/src/world-gpu-validation.ts +518 -0
- package/src/world-heightfield.ts +802 -0
- package/src/world-load-limiter.ts +106 -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-terrain-splat.ts +365 -149
- package/src/world-tile-budget.ts +256 -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 +170 -1745
- package/src/world-water-bodies.ts +359 -0
- package/src/world.ts +35 -741
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A level's record, its placeholder light and the stock shadow node it draws through: the settings
|
|
3
|
+
* mirrored into that node, and the registration that keeps its depth texture alive.
|
|
4
|
+
*/
|
|
5
|
+
import { type DirectionalLight, Object3D, type RenderTarget } from "three";
|
|
6
|
+
import { renderGroup, type shadow } from "three/tsl";
|
|
7
|
+
import type { NodeBuilder, UniformNode } from "three/webgpu";
|
|
8
|
+
import type { IPageRect } from "./virtual-shadow-pages.js";
|
|
9
|
+
import type { IPartialPass } from "./virtual-shadow-partial.js";
|
|
10
|
+
|
|
11
|
+
/** One clipmap axis' view of a world region, as the interval it covers in light space. */
|
|
12
|
+
export type ILightAxisRange = { low: number; high: number };
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Why a level owes a render: not at all, a window that moved, or an invalidation that asked and
|
|
16
|
+
* waited out its delay. The render it finally takes is counted against this, so a level the frame's
|
|
17
|
+
* single budget passed over is not counted twice.
|
|
18
|
+
*/
|
|
19
|
+
export type RenderReason = 0 | 1 | 2;
|
|
20
|
+
export const REASON_NONE: RenderReason = 0;
|
|
21
|
+
export const REASON_MOVE: RenderReason = 1;
|
|
22
|
+
export const REASON_INVALIDATION: RenderReason = 2;
|
|
23
|
+
/** A placeholder light per level: the stock shadow node reads position and target from it. */
|
|
24
|
+
export class LevelLight extends Object3D {
|
|
25
|
+
readonly target = new Object3D();
|
|
26
|
+
shadow: DirectionalLight["shadow"];
|
|
27
|
+
override castShadow = true;
|
|
28
|
+
|
|
29
|
+
constructor(shadow: DirectionalLight["shadow"]) {
|
|
30
|
+
super();
|
|
31
|
+
this.shadow = shadow;
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export interface ILevel {
|
|
36
|
+
readonly light: LevelLight;
|
|
37
|
+
readonly shadow: DirectionalLight["shadow"];
|
|
38
|
+
readonly node: ReturnType<typeof shadow>;
|
|
39
|
+
/** Same window and placement as `shadow`, rendered every frame with only the tracked casters. */
|
|
40
|
+
readonly moverShadow: DirectionalLight["shadow"];
|
|
41
|
+
readonly moverNode: ReturnType<typeof shadow>;
|
|
42
|
+
readonly extent: number;
|
|
43
|
+
readonly extentUniform: UniformNode<"float", number>;
|
|
44
|
+
/**
|
|
45
|
+
* The light-space depth this level's last render derived: how far behind its window centre the
|
|
46
|
+
* camera sat, and the near/far it drew with. Held between renders, because a level that keeps its
|
|
47
|
+
* map is placed with the same span it drew that map with.
|
|
48
|
+
*/
|
|
49
|
+
eye: number;
|
|
50
|
+
depthNear: number;
|
|
51
|
+
depthFar: number;
|
|
52
|
+
minX: number;
|
|
53
|
+
minY: number;
|
|
54
|
+
/** Light-space depth of the window centre when this level's map was last rendered. */
|
|
55
|
+
centerW: number;
|
|
56
|
+
/**
|
|
57
|
+
* 1 once this level's map has been rendered at least once, 0 until then. A fragment never
|
|
58
|
+
* samples a map this level has not drawn yet: with one render per frame the coarse levels are
|
|
59
|
+
* behind on the frame the fine one comes due, and their targets have no depth in them yet.
|
|
60
|
+
*/
|
|
61
|
+
readonly mapped: UniformNode<"float", number>;
|
|
62
|
+
/**
|
|
63
|
+
* Set when an invalidation asked for a redraw that has not been rendered yet, 0 until then. The
|
|
64
|
+
* ask is held here instead of being consumed on the frame it arrives, so a level can wait out
|
|
65
|
+
* `invalidationDelay` and still redraw; a render of any reason clears it.
|
|
66
|
+
*/
|
|
67
|
+
dirty: boolean;
|
|
68
|
+
/**
|
|
69
|
+
* The pages casters streamed into since this level's last render, in the clipmap's absolute page
|
|
70
|
+
* coordinates, or undefined while none did. An added caster only brings depth closer, so these
|
|
71
|
+
* pages need no clear. Meaningless while {@link dirtyAll} is set.
|
|
72
|
+
*/
|
|
73
|
+
dirtyAdmit: IPageRect | undefined;
|
|
74
|
+
/**
|
|
75
|
+
* The pages any other ask touched: a removed caster, a flag change, the tracker's pages. The old
|
|
76
|
+
* depth in them can be wrong, so they are put back to the far plane before they are redrawn.
|
|
77
|
+
*/
|
|
78
|
+
dirtyEvict: IPageRect | undefined;
|
|
79
|
+
/** An ask named no pages, or none inside the window, so the whole level is dirty. */
|
|
80
|
+
dirtyAll: boolean;
|
|
81
|
+
/** The rectangle this level is rendering now, set only around a partial redraw. */
|
|
82
|
+
pass: IPartialPass | undefined;
|
|
83
|
+
/** The caster interval along the light, from the centre, that the derived depth was drawn for. */
|
|
84
|
+
drawnSpan: ILightAxisRange;
|
|
85
|
+
/**
|
|
86
|
+
* The engine frame clock's reading when this level last rendered, in seconds. A dirty level
|
|
87
|
+
* re-renders for the invalidation no sooner than `invalidationDelay` after this. `-Infinity`
|
|
88
|
+
* until the first render, so a level invalidated before it holds a map is due immediately.
|
|
89
|
+
*/
|
|
90
|
+
lastRender: number;
|
|
91
|
+
/**
|
|
92
|
+
* Why this level owes a render the frame's single budget did not grant it: {@link REASON_NONE},
|
|
93
|
+
* and the reason it was due otherwise. Sticky, so a level that was passed over stays due on the
|
|
94
|
+
* next frame instead of waiting for its window to move again — and the render it eventually takes
|
|
95
|
+
* is counted against the reason that queued it.
|
|
96
|
+
*/
|
|
97
|
+
pending: RenderReason;
|
|
98
|
+
/**
|
|
99
|
+
* Smoothed cost of this level's own last render, in milliseconds, and 0 until it has rendered
|
|
100
|
+
* once. This is the only measure of what a level's render is worth there is — a level render is a
|
|
101
|
+
* whole scene draw — and what it buys is a wider refresh trail; see `adaptiveRefresh`.
|
|
102
|
+
*/
|
|
103
|
+
costMs: number;
|
|
104
|
+
/**
|
|
105
|
+
* How many of this level's renders have been measured, warm-up included. The first
|
|
106
|
+
* {@link COST_WARMUP_RENDERS} are compile and upload, not the level's price, so `costMs` stays 0
|
|
107
|
+
* until the counter passes them and nothing adapts before it.
|
|
108
|
+
*/
|
|
109
|
+
costReadings: number;
|
|
110
|
+
/**
|
|
111
|
+
* The trail this level is actually being stepped with, which is its configured `refreshStep`
|
|
112
|
+
* until a measurement widens it. Held so a level that got cheap again is put back rather than
|
|
113
|
+
* left on the trail it bought.
|
|
114
|
+
*/
|
|
115
|
+
appliedStep: number;
|
|
116
|
+
/** Engine clock of this level's last `TN_SHADOW_REFRESH` line, in seconds. */
|
|
117
|
+
lastRefreshNote: number;
|
|
118
|
+
/**
|
|
119
|
+
* The adaptive caster gate's scale on this level: the factor `minCasterTexels` is multiplied by,
|
|
120
|
+
* 1 until a render comes in over budget. See `adaptiveCasterGate`.
|
|
121
|
+
*/
|
|
122
|
+
gateScale: number;
|
|
123
|
+
/**
|
|
124
|
+
* The texel gate `#probe` last computed for this level, in world metres. Held so the level's own
|
|
125
|
+
* dispatch is handed the gate that render decided on, rather than recomputing it and risking the
|
|
126
|
+
* two answering about different numbers. 0 until the level has been probed.
|
|
127
|
+
*/
|
|
128
|
+
gateMetres: number;
|
|
129
|
+
/**
|
|
130
|
+
* Casters the adaptive gate hid on this level's last render, for the `TN_SHADOW_GATE` line. Not
|
|
131
|
+
* reset by a frame that did not render: the line reports the render the change was read from.
|
|
132
|
+
*/
|
|
133
|
+
gateHidden: number;
|
|
134
|
+
/** Engine clock of this level's last `TN_SHADOW_GATE` line, in seconds. */
|
|
135
|
+
lastGateNote: number;
|
|
136
|
+
/**
|
|
137
|
+
* Engine clock of the render whose cost the gate has already been adapted to. `#adaptiveTrails`
|
|
138
|
+
* changes the scale at most once per render, never twice for the same measured cost.
|
|
139
|
+
*/
|
|
140
|
+
gatedRender: number;
|
|
141
|
+
/**
|
|
142
|
+
* Where this level's *rendered* map sits, relative to the centre the fragment test measures
|
|
143
|
+
* from. A level whose re-render was deferred still holds an older window, and its selection has
|
|
144
|
+
* to be made against that window rather than the followed centre: the sampler reads through this
|
|
145
|
+
* level's own camera, so testing against anything else is what makes a fragment reach past a
|
|
146
|
+
* rendered map.
|
|
147
|
+
*/
|
|
148
|
+
readonly offsetU: UniformNode<"float", number>;
|
|
149
|
+
readonly offsetV: UniformNode<"float", number>;
|
|
150
|
+
/** This level's own guarded extent fraction, for the same reason. */
|
|
151
|
+
readonly guardUniform: UniformNode<"float", number>;
|
|
152
|
+
}
|
|
153
|
+
export type ShadowWithFilter = DirectionalLight["shadow"] & { filterNode?: unknown };
|
|
154
|
+
/** Keep each stock node's source-owned settings aligned with the public light shadow. */
|
|
155
|
+
export function syncShadowSettings(
|
|
156
|
+
source: DirectionalLight["shadow"],
|
|
157
|
+
target: DirectionalLight["shadow"],
|
|
158
|
+
): void {
|
|
159
|
+
target.bias = source.bias;
|
|
160
|
+
target.biasNode = source.biasNode;
|
|
161
|
+
target.blurSamples = source.blurSamples;
|
|
162
|
+
target.intensity = source.intensity;
|
|
163
|
+
target.mapType = source.mapType;
|
|
164
|
+
target.normalBias = source.normalBias;
|
|
165
|
+
target.radius = source.radius;
|
|
166
|
+
(target as ShadowWithFilter).filterNode = (source as ShadowWithFilter).filterNode;
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
export function syncLevelShadowSettings(
|
|
170
|
+
source: DirectionalLight["shadow"],
|
|
171
|
+
levels: readonly ILevel[],
|
|
172
|
+
): void {
|
|
173
|
+
for (const level of levels) {
|
|
174
|
+
syncShadowSettings(source, level.shadow);
|
|
175
|
+
syncShadowSettings(source, level.moverShadow);
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/** The stock node's target factory, which three calls once from `setupShadow`. */
|
|
180
|
+
interface IStockShadowTarget {
|
|
181
|
+
setupRenderTarget(
|
|
182
|
+
shadow: unknown,
|
|
183
|
+
builder: NodeBuilder,
|
|
184
|
+
): { shadowMap: RenderTarget; depthTexture: unknown };
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/**
|
|
188
|
+
* Move a receiver input into the render group. The patched renderer skips object-group uploads for
|
|
189
|
+
* a settled static object, so a value in that group freezes at whatever the receiver settled with.
|
|
190
|
+
*/
|
|
191
|
+
export function rendered<T>(node: T): T {
|
|
192
|
+
// quality-allow: three's ReferenceNode has setGroup at runtime; its declaration omits it
|
|
193
|
+
return (node as unknown as { setGroup(group: typeof renderGroup): T }).setGroup(renderGroup);
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/**
|
|
197
|
+
* Register a stock shadow node's render target with the renderer the moment the node creates it,
|
|
198
|
+
* inside the material build and before any bind group can sample its depth texture.
|
|
199
|
+
*
|
|
200
|
+
* three re-versions a target's depth texture on the target's *first* registration — the size
|
|
201
|
+
* branch of `Textures.updateRenderTarget`, which finds no recorded size — and when a bind group
|
|
202
|
+
* already holds that texture the re-version destroys its GPUTexture. Every submit through that bind
|
|
203
|
+
* group then fails with `Destroyed texture [Texture "ShadowDepthTexture"] used in a submit`, and a
|
|
204
|
+
* settled static object never rebuilds its bind group, so nothing is presented again. A level whose
|
|
205
|
+
* first render comes after the main pass bound its map — every level but the one drawn in the first
|
|
206
|
+
* frame, every mover map, and every level a warm-up compile binds — hit it once per scene.
|
|
207
|
+
* Registering at creation makes that first registration happen before anything is bound.
|
|
208
|
+
*/
|
|
209
|
+
export function registeredOnCreate<T>(node: T): T {
|
|
210
|
+
// quality-allow: Three's public node type omits the target setup hook this wrapper must replace
|
|
211
|
+
const stock = node as unknown as IStockShadowTarget;
|
|
212
|
+
const create = stock.setupRenderTarget.bind(stock);
|
|
213
|
+
stock.setupRenderTarget = (lightShadow, builder) => {
|
|
214
|
+
const made = create(lightShadow, builder);
|
|
215
|
+
// A renderer without three's texture manager (a test double) registers on first render.
|
|
216
|
+
// quality-allow: Three's public renderer type hides the manager that must register this target early
|
|
217
|
+
const host = builder.renderer as unknown as {
|
|
218
|
+
_textures?: { updateRenderTarget?(target: RenderTarget): void };
|
|
219
|
+
};
|
|
220
|
+
host._textures?.updateRenderTarget?.(made.shadowMap);
|
|
221
|
+
return made;
|
|
222
|
+
};
|
|
223
|
+
return node;
|
|
224
|
+
}
|
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
import type { IVirtualShadowStats } from "./virtual-shadow-options.js";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The `TN_VIRTUAL_SHADOW`, `TN_SHADOW_REFRESH`, `TN_SHADOW_GATE` and `TN_LAMP_SHADOW` lines, how
|
|
5
|
+
* often each prints, and the parsers that read them back.
|
|
6
|
+
*
|
|
7
|
+
* A marker is the only way a browser run can see inside the node: which level is being throttled,
|
|
8
|
+
* which one is shedding its tiniest casters, and what a frame's shadow work cost. The parsers are
|
|
9
|
+
* here so a harness reads exactly the shape the node prints.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
export const VIRTUAL_SHADOW_MARKER = "TN_VIRTUAL_SHADOW";
|
|
13
|
+
/**
|
|
14
|
+
* One line per level whose refresh trail adaptive refresh widened, at most once a second: the level,
|
|
15
|
+
* the width of the window it re-renders, the smoothed cost of that render in ms, and the trail it
|
|
16
|
+
* bought. A browser run can see which level is being throttled and by how much, which is the only
|
|
17
|
+
* way to tell an expensive level from a slow frame.
|
|
18
|
+
*/
|
|
19
|
+
export const VIRTUAL_SHADOW_REFRESH_MARKER = "TN_SHADOW_REFRESH";
|
|
20
|
+
/** Seconds between two `TN_SHADOW_REFRESH` lines for the same level. */
|
|
21
|
+
export const REFRESH_MARKER_SECONDS = 1;
|
|
22
|
+
/**
|
|
23
|
+
* One line per level whose adaptive caster gate changed, at most once a second: the level, the width
|
|
24
|
+
* of the window it re-renders, the smoothed cost of that render, the scale its gate bought, and how
|
|
25
|
+
* many casters that gate hid on the render the change was read from. A browser run can see which
|
|
26
|
+
* level is shedding its tiniest props and by how much.
|
|
27
|
+
*/
|
|
28
|
+
export const VIRTUAL_SHADOW_GATE_MARKER = "TN_SHADOW_GATE";
|
|
29
|
+
/** Seconds between two `TN_SHADOW_GATE` lines for the same level. */
|
|
30
|
+
export const GATE_MARKER_SECONDS = 1;
|
|
31
|
+
/** Frames between markers while `?tnShadowStats=1` is on the URL: about a second a walk is long. */
|
|
32
|
+
export const STATS_QUERY_EVERY = 60;
|
|
33
|
+
|
|
34
|
+
const VIRTUAL_SHADOW_STAT_FIELDS = [
|
|
35
|
+
"autoMovers",
|
|
36
|
+
"autoScanMs",
|
|
37
|
+
"autoTransitions",
|
|
38
|
+
"byAdmission",
|
|
39
|
+
"byEviction",
|
|
40
|
+
"byInvalidation",
|
|
41
|
+
"byMove",
|
|
42
|
+
"cached",
|
|
43
|
+
"coalesced",
|
|
44
|
+
"deferred",
|
|
45
|
+
"frame",
|
|
46
|
+
"held",
|
|
47
|
+
"invalidated",
|
|
48
|
+
"levels",
|
|
49
|
+
"moved",
|
|
50
|
+
"moverRenders",
|
|
51
|
+
"movers",
|
|
52
|
+
"pagesDirty",
|
|
53
|
+
"pagesRedrawn",
|
|
54
|
+
"rendered",
|
|
55
|
+
"rendersTotal",
|
|
56
|
+
"reuseRatio",
|
|
57
|
+
] as const;
|
|
58
|
+
|
|
59
|
+
function isVirtualShadowStats(value: unknown): value is IVirtualShadowStats {
|
|
60
|
+
if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
|
|
61
|
+
const stats = value as Record<string, unknown>;
|
|
62
|
+
if (
|
|
63
|
+
VIRTUAL_SHADOW_STAT_FIELDS.some(
|
|
64
|
+
(field) => typeof stats[field] !== "number" || !Number.isFinite(stats[field]),
|
|
65
|
+
)
|
|
66
|
+
) {
|
|
67
|
+
return false;
|
|
68
|
+
}
|
|
69
|
+
// Two fields are measurements, not counts: a ratio and a mean in milliseconds.
|
|
70
|
+
const countFields = VIRTUAL_SHADOW_STAT_FIELDS.filter(
|
|
71
|
+
(field) => field !== "reuseRatio" && field !== "autoScanMs",
|
|
72
|
+
);
|
|
73
|
+
if (
|
|
74
|
+
countFields.some((field) => !Number.isInteger(stats[field]) || (stats[field] as number) < 0)
|
|
75
|
+
) {
|
|
76
|
+
return false;
|
|
77
|
+
}
|
|
78
|
+
const reuseRatio = stats.reuseRatio as number;
|
|
79
|
+
return reuseRatio >= 0 && reuseRatio <= 1 && (stats.autoScanMs as number) >= 0;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* Parse a `TN_VIRTUAL_SHADOW` console line back into its complete stats, or `undefined`.
|
|
84
|
+
*
|
|
85
|
+
* @situation inspect virtual shadow cache and mover counters from a renderer log
|
|
86
|
+
* @constraint non-marker lines and markers with incomplete or non-numeric stats return `undefined`
|
|
87
|
+
* @example
|
|
88
|
+
* const stats = readVirtualShadowMarker(line);
|
|
89
|
+
* if (stats !== undefined) console.log(stats.reuseRatio);
|
|
90
|
+
*/
|
|
91
|
+
export function readVirtualShadowMarker(line: string): IVirtualShadowStats | undefined {
|
|
92
|
+
if (!line.startsWith(`${VIRTUAL_SHADOW_MARKER}:`)) return undefined;
|
|
93
|
+
try {
|
|
94
|
+
const value: unknown = JSON.parse(line.slice(VIRTUAL_SHADOW_MARKER.length + 1));
|
|
95
|
+
return isVirtualShadowStats(value) ? value : undefined;
|
|
96
|
+
} catch {
|
|
97
|
+
return undefined;
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* One frame's shadow passes on the owned engine with the spot and point light maps apart from the
|
|
103
|
+
* sun's (PRD-650). The sun's draws and the lamps' add up to every shadow draw the renderer submitted.
|
|
104
|
+
*/
|
|
105
|
+
export interface ILampShadowStats {
|
|
106
|
+
readonly frame: number;
|
|
107
|
+
readonly shadowDraws: number;
|
|
108
|
+
/** The sun's maps: its virtual levels or its plain map. `gpuMs` is -1 until a GPU sample resolves. */
|
|
109
|
+
readonly sun: { readonly draws: number; readonly gpuMs: number };
|
|
110
|
+
/** The lamp maps the frame redrew (a cube's six faces are one), their draws, and their GPU time. */
|
|
111
|
+
readonly lamps: { readonly redraws: number; readonly draws: number; readonly gpuMs: number };
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
export const LAMP_SHADOW_MARKER = "TN_LAMP_SHADOW";
|
|
115
|
+
|
|
116
|
+
interface ILampShadowCounters {
|
|
117
|
+
readonly lampRedraws: number;
|
|
118
|
+
readonly lampDraws: number;
|
|
119
|
+
readonly shadowDraws: number;
|
|
120
|
+
readonly sunGpuMs: number;
|
|
121
|
+
readonly lampGpuMs: number;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
const isCount = (n: unknown): n is number => Number.isInteger(n) && (n as number) >= 0;
|
|
125
|
+
const isGpuMs = (n: unknown): n is number => n === -1 || (Number.isFinite(n) && (n as number) >= 0);
|
|
126
|
+
|
|
127
|
+
function isLampShadowStats(value: unknown): value is ILampShadowStats {
|
|
128
|
+
const stats = value as Partial<Record<keyof ILampShadowStats, Record<string, unknown>>> | null;
|
|
129
|
+
if (typeof stats !== "object" || stats === null) return false;
|
|
130
|
+
const { frame, shadowDraws } = stats as Record<string, unknown>;
|
|
131
|
+
const sun = stats.sun;
|
|
132
|
+
const lamps = stats.lamps;
|
|
133
|
+
return (
|
|
134
|
+
isCount(frame) &&
|
|
135
|
+
isCount(shadowDraws) &&
|
|
136
|
+
typeof sun === "object" &&
|
|
137
|
+
sun !== null &&
|
|
138
|
+
typeof lamps === "object" &&
|
|
139
|
+
lamps !== null &&
|
|
140
|
+
isCount(sun.draws) &&
|
|
141
|
+
isGpuMs(sun.gpuMs) &&
|
|
142
|
+
isCount(lamps.redraws) &&
|
|
143
|
+
isCount(lamps.draws) &&
|
|
144
|
+
isGpuMs(lamps.gpuMs) &&
|
|
145
|
+
sun.draws + lamps.draws === shadowDraws
|
|
146
|
+
);
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
/**
|
|
150
|
+
* The `TN_LAMP_SHADOW` line for the renderer's last frame, or `undefined` on a renderer that keeps
|
|
151
|
+
* no lamp counters (three's own).
|
|
152
|
+
*
|
|
153
|
+
* @situation log lamp shadow redraws and GPU time apart from the sun's on the owned engine
|
|
154
|
+
* @constraint counters that do not add up to the frame's shadow draws throw TN_LAMP_SHADOW_INVALID
|
|
155
|
+
* @example
|
|
156
|
+
* const line = lampShadowMarker(renderer, frame);
|
|
157
|
+
* if (line !== undefined) console.info(line);
|
|
158
|
+
*/
|
|
159
|
+
export function lampShadowMarker(
|
|
160
|
+
renderer: { readonly info?: { readonly engine?: { readonly shadows?: ILampShadowCounters } } },
|
|
161
|
+
frame: number,
|
|
162
|
+
): string | undefined {
|
|
163
|
+
const counters = renderer.info?.engine?.shadows;
|
|
164
|
+
if (counters === undefined) return undefined;
|
|
165
|
+
const stats: ILampShadowStats = {
|
|
166
|
+
frame,
|
|
167
|
+
shadowDraws: counters.shadowDraws,
|
|
168
|
+
sun: { draws: counters.shadowDraws - counters.lampDraws, gpuMs: counters.sunGpuMs },
|
|
169
|
+
lamps: { redraws: counters.lampRedraws, draws: counters.lampDraws, gpuMs: counters.lampGpuMs },
|
|
170
|
+
};
|
|
171
|
+
if (!isLampShadowStats(stats))
|
|
172
|
+
throw new Error(`TN_LAMP_SHADOW_INVALID: ${JSON.stringify(counters)} at frame ${frame}`);
|
|
173
|
+
return `${LAMP_SHADOW_MARKER}:${JSON.stringify(stats)}`;
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
/**
|
|
177
|
+
* Parse a `TN_LAMP_SHADOW` line back into its stats, or `undefined`.
|
|
178
|
+
*
|
|
179
|
+
* @situation count lamp shadow redraws from a renderer log, for example a moving-caster run
|
|
180
|
+
* @constraint non-marker lines and markers whose sun and lamp draws do not add up return `undefined`
|
|
181
|
+
* @example
|
|
182
|
+
* const stats = readLampShadowMarker(line);
|
|
183
|
+
* if (stats !== undefined) console.log(stats.lamps.redraws);
|
|
184
|
+
*/
|
|
185
|
+
export function readLampShadowMarker(line: string): ILampShadowStats | undefined {
|
|
186
|
+
if (!line.startsWith(`${LAMP_SHADOW_MARKER}:`)) return undefined;
|
|
187
|
+
try {
|
|
188
|
+
const value: unknown = JSON.parse(line.slice(LAMP_SHADOW_MARKER.length + 1));
|
|
189
|
+
return isLampShadowStats(value) ? value : undefined;
|
|
190
|
+
} catch {
|
|
191
|
+
return undefined;
|
|
192
|
+
}
|
|
193
|
+
}
|