@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,995 @@
|
|
|
1
|
+
import type {
|
|
2
|
+
Box3,
|
|
3
|
+
BufferGeometry,
|
|
4
|
+
Camera,
|
|
5
|
+
InstancedMesh,
|
|
6
|
+
Material,
|
|
7
|
+
Matrix4,
|
|
8
|
+
Mesh,
|
|
9
|
+
Object3D,
|
|
10
|
+
} from "three";
|
|
11
|
+
|
|
12
|
+
import type { IAssetLoader } from "./assets.js";
|
|
13
|
+
import type { InstancedBatch } from "./instanced-batch.js";
|
|
14
|
+
import type { OcclusionMode } from "./render/depth-pyramid.js";
|
|
15
|
+
import type { SharedBatch } from "./world-cell-batches.js";
|
|
16
|
+
import type { CellProxySelection, IPreparedCellProxy } from "./world-cell-proxy.js";
|
|
17
|
+
|
|
18
|
+
import type { IAssetState } from "./world-cell-models.js";
|
|
19
|
+
import type { IWorldCell, IWorldPackage, IWorldRun } from "./world-package.js";
|
|
20
|
+
|
|
21
|
+
import type { IWorldTilesOptions } from "./world-tiles.js";
|
|
22
|
+
|
|
23
|
+
/** The point a streamed world follows; an `Object3D` satisfies this shape. */
|
|
24
|
+
export interface IWorldCellsFollow {
|
|
25
|
+
readonly position: { readonly x: number; readonly y?: number; readonly z: number };
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** Hard caps on what stays resident. A cap that is reached reports pressure, it never throws. */
|
|
29
|
+
export interface IWorldCellsBudget {
|
|
30
|
+
readonly residentCells: number;
|
|
31
|
+
readonly instances: number;
|
|
32
|
+
/** Placement-record bytes (`32` per instance) the resident cells are allowed to weigh. */
|
|
33
|
+
readonly bytes: number;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** Terrain options forwarded to the composed `TerrainTiles`; `tileSize` defaults to `cellSize`. */
|
|
37
|
+
export interface IWorldCellsTerrainOptions {
|
|
38
|
+
readonly tileSize?: number;
|
|
39
|
+
readonly tileResolution?: number;
|
|
40
|
+
readonly lodFactors?: readonly number[];
|
|
41
|
+
readonly lodDistances?: readonly number[];
|
|
42
|
+
readonly skirtDepth?: number;
|
|
43
|
+
/**
|
|
44
|
+
* Tiles kept resident around the follow tile, independent of the cell `ring`: terrain can reach
|
|
45
|
+
* to the horizon while props stay near. Defaults to `ring`, so raising only this widens the
|
|
46
|
+
* ground without widening the props, and the far tiles take the coarser `lodDistances` levels.
|
|
47
|
+
*/
|
|
48
|
+
readonly streamRadius?: number;
|
|
49
|
+
/**
|
|
50
|
+
* Tiles that get a `createCollider` body, by Chebyshev radius from the follow tile. Defaults to
|
|
51
|
+
* `ring`. A tile entering or leaving it creates or disposes its collider, so a wide terrain
|
|
52
|
+
* radius does not have to mean a physics body for every tile in it.
|
|
53
|
+
*/
|
|
54
|
+
readonly colliderRadius?: number;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export interface IWorldCellsLoadOptions {
|
|
58
|
+
/**
|
|
59
|
+
* Logical path of `world.json` (`world/world.json`); every other path in the package resolves
|
|
60
|
+
* against it. A leading `/` is accepted and stripped, so an uncompiled `public/world` keeps
|
|
61
|
+
* working.
|
|
62
|
+
*/
|
|
63
|
+
readonly url: string;
|
|
64
|
+
/**
|
|
65
|
+
* Loader the package's paths resolve through — its manifest, or the authored names when there is
|
|
66
|
+
* none. Defaults to a fresh `createAssetLoader()`; inside a game, pass `ctx.assets` so the
|
|
67
|
+
* package's compiled output and compressed textures reach the renderer the game booted with.
|
|
68
|
+
*
|
|
69
|
+
* The world releases the source models it asks this loader for only when it created the loader
|
|
70
|
+
* itself: each asset's requested level paths are released through `release("model", path)` once
|
|
71
|
+
* the last asset naming a path is gone, so a streamed package does not pin an internally owned
|
|
72
|
+
* cache. An explicitly supplied loader is the caller's — the world never releases its cache, so a
|
|
73
|
+
* second game or world holding the same model keeps it alive; the caller ends that lifetime with
|
|
74
|
+
* its own `release`. The loader is never cleared, and a path this world never asked for is never
|
|
75
|
+
* touched either way.
|
|
76
|
+
*/
|
|
77
|
+
readonly assets?: IAssetLoader;
|
|
78
|
+
/** Game-owned terrain surface, handed straight to `TerrainTiles`. */
|
|
79
|
+
readonly surface: IWorldTilesOptions["surface"];
|
|
80
|
+
/** Passed straight to `TerrainTiles` for per-tile colliders. */
|
|
81
|
+
readonly createCollider?: IWorldTilesOptions["createCollider"];
|
|
82
|
+
/** Read once per update; an `Object3D` works. */
|
|
83
|
+
readonly follow: IWorldCellsFollow;
|
|
84
|
+
/** Called when a nonempty cell batch becomes visible to the renderer. */
|
|
85
|
+
readonly onPublication?: (bounds: Box3) => void;
|
|
86
|
+
/** Chebyshev radius in cells to keep resident; a cell leaves only beyond `ring + 1`. */
|
|
87
|
+
readonly ring: number;
|
|
88
|
+
readonly budgets: IWorldCellsBudget;
|
|
89
|
+
/** False streams props/chunks only; the caller owns terrain geometry and collision. */
|
|
90
|
+
readonly terrain?: IWorldCellsTerrainOptions | false;
|
|
91
|
+
/** Cooked cell proxies are considered by default; false retains source rendering. Static CPU
|
|
92
|
+
* cells only, with strict measured triangle/draw savings and projected-error hysteresis.
|
|
93
|
+
* Source collision and shadow representations stay resident; unsupported sources retain detail. */
|
|
94
|
+
readonly hlod?: boolean;
|
|
95
|
+
/**
|
|
96
|
+
* Whether an asset whose authored `maxDistance` ends inside the near ring keeps a whole-map far
|
|
97
|
+
* aggregate. `"ring"` (the default) skips it: the ring always draws those cells itself, and a
|
|
98
|
+
* far record it does not own is further away than the asset's own cull, so the aggregate could
|
|
99
|
+
* never draw a pixel while still costing an instance buffer, an atlas and a draw. `"always"` is
|
|
100
|
+
* the named override, reported once per kept asset as `TN_WORLD_IMPOSTOR_FAR ...
|
|
101
|
+
* override=impostorFar`.
|
|
102
|
+
*/
|
|
103
|
+
readonly impostorFar?: "ring" | "always";
|
|
104
|
+
/** Optional immutable per-record 3D draw reach in metres, indexed like placements.
|
|
105
|
+
* Nonnegative finite values or Infinity (no extra limit); combined with asset maxDistance.
|
|
106
|
+
* Filtered by the existing admission/refilter budget, never by a separate culler.
|
|
107
|
+
*/
|
|
108
|
+
readonly placementReach?: Float32Array;
|
|
109
|
+
/** Inward return margin for authored CPU LODs, in [0, 1). Requires gpuScene:false; when
|
|
110
|
+
* combined with automatic impostors, also requires preserveAuthoredParts and authored distances.
|
|
111
|
+
* Omitted, selection uses the existing direct gates. State survives cell eviction/revisit. */
|
|
112
|
+
readonly lodHysteresis?: number;
|
|
113
|
+
/** How a `lodHysteresis` level change reaches the screen. `"band"` (default) cross-fades over a
|
|
114
|
+
* distance band `lodHysteresis` wide with a per-pixel dither; a placement standing in the band
|
|
115
|
+
* stays dithered, which crawls without temporal AA. `"temporal"` is UE 5.8.3's instanced foliage
|
|
116
|
+
* (`foliage.DitheredLOD` 1, `lod.TemporalLag` 0.5 s): the gate is hard in space and the change
|
|
117
|
+
* fades over half a second, so no placement stays mid-fade while the viewer stands still.
|
|
118
|
+
* `"none"` pops whole at the gate. */
|
|
119
|
+
readonly lodTransition?: "band" | "none" | "temporal";
|
|
120
|
+
/** Where the CPU path measures a placement's level and `maxDistance` cull from. `"camera"` (the
|
|
121
|
+
* default) is the render camera's world position, the eye the GPU dispatch already uses: UE 5.8.3
|
|
122
|
+
* picks instance LODs per view from the view origin
|
|
123
|
+
* (`Engine/Source/Runtime/Engine/Private/HierarchicalInstancedStaticMesh.cpp:1652`) and streams
|
|
124
|
+
* around the view target (`Engine/Source/Runtime/Engine/Private/PlayerController.cpp:3705`), so a
|
|
125
|
+
* camera far from the player no longer draws the player's full-detail trees. Residency and
|
|
126
|
+
* `placementReach` stay on `follow`. Until a camera reaches `update`, the eye is `follow`.
|
|
127
|
+
* `"follow"` is the named override, as are `TN_LOD_FROM_CAMERA=0` and `?tnLodFromCamera=0`;
|
|
128
|
+
* `stats().lodFrom` and `TN_WORLD_MAIN_CULL lodFrom=` report which one ran. */
|
|
129
|
+
readonly lodFrom?: "camera" | "follow";
|
|
130
|
+
/** Preserve supplied part/material identity and exact authored LOD membership, including shadow batches. Automatic impostors require each asset to author `impostorDistance`.
|
|
131
|
+
* Default content sharing and missing-alpha-part coverage remain enabled when omitted. */
|
|
132
|
+
readonly preserveAuthoredParts?: boolean;
|
|
133
|
+
/** Already decoded immutable world-v1 data; URL still supplies the base for model paths. */
|
|
134
|
+
readonly data?: {
|
|
135
|
+
readonly manifest: IWorldPackage;
|
|
136
|
+
readonly placements: ArrayBuffer;
|
|
137
|
+
/** Omitted values load the manifest heightmap unless terrain is false. */
|
|
138
|
+
readonly heightmap?: Uint16Array;
|
|
139
|
+
};
|
|
140
|
+
/**
|
|
141
|
+
* How a scattered part whose own material is `transparent` is drawn. `"cutout"` (the default)
|
|
142
|
+
* gives the part a clone of that material with `transparent: false` and an `alphaTest`, so the
|
|
143
|
+
* instanced draw needs no per-instance sorting and the depth buffer rejects what is behind it;
|
|
144
|
+
* `"blend"` draws the material as authored. One clone per asset part, never per cell.
|
|
145
|
+
*/
|
|
146
|
+
readonly transparentScatter?: "cutout" | "blend";
|
|
147
|
+
/**
|
|
148
|
+
* Shadows for the streamed world, all off by default. `cast` makes scattered batches cast into
|
|
149
|
+
* the scene's shadow map. Their `castLevels` finest distance levels (default 1: the near shape)
|
|
150
|
+
* each cast their own shape; a placement drawn at a coarser level of a chain casts with the
|
|
151
|
+
* coarsest of those, so it keeps its shadow without a caster mesh per level — every level casting
|
|
152
|
+
* its own minted ~3x the casters and the churn showed as garbage collection on a walk (PRD-541).
|
|
153
|
+
* Authored `lods` past `castLevels` cast nothing. `receive` lets scatter and terrain receive
|
|
154
|
+
* shadows.
|
|
155
|
+
*/
|
|
156
|
+
readonly shadows?: {
|
|
157
|
+
readonly cast?: boolean;
|
|
158
|
+
readonly castLevels?: number;
|
|
159
|
+
/**
|
|
160
|
+
* The finest level a shadow draws, default 0. A placement drawn at a finer level casts in this
|
|
161
|
+
* level's shape when every finer level has as many parts at the same local transforms, so the
|
|
162
|
+
* shadow keeps one shape while the view swaps levels: a cached shadow page redraws at most once a
|
|
163
|
+
* second and showed every swap since in one batch. UE 5.8.3 draws shadows a level coarser by
|
|
164
|
+
* default (`r.Shadow.NaniteLODBias` 1, Renderer/Private/Shadows/ShadowSceneRenderer.cpp:48-52).
|
|
165
|
+
* It applies to the caster clusters; a world whose shadow levels draw its GPU keys casts as before.
|
|
166
|
+
*/
|
|
167
|
+
readonly minLevel?: number;
|
|
168
|
+
readonly receive?: boolean;
|
|
169
|
+
/**
|
|
170
|
+
* @deprecated Accepted and ignored. Clusters replace it: what a shadow level submits is bounded
|
|
171
|
+
* by the clusters its own window covers, not by a hand-tuned radius. It still validates, so a
|
|
172
|
+
* game that set it keeps compiling and keeps loading.
|
|
173
|
+
*/
|
|
174
|
+
readonly castDistance?: number;
|
|
175
|
+
/**
|
|
176
|
+
* Called in a batch at most once a second after streamed records changed, so the shadow levels
|
|
177
|
+
* that read them redraw. A call with no region asks `VirtualShadowNode.invalidateAll`;
|
|
178
|
+
* nothing changed means no call.
|
|
179
|
+
*
|
|
180
|
+
* Admissions and evictions are separate calls, each with the union of the bounds of the records
|
|
181
|
+
* that changed — the placement position widened by the asset's own bounds, unioned over the
|
|
182
|
+
* records of this update and nothing else, so a hook that forwards it to
|
|
183
|
+
* `VirtualShadowNode.invalidateRegion` redraws the levels whose window covers them and leaves
|
|
184
|
+
* the rest of the cascade holding its maps. A call with no region is still a blanket one: the
|
|
185
|
+
* prewarm passes it while a caster's first draw is owed, and there is no region for that.
|
|
186
|
+
*/
|
|
187
|
+
readonly invalidate?: (region?: IShadowRegion) => void;
|
|
188
|
+
/**
|
|
189
|
+
* An asset whose authored bounds are shorter than this casts into the finest shadow level only,
|
|
190
|
+
* default 1.5 m. Ground cover below it — ferns, grass, bushes — casts a shadow that is sub-texel
|
|
191
|
+
* noise at every range a wide level covers, and costs one draw per key per level there. Raise it
|
|
192
|
+
* to draw everything at every range, lower it to cull more. Measured on the authored bounds, so
|
|
193
|
+
* a package that scales a fern up four times is judged on the un-scaled fern.
|
|
194
|
+
*/
|
|
195
|
+
readonly smallCasterMetres?: number;
|
|
196
|
+
};
|
|
197
|
+
/**
|
|
198
|
+
* Triangles a hand-placed chunk's merged material group may reach before one of its
|
|
199
|
+
* `InstancedMesh` is left instanced. Defaults to 43,690, the same 4 MiB
|
|
200
|
+
* budget the merged buffers are split on counted in the worst case, a de-indexed triangle: a merged
|
|
201
|
+
* group is a single draw, so expanding into it wins until the merged geometry is too big for the
|
|
202
|
+
* frame, and above it the instanced draw is the cheaper of the two. A group that crosses the budget
|
|
203
|
+
* is split into several meshes in traversal order rather than grown, and an instanced shape over
|
|
204
|
+
* 2,048 triangles is never expanded. Everything else in a chunk merges regardless — one mesh per
|
|
205
|
+
* material, in the main pass and in every shadow pass that redraws it.
|
|
206
|
+
*/
|
|
207
|
+
readonly chunkMergeMaxTriangles?: number;
|
|
208
|
+
/**
|
|
209
|
+
* `(url) => Promise<Object3D>`, overriding `assets.model`; a raw `GLTFLoader` or a game's own
|
|
210
|
+
* loader works. The url is the authored one, so a compiled package wants `assets` instead.
|
|
211
|
+
*/
|
|
212
|
+
readonly loadModel?: (url: string) => Promise<Object3D>;
|
|
213
|
+
/**
|
|
214
|
+
* Model loads in flight at once, assets and chunks together. Defaults to `loadAll`'s
|
|
215
|
+
* `concurrency`, six.
|
|
216
|
+
*/
|
|
217
|
+
readonly concurrency?: number;
|
|
218
|
+
/**
|
|
219
|
+
* Cell-asset batches refiltered per `update`, nearest cell first. Defaults to 16. A cell that did
|
|
220
|
+
* not get its turn keeps drawing the batches it has until a later update replaces them.
|
|
221
|
+
*/
|
|
222
|
+
readonly rebuildsPerUpdate?: number;
|
|
223
|
+
/**
|
|
224
|
+
* Seconds of motion to stream ahead of, default 1.5: the ring centres on where the follow point
|
|
225
|
+
* will be (`position + velocity * prefetchSeconds`), so a fast camera finds cells already loaded
|
|
226
|
+
* instead of outrunning them. The lead is capped at three quarters of the ring, so the cell the
|
|
227
|
+
* follow point is in always stays resident. `0` streams around the follow point itself.
|
|
228
|
+
*/
|
|
229
|
+
readonly prefetchSeconds?: number;
|
|
230
|
+
/**
|
|
231
|
+
* New batch meshes created per update, default 2. On WebGPU each new InstancedMesh builds its
|
|
232
|
+
* own shader the first frame it draws (~10-20 ms of main thread), so a burst of first-seen assets
|
|
233
|
+
* is spread over frames instead of stacked into one; recycled meshes are not counted.
|
|
234
|
+
*/
|
|
235
|
+
readonly freshMeshesPerUpdate?: number;
|
|
236
|
+
/**
|
|
237
|
+
* New batch meshes per update while the startup cover hides the world, default 8x
|
|
238
|
+
* `freshMeshesPerUpdate`. The first-draw shader cost the default spreads is invisible behind an
|
|
239
|
+
* opaque loading screen, and a canopy that needs fresh meshes otherwise trickles in two a frame.
|
|
240
|
+
*/
|
|
241
|
+
readonly coveredFreshMeshesPerUpdate?: number;
|
|
242
|
+
/**
|
|
243
|
+
* Side of the world-grid square one shared batch's records are clustered into, in world units.
|
|
244
|
+
* Defaults to the package's own `cellSize`, which is the square the placements are already cut
|
|
245
|
+
* on. Each `(key, cluster)` is its own caster InstancedMesh with its own bounds on the shadow
|
|
246
|
+
* caster layer, so a virtual-shadow level submits only the clusters its window covers. The main
|
|
247
|
+
* pass keeps one mesh per `asset:level:part` whatever this is, so it costs main-pass draws
|
|
248
|
+
* nothing. A larger square means fewer caster meshes and more of the world in every level render.
|
|
249
|
+
*/
|
|
250
|
+
readonly clusterSize?: number;
|
|
251
|
+
/**
|
|
252
|
+
* Milliseconds one `update` may spend admitting streamed content — cell batches, terrain tiles,
|
|
253
|
+
* colliders and `maxDistance`/`lods` refilters together. Defaults to 2, and `Infinity` opts out
|
|
254
|
+
* of the ceiling entirely.
|
|
255
|
+
*
|
|
256
|
+
* The ceiling is a budget, not a promise: one unit of work always finishes, so a frame spends at
|
|
257
|
+
* most this plus its last unit. Work that does not fit waits for the next `update` rather than
|
|
258
|
+
* being dropped, and `stats().admission` reports what is waiting. A frame that admits nothing
|
|
259
|
+
* costs nothing here.
|
|
260
|
+
*/
|
|
261
|
+
readonly admissionBudgetMs?: number;
|
|
262
|
+
/**
|
|
263
|
+
* The admission budget while the startup cover hides the world and readiness is pending. Defaults
|
|
264
|
+
* to 8x `admissionBudgetMs` (16 ms for the 2 ms default), so the spawn a loading screen waits on
|
|
265
|
+
* is admitted in fewer frames. Set it equal to `admissionBudgetMs` to keep one budget throughout.
|
|
266
|
+
*/
|
|
267
|
+
readonly coveredAdmissionBudgetMs?: number;
|
|
268
|
+
/**
|
|
269
|
+
* Milliseconds source for the admission budget, `performance.now` by default. Injectable so a
|
|
270
|
+
* test can prove the ceiling instead of hoping a machine is slow enough to show it.
|
|
271
|
+
*/
|
|
272
|
+
readonly admissionNow?: () => number;
|
|
273
|
+
/**
|
|
274
|
+
* The screen-space projection the extra levels of a baked AutoLOD chain are switched at, for an
|
|
275
|
+
* asset whose `world.json` entry names no nonempty authored `lods` of its own. An explicit empty
|
|
276
|
+
* list also uses the chain when prepared geometry and material still match its static contract.
|
|
277
|
+
*
|
|
278
|
+
* A chain measures its levels' geometric error in world units and the model runtime turns that
|
|
279
|
+
* into pixels per frame; a batched draw cannot, so the same test is solved for distance once,
|
|
280
|
+
* here, and every placement beyond it draws the next level. `fovY` is the vertical field of view
|
|
281
|
+
* in degrees and `viewportHeight` the drawing-buffer height in raster pixels — a CSS height is the
|
|
282
|
+
* wrong number, exactly as it is for the model runtime.
|
|
283
|
+
*
|
|
284
|
+
* Defaults are 60° over 1080 raster rows: a desktop view, and what the switch distance is a
|
|
285
|
+
* function of. A world whose camera this class cannot see should pass its own, or a world with a
|
|
286
|
+
* narrow field of view (a telephoto gun sight) or a tall window will switch earlier than its
|
|
287
|
+
* pixels ask for. An asset with nonempty authored `lods` ignores all three numbers entirely: the package is
|
|
288
|
+
* the authority on its own shape.
|
|
289
|
+
*
|
|
290
|
+
* `maxPixelError` is the error budget, in pixels, every synthesized level is selected against, and
|
|
291
|
+
* it defaults to 4 rather than to the budget the asset's chain was registered with. The
|
|
292
|
+
* registered budget is calibrated for a `ModelLod`, which picks a level for *one* mesh from where
|
|
293
|
+
* that mesh is on screen; an instanced draw cannot, because every placement in the draw is at its
|
|
294
|
+
* own distance and the draw is one call with one geometry. The batched answer has to be solved
|
|
295
|
+
* once, for the whole key, which moves every switch distance outward by the ratio of the budgets —
|
|
296
|
+
* and a 1 px budget is calibrated for a hero object filling the screen. At 1 px a tree's switches
|
|
297
|
+
* land at 400–600 m on a 1080-row view, which on a 2 km map with a 640 m ring is past most of the
|
|
298
|
+
* resident world: the levels are all there and none of them is ever selected, which is the same
|
|
299
|
+
* full triangle bill the chain was added to remove. Four pixels puts the first switch inside the
|
|
300
|
+
* ring, where it can actually do something.
|
|
301
|
+
*/
|
|
302
|
+
readonly autoLod?: {
|
|
303
|
+
readonly fovY?: number;
|
|
304
|
+
readonly viewportHeight?: number;
|
|
305
|
+
readonly maxPixelError?: number;
|
|
306
|
+
};
|
|
307
|
+
/**
|
|
308
|
+
* The GPU-driven main pass: one compute dispatch culls and LOD-selects every resident placement
|
|
309
|
+
* into a shared matrix buffer, and each main key draws its own region of it through an indirect
|
|
310
|
+
* record. The CPU keeps only coarse per-cell visibility and admits the complete resident
|
|
311
|
+
* `maxDistance` source set; a walking camera therefore costs no instance repack or cull/LOD
|
|
312
|
+
* replacement. An explicit `placementReach` remains an admission boundary because it has no GPU
|
|
313
|
+
* slot equivalent.
|
|
314
|
+
*
|
|
315
|
+
* `true` by default where the backend can run it: it needs compute, storage buffers and
|
|
316
|
+
* `drawIndexedIndirect`, and a backend without them falls back to exactly this class's CPU path —
|
|
317
|
+
* a lost saving, never a wrong picture. `gpuScene: false`, `TN_GPU_SCENE=0` or `?tnGpuScene=0`
|
|
318
|
+
* turns it off, and `stats().gpuScene` and the `TN_WORLD_GPU_SCENE` line say which path a run
|
|
319
|
+
* took.
|
|
320
|
+
*/
|
|
321
|
+
readonly gpuScene?: boolean;
|
|
322
|
+
/**
|
|
323
|
+
* Hold every dispatch's indirect args against the pure `cullAndSelect` reference and print the keys
|
|
324
|
+
* that disagree. `false` by default, and `TN_GPU_SCENE_VALIDATE=1` or `?tnGpuSceneValidate=1` turns
|
|
325
|
+
* it on.
|
|
326
|
+
*
|
|
327
|
+
* A readback is a queue submission and a mapped buffer, so this is a mode for answering "which key
|
|
328
|
+
* draws fewer instances than the CPU path" and never a walk to be measured with.
|
|
329
|
+
* For a fixed-step diagnostic walk, call {@link validateGpuFrame} after the render and await its
|
|
330
|
+
* promise before advancing the next frame; that opt-in fence checks every dispatch and replaces
|
|
331
|
+
* the periodic samples for that world.
|
|
332
|
+
*/
|
|
333
|
+
readonly gpuSceneValidate?: boolean;
|
|
334
|
+
/**
|
|
335
|
+
* Sample what the GPU actually selects in the main pass — a readback of the indirect args every
|
|
336
|
+
* 30 dispatches — and report it as `stats().gpuScene` and on the `TN_WORLD_GPU_SCENE`
|
|
337
|
+
* line. Off unless asked: the engine asks when the frame budget is on, and a validation turns it on
|
|
338
|
+
* by itself, so `TN_FRAME_BUDGET`'s `mainGpuTriangles` is the GPU-selected count and not the mesh
|
|
339
|
+
* capacity `tri=` reports. Set it explicitly when driving the world without a frame budget.
|
|
340
|
+
*/
|
|
341
|
+
readonly gpuSceneTally?: boolean;
|
|
342
|
+
/**
|
|
343
|
+
* Run the hierarchical-depth occlusion test in the cull kernel and report what it would cull.
|
|
344
|
+
*
|
|
345
|
+
* `"measure"` (the default unless `?tnOcclusion=off`, `TN_OCCLUSION=off` or a caller's own value
|
|
346
|
+
* says otherwise) builds a max-distance pyramid from the previous frame's scene-pass depth and
|
|
347
|
+
* counts the placements the test hides **while drawing all of them**: a measured frame is the frame
|
|
348
|
+
* an unmeasured run draws, so the only difference between the two runs is the count and the cost of
|
|
349
|
+
* building the pyramid. `"off"` runs no test and allocates nothing. `stats().gpuScene.occlusion`
|
|
350
|
+
* reports the counts, the pyramid's own cost, and `refused: no scene depth` when no render chain
|
|
351
|
+
* installed a pass to take a depth from.
|
|
352
|
+
*
|
|
353
|
+
* See {@link occlusionMode} and `render/depth-pyramid.ts`.
|
|
354
|
+
*/
|
|
355
|
+
readonly occlusion?: OcclusionMode;
|
|
356
|
+
/**
|
|
357
|
+
* Record every GPU-dressed main batch mesh and every resident cell's hand-placed chunks into
|
|
358
|
+
* `BundleGroup`s, and replay the records instead of re-walking three's per-object path for each
|
|
359
|
+
* draw. On by default: PRD-494 AC-2 measured the walking `draw` span at a 5.0 ms lower p95 than
|
|
360
|
+
* develop over 3 interleaved runs with bundles on and a picture a blind world gate called equal,
|
|
361
|
+
* which is the measurement the old opt-in default was decided without — so `bundles: false`,
|
|
362
|
+
* `?tnBundles=0` or `TN_BUNDLES=0` is the way back to the per-object path, and `stats().bundle`
|
|
363
|
+
* and the `TN_WORLD_BUNDLE` line say which way a run took and what asked for it.
|
|
364
|
+
*
|
|
365
|
+
* A record is an encoder, not a render pass, so only a draw that needs no live pass is recorded:
|
|
366
|
+
* a framebuffer reader, a transmissive impostor, a skinned or morphed mesh and a per-object hook
|
|
367
|
+
* all stay on the path they were already on. See `bundleSafe`.
|
|
368
|
+
*
|
|
369
|
+
* The render list inside a bundle is fixed when it is recorded, so a bundled mesh is never hidden:
|
|
370
|
+
* the dispatch draws zero instances for a key the camera cannot see, and an indirect draw of zero
|
|
371
|
+
* instances costs the GPU nothing. Toggling `visible` would force a re-record instead, and the
|
|
372
|
+
* shadow node's texel gate skips a bundled mesh for the same reason.
|
|
373
|
+
*
|
|
374
|
+
* A chunk has no dispatch behind it, so the two answers it needs are its own: its meshes are never
|
|
375
|
+
* culled by the record, because a mesh a record dropped is missing geometry the moment the camera
|
|
376
|
+
* turns towards it, and each cell records into its own group whose `visible` is the main cull's
|
|
377
|
+
* answer for that cell — the same coarse answer the scatter batches take, one cell wide. What that
|
|
378
|
+
* costs is the price of the option: a cell the cull cannot see is not drawn at all, which takes its
|
|
379
|
+
* chunk casters out of the shadow levels with it, and a cell it can only partly see draws the part
|
|
380
|
+
* facing away. Both rasterize nothing or nearly so; the missing shadow is the real difference.
|
|
381
|
+
*/
|
|
382
|
+
readonly bundles?: boolean;
|
|
383
|
+
/**
|
|
384
|
+
* Raise the LOD distance bias when the main pass is over its share of the frame's GPU budget, and
|
|
385
|
+
* decay it back toward 1 when it is comfortably under, default true.
|
|
386
|
+
*
|
|
387
|
+
* The main pass is triangle-bound: a flyover's near and mid tree levels are millions of triangles
|
|
388
|
+
* and the GPU time tracks that count. When `renderer.gpuMainMs()` — the smoothed main-pass GPU
|
|
389
|
+
* time — exceeds `mainGpuShare` of a 60 fps frame, every LOD switch is crossed earlier by
|
|
390
|
+
* multiplying the camera distance both selection paths compare by one shared multiplier, coarsening
|
|
391
|
+
* the same placements the GPU is already struggling to draw. It rises in bounded steps, never in a
|
|
392
|
+
* jump, so no level pops. `false` pins the bias at 1 for the whole run, which is byte-identical to
|
|
393
|
+
* the selection before this feature existed: `?tnAdaptiveLod=0`, `TN_ADAPTIVE_LOD=0` or
|
|
394
|
+
* `__tnAdaptiveLod = 0` also turns it off.
|
|
395
|
+
*/
|
|
396
|
+
readonly adaptiveLod?: boolean;
|
|
397
|
+
/**
|
|
398
|
+
* The fraction of a frame's GPU time the main pass may take before the adaptive LOD bias rises,
|
|
399
|
+
* `(0, 1]`, default 0.5.
|
|
400
|
+
*
|
|
401
|
+
* The budget is `mainGpuShare x min(deltaTime, 1/60 s)`: the frame cap keeps the budget honest the
|
|
402
|
+
* same way the shadow refresh gate does, because the frame that draws an expensive main pass is
|
|
403
|
+
* itself long and reading its own inflated delta would let the cost it judges pass its own test.
|
|
404
|
+
* `?tnMainGpuShare=0.1`, `TN_MAIN_GPU_SHARE=0.1` or `__tnMainGpuShare = 0.1` forces adaptation on a
|
|
405
|
+
* GPU that would otherwise never exceed the share.
|
|
406
|
+
*/
|
|
407
|
+
readonly mainGpuShare?: number;
|
|
408
|
+
/**
|
|
409
|
+
* Bake a whole-asset octahedral impostor for every alpha-cutout foliage asset and append it as the
|
|
410
|
+
* asset's terminal, two-triangle LOD. Default false: omission keeps the authored/generated source
|
|
411
|
+
* levels, and `?tnImpostors=1` or `TN_IMPOSTORS=1` opts a launch in. It is opt-in until the judged
|
|
412
|
+
* Machinefall capture passes (PRD-473 AC-3). With `preserveAuthoredParts`, an asset must author
|
|
413
|
+
* `impostorDistance` to receive a terminal impostor.
|
|
414
|
+
*
|
|
415
|
+
* Set true to bake them, or leave it off to keep the source levels for a visual comparison.
|
|
416
|
+
*
|
|
417
|
+
* The bake runs inside the render cadence — one atlas view per `process` — so it costs a
|
|
418
|
+
* slice of a frame rather than a hitch, and it starts only after the asset's own model has been
|
|
419
|
+
* adopted. A seamless switch needs the impostor's atlas to cover the same cutout the source draws,
|
|
420
|
+
* so an asset whose levels carry no alpha-cutout part is never baked. `false` drops only the atlas
|
|
421
|
+
* terminal: every level the authored package and its baked chain give is kept, and the authored
|
|
422
|
+
* middle-level cutout coverage a level would otherwise be missing its foliage at is still applied.
|
|
423
|
+
*/
|
|
424
|
+
readonly impostors?: boolean;
|
|
425
|
+
}
|
|
426
|
+
|
|
427
|
+
/**
|
|
428
|
+
* What the GPU actually selected in the main pass, from the scene's last landed tally.
|
|
429
|
+
*
|
|
430
|
+
* `triangles` is the GPU-selected count (`instanceCount x indexCount / 3` summed over the indirect
|
|
431
|
+
* records), never the mesh-capacity upper bound `renderer.info.render.triangles` reports, and it
|
|
432
|
+
* covers the main pass only: shadow passes are not tallied. `ageFrames` is how many dispatches have
|
|
433
|
+
* passed since those bytes were issued, so a caller never mistakes a stale sample for this frame's.
|
|
434
|
+
*/
|
|
435
|
+
export interface IWorldCellsGpuTally {
|
|
436
|
+
readonly instances: number;
|
|
437
|
+
readonly triangles: number;
|
|
438
|
+
readonly ageFrames: number;
|
|
439
|
+
}
|
|
440
|
+
|
|
441
|
+
/** Local render coverage, independent of shader prewarm and distant admission. */
|
|
442
|
+
export interface IWorldRegionReadiness {
|
|
443
|
+
readonly requiredCells: number;
|
|
444
|
+
readonly loadedCells: number;
|
|
445
|
+
readonly requiredTerrainTiles: number;
|
|
446
|
+
readonly loadedTerrainTiles: number;
|
|
447
|
+
readonly failures: number;
|
|
448
|
+
readonly cancelled: boolean;
|
|
449
|
+
readonly ready: boolean;
|
|
450
|
+
}
|
|
451
|
+
|
|
452
|
+
/** One `whenSpawnReady` caller: a fixed region snapshot, its deadline and its promise sinks. */
|
|
453
|
+
export interface ISpawnWaiter {
|
|
454
|
+
readonly position: { readonly x: number; readonly z: number };
|
|
455
|
+
readonly radius: number;
|
|
456
|
+
readonly resolve: (readiness: IWorldRegionReadiness) => void;
|
|
457
|
+
readonly reject: (error: Error) => void;
|
|
458
|
+
readonly timer: ReturnType<typeof setTimeout>;
|
|
459
|
+
}
|
|
460
|
+
|
|
461
|
+
export interface ICellBatch {
|
|
462
|
+
readonly asset: string;
|
|
463
|
+
/**
|
|
464
|
+
* The run these records came from. One cell can hold two runs of one canonical asset — two names
|
|
465
|
+
* for the same model — and each builds its own, so a refilter and a rebuild have to know which of
|
|
466
|
+
* the cell's entries belong to the run they are replacing.
|
|
467
|
+
*/
|
|
468
|
+
readonly run: IWorldRun;
|
|
469
|
+
readonly batch: InstancedBatch;
|
|
470
|
+
/** Published adjacent LOD interval per instance, present only on the CPU dither path. */
|
|
471
|
+
readonly lodRanges: Float32Array | undefined;
|
|
472
|
+
readonly level: number;
|
|
473
|
+
readonly part: number;
|
|
474
|
+
/** How far the follow point has to move before this batch is refiltered, `undefined` never. */
|
|
475
|
+
readonly threshold: number | undefined;
|
|
476
|
+
/** The shared mesh this cell's instances are written into, and its segment there (-1: none). */
|
|
477
|
+
shared: SharedBatch | undefined;
|
|
478
|
+
segment: number;
|
|
479
|
+
/**
|
|
480
|
+
* The GPU scene's source records this entry draws from, shared by every part of its level, and
|
|
481
|
+
* handed back by `#clearSegment`. `undefined` while the scene is off or the records are the
|
|
482
|
+
* dispatches' own already — a record released twice is a no-op, which is what lets one list be
|
|
483
|
+
* held by a whole level's parts.
|
|
484
|
+
*/
|
|
485
|
+
gpu: number[] | undefined;
|
|
486
|
+
/**
|
|
487
|
+
* The shadow-caster cluster this cell's records also go into, and its segment there (-1: none).
|
|
488
|
+
* The main mesh is one per key and casts nothing; the same records are written into one mesh per
|
|
489
|
+
* `(key, cluster)` on the caster layer, which is what a virtual-shadow level culls.
|
|
490
|
+
*/
|
|
491
|
+
caster: SharedBatch | undefined;
|
|
492
|
+
casterSegment: number;
|
|
493
|
+
/**
|
|
494
|
+
* The wide-caster half, and its segment there (-1: none): the same records again, in one mesh per
|
|
495
|
+
* key covering the whole ring, alone on the wide caster layer. A shadow level whose window covers
|
|
496
|
+
* the ring would otherwise submit one cluster per square for the same pixels.
|
|
497
|
+
*/
|
|
498
|
+
wide: SharedBatch | undefined;
|
|
499
|
+
wideSegment: number;
|
|
500
|
+
/**
|
|
501
|
+
* The root-matrix records this entry's level put in the far shadow, when the asset has an
|
|
502
|
+
* impostor: the placement transform alone, never `placement * part local`. The whole-asset impostor
|
|
503
|
+
* bakes every LOD0 part's own transform into its atlas, so its quad is drawn at the placement root
|
|
504
|
+
* and composing a source part's offset again would apply that part's transform twice. `undefined`
|
|
505
|
+
* for a non-impostor asset, whose wide half keeps the per-part source records.
|
|
506
|
+
*/
|
|
507
|
+
wideRoot: InstancedBatch | undefined;
|
|
508
|
+
/**
|
|
509
|
+
* The world bounds of the records this entry holds, from the filter that built it. The shadow
|
|
510
|
+
* invalidation is the union of these over the entries a swap moved in and out, which is the point
|
|
511
|
+
* of measuring them per record rather than per cell: a 48 m level's window is smaller than the
|
|
512
|
+
* cell box, so the cell box always covered it and always redrew it.
|
|
513
|
+
*/
|
|
514
|
+
shadowBounds: Box3 | undefined;
|
|
515
|
+
lastFilterY: number;
|
|
516
|
+
lastFilterX: number;
|
|
517
|
+
lastFilterZ: number;
|
|
518
|
+
/** The LOD eye the levels were picked from; see `IWorldCellsLoadOptions.lodFrom`. */
|
|
519
|
+
lastLodX: number;
|
|
520
|
+
lastLodY: number;
|
|
521
|
+
lastLodZ: number;
|
|
522
|
+
}
|
|
523
|
+
|
|
524
|
+
/** The geometry and material one batch draws; a part is one of these plus what it does not need. */
|
|
525
|
+
export type IBatchShape = Pick<IAssetPart, "geometry" | "material">;
|
|
526
|
+
|
|
527
|
+
/** Which GPU-scene key one main batch draws: `asset:level:part`, and the part's place in the model. */
|
|
528
|
+
export interface IKeyDescriptor {
|
|
529
|
+
readonly asset: string;
|
|
530
|
+
readonly key: string;
|
|
531
|
+
readonly level: number;
|
|
532
|
+
readonly part: number;
|
|
533
|
+
}
|
|
534
|
+
|
|
535
|
+
/** One key a loaded asset's levels contributed to the prewarm queue. */
|
|
536
|
+
|
|
537
|
+
/** One asset's placements, waiting to be built, or already holding their own cell's records. */
|
|
538
|
+
export interface IPrewarmEntry {
|
|
539
|
+
readonly asset: string;
|
|
540
|
+
/**
|
|
541
|
+
* Which pass this mesh is: the main pass's key, its caster cluster, its wide, or the shadow twin
|
|
542
|
+
* of the main key that a GPU-driven map draws instead of the two caster halves.
|
|
543
|
+
*/
|
|
544
|
+
readonly role: "cluster" | "key" | "main" | "wide";
|
|
545
|
+
readonly geometry: BufferGeometry;
|
|
546
|
+
readonly key: string;
|
|
547
|
+
readonly level: number;
|
|
548
|
+
readonly material: Material;
|
|
549
|
+
/** The part of the level, which is the third half of a key's name. */
|
|
550
|
+
readonly part: number;
|
|
551
|
+
}
|
|
552
|
+
|
|
553
|
+
/**
|
|
554
|
+
* A plain `{ min, max }` region, the shape a shadow level's invalidation reads and the shape a game
|
|
555
|
+
* can be handed without importing three. Plain numbers, so the object a caller records its bounds
|
|
556
|
+
* in is the object that crosses the boundary.
|
|
557
|
+
*/
|
|
558
|
+
export interface IShadowRegion {
|
|
559
|
+
/** Only added casters; their redraw can retain the existing depth. */
|
|
560
|
+
admission?: boolean;
|
|
561
|
+
min: { x: number; y: number; z: number };
|
|
562
|
+
max: { x: number; y: number; z: number };
|
|
563
|
+
}
|
|
564
|
+
|
|
565
|
+
/**
|
|
566
|
+
* A camera, plus the one flag the exclusion rule reads. Three sets `isOrthographicCamera` on an
|
|
567
|
+
* `OrthographicCamera` at runtime and declares it on no base camera type, so it is duck-typed here
|
|
568
|
+
* the same way `ICasterScaleMesh` and `isInstancedMesh` are.
|
|
569
|
+
*/
|
|
570
|
+
export type ICamera = Camera & { readonly isOrthographicCamera?: boolean };
|
|
571
|
+
|
|
572
|
+
/**
|
|
573
|
+
* The `@x,z` half of a cluster key, for a cell index. `cellsPerCluster` squares of cells per
|
|
574
|
+
* cluster, so the answer is stable for as long as the grid is: placements never move, so a record is
|
|
575
|
+
* only ever clustered when the cell holding it is admitted or evicted.
|
|
576
|
+
*/
|
|
577
|
+
export function clusterOf(cellX: number, cellZ: number, cellsPerCluster: number): string {
|
|
578
|
+
return `${String(Math.floor(cellX / cellsPerCluster))},${String(Math.floor(cellZ / cellsPerCluster))}`;
|
|
579
|
+
}
|
|
580
|
+
|
|
581
|
+
/**
|
|
582
|
+
* Whether any of `gates` — ascending — lies in `[low, high]`. One binary search for the first gate at
|
|
583
|
+
* or past `low`, against the walk of every gate a scan does per cell: a follow point that has not
|
|
584
|
+
* carried anything across a boundary is the common case, and the refilter runs it over every resident
|
|
585
|
+
* cell every 2 m of travel. Ends included, so a placement exactly on a gate is one of the reasons to
|
|
586
|
+
* rebuild.
|
|
587
|
+
*/
|
|
588
|
+
export function crossesGate(gates: readonly number[], low: number, high: number): boolean {
|
|
589
|
+
let start = 0;
|
|
590
|
+
let end = gates.length;
|
|
591
|
+
while (start < end) {
|
|
592
|
+
const middle = (start + end) >> 1;
|
|
593
|
+
if ((gates[middle] as number) < low) start = middle + 1;
|
|
594
|
+
else end = middle;
|
|
595
|
+
}
|
|
596
|
+
return start < gates.length && (gates[start] as number) <= high;
|
|
597
|
+
}
|
|
598
|
+
|
|
599
|
+
export interface ICellProxyState {
|
|
600
|
+
readonly cell: IResidentCell;
|
|
601
|
+
readonly selector: CellProxySelection;
|
|
602
|
+
readonly retainedPaths: string[];
|
|
603
|
+
pending: boolean;
|
|
604
|
+
compiling: boolean;
|
|
605
|
+
cancelled: boolean;
|
|
606
|
+
compiled: boolean;
|
|
607
|
+
active: boolean;
|
|
608
|
+
bytes: number;
|
|
609
|
+
model?: Object3D;
|
|
610
|
+
prepared?: IPreparedCellProxy;
|
|
611
|
+
readonly observed: Set<Mesh>;
|
|
612
|
+
readonly hidden: Map<Mesh, boolean>;
|
|
613
|
+
readonly mainMasks: Map<Mesh, number>;
|
|
614
|
+
}
|
|
615
|
+
|
|
616
|
+
export interface IResidentCell {
|
|
617
|
+
proxy?: ICellProxyState;
|
|
618
|
+
readonly mainChunkMeshes: Mesh[];
|
|
619
|
+
readonly chunkInstances: Map<
|
|
620
|
+
InstancedMesh,
|
|
621
|
+
{
|
|
622
|
+
readonly matrix: InstancedMesh["instanceMatrix"];
|
|
623
|
+
readonly version: number;
|
|
624
|
+
readonly count: number;
|
|
625
|
+
}
|
|
626
|
+
>;
|
|
627
|
+
readonly completedRuns: Set<IWorldRun>;
|
|
628
|
+
chunksLoaded: boolean;
|
|
629
|
+
chunkFailed: boolean;
|
|
630
|
+
readonly key: string;
|
|
631
|
+
readonly x: number;
|
|
632
|
+
readonly z: number;
|
|
633
|
+
readonly cell: IWorldCell;
|
|
634
|
+
/**
|
|
635
|
+
* The union of the distances from every one of this cell's batches' own LOD eyes to the cell's
|
|
636
|
+
* rectangle, widened as batches are built and never narrowed; see `#staleIn`. Monotone on purpose:
|
|
637
|
+
* too wide a range means a cell the gate test does not reject, and too narrow one would drop a
|
|
638
|
+
* rebuild the pass owes.
|
|
639
|
+
*/
|
|
640
|
+
filterNear: number;
|
|
641
|
+
filterFar: number;
|
|
642
|
+
readonly generation: number;
|
|
643
|
+
readonly instances: number;
|
|
644
|
+
readonly bytes: number;
|
|
645
|
+
readonly batches: ICellBatch[];
|
|
646
|
+
readonly chunks: Object3D[];
|
|
647
|
+
/**
|
|
648
|
+
* The exact `assets.model` cache paths this cell's chunks asked the loader for, held in
|
|
649
|
+
* `#modelPaths` and handed back once the last cell naming a path is gone, exactly like an asset's
|
|
650
|
+
* levels; see `#releaseModelPaths`. Empty for a cell with no chunks or a `loadModel` override.
|
|
651
|
+
*/
|
|
652
|
+
readonly retainedModelPaths: string[];
|
|
653
|
+
/**
|
|
654
|
+
* Per run, the placements its last swapped build kept, as `PLACED_STRIDE` numbers each: the
|
|
655
|
+
* placement index, then its world box (min xyz, max xyz). A refilter's swap tells the shadow levels
|
|
656
|
+
* only the placements that entered or left this list; see `WorldCellRender.swap`.
|
|
657
|
+
*/
|
|
658
|
+
placed?: Map<IWorldRun, readonly number[]>;
|
|
659
|
+
}
|
|
660
|
+
|
|
661
|
+
/** Numbers per placement in `IBuildJob.placed` and `IResidentCell.placed`: index, then a box. */
|
|
662
|
+
export const PLACED_STRIDE = 7;
|
|
663
|
+
|
|
664
|
+
/**
|
|
665
|
+
* One cell's asset run waiting to be built, in units small enough to fit a frame's admission
|
|
666
|
+
* budget: a slice of placements, or one mesh built.
|
|
667
|
+
*
|
|
668
|
+
* A job outlives the `update` that queued it, so every field it needs to resume is on the job and
|
|
669
|
+
* not on the call stack — a streamed cell holds its residency slot while it waits, so the work is
|
|
670
|
+
* never spent on a cell that has since left.
|
|
671
|
+
*/
|
|
672
|
+
export interface IBuildJob {
|
|
673
|
+
readonly asset: IAssetState;
|
|
674
|
+
readonly cell: IResidentCell;
|
|
675
|
+
readonly run: IWorldRun;
|
|
676
|
+
/** The follow snapshot taken at first admission, held fixed across every placement slice. */
|
|
677
|
+
filterY: number;
|
|
678
|
+
filterX: number;
|
|
679
|
+
filterZ: number;
|
|
680
|
+
/** The LOD eye snapshot, taken with the follow snapshot; levels and `maxDistance` read it. */
|
|
681
|
+
lodX: number;
|
|
682
|
+
lodY: number;
|
|
683
|
+
lodZ: number;
|
|
684
|
+
/** A refilter's outgoing batches, drawn until this job's own batches are attached. */
|
|
685
|
+
replaced: ICellBatch[];
|
|
686
|
+
readonly replacement: boolean;
|
|
687
|
+
/** This job's built batches, attached together when the last one is ready. */
|
|
688
|
+
readonly fresh: ICellBatch[];
|
|
689
|
+
/** The run's placement records, read once and kept across the slices that filter them. */
|
|
690
|
+
records: Float32Array | undefined;
|
|
691
|
+
/** Next placement to filter; the filter is complete when it reaches `run.count`. */
|
|
692
|
+
next: number;
|
|
693
|
+
batches: InstancedBatch[][] | undefined;
|
|
694
|
+
/** Two published LOD bounds per `(level, part)` instance, in matrix append order. */
|
|
695
|
+
lodRanges: number[][][] | undefined;
|
|
696
|
+
/**
|
|
697
|
+
* One root-matrix batch per level the filter reached, filled only when the asset can become a
|
|
698
|
+
* whole-asset impostor: the placement transform with no part offset, which is what its far quad
|
|
699
|
+
* needs. `undefined` for every other asset, so nothing pays for records the wide half never reads.
|
|
700
|
+
*/
|
|
701
|
+
roots: (InstancedBatch | undefined)[] | undefined;
|
|
702
|
+
/**
|
|
703
|
+
* Bypass the refilter's identical-answer fast path. A handoff that changes what a wide segment must
|
|
704
|
+
* hold is not an identical answer even when the level and records are, so the rebuild has to swap.
|
|
705
|
+
*/
|
|
706
|
+
force: boolean;
|
|
707
|
+
/** One world-bounds box per `(level, part)` batch, filled by `#addPlacements` and read on swap. */
|
|
708
|
+
boxes: Box3[][] | undefined;
|
|
709
|
+
/** The placements this filter kept, `PLACED_STRIDE` numbers each; see `IResidentCell.placed`. */
|
|
710
|
+
placed: number[] | undefined;
|
|
711
|
+
/** How many of the (level, part) meshes have been built. */
|
|
712
|
+
published: number;
|
|
713
|
+
/**
|
|
714
|
+
* The GPU scene's source records for the placements this filter kept, one per placement beside the
|
|
715
|
+
* level it reached — filled by `#addPlacements` only while the scene is on, and read on the swap.
|
|
716
|
+
*/
|
|
717
|
+
sources: IGpuSource[] | undefined;
|
|
718
|
+
/** The records placed per level, so every part of a level shares one list; see `#placeSources`. */
|
|
719
|
+
gpuByLevel: Map<number, number[]> | undefined;
|
|
720
|
+
}
|
|
721
|
+
|
|
722
|
+
/** One placement as the GPU scene's source buffer holds it: the placement's own transform, no part. */
|
|
723
|
+
export interface IGpuSource {
|
|
724
|
+
readonly level: number;
|
|
725
|
+
readonly matrix: Matrix4;
|
|
726
|
+
readonly x: number;
|
|
727
|
+
readonly y: number;
|
|
728
|
+
readonly z: number;
|
|
729
|
+
/** Half the diagonal of the asset's authored bounds at this placement's scale. */
|
|
730
|
+
readonly radius: number;
|
|
731
|
+
/** The placement's uniform scale, carried so the dispatch can scale a whole-asset impostor gate. */
|
|
732
|
+
readonly scale: number;
|
|
733
|
+
}
|
|
734
|
+
|
|
735
|
+
/** One drawable part of one level, read out of the level's own GLB. */
|
|
736
|
+
export interface IAssetPart {
|
|
737
|
+
readonly geometry: BufferGeometry;
|
|
738
|
+
/** The mesh's transform relative to the model root, composed into every instance matrix. */
|
|
739
|
+
readonly local: Matrix4;
|
|
740
|
+
/** The surface the batch draws with: the shared surface for this part's material content. */
|
|
741
|
+
readonly material: Material;
|
|
742
|
+
/** The `materialKey` of that surface, released through the shared-surface registry. */
|
|
743
|
+
readonly surface: string;
|
|
744
|
+
}
|
|
745
|
+
|
|
746
|
+
export function positiveInteger(value: number, name: string): number {
|
|
747
|
+
if (!Number.isInteger(value) || value < 1)
|
|
748
|
+
throw new Error(`WorldCells ${name} must be a positive integer.`);
|
|
749
|
+
return value;
|
|
750
|
+
}
|
|
751
|
+
|
|
752
|
+
export function nonNegativeInteger(value: number, name: string): number {
|
|
753
|
+
if (!Number.isInteger(value) || value < 0)
|
|
754
|
+
throw new Error(`WorldCells ${name} must be a non-negative integer.`);
|
|
755
|
+
return value;
|
|
756
|
+
}
|
|
757
|
+
|
|
758
|
+
/** A metre threshold, unlike the counts above: 1.5 m is the whole point of the option. */
|
|
759
|
+
export function positiveMetres(value: number, name: string): number {
|
|
760
|
+
if (!Number.isFinite(value) || value <= 0)
|
|
761
|
+
throw new Error(`WorldCells ${name} must be a finite number greater than 0.`);
|
|
762
|
+
return value;
|
|
763
|
+
}
|
|
764
|
+
|
|
765
|
+
/**
|
|
766
|
+
* The admission budget: a positive number of milliseconds, or `Infinity` for no ceiling at all —
|
|
767
|
+
* which is what a game that wants one `update` to admit everything it can asks for. Zero is refused
|
|
768
|
+
* rather than obeyed, because a world whose budget is spent before it starts never streams at all,
|
|
769
|
+
* and that is never what anyone meant to write.
|
|
770
|
+
*/
|
|
771
|
+
export function admissionBudgetMs(value: number): number {
|
|
772
|
+
if (Number.isNaN(value) || value <= 0)
|
|
773
|
+
throw new Error("WorldCells admissionBudgetMs must be a positive number of milliseconds.");
|
|
774
|
+
return value;
|
|
775
|
+
}
|
|
776
|
+
|
|
777
|
+
export function cellKey(x: number, z: number): string {
|
|
778
|
+
return `${String(x)}:${String(z)}`;
|
|
779
|
+
}
|
|
780
|
+
|
|
781
|
+
/**
|
|
782
|
+
* Whether two batches publish the same levels per record. Records are `LOD_RANGE_STRIDE` (4) floats;
|
|
783
|
+
* only the levels (the first two) count: the fade a swap stamps describes the swap, not the answer.
|
|
784
|
+
*/
|
|
785
|
+
export function sameLodRanges(a: Float32Array | undefined, b: Float32Array | undefined): boolean {
|
|
786
|
+
if (a === undefined || b === undefined) return a === b;
|
|
787
|
+
if (a.length !== b.length) return false;
|
|
788
|
+
for (let index = 0; index < a.length; index += 4)
|
|
789
|
+
if (a[index] !== b[index] || a[index + 1] !== b[index + 1]) return false;
|
|
790
|
+
return true;
|
|
791
|
+
}
|
|
792
|
+
|
|
793
|
+
import type { IWorldGpuSceneReport } from "./world-gpu-scene.js";
|
|
794
|
+
|
|
795
|
+
export interface IWorldCellsStats {
|
|
796
|
+
readonly residentCells: number;
|
|
797
|
+
/**
|
|
798
|
+
* Placement bytes the resident cells hold. Admission adds them. Eviction removes them.
|
|
799
|
+
* Far-impostor and HLOD bytes sit outside this figure, in `impostor.far.bytes` and `hlod.bytes`.
|
|
800
|
+
* `budgets.bytes` caps the sum of all three.
|
|
801
|
+
*/
|
|
802
|
+
readonly residentBytes: number;
|
|
803
|
+
/** Resident cells whose initial placement runs and chunks have completed admission. */
|
|
804
|
+
readonly loadedCells: number;
|
|
805
|
+
readonly residentKeys: readonly string[];
|
|
806
|
+
/** Terrain tiles drawn, out to `terrain.streamRadius`; independent of the props' `ring`. */
|
|
807
|
+
readonly residentTiles: number;
|
|
808
|
+
/** Tiles holding a `createCollider` body, inside `terrain.colliderRadius`; 0 with no factory. */
|
|
809
|
+
readonly residentColliders: number;
|
|
810
|
+
/** Placement instances the resident cells hold, before any `maxDistance` filter. */
|
|
811
|
+
readonly instances: number;
|
|
812
|
+
readonly loadsInFlight: number;
|
|
813
|
+
/** Model loads waiting for a free lane; served nearest-cell first, in admission order. */
|
|
814
|
+
readonly loadsQueued: number;
|
|
815
|
+
/** Remaining placement slices and batch publications waiting for admission. */
|
|
816
|
+
readonly admissionBacklog: number;
|
|
817
|
+
/** Cumulative placement slices, mesh builds, and final run swaps completed by admission. */
|
|
818
|
+
readonly admissionCompletedUnits: number;
|
|
819
|
+
/**
|
|
820
|
+
* Shared batches still to be minted, plus the ones minted and not yet drawn; `0` once
|
|
821
|
+
* `prewarmed` has resolved.
|
|
822
|
+
*/
|
|
823
|
+
readonly pendingPrewarm: number;
|
|
824
|
+
/** Shared batches minted by the prewarm so far, cumulative. */
|
|
825
|
+
readonly prewarmMinted: number;
|
|
826
|
+
readonly evictions: number;
|
|
827
|
+
/** Cumulative `maxDistance`/`lods` refilters performed, across every update. */
|
|
828
|
+
readonly rebuilds: number;
|
|
829
|
+
/**
|
|
830
|
+
* Cumulative refilter *passes* run, whether or not they queued a rebuild. The pass walks every
|
|
831
|
+
* resident cell, derives both distance brackets and sorts what it found, so this is what says
|
|
832
|
+
* whether a follow point standing inside the 2 m step paid for it; `rebuilds` only says whether it
|
|
833
|
+
* was worth anything. See `LEVEL_REFILTER_STEP_METRES`.
|
|
834
|
+
*/
|
|
835
|
+
readonly refilters: number;
|
|
836
|
+
readonly levelRefilters: number;
|
|
837
|
+
/** Where the CPU path's levels were measured from; see `IWorldCellsLoadOptions.lodFrom`. */
|
|
838
|
+
readonly lodFrom: "camera" | "follow";
|
|
839
|
+
/**
|
|
840
|
+
* Cumulative stale cell-assets the refilter passes found, across every update. The pass walks every
|
|
841
|
+
* resident cell and gates it as a whole before it looks at one batch, so a follow point that has
|
|
842
|
+
* crossed nothing leaves this still — which is what says the walk cost brackets and comparisons and
|
|
843
|
+
* not allocations.
|
|
844
|
+
*/
|
|
845
|
+
readonly refilterEntries: number;
|
|
846
|
+
/**
|
|
847
|
+
* Cumulative refilters whose rebuild held the same records and were settled without a write,
|
|
848
|
+
* clear or compaction. A rising share of `rebuilds` is a follow point crossing a cell's distance
|
|
849
|
+
* bracket rather than any placement crossing a gate.
|
|
850
|
+
*/
|
|
851
|
+
readonly unchanged: number;
|
|
852
|
+
readonly failures: number;
|
|
853
|
+
/**
|
|
854
|
+
* What the main-pass cull cost, cumulative, and the evidence that a settled camera costs nothing.
|
|
855
|
+
*
|
|
856
|
+
* `frustums` is one a frame that had a perspective camera — it used to be one per main mesh, ~230
|
|
857
|
+
* of them on a 2 km walk. `windows` is how many of those meshes had to re-derive their window at
|
|
858
|
+
* all, and `repacks` how many copied records: both are 0 on a frame where the visible squares did
|
|
859
|
+
* not change and no record joined or left, which is what the two integer comparisons in
|
|
860
|
+
* `SharedBatch.cullFrom` buy.
|
|
861
|
+
*/
|
|
862
|
+
readonly mainCull: {
|
|
863
|
+
readonly frustums: number;
|
|
864
|
+
readonly windows: number;
|
|
865
|
+
readonly repacks: number;
|
|
866
|
+
readonly visibleEpoch: number;
|
|
867
|
+
};
|
|
868
|
+
/**
|
|
869
|
+
* What the GPU-driven main pass is doing, and why it is not: `on` is the answer, `reason` is the
|
|
870
|
+
* one line `TN_WORLD_GPU_SCENE` printed, and `dispatches` is what the walk actually paid for its
|
|
871
|
+
* per-instance work. `mainCull.repacks` and `refilters` stay at `0` while it is on — that is the
|
|
872
|
+
* CPU work it replaced, counted by the same counters that report it when it is off. `dressed` over
|
|
873
|
+
* `meshes` is the marker line's own pair, and it is the one that says the scene has meshes to draw
|
|
874
|
+
* with: an `on` with `0` dressed is a ring the CPU path is still drawing.
|
|
875
|
+
*/
|
|
876
|
+
readonly gpuScene: {
|
|
877
|
+
readonly on: boolean;
|
|
878
|
+
readonly reason: string;
|
|
879
|
+
readonly dispatches: number;
|
|
880
|
+
/** Resident source records: one per placement, shared by every part of the level it reached. */
|
|
881
|
+
readonly instances: number;
|
|
882
|
+
readonly keys: number;
|
|
883
|
+
readonly dressed: number;
|
|
884
|
+
readonly meshes: number;
|
|
885
|
+
/**
|
|
886
|
+
* Instances and triangles the GPU actually selected in the main pass, and the age of that
|
|
887
|
+
* sample in dispatches. Absent until the first tally lands, never zero: the scene's own
|
|
888
|
+
* `instances` above is what it holds, and `gpuInstances` is what the GPU drew.
|
|
889
|
+
*/
|
|
890
|
+
readonly gpuInstances?: number;
|
|
891
|
+
readonly gpuTriangles?: number;
|
|
892
|
+
readonly gpuTallyAgeFrames?: number;
|
|
893
|
+
/**
|
|
894
|
+
* What the pyramid occlusion test would cull, when a launch asked it to measure. `share` is the
|
|
895
|
+
* would-cull share of the main pass's GPU-selected triangles from the same landed readback, which
|
|
896
|
+
* is the number the go/no-go multiplies by `gpuMain`; `reason` names why nothing was measured.
|
|
897
|
+
*/
|
|
898
|
+
readonly occlusion?: NonNullable<IWorldGpuSceneReport["occlusion"]>;
|
|
899
|
+
};
|
|
900
|
+
/**
|
|
901
|
+
* Main-pass bundle membership: `children` counts grouped roots — every recorded main mesh under one
|
|
902
|
+
* of the main record's shards, plus every chunk of every resident cell under that cell's own group —
|
|
903
|
+
* `cpuMeshes` and `gpuMeshes` count shared batch members, and `on` reports actual main/chunk
|
|
904
|
+
* membership. These are membership counts, not observed backend draws. `records` counts
|
|
905
|
+
* invalidations since load: membership, material or geometry changes and CPU window repacks
|
|
906
|
+
* invalidate; GPU indirect count updates do not.
|
|
907
|
+
*
|
|
908
|
+
* `eligibility` counts CPU material checks, snapshot validations, fresh structural walks,
|
|
909
|
+
* oversized or unsupported child output, and `deferred` deep proofs. Snapshots check own links and
|
|
910
|
+
* Three's child readers, detecting deep edits without requiring `needsUpdate`, once per
|
|
911
|
+
* `staleFrames` period: 1 for a small world, the tested rows over a per-frame budget for a forest.
|
|
912
|
+
* Child discovery still allocates.
|
|
913
|
+
*
|
|
914
|
+
* `reason` is who asked: `default` is a run that set nothing, `option` is a load that named
|
|
915
|
+
* `bundles`, and `launch` is `?tnBundles` / `TN_BUNDLES` / `__tnBundles`. It is on the marker line
|
|
916
|
+
* too, because a run that turns the default off is exactly the run a reader cannot tell from a
|
|
917
|
+
* failing one without it.
|
|
918
|
+
*/
|
|
919
|
+
readonly bundle: {
|
|
920
|
+
readonly on: boolean;
|
|
921
|
+
readonly children: number;
|
|
922
|
+
readonly cpuMeshes: number;
|
|
923
|
+
readonly gpuMeshes: number;
|
|
924
|
+
readonly eligibility: {
|
|
925
|
+
readonly checks: number;
|
|
926
|
+
readonly refreshes: number;
|
|
927
|
+
readonly validations: number;
|
|
928
|
+
readonly uncached: number;
|
|
929
|
+
readonly deferred: number;
|
|
930
|
+
readonly staleFrames: number;
|
|
931
|
+
};
|
|
932
|
+
readonly reason: string;
|
|
933
|
+
readonly records: number;
|
|
934
|
+
};
|
|
935
|
+
/**
|
|
936
|
+
* The runtime impostor path: how many assets appended a terminal level, how many bakes are still
|
|
937
|
+
* queued or in flight, the triangles all terminal levels submit together — the number the whole
|
|
938
|
+
* feature exists to reduce — and the cache size: the logical colour atlas bytes held (each atlas's
|
|
939
|
+
* RGBA8 colour and normal mip chains), not every physical GPU buffer a render target may own, and
|
|
940
|
+
* the budget those bytes are enforced against.
|
|
941
|
+
*/
|
|
942
|
+
readonly impostor: {
|
|
943
|
+
readonly assets: number;
|
|
944
|
+
readonly pending: number;
|
|
945
|
+
readonly drawn: number;
|
|
946
|
+
readonly atlasBytes: number;
|
|
947
|
+
readonly budgetBytes: number;
|
|
948
|
+
readonly terminalTriangles: number;
|
|
949
|
+
/**
|
|
950
|
+
* The whole-map far aggregates: one `InstancedMesh` per atlas cache key, the ORIGINAL placements
|
|
951
|
+
* they hold (`instances`), how many of those the near ring has taken back (`nearOwned`), the
|
|
952
|
+
* physical instance bytes, and how many times an aggregate's buffer has been written. Missing
|
|
953
|
+
* measurements stay absent; a settled camera holds `uploads` still.
|
|
954
|
+
*/
|
|
955
|
+
readonly far: {
|
|
956
|
+
readonly aggregates: number;
|
|
957
|
+
readonly instances: number;
|
|
958
|
+
readonly live: number;
|
|
959
|
+
readonly nearOwned: number;
|
|
960
|
+
readonly bytes: number;
|
|
961
|
+
readonly uploads: number;
|
|
962
|
+
};
|
|
963
|
+
};
|
|
964
|
+
/** Cumulative rejected requests: cells skipped, instances or bytes refused, terrain retries. */
|
|
965
|
+
/** Compilation and zero-count main backend submission are separate observations. These counts
|
|
966
|
+
* do not prove GPU execution, image quality, or reduced frame time. bytes includes pending
|
|
967
|
+
* reservation and decoded copies/textures, never a claim about physical driver allocation. */
|
|
968
|
+
readonly hlod: {
|
|
969
|
+
readonly on: boolean;
|
|
970
|
+
readonly loaded: number;
|
|
971
|
+
readonly compiled: number;
|
|
972
|
+
readonly observed: number;
|
|
973
|
+
readonly active: number;
|
|
974
|
+
readonly pending: number;
|
|
975
|
+
readonly bytes: number;
|
|
976
|
+
readonly refused: number;
|
|
977
|
+
readonly reason: string;
|
|
978
|
+
readonly failures: number;
|
|
979
|
+
};
|
|
980
|
+
readonly pressure: { readonly cells: number; readonly instances: number; readonly bytes: number };
|
|
981
|
+
/**
|
|
982
|
+
* What the last `update` spent on admitting streamed content, and what it left behind.
|
|
983
|
+
*
|
|
984
|
+
* A rising `backlog` is the honest signal that admission is not keeping up with the follow point;
|
|
985
|
+
* it is the one number that says a player is outrunning the world.
|
|
986
|
+
*/
|
|
987
|
+
readonly admission: {
|
|
988
|
+
/** Milliseconds the last `update` spent admitting; at most the budget plus its last unit. */
|
|
989
|
+
readonly spentMs: number;
|
|
990
|
+
/** Cell-asset builds the last `update` had no budget for, still queued for a later one. */
|
|
991
|
+
readonly deferred: number;
|
|
992
|
+
/** Placement slices and meshes left to publish, plus one unit while terrain admission is owed. */
|
|
993
|
+
readonly backlog: number;
|
|
994
|
+
};
|
|
995
|
+
}
|