@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,1449 @@
|
|
|
1
|
+
import {
|
|
2
|
+
type BufferGeometry,
|
|
3
|
+
InstancedBufferAttribute,
|
|
4
|
+
InstancedMesh,
|
|
5
|
+
type Material,
|
|
6
|
+
Matrix4,
|
|
7
|
+
type Object3D,
|
|
8
|
+
Quaternion,
|
|
9
|
+
Vector3,
|
|
10
|
+
} from "three";
|
|
11
|
+
import { dropPooledFor } from "./render/mesh-pool.js";
|
|
12
|
+
import {
|
|
13
|
+
IMPOSTOR_FAR_CULL_ATTRIBUTE,
|
|
14
|
+
WorldImpostorSurface,
|
|
15
|
+
} from "./render/world-impostor-surface.js";
|
|
16
|
+
import {
|
|
17
|
+
type IImpostorPart,
|
|
18
|
+
type IImpostorRawRenderer,
|
|
19
|
+
IMPOSTOR_FRAME_PIXELS,
|
|
20
|
+
IMPOSTOR_VIEWS,
|
|
21
|
+
WORLD_IMPOSTOR_MARKER,
|
|
22
|
+
type WorldImpostorAtlas,
|
|
23
|
+
WorldImpostorBaker,
|
|
24
|
+
impostorBounds,
|
|
25
|
+
} from "./render/world-impostor.js";
|
|
26
|
+
import type { IRendererLike } from "./renderer.js";
|
|
27
|
+
import { levelTriangles } from "./world-cell-chunks.js";
|
|
28
|
+
import { cellKey } from "./world-cell-data.js";
|
|
29
|
+
import type {
|
|
30
|
+
IAssetPart,
|
|
31
|
+
IResidentCell,
|
|
32
|
+
IWorldCellsBudget,
|
|
33
|
+
IWorldCellsStats,
|
|
34
|
+
} from "./world-cell-data.js";
|
|
35
|
+
import type { IAssetState } from "./world-cell-models.js";
|
|
36
|
+
import { VIRTUAL_SHADOW_WIDE_CASTER_LAYER } from "./world-chunk-shadow.js";
|
|
37
|
+
import {
|
|
38
|
+
type IWorldAsset,
|
|
39
|
+
type IWorldCell,
|
|
40
|
+
type IWorldPackage,
|
|
41
|
+
type IWorldRun,
|
|
42
|
+
cellPlacements,
|
|
43
|
+
} from "./world-package.js";
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* GPU bytes of completed impostor atlases one world admits, 128 MiB. A 128 px two-attachment RGBA8
|
|
47
|
+
* atlas with mips is 2,796,160 B, so 48 fit and the 49th is refused before its atlas is allocated,
|
|
48
|
+
* keeping its source LODs. An atlas a live asset still draws from is never evicted, so the active
|
|
49
|
+
* record count is a hard admission cap rather than a target the cache trims toward — eviction only
|
|
50
|
+
* ever drops an inactive record to make room for a new one.
|
|
51
|
+
*/
|
|
52
|
+
const DEFAULT_IMPOSTOR_ATLAS_BUDGET_BYTES = 128 * 1024 * 1024;
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* The declared byte cost of one atlas at the bake's fixed frame, the same numbers
|
|
56
|
+
* `WorldImpostorAtlas.bytes` reports: both RGBA8 attachments' mip chains, the logical colour atlas
|
|
57
|
+
* cost rather than every physical GPU buffer a render target holds. Computed here so the cache
|
|
58
|
+
* budget is enforced BEFORE `baker.begin` allocates the atlas, never after.
|
|
59
|
+
*/
|
|
60
|
+
const IMPOSTOR_ATLAS_BYTES = ((): number => {
|
|
61
|
+
const levels = Math.floor(Math.log2(Math.max(1, IMPOSTOR_FRAME_PIXELS))) + 1;
|
|
62
|
+
let bytes = 0;
|
|
63
|
+
for (let level = 0; level < levels; level += 1) {
|
|
64
|
+
const edge = Math.max(1, IMPOSTOR_FRAME_PIXELS >> level);
|
|
65
|
+
bytes += edge * edge * IMPOSTOR_VIEWS * 4;
|
|
66
|
+
}
|
|
67
|
+
return 2 * bytes;
|
|
68
|
+
})();
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* The far-residency diagnostic marker: one bounded line per whole-map aggregate built, naming the one
|
|
72
|
+
* `InstancedMesh` per atlas cache key, its original placements, the live/near-owned split, its
|
|
73
|
+
* physical instance bytes and how many times its instance buffer has been written.
|
|
74
|
+
*/
|
|
75
|
+
const WORLD_IMPOSTOR_FAR_MARKER = "TN_WORLD_IMPOSTOR_FAR";
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* Bytes one far instance costs: its sixteen-float32 matrix plus the one-float per-instance cull the
|
|
79
|
+
* shared far surface reads. Both are physical allocations the budget bounds; the cull is uploaded
|
|
80
|
+
* once because the placement never moves.
|
|
81
|
+
*/
|
|
82
|
+
const FAR_INSTANCE_BYTES = 16 * 4 + 4;
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* One completed whole-asset atlas, cached by its content key and its source cutout contract.
|
|
86
|
+
*
|
|
87
|
+
* Bounded, not a generic cache: the atlas is the one GPU resource a later far reference may want to
|
|
88
|
+
* hold without keeping the full source GLB, and the CPU `center`/`radius` are the two scalars the
|
|
89
|
+
* surface needs to project it. `users` counts the live assets drawing it; a record with no user is
|
|
90
|
+
* inactive and evictable once the byte budget is over, and one with a user is never evicted.
|
|
91
|
+
*/
|
|
92
|
+
interface IImpostorRecord {
|
|
93
|
+
readonly key: string;
|
|
94
|
+
readonly atlas: WorldImpostorAtlas;
|
|
95
|
+
readonly center: Vector3;
|
|
96
|
+
readonly radius: number;
|
|
97
|
+
readonly bytes: number;
|
|
98
|
+
users: number;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/** The terminal LOD one asset appended once its bake landed; owned and released with the asset. */
|
|
102
|
+
export interface IImpostorState {
|
|
103
|
+
readonly part: IAssetPart;
|
|
104
|
+
readonly surface: WorldImpostorSurface;
|
|
105
|
+
readonly record: IImpostorRecord;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* One `(cell, run)`'s slice of a whole-map far aggregate.
|
|
110
|
+
*
|
|
111
|
+
* The records are the run's ORIGINAL placement roots, composed once when the aggregate is built and
|
|
112
|
+
* never rewritten while the camera moves. `live` is false while the near ring owns the run, which is
|
|
113
|
+
* the atomic handoff: a run is drawn by exactly one of the two, never both and never neither.
|
|
114
|
+
*/
|
|
115
|
+
interface IFarSegment {
|
|
116
|
+
readonly cell: IWorldCell;
|
|
117
|
+
readonly run: IWorldRun;
|
|
118
|
+
/** First instance record in the aggregate's buffer, and how many the run holds. */
|
|
119
|
+
readonly start: number;
|
|
120
|
+
readonly count: number;
|
|
121
|
+
/** This run's own view-distance gate, `Infinity` when its asset authored no `maxDistance`. */
|
|
122
|
+
readonly cull: number;
|
|
123
|
+
live: boolean;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* One whole-map far aggregate per exact atlas cache key: a single `InstancedMesh` holding every
|
|
128
|
+
* ORIGINAL placement root of every canonical asset that bakes to that key, independent of the near
|
|
129
|
+
* full-geometry ring and of the near source GLBs.
|
|
130
|
+
*
|
|
131
|
+
* The surface is the aggregate's own, built from the record's atlas and the first source material
|
|
132
|
+
* that baked to it, so disposing a near asset's surface cannot invalidate the far mesh. The atlas is
|
|
133
|
+
* borrowed: `record.users` is incremented once for the aggregate and held until the world disposes,
|
|
134
|
+
* which is what stops `#evictImpostors` dropping an atlas the far mesh still draws.
|
|
135
|
+
*/
|
|
136
|
+
interface IFarAggregate {
|
|
137
|
+
readonly key: string;
|
|
138
|
+
readonly surface: WorldImpostorSurface;
|
|
139
|
+
readonly record: IImpostorRecord;
|
|
140
|
+
mesh: InstancedMesh;
|
|
141
|
+
capacity: number;
|
|
142
|
+
/** Every original placement root the aggregate holds, live and near-owned. */
|
|
143
|
+
readonly segments: Map<IWorldRun, IFarSegment>;
|
|
144
|
+
/** How many times the instance buffer has been written, for the settled-frame check. */
|
|
145
|
+
uploads: number;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* The metadata a refused far cohort is kept as, without its source GLB.
|
|
150
|
+
*
|
|
151
|
+
* A hard budget refusal releases the asset's geometry and materials the way any release does; the
|
|
152
|
+
* atlas is pinned by one borrowed `users` and the aggregate's own surface is built once here, so a
|
|
153
|
+
* later capacity release retries from this alone — no full model is held alive for a cohort that may
|
|
154
|
+
* never fit. See `#deferFar`, `#retryFar`.
|
|
155
|
+
*/
|
|
156
|
+
interface IFarCohort {
|
|
157
|
+
readonly id: string;
|
|
158
|
+
readonly key: string;
|
|
159
|
+
readonly record: IImpostorRecord;
|
|
160
|
+
/** The alpha-foliage source material to twin; absent once a refused cohort has its surface built. */
|
|
161
|
+
readonly source?: Material;
|
|
162
|
+
readonly alphaTest: number;
|
|
163
|
+
readonly cull: number;
|
|
164
|
+
readonly runs: ReadonlyArray<{ cell: IWorldCell; run: IWorldRun }>;
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* A refused far cohort kept without its source GLB: metadata plus the surface already built from the
|
|
169
|
+
* source at refusal. No material, geometry or texture of the model survives here — only the surface,
|
|
170
|
+
* which cleared its UV maps and borrows the pinned atlas.
|
|
171
|
+
*/
|
|
172
|
+
interface IFarRetryEntry {
|
|
173
|
+
readonly id: string;
|
|
174
|
+
readonly key: string;
|
|
175
|
+
readonly record: IImpostorRecord;
|
|
176
|
+
readonly alphaTest: number;
|
|
177
|
+
readonly cull: number;
|
|
178
|
+
readonly runs: ReadonlyArray<{ cell: IWorldCell; run: IWorldRun }>;
|
|
179
|
+
readonly surface: WorldImpostorSurface;
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
/**
|
|
183
|
+
* The raw renderer seam the impostor bake needs, or `undefined` when this backend does not expose it.
|
|
184
|
+
*
|
|
185
|
+
* `IRendererLike.raw` is `unknown` on purpose: it is whatever the running renderer is, and a backend
|
|
186
|
+
* without layered render targets has no bake seam at all. The shape is checked rather than cast, so a
|
|
187
|
+
* stub whose raw is not a renderer leaves the bake un-run instead of throwing inside a frame.
|
|
188
|
+
*
|
|
189
|
+
* A WebGL renderer is the reason the three-method shape alone is not enough: it carries `render`,
|
|
190
|
+
* `setRenderTarget` and `initRenderTarget` and would pass, then fail mid-frame on the layered MRT
|
|
191
|
+
* capture it cannot run. So the backend must declare itself WebGPU (`kind` and the renderer's own
|
|
192
|
+
* `isWebGPURenderer`), which a WebGL fallback and an unsupported native backend do not, and the full
|
|
193
|
+
* getter/setter seam the baker calls must be present before the cast — the ones the baker reaches
|
|
194
|
+
* with `?.` still have to exist on a real backend, and a raw object missing them would be half-run,
|
|
195
|
+
* not skipped cleanly.
|
|
196
|
+
*/
|
|
197
|
+
const REQUIRED_IMPOSTOR_METHODS = [
|
|
198
|
+
"getActiveCubeFace",
|
|
199
|
+
"getActiveMipmapLevel",
|
|
200
|
+
"getClearAlpha",
|
|
201
|
+
"getClearColor",
|
|
202
|
+
"getMRT",
|
|
203
|
+
"getRenderTarget",
|
|
204
|
+
"initRenderTarget",
|
|
205
|
+
"render",
|
|
206
|
+
"setClearAlpha",
|
|
207
|
+
"setClearColor",
|
|
208
|
+
"setMRT",
|
|
209
|
+
"setRenderTarget",
|
|
210
|
+
] as const;
|
|
211
|
+
|
|
212
|
+
function impostorRawRenderer(
|
|
213
|
+
renderer: IRendererLike | undefined,
|
|
214
|
+
): IImpostorRawRenderer | undefined {
|
|
215
|
+
if (renderer === undefined || renderer.kind !== "webgpu") return undefined;
|
|
216
|
+
const raw = renderer.raw as
|
|
217
|
+
| (Partial<IImpostorRawRenderer> & { isWebGPURenderer?: boolean })
|
|
218
|
+
| null;
|
|
219
|
+
if (raw === null || raw === undefined) return undefined;
|
|
220
|
+
if (raw.isWebGPURenderer !== true) return undefined;
|
|
221
|
+
// A `WebGPURenderer` can wrap the WebGL fallback backend and still report `kind: 'webgpu'` and
|
|
222
|
+
// `isWebGPURenderer === true`; that backend cannot run a layered MRT capture, so the method shape
|
|
223
|
+
// alone would accept it and fail mid-frame. The backend it actually wrapped is the honest answer.
|
|
224
|
+
if ((raw as { backend?: { isWebGLBackend?: boolean } }).backend?.isWebGLBackend === true)
|
|
225
|
+
return undefined;
|
|
226
|
+
for (const method of REQUIRED_IMPOSTOR_METHODS)
|
|
227
|
+
if (typeof raw[method] !== "function") return undefined;
|
|
228
|
+
return raw as IImpostorRawRenderer;
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
/** The bake's view of one asset level: each part's geometry, transform and surface, by reference. */
|
|
232
|
+
function impostorParts(parts: readonly IAssetPart[]): IImpostorPart[] {
|
|
233
|
+
const staged: IImpostorPart[] = [];
|
|
234
|
+
for (const part of parts)
|
|
235
|
+
staged.push({ geometry: part.geometry, local: part.local, material: part.material });
|
|
236
|
+
return staged;
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
/**
|
|
240
|
+
* The alpha threshold a cutout gets when the part's own material names none. ponytail: a fixed
|
|
241
|
+
* 0.5, because the cutout point is authored data a GLB carries per texture and nothing reads it
|
|
242
|
+
* here. A tree whose needles visibly dither at 0.5 wants a lower one — give
|
|
243
|
+
* `transparentScatter` a third mode carrying a threshold when that is worth a knob.
|
|
244
|
+
*/
|
|
245
|
+
export const DEFAULT_CUTOUT_ALPHA = 0.5;
|
|
246
|
+
|
|
247
|
+
/** The one test that separates an alpha-cutout foliage part from an opaque one: MASK or BLEND. */
|
|
248
|
+
export function isAlphaFoliage(material: Material): boolean {
|
|
249
|
+
return material.transparent || material.alphaTest > 0;
|
|
250
|
+
}
|
|
251
|
+
export interface ICellImpostorsHost {
|
|
252
|
+
released(): boolean;
|
|
253
|
+
covered(): boolean;
|
|
254
|
+
renderer(): IRendererLike | undefined;
|
|
255
|
+
asset(id: string): IAssetState | undefined;
|
|
256
|
+
hasAsset(id: string): boolean;
|
|
257
|
+
assets(): Iterable<IAssetState>;
|
|
258
|
+
nearWorkPending(): boolean;
|
|
259
|
+
newAsset(id: string, definition: IWorldAsset): IAssetState;
|
|
260
|
+
startAssetLoad(asset: IAssetState): void;
|
|
261
|
+
release(id: string): void;
|
|
262
|
+
noteGate(gate: number): void;
|
|
263
|
+
retargetWideCasters(asset: IAssetState): void;
|
|
264
|
+
terminalPrewarm(asset: IAssetState): void;
|
|
265
|
+
terminalLevelReady(asset: IAssetState): void;
|
|
266
|
+
residentCell(key: string): IResidentCell | undefined;
|
|
267
|
+
canonical(id: string): string;
|
|
268
|
+
shadowRecordsMoved(): void;
|
|
269
|
+
residency(): { readonly instances: number; readonly bytes: number; readonly hlodBytes: number };
|
|
270
|
+
add(object: Object3D): void;
|
|
271
|
+
remove(object: Object3D): void;
|
|
272
|
+
addFailure(): void;
|
|
273
|
+
markReleasedPart(part: IAssetPart): void;
|
|
274
|
+
drawnImpostorInstances(): number;
|
|
275
|
+
}
|
|
276
|
+
export interface ICellImpostorsSettings {
|
|
277
|
+
readonly enabled: boolean;
|
|
278
|
+
readonly preserveAuthoredParts: boolean;
|
|
279
|
+
readonly receiveShadow: boolean;
|
|
280
|
+
readonly candidates: readonly string[];
|
|
281
|
+
readonly cells: readonly IWorldCell[];
|
|
282
|
+
readonly manifest: IWorldPackage;
|
|
283
|
+
readonly placements: ArrayBuffer;
|
|
284
|
+
readonly transparentScatter: "cutout" | "blend";
|
|
285
|
+
readonly autoLodPixelsPerUnit: number;
|
|
286
|
+
readonly castShadowLevels: number;
|
|
287
|
+
readonly budgets: IWorldCellsBudget;
|
|
288
|
+
/** Whether a short-range asset keeps a far aggregate anyway; see `#farReaches`. */
|
|
289
|
+
readonly impostorFar: "ring" | "always";
|
|
290
|
+
/** `ring * cellSize`: the distance inside which a near cell is always resident. */
|
|
291
|
+
readonly nearRingRadius: number;
|
|
292
|
+
}
|
|
293
|
+
export class CellImpostors {
|
|
294
|
+
readonly #host: ICellImpostorsHost;
|
|
295
|
+
|
|
296
|
+
readonly #cells: readonly IWorldCell[];
|
|
297
|
+
|
|
298
|
+
readonly #manifest: IWorldPackage;
|
|
299
|
+
|
|
300
|
+
readonly #placements: ArrayBuffer;
|
|
301
|
+
|
|
302
|
+
readonly #transparentScatter: "cutout" | "blend";
|
|
303
|
+
|
|
304
|
+
/**
|
|
305
|
+
* Pixels per world unit at unit depth, the scale a baked chain's level errors are divided by to
|
|
306
|
+
* reach a switch distance. See `IWorldCellsLoadOptions.autoLod` and {@link chainLevels}.
|
|
307
|
+
*/
|
|
308
|
+
readonly #autoLodPixelsPerUnit: number;
|
|
309
|
+
|
|
310
|
+
/** How many of an asset's finest levels cast shadows; 0 when the game asked for none. */
|
|
311
|
+
readonly #castShadowLevels: number;
|
|
312
|
+
|
|
313
|
+
readonly #budgets: IWorldCellsBudget;
|
|
314
|
+
|
|
315
|
+
/** The named `impostorFar` override, and the radius the near ring guarantees below it. */
|
|
316
|
+
readonly #impostorFar: "ring" | "always";
|
|
317
|
+
readonly #nearRingRadius: number;
|
|
318
|
+
|
|
319
|
+
/** Asset ids the `impostorFar: "always"` override kept, so its report prints once each. */
|
|
320
|
+
readonly #farOverrideReported = new Set<string>();
|
|
321
|
+
|
|
322
|
+
readonly #position = new Vector3();
|
|
323
|
+
|
|
324
|
+
readonly #rotation = new Quaternion();
|
|
325
|
+
|
|
326
|
+
readonly #scale = new Vector3();
|
|
327
|
+
|
|
328
|
+
readonly #matrix = new Matrix4();
|
|
329
|
+
|
|
330
|
+
/** Whether alpha-foliage assets append a baked whole-asset terminal level; see the option. */
|
|
331
|
+
readonly #impostors: boolean;
|
|
332
|
+
readonly #preserveAuthoredParts: boolean;
|
|
333
|
+
readonly #receiveShadow: boolean;
|
|
334
|
+
|
|
335
|
+
/** The baker one view per render-cadence update; see `#stepImpostor`. */
|
|
336
|
+
readonly #baker = new WorldImpostorBaker();
|
|
337
|
+
|
|
338
|
+
/** Assets whose bake is queued, in adoption order; `#impostorQueued` is the same set by id. */
|
|
339
|
+
readonly #impostorQueue: IAssetState[] = [];
|
|
340
|
+
|
|
341
|
+
readonly #impostorQueued = new Set<string>();
|
|
342
|
+
|
|
343
|
+
/** The asset whose bake holds the baker right now, if any. */
|
|
344
|
+
#impostorBaking: IAssetState | undefined;
|
|
345
|
+
|
|
346
|
+
/**
|
|
347
|
+
* Completed atlases by content key. An atlas a live asset draws from is active and never evicted;
|
|
348
|
+
* one with no user is kept for a later reference until the byte budget needs the room.
|
|
349
|
+
*/
|
|
350
|
+
readonly #impostorRecords = new Map<string, IImpostorRecord>();
|
|
351
|
+
|
|
352
|
+
#impostorRecordBytes = 0;
|
|
353
|
+
|
|
354
|
+
/** The declared bytes of the one bake in flight, held against the budget before `begin`. */
|
|
355
|
+
#impostorReservedBytes = 0;
|
|
356
|
+
|
|
357
|
+
readonly #impostorBudgetBytes: number;
|
|
358
|
+
|
|
359
|
+
/** Assets whose `TN_WORLD_IMPOSTOR` line has printed, so the marker is one per asset. */
|
|
360
|
+
readonly #impostorReported = new Set<string>();
|
|
361
|
+
|
|
362
|
+
/**
|
|
363
|
+
* Assets whose pre-bake wide segments are still waiting for a block in the one whole-asset mesh,
|
|
364
|
+
* because the frame that handed the bake over had spent its fresh-mesh allowance. Retried on the
|
|
365
|
+
* next update rather than left with no far shadow.
|
|
366
|
+
*/
|
|
367
|
+
readonly #wideRetry = new Set<string>();
|
|
368
|
+
|
|
369
|
+
/**
|
|
370
|
+
* The whole-map far aggregates, one per exact atlas cache key, and the `run -> aggregate` index a
|
|
371
|
+
* near-ready handoff and an eviction read to toggle a run's far segment without asking the asset.
|
|
372
|
+
*
|
|
373
|
+
* `#farInstances` and `#farBytes` are the physical allocations those meshes hold, charged against
|
|
374
|
+
* the world's own instance and byte budgets beside the near ring's records.
|
|
375
|
+
*/
|
|
376
|
+
readonly #far = new Map<string, IFarAggregate>();
|
|
377
|
+
|
|
378
|
+
readonly #farSegments = new Map<IWorldRun, IFarAggregate>();
|
|
379
|
+
|
|
380
|
+
#farInstances = 0;
|
|
381
|
+
|
|
382
|
+
#farBytes = 0;
|
|
383
|
+
|
|
384
|
+
/** Atlas keys whose `TN_WORLD_IMPOSTOR_FAR` line has printed, so the marker is one per aggregate. */
|
|
385
|
+
readonly #farReported = new Set<string>();
|
|
386
|
+
|
|
387
|
+
/**
|
|
388
|
+
* Cohorts whose far aggregate a full budget refused, as metadata plus a built surface and never
|
|
389
|
+
* the source GLB. Retried when a near cell releases its allocation — an event, not a per-frame
|
|
390
|
+
* scan — so a walk away from the ring makes room and the refused species appears without holding
|
|
391
|
+
* a full model alive; see {@link IFarRetryEntry}, `#retryFar` and `#deferFar`.
|
|
392
|
+
*/
|
|
393
|
+
readonly #farRetry = new Map<string, IFarRetryEntry>();
|
|
394
|
+
|
|
395
|
+
/**
|
|
396
|
+
* Canonical asset ids placed anywhere in the map, adopted on idle frames so a species that never
|
|
397
|
+
* enters the near ring still bakes its atlas and appears on the far mesh. Enumerated once from the
|
|
398
|
+
* static placements; see `#pumpFarAcquisition`.
|
|
399
|
+
*/
|
|
400
|
+
readonly #farCandidateIds: readonly string[];
|
|
401
|
+
|
|
402
|
+
/** The rotating cursor over `#farCandidateIds`, so the map is walked a bounded step per idle frame. */
|
|
403
|
+
#farCursor = 0;
|
|
404
|
+
|
|
405
|
+
/** Canonical ids whose far handling has settled: baked and built, or classified with no atlas. */
|
|
406
|
+
readonly #farSeen = new Set<string>();
|
|
407
|
+
|
|
408
|
+
/** Canonical ids acquired for the far half alone, held until their aggregate lands or is refused. */
|
|
409
|
+
readonly #farTemp = new Set<string>();
|
|
410
|
+
|
|
411
|
+
/** Every candidate is settled, so the idle pump can stop scanning the map; see `#pumpFarAcquisition`. */
|
|
412
|
+
#farExhausted = false;
|
|
413
|
+
constructor(settings: ICellImpostorsSettings, host: ICellImpostorsHost) {
|
|
414
|
+
this.#host = host;
|
|
415
|
+
this.#impostors = settings.enabled;
|
|
416
|
+
this.#preserveAuthoredParts = settings.preserveAuthoredParts;
|
|
417
|
+
this.#receiveShadow = settings.receiveShadow;
|
|
418
|
+
this.#farCandidateIds = settings.candidates;
|
|
419
|
+
this.#impostorBudgetBytes = DEFAULT_IMPOSTOR_ATLAS_BUDGET_BYTES;
|
|
420
|
+
this.#cells = settings.cells;
|
|
421
|
+
this.#manifest = settings.manifest;
|
|
422
|
+
this.#placements = settings.placements;
|
|
423
|
+
this.#transparentScatter = settings.transparentScatter;
|
|
424
|
+
this.#autoLodPixelsPerUnit = settings.autoLodPixelsPerUnit;
|
|
425
|
+
this.#castShadowLevels = settings.castShadowLevels;
|
|
426
|
+
this.#budgets = settings.budgets;
|
|
427
|
+
this.#impostorFar = settings.impostorFar;
|
|
428
|
+
this.#nearRingRadius = settings.nearRingRadius;
|
|
429
|
+
}
|
|
430
|
+
get farBytes(): number {
|
|
431
|
+
return this.#farBytes;
|
|
432
|
+
}
|
|
433
|
+
get farInstances(): number {
|
|
434
|
+
return this.#farInstances;
|
|
435
|
+
}
|
|
436
|
+
hasFarTemp(id: string): boolean {
|
|
437
|
+
return this.#farTemp.has(id);
|
|
438
|
+
}
|
|
439
|
+
hasQueued(id: string): boolean {
|
|
440
|
+
return this.#impostorQueued.has(id);
|
|
441
|
+
}
|
|
442
|
+
deferWide(id: string): void {
|
|
443
|
+
this.#wideRetry.add(id);
|
|
444
|
+
}
|
|
445
|
+
|
|
446
|
+
/**
|
|
447
|
+
* Whether this asset needs extra placement-root records for the generated wide impostor. Preserved
|
|
448
|
+
* authored parts keep their own wide casters, so they use each part's regular instance records.
|
|
449
|
+
*/
|
|
450
|
+
rootsNeeded(asset: IAssetState): boolean {
|
|
451
|
+
if (this.#impostors === false || this.#preserveAuthoredParts) return false;
|
|
452
|
+
const parts = asset.levels[0];
|
|
453
|
+
return parts !== undefined && this.#impostorSource(parts) !== undefined;
|
|
454
|
+
}
|
|
455
|
+
|
|
456
|
+
/**
|
|
457
|
+
* The first LOD0 part that is alpha foliage, and the cutoff its own material authored — or
|
|
458
|
+
* `undefined` when no part is. A BLEND part carries `alphaTest 0`, and the scatter path draws it
|
|
459
|
+
* through the same cutout a MASK part gets, so the contract records that default rather than a
|
|
460
|
+
* zero that would bake a solid impostor.
|
|
461
|
+
*/
|
|
462
|
+
#impostorSource(
|
|
463
|
+
parts: readonly IAssetPart[],
|
|
464
|
+
): { readonly source: Material; readonly alphaTest: number } | undefined {
|
|
465
|
+
for (const part of parts) {
|
|
466
|
+
const material = part.material;
|
|
467
|
+
if (!isAlphaFoliage(material)) continue;
|
|
468
|
+
return {
|
|
469
|
+
source: material,
|
|
470
|
+
alphaTest: material.alphaTest > 0 ? material.alphaTest : DEFAULT_CUTOUT_ALPHA,
|
|
471
|
+
};
|
|
472
|
+
}
|
|
473
|
+
return undefined;
|
|
474
|
+
}
|
|
475
|
+
|
|
476
|
+
/**
|
|
477
|
+
* The content key one impostor atlas is cached under: the loader's resolved cooked url of LOD0,
|
|
478
|
+
* plus every LOD0 source part's surface/content key and its exact cutout contract. Two package
|
|
479
|
+
* entries that fetch the same cooked model and draw the same parts with the same cutoffs are one
|
|
480
|
+
* bake, which is the canonical-asset idea applied to the atlas rather than to the levels — the
|
|
481
|
+
* package's own `lods`/`maxDistance` metadata may have stopped the two entries aliasing, but the
|
|
482
|
+
* atlas is built from LOD0 alone, so it must be shared anyway.
|
|
483
|
+
*
|
|
484
|
+
* The cutoff is the exact number the bake uses, never a rounded one: `0.42` and `0.420001` are
|
|
485
|
+
* different silhouettes and must not collide in the cache.
|
|
486
|
+
*/
|
|
487
|
+
#impostorKey(asset: IAssetState): string {
|
|
488
|
+
const parts = asset.levels[0] ?? [];
|
|
489
|
+
const contract: string[] = [];
|
|
490
|
+
for (const part of parts) {
|
|
491
|
+
const cutoff = isAlphaFoliage(part.material)
|
|
492
|
+
? part.material.alphaTest > 0
|
|
493
|
+
? part.material.alphaTest
|
|
494
|
+
: DEFAULT_CUTOUT_ALPHA
|
|
495
|
+
: 0;
|
|
496
|
+
contract.push(`${part.surface}@${String(cutoff)}`);
|
|
497
|
+
}
|
|
498
|
+
return `${asset.resolvedGlb}|${this.#transparentScatter}|${contract.join(",")}`;
|
|
499
|
+
}
|
|
500
|
+
|
|
501
|
+
/** Mark a cached atlas touched, so the least recently used inactive record is the one evicted. */
|
|
502
|
+
#touchImpostor(key: string, record: IImpostorRecord): void {
|
|
503
|
+
this.#impostorRecords.delete(key);
|
|
504
|
+
this.#impostorRecords.set(key, record);
|
|
505
|
+
}
|
|
506
|
+
|
|
507
|
+
/**
|
|
508
|
+
* Queue one adopted asset's whole-asset impostor, or append it at once from a cached atlas.
|
|
509
|
+
*
|
|
510
|
+
* Called after `#widenWithChain` and before the prewarm, so the terminal level is known to the same
|
|
511
|
+
* prewarm and rebuild machinery every adoption uses. An asset with no alpha-cutout LOD0 part is
|
|
512
|
+
* never baked: a solid impostor is not the thing it replaces.
|
|
513
|
+
*/
|
|
514
|
+
maybeQueueImpostor(asset: IAssetState): void {
|
|
515
|
+
if (
|
|
516
|
+
this.#impostors === false ||
|
|
517
|
+
asset.impostor !== undefined ||
|
|
518
|
+
(this.#preserveAuthoredParts && asset.definition.impostorDistance === undefined)
|
|
519
|
+
)
|
|
520
|
+
return;
|
|
521
|
+
const parts = asset.levels[0];
|
|
522
|
+
if (parts === undefined) return;
|
|
523
|
+
const source = this.#impostorSource(parts);
|
|
524
|
+
if (source === undefined) return;
|
|
525
|
+
const key = this.#impostorKey(asset);
|
|
526
|
+
const cached = this.#impostorRecords.get(key);
|
|
527
|
+
if (cached !== undefined) {
|
|
528
|
+
this.#touchImpostor(key, cached);
|
|
529
|
+
this.#finishImpostor(asset, cached);
|
|
530
|
+
return;
|
|
531
|
+
}
|
|
532
|
+
if (this.#impostorQueued.has(asset.id)) return;
|
|
533
|
+
this.#impostorQueued.add(asset.id);
|
|
534
|
+
this.#impostorQueue.push(asset);
|
|
535
|
+
}
|
|
536
|
+
|
|
537
|
+
/**
|
|
538
|
+
* One view of the bake per render-cadence update, then the terminal level when it completes.
|
|
539
|
+
*
|
|
540
|
+
* The renderer is asked for its raw seam and the bake waits for one that can run it: a world that
|
|
541
|
+
* has no renderer yet — or a backend whose raw seam is not the layered-target API — simply does
|
|
542
|
+
* not advance, and nothing downstream of the bake is owed until it does. No landmark is already
|
|
543
|
+
* waited on, so a bake that never runs never deadlocks a loading screen.
|
|
544
|
+
*/
|
|
545
|
+
stepImpostor(renderer: IRendererLike | undefined): void {
|
|
546
|
+
if (this.#impostors === false || this.#host.released()) return;
|
|
547
|
+
// A renderer that exists but carries no layered bake seam is a real answer, not a delay. Waiting
|
|
548
|
+
// on it would leave every queued asset pending and its atlas bytes reserved for the world's whole
|
|
549
|
+
// life, so the bake is cancelled, the reservation and queue dropped, and each asset reported:
|
|
550
|
+
// the source LODs stay, which is the documented fallback. A world with no renderer yet keeps
|
|
551
|
+
// waiting — that is the loading-screen case the wait exists for.
|
|
552
|
+
const current = renderer ?? this.#host.renderer();
|
|
553
|
+
if (current !== undefined && impostorRawRenderer(current) === undefined) {
|
|
554
|
+
this.#dropUnsupportedImpostors();
|
|
555
|
+
return;
|
|
556
|
+
}
|
|
557
|
+
const covered = this.#host.covered();
|
|
558
|
+
let jobs = covered
|
|
559
|
+
? this.#impostorQueue.length + (this.#impostorBaking === undefined ? 0 : 1)
|
|
560
|
+
: 1;
|
|
561
|
+
while (jobs > 0) {
|
|
562
|
+
jobs -= 1;
|
|
563
|
+
if (this.#impostorBaking === undefined) {
|
|
564
|
+
while (this.#impostorQueue.length > 0) {
|
|
565
|
+
const asset = this.#impostorQueue.shift() as IAssetState;
|
|
566
|
+
this.#impostorQueued.delete(asset.id);
|
|
567
|
+
if (
|
|
568
|
+
this.#host.asset(asset.id) !== asset ||
|
|
569
|
+
asset.disposed ||
|
|
570
|
+
asset.impostor !== undefined
|
|
571
|
+
)
|
|
572
|
+
continue;
|
|
573
|
+
const parts = asset.levels[0];
|
|
574
|
+
if (parts === undefined || this.#impostorSource(parts) === undefined) continue;
|
|
575
|
+
// Re-check the completed cache when DEQUEUED, not only when queued: two entries whose bake
|
|
576
|
+
// was queued before either finished share one atlas instead of baking it twice.
|
|
577
|
+
const key = this.#impostorKey(asset);
|
|
578
|
+
const cached = this.#impostorRecords.get(key);
|
|
579
|
+
if (cached !== undefined) {
|
|
580
|
+
this.#touchImpostor(key, cached);
|
|
581
|
+
this.#finishImpostor(asset, cached);
|
|
582
|
+
continue;
|
|
583
|
+
}
|
|
584
|
+
// Enforce the declared colour+mip budget BEFORE the atlas is allocated, and never at the
|
|
585
|
+
// cost of an atlas a live asset draws from: inactive LRU records make room first.
|
|
586
|
+
if (
|
|
587
|
+
this.#impostorRecordBytes + this.#impostorReservedBytes + IMPOSTOR_ATLAS_BYTES >
|
|
588
|
+
this.#impostorBudgetBytes
|
|
589
|
+
)
|
|
590
|
+
this.#evictImpostors(IMPOSTOR_ATLAS_BYTES);
|
|
591
|
+
if (this.#impostorRecordBytes + IMPOSTOR_ATLAS_BYTES > this.#impostorBudgetBytes) {
|
|
592
|
+
// Out of room: keep the source LODs and say why, rather than overrun the budget with one
|
|
593
|
+
// more atlas or evict one still in use.
|
|
594
|
+
this.#reportImpostor(asset, "budget");
|
|
595
|
+
// A far-only species fetched for the far half alone has no near run to fall back on, and
|
|
596
|
+
// nothing here retries an atlas-budget refusal, so keeping its source GLB alive buys
|
|
597
|
+
// nothing. Release it; the near path re-acquires it normally if the follow point reaches it.
|
|
598
|
+
if (this.#farTemp.has(asset.id)) this.releaseFarTemp(asset.id);
|
|
599
|
+
continue;
|
|
600
|
+
}
|
|
601
|
+
const staged: IImpostorPart[] = impostorParts(parts);
|
|
602
|
+
try {
|
|
603
|
+
this.#baker.begin(asset.id, staged, { pixels: IMPOSTOR_FRAME_PIXELS });
|
|
604
|
+
} catch {
|
|
605
|
+
this.#host.addFailure();
|
|
606
|
+
this.#reportImpostor(asset, "begin-failed");
|
|
607
|
+
continue;
|
|
608
|
+
}
|
|
609
|
+
this.#impostorReservedBytes = IMPOSTOR_ATLAS_BYTES;
|
|
610
|
+
this.#impostorBaking = asset;
|
|
611
|
+
break;
|
|
612
|
+
}
|
|
613
|
+
}
|
|
614
|
+
const baking = this.#impostorBaking;
|
|
615
|
+
if (baking === undefined) return;
|
|
616
|
+
const raw = impostorRawRenderer(renderer);
|
|
617
|
+
if (raw === undefined) return;
|
|
618
|
+
let atlas: WorldImpostorAtlas | undefined;
|
|
619
|
+
try {
|
|
620
|
+
const views = covered ? IMPOSTOR_VIEWS - (this.#baker.pending?.view ?? 0) : 1;
|
|
621
|
+
for (let remaining = views; remaining > 0; remaining -= 1) {
|
|
622
|
+
const view = this.#baker.pending?.view;
|
|
623
|
+
atlas = this.#baker.step(raw);
|
|
624
|
+
if (atlas !== undefined || this.#baker.pending?.view === view) break;
|
|
625
|
+
}
|
|
626
|
+
} catch {
|
|
627
|
+
this.#host.addFailure();
|
|
628
|
+
this.#impostorBaking = undefined;
|
|
629
|
+
this.#impostorReservedBytes = 0;
|
|
630
|
+
this.#reportImpostor(baking, "bake-failed");
|
|
631
|
+
return;
|
|
632
|
+
}
|
|
633
|
+
if (atlas === undefined) return;
|
|
634
|
+
this.#impostorBaking = undefined;
|
|
635
|
+
this.#adoptImpostorAtlas(baking, atlas);
|
|
636
|
+
}
|
|
637
|
+
}
|
|
638
|
+
|
|
639
|
+
/**
|
|
640
|
+
* Drop every queued and in-flight bake because the renderer cannot run the layered capture, and
|
|
641
|
+
* report each asset once. The reservation is released with the abort, so a later supported renderer
|
|
642
|
+
* (a device swap, a backend that only comes up after a frame) can still bake: the queue is empty,
|
|
643
|
+
* but a fresh adoption re-queues, and an asset already refused here is left with its source LODs.
|
|
644
|
+
*/
|
|
645
|
+
#dropUnsupportedImpostors(): void {
|
|
646
|
+
if (this.#impostorQueue.length === 0 && this.#impostorBaking === undefined) return;
|
|
647
|
+
const dropped: IAssetState[] = [];
|
|
648
|
+
if (this.#impostorBaking !== undefined) {
|
|
649
|
+
dropped.push(this.#impostorBaking);
|
|
650
|
+
this.#reportImpostor(this.#impostorBaking, "unsupported");
|
|
651
|
+
this.#baker.abort();
|
|
652
|
+
this.#impostorBaking = undefined;
|
|
653
|
+
this.#impostorReservedBytes = 0;
|
|
654
|
+
}
|
|
655
|
+
const queued = this.#impostorQueue.splice(0, this.#impostorQueue.length);
|
|
656
|
+
this.#impostorQueued.clear();
|
|
657
|
+
dropped.push(...queued);
|
|
658
|
+
for (const asset of queued) this.#reportImpostor(asset, "unsupported");
|
|
659
|
+
// A far-only species cannot bake on a backend that has none, so it must not keep holding the
|
|
660
|
+
// source it fetched for a bake that will never land. Its atlas cache key stays for a later backend.
|
|
661
|
+
for (const asset of dropped) if (this.#farTemp.has(asset.id)) this.releaseFarTemp(asset.id);
|
|
662
|
+
}
|
|
663
|
+
|
|
664
|
+
/** Store a finished atlas and hand the asset its terminal level. */ #adoptImpostorAtlas(
|
|
665
|
+
asset: IAssetState,
|
|
666
|
+
atlas: WorldImpostorAtlas,
|
|
667
|
+
): void {
|
|
668
|
+
this.#impostorReservedBytes = 0;
|
|
669
|
+
const parts = asset.levels[0];
|
|
670
|
+
const source = parts === undefined ? undefined : this.#impostorSource(parts);
|
|
671
|
+
if (parts === undefined || source === undefined || asset.impostor !== undefined) {
|
|
672
|
+
atlas.dispose();
|
|
673
|
+
return;
|
|
674
|
+
}
|
|
675
|
+
const key = this.#impostorKey(asset);
|
|
676
|
+
const existing = this.#impostorRecords.get(key);
|
|
677
|
+
if (existing !== undefined) {
|
|
678
|
+
atlas.dispose();
|
|
679
|
+
this.#touchImpostor(key, existing);
|
|
680
|
+
this.#finishImpostor(asset, existing);
|
|
681
|
+
return;
|
|
682
|
+
}
|
|
683
|
+
const staged: IImpostorPart[] = impostorParts(parts);
|
|
684
|
+
const bounds = impostorBounds(staged);
|
|
685
|
+
const record: IImpostorRecord = {
|
|
686
|
+
atlas,
|
|
687
|
+
bytes: atlas.bytes,
|
|
688
|
+
center: bounds.center,
|
|
689
|
+
key,
|
|
690
|
+
radius: bounds.radius,
|
|
691
|
+
users: 0,
|
|
692
|
+
};
|
|
693
|
+
this.#impostorRecords.set(key, record);
|
|
694
|
+
this.#impostorRecordBytes += record.bytes;
|
|
695
|
+
// Acquire the active user BEFORE any eviction, so the fresh record cannot be the eviction
|
|
696
|
+
// victim and `#finishImpostor` never builds a surface that borrows a disposed atlas. Admission
|
|
697
|
+
// already reserved this record's bytes, so the trim below only drops older inactive records.
|
|
698
|
+
this.#finishImpostor(asset, record);
|
|
699
|
+
this.#evictImpostors();
|
|
700
|
+
}
|
|
701
|
+
|
|
702
|
+
/**
|
|
703
|
+
* Append the whole-asset terminal level: one part, identity local, two triangles, and a switch at
|
|
704
|
+
* the projection the 128 px atlas sphere reaches — never a fixed metre, and strictly beyond the
|
|
705
|
+
* last authored or chain gate so `levelAt` cannot pick it before the level that gate named.
|
|
706
|
+
*
|
|
707
|
+
* The surface's own geometry and material are the part's, so the level is a normal level to every
|
|
708
|
+
* consumer downstream: the prewarm mints its keys, the swap rebuilds the resident runs, and the
|
|
709
|
+
* caster halves read it through `#shapeFor` like any other. The atlas is borrowed and released by
|
|
710
|
+
* the record; see `#releaseImpostor`.
|
|
711
|
+
*/
|
|
712
|
+
#finishImpostor(asset: IAssetState, record: IImpostorRecord): void {
|
|
713
|
+
if (asset.impostor !== undefined || asset.disposed) return;
|
|
714
|
+
if (this.#host.asset(asset.id) !== asset) return;
|
|
715
|
+
const parts = asset.levels[0];
|
|
716
|
+
if (parts === undefined) return;
|
|
717
|
+
const source = this.#impostorSource(parts);
|
|
718
|
+
if (source === undefined) return;
|
|
719
|
+
let surface: WorldImpostorSurface;
|
|
720
|
+
try {
|
|
721
|
+
surface = new WorldImpostorSurface({
|
|
722
|
+
alphaTest: source.alphaTest,
|
|
723
|
+
atlas: record.atlas,
|
|
724
|
+
center: record.center,
|
|
725
|
+
radius: record.radius,
|
|
726
|
+
source: source.source,
|
|
727
|
+
});
|
|
728
|
+
} catch {
|
|
729
|
+
this.#host.addFailure();
|
|
730
|
+
this.#reportImpostor(asset, "surface-failed");
|
|
731
|
+
return;
|
|
732
|
+
}
|
|
733
|
+
// The terminal gate is stored as the BASE-sphere projected distance — the distance at which the
|
|
734
|
+
// asset's own LOD0 sphere, at scale 1, covers the 128 px atlas — and the placement's own scale is
|
|
735
|
+
// applied per placement at selection (`levelAtGates`). A placement scaled 8-12x therefore reaches
|
|
736
|
+
// the atlas 8-12x as far instead of switching at the unit-scale distance. There is no fixed
|
|
737
|
+
// margin: `levelAtGates` floors the terminal one representable Float32 step past the last source
|
|
738
|
+
// gate, so the source level keeps a window while the ordering survives the f32 store.
|
|
739
|
+
const switchAt =
|
|
740
|
+
asset.definition.impostorDistance ??
|
|
741
|
+
(2 * record.radius * this.#autoLodPixelsPerUnit) / IMPOSTOR_FRAME_PIXELS;
|
|
742
|
+
if (!Number.isFinite(switchAt) || switchAt <= 0) {
|
|
743
|
+
surface.dispose();
|
|
744
|
+
return;
|
|
745
|
+
}
|
|
746
|
+
const part: IAssetPart = {
|
|
747
|
+
geometry: surface.geometry,
|
|
748
|
+
local: new Matrix4(),
|
|
749
|
+
material: surface.material,
|
|
750
|
+
surface: "",
|
|
751
|
+
};
|
|
752
|
+
asset.levels = [...asset.levels, [part]];
|
|
753
|
+
asset.distances = [...asset.distances, switchAt];
|
|
754
|
+
asset.gates = [...asset.gates, switchAt];
|
|
755
|
+
this.#host.noteGate(switchAt);
|
|
756
|
+
asset.threshold = asset.gates.length === 0 ? undefined : Math.min(...asset.gates);
|
|
757
|
+
asset.impostor = { part, record, surface };
|
|
758
|
+
record.users += 1;
|
|
759
|
+
// The terminal key is part of the same load-time prewarm as the authored levels. Do this before
|
|
760
|
+
// building the far aggregate and before a far-only source is released: either path can bypass
|
|
761
|
+
// `terminalLevelReady`, which owns only resident/GPU publication after this semantic prewarm.
|
|
762
|
+
this.#host.terminalPrewarm(asset);
|
|
763
|
+
// The whole-map far aggregate for this atlas key, before the rebuild loop below: its segments
|
|
764
|
+
// exist when the swaps land, and any run already near-ready is handed over immediately. A budget
|
|
765
|
+
// refusal keeps only the far cohort's metadata and surface in `#farRetry`; see `#buildFar`.
|
|
766
|
+
if (!this.#preserveAuthoredParts || asset.definition.impostorDistance !== undefined)
|
|
767
|
+
this.#buildFar(asset, record);
|
|
768
|
+
this.#reportImpostor(asset, "ready");
|
|
769
|
+
// A far-only asset has no near batches or casters to hand over; once its aggregate is up its
|
|
770
|
+
// temporary source has done its job and goes, while the atlas the aggregate borrows stays. A
|
|
771
|
+
// refusal releases the source too — the deferred cohort in `#farRetry` holds only metadata and a
|
|
772
|
+
// surface, never the GLB — so a far species that cannot fit is not kept alive wholesale.
|
|
773
|
+
if (this.#farTemp.has(asset.id)) {
|
|
774
|
+
this.releaseFarTemp(asset.id);
|
|
775
|
+
return;
|
|
776
|
+
}
|
|
777
|
+
// The far casters of the levels that were already built: part 0's key is re-pointed at the one
|
|
778
|
+
// whole-asset shape, and the per-part keys the terminal level has no counterpart for are dropped,
|
|
779
|
+
// so the far shadow draws one quad per placement rather than a duplicate per bark/needle part.
|
|
780
|
+
if (!this.#preserveAuthoredParts) this.#host.retargetWideCasters(asset);
|
|
781
|
+
// The terminal level's keys and every resident run of this asset, through the same prewarm and
|
|
782
|
+
// swap the first build took: no active job array is mutated halfway.
|
|
783
|
+
this.#host.terminalLevelReady(asset);
|
|
784
|
+
}
|
|
785
|
+
|
|
786
|
+
/**
|
|
787
|
+
* The whole-map far aggregate for one exact atlas cache key: every ORIGINAL placement root of every
|
|
788
|
+
* canonical asset that bakes to that key, in one `InstancedMesh`, independent of the near ring and
|
|
789
|
+
* of the near source GLBs.
|
|
790
|
+
*
|
|
791
|
+
* One aggregate per EXACT atlas key, never one per `maxDistance`: a shared atlas can back assets
|
|
792
|
+
* with different authored cutoffs, and each placement's own value rides the instance buffer (see
|
|
793
|
+
* {@link IFarSegment.cull}) rather than splitting the key into a second aggregate — the exact key
|
|
794
|
+
* is what the atlas cache already bounds, and a split would build a second surface for one atlas.
|
|
795
|
+
* The first asset to bake a key builds the aggregate's own surface and instance buffer; a later
|
|
796
|
+
* canonical asset that shares the key appends its own runs to the same mesh, growing the buffer at
|
|
797
|
+
* most once per asset. A key already carrying every one of this asset's runs is left untouched, so
|
|
798
|
+
* re-adopting an asset from the cached atlas after its near source was released rebuilds nothing.
|
|
799
|
+
* Never `part.local`: the atlas bakes each part's own transform, so the far quad is the placement
|
|
800
|
+
* root alone.
|
|
801
|
+
*/
|
|
802
|
+
#buildFar(asset: IAssetState, record: IImpostorRecord): boolean {
|
|
803
|
+
const parts = asset.levels[0];
|
|
804
|
+
const source = parts === undefined ? undefined : this.#impostorSource(parts);
|
|
805
|
+
if (parts === undefined || source === undefined) return false;
|
|
806
|
+
// Every run this asset owns anywhere in the map: the far half covers the whole map, not the ring.
|
|
807
|
+
const runs = this.#farRuns(asset.id);
|
|
808
|
+
if (runs.length === 0) return true;
|
|
809
|
+
const cull = cullDistance(asset.definition.maxDistance) ?? Number.POSITIVE_INFINITY;
|
|
810
|
+
if (!this.#farReaches(cull, asset.id)) {
|
|
811
|
+
this.#dropFarRetry(asset.id);
|
|
812
|
+
return true;
|
|
813
|
+
}
|
|
814
|
+
return this.#buildFarCohort({
|
|
815
|
+
alphaTest: source.alphaTest,
|
|
816
|
+
cull,
|
|
817
|
+
id: asset.id,
|
|
818
|
+
key: record.key,
|
|
819
|
+
record,
|
|
820
|
+
runs,
|
|
821
|
+
source: source.source,
|
|
822
|
+
});
|
|
823
|
+
}
|
|
824
|
+
|
|
825
|
+
/**
|
|
826
|
+
* Whether an asset needs a whole-map far aggregate at all, which only one whose authored draw
|
|
827
|
+
* distance reaches past the near ring's guaranteed radius does.
|
|
828
|
+
*
|
|
829
|
+
* The ring keeps every cell within `ring * cellSize` of the follow point resident, so a run the
|
|
830
|
+
* far half owns is that far from the camera at the closest — and the far surface's own
|
|
831
|
+
* per-instance cull (`cullDistance(maxDistance)`) drops it there. An aggregate for a shorter
|
|
832
|
+
* asset could never draw a pixel while still costing its instance buffer, its atlas and a draw.
|
|
833
|
+
* UE ends grass at `EndCullDistance` with no far representation for the same reason
|
|
834
|
+
* (UE 5.8.3: Engine/Source/Runtime/Landscape/Classes/LandscapeGrassType.h:43-45).
|
|
835
|
+
*
|
|
836
|
+
* `impostorFar: "always"` is the named override; it reports every asset it keeps.
|
|
837
|
+
*/
|
|
838
|
+
#farReaches(cull: number, id: string): boolean {
|
|
839
|
+
if (cull >= this.#nearRingRadius) return true;
|
|
840
|
+
if (this.#impostorFar !== "always") return false;
|
|
841
|
+
if (this.#farOverrideReported.has(id)) return true;
|
|
842
|
+
this.#farOverrideReported.add(id);
|
|
843
|
+
console.info(
|
|
844
|
+
`${WORLD_IMPOSTOR_FAR_MARKER} asset=${id} reason=override override=impostorFar ` +
|
|
845
|
+
`cull=${cull.toFixed(2)} nearRingRadius=${String(this.#nearRingRadius)}`,
|
|
846
|
+
);
|
|
847
|
+
return true;
|
|
848
|
+
}
|
|
849
|
+
|
|
850
|
+
/** Every run of one canonical asset anywhere in the map, the whole set a far aggregate holds. */
|
|
851
|
+
#farRuns(id: string): Array<{ cell: IWorldCell; run: IWorldRun }> {
|
|
852
|
+
const runs: Array<{ cell: IWorldCell; run: IWorldRun }> = [];
|
|
853
|
+
for (const held of this.#cells)
|
|
854
|
+
for (const run of held.runs) {
|
|
855
|
+
if (this.#host.canonical(run.asset) !== id || run.count <= 0) continue;
|
|
856
|
+
runs.push({ cell: held, run });
|
|
857
|
+
}
|
|
858
|
+
return runs;
|
|
859
|
+
}
|
|
860
|
+
|
|
861
|
+
/**
|
|
862
|
+
* Build or grow one far cohort's aggregate, or defer it against the hard budget.
|
|
863
|
+
*
|
|
864
|
+
* The budget check counts the growth transient, not the net new count: a grow allocates the new
|
|
865
|
+
* larger buffer while the old one is still alive, so the peak is the new buffer's size — the old
|
|
866
|
+
* buffer is already charged in `#farBytes`. See {@link #farBudgetRefuses}. A refusal is remembered
|
|
867
|
+
* as metadata plus a built surface, never the source GLB; see {@link #deferFar}.
|
|
868
|
+
*/
|
|
869
|
+
#buildFarCohort(cohort: IFarCohort): boolean {
|
|
870
|
+
const key = cohort.key;
|
|
871
|
+
const aggregate = this.#far.get(key);
|
|
872
|
+
const missing =
|
|
873
|
+
aggregate === undefined
|
|
874
|
+
? cohort.runs
|
|
875
|
+
: cohort.runs.filter((entry) => !(aggregate as IFarAggregate).segments.has(entry.run));
|
|
876
|
+
if (missing.length === 0) {
|
|
877
|
+
this.#dropFarRetry(cohort.id);
|
|
878
|
+
return true;
|
|
879
|
+
}
|
|
880
|
+
const extra = missing.reduce((total, entry) => total + entry.run.count, 0);
|
|
881
|
+
const peak = aggregate === undefined ? extra : (aggregate as IFarAggregate).capacity + extra;
|
|
882
|
+
if (this.#farBudgetRefuses(peak)) {
|
|
883
|
+
// Hard finite budget: say why rather than overrun it, and keep only the metadata the retry
|
|
884
|
+
// needs. Never the full source GLB; see `#deferFar`.
|
|
885
|
+
this.#reportFarBudget(key, cohort.id, extra);
|
|
886
|
+
this.#deferFar(cohort);
|
|
887
|
+
return false;
|
|
888
|
+
}
|
|
889
|
+
let built = aggregate as IFarAggregate | undefined;
|
|
890
|
+
const deferred = this.#farRetry.get(cohort.id);
|
|
891
|
+
// The surface actually drawn by the aggregate after this call. A new aggregate adopts the
|
|
892
|
+
// deferred surface; a grow reuses the aggregate's own and leaves the deferred one unused.
|
|
893
|
+
let usedSurface: WorldImpostorSurface | undefined;
|
|
894
|
+
if (built === undefined) {
|
|
895
|
+
usedSurface = deferred?.surface ?? this.#makeFarSurface(cohort);
|
|
896
|
+
if (usedSurface === undefined) return false;
|
|
897
|
+
built = {
|
|
898
|
+
capacity: extra,
|
|
899
|
+
key,
|
|
900
|
+
mesh: this.#newFarMesh(usedSurface, extra, cohort.id),
|
|
901
|
+
record: cohort.record,
|
|
902
|
+
segments: new Map<IWorldRun, IFarSegment>(),
|
|
903
|
+
surface: usedSurface,
|
|
904
|
+
uploads: 0,
|
|
905
|
+
};
|
|
906
|
+
cohort.record.users += 1;
|
|
907
|
+
this.#far.set(key, built);
|
|
908
|
+
this.#farInstances += extra;
|
|
909
|
+
this.#farBytes += extra * FAR_INSTANCE_BYTES;
|
|
910
|
+
} else {
|
|
911
|
+
this.#growFar(built, extra);
|
|
912
|
+
}
|
|
913
|
+
this.#dropFarRetry(cohort.id, usedSurface);
|
|
914
|
+
let at = this.#farAllocated(built);
|
|
915
|
+
for (const { cell: held, run } of missing) {
|
|
916
|
+
const segment: IFarSegment = {
|
|
917
|
+
cell: held,
|
|
918
|
+
count: run.count,
|
|
919
|
+
cull: cohort.cull,
|
|
920
|
+
live: true,
|
|
921
|
+
run,
|
|
922
|
+
start: at,
|
|
923
|
+
};
|
|
924
|
+
at += run.count;
|
|
925
|
+
built.segments.set(run, segment);
|
|
926
|
+
this.#farSegments.set(run, built);
|
|
927
|
+
this.#writeFarSegment(built, segment);
|
|
928
|
+
}
|
|
929
|
+
this.#syncFarSegments(built);
|
|
930
|
+
// The far half just gained records, so the shadow levels drawing the ground they stand on are
|
|
931
|
+
// stale; the same blanket tell a near swap makes. See `#shadowRecordsMoved`.
|
|
932
|
+
this.#host.shadowRecordsMoved();
|
|
933
|
+
if (!this.#farReported.has(key)) {
|
|
934
|
+
this.#farReported.add(key);
|
|
935
|
+
const split = this.#farSplit(built);
|
|
936
|
+
console.info(
|
|
937
|
+
`${WORLD_IMPOSTOR_FAR_MARKER} key=${key} asset=${cohort.id} ` +
|
|
938
|
+
`instances=${String(built.capacity)} live=${String(split.live)} ` +
|
|
939
|
+
`nearOwned=${String(split.nearOwned)} bytes=${String(built.capacity * FAR_INSTANCE_BYTES)} ` +
|
|
940
|
+
`uploads=${String(built.uploads)}`,
|
|
941
|
+
);
|
|
942
|
+
}
|
|
943
|
+
return true;
|
|
944
|
+
}
|
|
945
|
+
|
|
946
|
+
/** The aggregate's own far surface: the record's atlas, the cohort's material twin, per-instance cull. */
|
|
947
|
+
#makeFarSurface(cohort: IFarCohort): WorldImpostorSurface | undefined {
|
|
948
|
+
if (cohort.source === undefined) return undefined;
|
|
949
|
+
try {
|
|
950
|
+
return new WorldImpostorSurface({
|
|
951
|
+
alphaTest: cohort.alphaTest,
|
|
952
|
+
atlas: cohort.record.atlas,
|
|
953
|
+
center: cohort.record.center,
|
|
954
|
+
cull: true,
|
|
955
|
+
radius: cohort.record.radius,
|
|
956
|
+
source: cohort.source,
|
|
957
|
+
});
|
|
958
|
+
} catch {
|
|
959
|
+
this.#host.addFailure();
|
|
960
|
+
return undefined;
|
|
961
|
+
}
|
|
962
|
+
}
|
|
963
|
+
|
|
964
|
+
/**
|
|
965
|
+
* Keep a refused far cohort as metadata alone: the atlas pinned by one borrowed user, the runs, and
|
|
966
|
+
* a built surface. The asset's own geometry and materials are released by the caller, so a refused
|
|
967
|
+
* far species never holds a full GLB alive; `#retryFar` rebuilds from this when a near release frees
|
|
968
|
+
* room. Idempotent: a repeat refusal keeps the surface already built.
|
|
969
|
+
*/
|
|
970
|
+
#deferFar(cohort: IFarCohort): void {
|
|
971
|
+
if (this.#farRetry.has(cohort.id)) return;
|
|
972
|
+
const surface = this.#makeFarSurface(cohort);
|
|
973
|
+
if (surface === undefined) return;
|
|
974
|
+
cohort.record.users += 1;
|
|
975
|
+
this.#farRetry.set(cohort.id, {
|
|
976
|
+
alphaTest: cohort.alphaTest,
|
|
977
|
+
cull: cohort.cull,
|
|
978
|
+
id: cohort.id,
|
|
979
|
+
key: cohort.key,
|
|
980
|
+
record: cohort.record,
|
|
981
|
+
runs: cohort.runs,
|
|
982
|
+
surface,
|
|
983
|
+
});
|
|
984
|
+
}
|
|
985
|
+
|
|
986
|
+
/** Drop a deferred cohort, releasing its surface and the atlas user it pinned. */
|
|
987
|
+
#dropFarRetry(id: string, consumedSurface?: WorldImpostorSurface): void {
|
|
988
|
+
const entry = this.#farRetry.get(id);
|
|
989
|
+
if (entry === undefined) return;
|
|
990
|
+
this.#farRetry.delete(id);
|
|
991
|
+
if (consumedSurface !== entry.surface) entry.surface.dispose();
|
|
992
|
+
entry.record.users = Math.max(0, entry.record.users - 1);
|
|
993
|
+
this.#evictImpostors();
|
|
994
|
+
}
|
|
995
|
+
|
|
996
|
+
/** Retry the far aggregates a full budget refused, when a near cell freed its allocation. */
|
|
997
|
+
retryFar(): void {
|
|
998
|
+
if (this.#farRetry.size === 0) return;
|
|
999
|
+
for (const entry of [...this.#farRetry.values()]) this.#buildFarCohort(entry);
|
|
1000
|
+
}
|
|
1001
|
+
|
|
1002
|
+
/**
|
|
1003
|
+
* Adopt one far-only species per idle frame: a canonical asset the map places but no resident run
|
|
1004
|
+
* has asked for yet. Its LOD0 is loaded through the same limiter, classified by its actual
|
|
1005
|
+
* materials, baked on the same queue, and its source released once the aggregate lands. Gated on an
|
|
1006
|
+
* empty near queue so loading the unseen never delays the near ring or holds its overlay open.
|
|
1007
|
+
*/
|
|
1008
|
+
pumpFarAcquisition(): void {
|
|
1009
|
+
if (this.#impostors === false || this.#host.released() || this.#farExhausted) return;
|
|
1010
|
+
if (this.#farCandidateIds.length === 0) return;
|
|
1011
|
+
// Near work first: a queued build, an in-flight near load, a bake in flight or waiting. Only a
|
|
1012
|
+
// settled frame spends itself on the unseen far half.
|
|
1013
|
+
if (
|
|
1014
|
+
this.#host.nearWorkPending() ||
|
|
1015
|
+
this.#impostorQueue.length > 0 ||
|
|
1016
|
+
this.#impostorBaking !== undefined
|
|
1017
|
+
)
|
|
1018
|
+
return;
|
|
1019
|
+
// The bake needs a renderer that can run it; acquiring before one exists would hold source GLBs
|
|
1020
|
+
// for a bake with no way to land. A renderer that is present but unsupported is the same answer.
|
|
1021
|
+
const renderer = this.#host.renderer();
|
|
1022
|
+
if (renderer === undefined || impostorRawRenderer(renderer) === undefined) return;
|
|
1023
|
+
const count = this.#farCandidateIds.length;
|
|
1024
|
+
for (let step = 0; step < count; step += 1) {
|
|
1025
|
+
const at = (this.#farCursor + step) % count;
|
|
1026
|
+
const id = this.#farCandidateIds[at] as string;
|
|
1027
|
+
if (this.#farSeen.has(id) || this.#host.hasAsset(id) || this.#farRetry.has(id)) continue;
|
|
1028
|
+
this.#farCursor = (at + 1) % count;
|
|
1029
|
+
const definition = this.#manifest.assets[id];
|
|
1030
|
+
// A species that can only ever draw inside the ring needs no aggregate, so nothing of it is
|
|
1031
|
+
// loaded or baked either: the save is the atlas and the source GLB, not just the draw.
|
|
1032
|
+
if (
|
|
1033
|
+
definition === undefined ||
|
|
1034
|
+
!this.#farReaches(cullDistance(definition.maxDistance) ?? Number.POSITIVE_INFINITY, id)
|
|
1035
|
+
) {
|
|
1036
|
+
this.#farSeen.add(id);
|
|
1037
|
+
continue;
|
|
1038
|
+
}
|
|
1039
|
+
const asset = this.#host.newAsset(id, definition);
|
|
1040
|
+
asset.refcount += 1;
|
|
1041
|
+
this.#farTemp.add(id);
|
|
1042
|
+
this.#host.startAssetLoad(asset);
|
|
1043
|
+
return;
|
|
1044
|
+
}
|
|
1045
|
+
// A full pass with nothing startable means every species is either baked, held for a retry, or
|
|
1046
|
+
// classified as having no atlas. Static placements add none later, so the scan stops here.
|
|
1047
|
+
this.#farExhausted = true;
|
|
1048
|
+
}
|
|
1049
|
+
|
|
1050
|
+
/**
|
|
1051
|
+
* Drop a far-only asset's temporary reference once its atlas is held by an aggregate or has been
|
|
1052
|
+
* deferred. The deferred cohort keeps its own pinned atlas user, so it is not dropped here.
|
|
1053
|
+
*/
|
|
1054
|
+
releaseFarTemp(id: string): void {
|
|
1055
|
+
this.#farTemp.delete(id);
|
|
1056
|
+
this.#farSeen.add(id);
|
|
1057
|
+
this.#host.release(id);
|
|
1058
|
+
}
|
|
1059
|
+
|
|
1060
|
+
/**
|
|
1061
|
+
* Whether an incoming far allocation would overrun the world's instance or byte budget.
|
|
1062
|
+
*
|
|
1063
|
+
* `count` is the peak, not the net: a grow allocates the new larger buffer while the old one is
|
|
1064
|
+
* still alive, so the caller passes the new buffer's full size — the old buffer is already inside
|
|
1065
|
+
* `#farInstances`/`#farBytes`. A net-new count would understate the transient a resize holds.
|
|
1066
|
+
*/
|
|
1067
|
+
#farBudgetRefuses(count: number): boolean {
|
|
1068
|
+
return (
|
|
1069
|
+
this.#host.residency().instances + this.#farInstances + count > this.#budgets.instances ||
|
|
1070
|
+
this.#host.residency().bytes +
|
|
1071
|
+
this.#farBytes +
|
|
1072
|
+
this.#host.residency().hlodBytes +
|
|
1073
|
+
count * FAR_INSTANCE_BYTES >
|
|
1074
|
+
this.#budgets.bytes
|
|
1075
|
+
);
|
|
1076
|
+
}
|
|
1077
|
+
|
|
1078
|
+
/** One bounded line for a far aggregate the world's own budgets refused, once per atlas key. */
|
|
1079
|
+
#reportFarBudget(key: string, assetId: string, count: number): void {
|
|
1080
|
+
if (this.#farReported.has(key)) return;
|
|
1081
|
+
this.#farReported.add(key);
|
|
1082
|
+
console.info(
|
|
1083
|
+
`${WORLD_IMPOSTOR_FAR_MARKER} key=${key} asset=${assetId} ` +
|
|
1084
|
+
`instances=${String(count)} reason=budget`,
|
|
1085
|
+
);
|
|
1086
|
+
}
|
|
1087
|
+
|
|
1088
|
+
/**
|
|
1089
|
+
* One far mesh: the whole-asset quad, every original root, drawn regardless of how far the camera
|
|
1090
|
+
* resolves it. `frustumCulled = false` is what keeps the draw: the projected-size gate exempts it
|
|
1091
|
+
* before it ever reads bounds, so no `alwaysRender` marker is needed when a game configured no
|
|
1092
|
+
* shadows to exempt it under `renderer.minimumProjectedPixels`. The per-placement cull rides the
|
|
1093
|
+
* geometry's instance attribute, one static value per placement; see
|
|
1094
|
+
* {@link IMPOSTOR_FAR_CULL_ATTRIBUTE}.
|
|
1095
|
+
*/
|
|
1096
|
+
#newFarMesh(surface: WorldImpostorSurface, capacity: number, assetId: string): InstancedMesh {
|
|
1097
|
+
const mesh = new InstancedMesh(surface.geometry, surface.material, capacity);
|
|
1098
|
+
mesh.count = capacity;
|
|
1099
|
+
mesh.frustumCulled = false;
|
|
1100
|
+
// Three's default usage uploads by version; grow/write/zero announce every matrix change through
|
|
1101
|
+
// needsUpdate. DynamicDrawUsage would upload the same whole-map buffer on every settled draw.
|
|
1102
|
+
mesh.name = `tn-far:${assetId}`;
|
|
1103
|
+
// Drawn on layer 0, so this is a main-pass draw the frame budget counts under the impostor
|
|
1104
|
+
// aggregate's own source rather than under `other` (`RenderPassBudget`).
|
|
1105
|
+
mesh.userData.tnDrawSource = "proxies";
|
|
1106
|
+
if (surface.cull) this.#attachFarCull(surface.geometry, capacity);
|
|
1107
|
+
// Far trees cast like near ones, into the coarse wide caster layer. The same mesh draws the main
|
|
1108
|
+
// pass (layer 0) and the virtual-shadow levels (wide layer), so one representation covers both
|
|
1109
|
+
// and a run hands its far segment over to the near ring exactly once; see `#disableFar`. The
|
|
1110
|
+
// per-asset maxDistance gate is a main-pass shader gate, so the shadow half still reaches the map.
|
|
1111
|
+
if (this.#castShadowLevels > 0) {
|
|
1112
|
+
mesh.layers.enable(VIRTUAL_SHADOW_WIDE_CASTER_LAYER);
|
|
1113
|
+
mesh.castShadow = true;
|
|
1114
|
+
}
|
|
1115
|
+
mesh.receiveShadow = this.#receiveShadow;
|
|
1116
|
+
this.#host.add(mesh);
|
|
1117
|
+
return mesh;
|
|
1118
|
+
}
|
|
1119
|
+
|
|
1120
|
+
/** Install a fresh per-instance cull buffer on the aggregate's shared geometry, all gates open. */
|
|
1121
|
+
#attachFarCull(geometry: BufferGeometry, capacity: number): void {
|
|
1122
|
+
geometry.setAttribute(
|
|
1123
|
+
IMPOSTOR_FAR_CULL_ATTRIBUTE,
|
|
1124
|
+
new InstancedBufferAttribute(new Float32Array(capacity).fill(Number.POSITIVE_INFINITY), 1),
|
|
1125
|
+
);
|
|
1126
|
+
}
|
|
1127
|
+
|
|
1128
|
+
/** Append `extra` instance slots to an aggregate, one mesh swap, charged to the budgets. */
|
|
1129
|
+
#growFar(aggregate: IFarAggregate, extra: number): void {
|
|
1130
|
+
const old = aggregate.mesh;
|
|
1131
|
+
const capacity = aggregate.capacity + extra;
|
|
1132
|
+
// Capture the cull values before the replacement mesh attaches a fresh buffer to the SHARED
|
|
1133
|
+
// geometry; the old attribute object is replaced in place there.
|
|
1134
|
+
const oldCull = aggregate.surface.cull
|
|
1135
|
+
? (
|
|
1136
|
+
aggregate.surface.geometry.getAttribute(IMPOSTOR_FAR_CULL_ATTRIBUTE)?.array as
|
|
1137
|
+
| Float32Array
|
|
1138
|
+
| undefined
|
|
1139
|
+
)?.slice(0, aggregate.capacity)
|
|
1140
|
+
: undefined;
|
|
1141
|
+
const next = this.#newFarMesh(aggregate.surface, capacity, old.name.replace(/^tn-far:/u, ""));
|
|
1142
|
+
(next.instanceMatrix.array as Float32Array).set(
|
|
1143
|
+
(old.instanceMatrix.array as Float32Array).subarray(0, aggregate.capacity * 16),
|
|
1144
|
+
);
|
|
1145
|
+
next.instanceMatrix.needsUpdate = true;
|
|
1146
|
+
if (oldCull !== undefined) {
|
|
1147
|
+
const attribute = next.geometry.getAttribute(IMPOSTOR_FAR_CULL_ATTRIBUTE) as
|
|
1148
|
+
| InstancedBufferAttribute
|
|
1149
|
+
| undefined;
|
|
1150
|
+
if (attribute !== undefined) (attribute.array as Float32Array).set(oldCull, 0);
|
|
1151
|
+
}
|
|
1152
|
+
this.#host.remove(old);
|
|
1153
|
+
old.dispose();
|
|
1154
|
+
aggregate.mesh = next;
|
|
1155
|
+
aggregate.capacity = capacity;
|
|
1156
|
+
aggregate.uploads += 1;
|
|
1157
|
+
this.#farInstances += extra;
|
|
1158
|
+
this.#farBytes += extra * FAR_INSTANCE_BYTES;
|
|
1159
|
+
}
|
|
1160
|
+
|
|
1161
|
+
/** Slots allocated in an aggregate: the sum of its segment counts, the offset the next one takes. */
|
|
1162
|
+
#farAllocated(aggregate: IFarAggregate): number {
|
|
1163
|
+
let at = 0;
|
|
1164
|
+
for (const segment of aggregate.segments.values()) at += segment.count;
|
|
1165
|
+
return at;
|
|
1166
|
+
}
|
|
1167
|
+
|
|
1168
|
+
/** Compose one run's ORIGINAL placement roots into its segment, exactly as `#addPlacements` does. */
|
|
1169
|
+
#writeFarSegment(aggregate: IFarAggregate, segment: IFarSegment): void {
|
|
1170
|
+
const records = cellPlacements(this.#placements, segment.run);
|
|
1171
|
+
const array = aggregate.mesh.instanceMatrix.array as Float32Array;
|
|
1172
|
+
const base = segment.start * 16;
|
|
1173
|
+
for (let index = 0; index < segment.count; index += 1) {
|
|
1174
|
+
const at = index * PLACEMENT_RECORD_FLOATS;
|
|
1175
|
+
this.#position.set(
|
|
1176
|
+
records[at] as number,
|
|
1177
|
+
records[at + 1] as number,
|
|
1178
|
+
records[at + 2] as number,
|
|
1179
|
+
);
|
|
1180
|
+
this.#rotation.set(
|
|
1181
|
+
records[at + 3] as number,
|
|
1182
|
+
records[at + 4] as number,
|
|
1183
|
+
records[at + 5] as number,
|
|
1184
|
+
records[at + 6] as number,
|
|
1185
|
+
);
|
|
1186
|
+
this.#scale.setScalar(records[at + 7] as number);
|
|
1187
|
+
this.#matrix.compose(this.#position, this.#rotation, this.#scale);
|
|
1188
|
+
this.#matrix.toArray(array, base + index * 16);
|
|
1189
|
+
}
|
|
1190
|
+
aggregate.mesh.instanceMatrix.needsUpdate = true;
|
|
1191
|
+
// The per-placement gate is static, so it is written with the matrices and re-uploaded only when
|
|
1192
|
+
// a handoff rewrites this segment. A whole-map surface reads it so every canonical asset keeps
|
|
1193
|
+
// its own authored cutoff over the shared atlas. See {@link IFarSegment.cull}.
|
|
1194
|
+
const cull = aggregate.mesh.geometry.getAttribute(IMPOSTOR_FAR_CULL_ATTRIBUTE) as
|
|
1195
|
+
| InstancedBufferAttribute
|
|
1196
|
+
| undefined;
|
|
1197
|
+
if (cull !== undefined) {
|
|
1198
|
+
(cull.array as Float32Array).fill(segment.cull, segment.start, segment.start + segment.count);
|
|
1199
|
+
cull.needsUpdate = true;
|
|
1200
|
+
}
|
|
1201
|
+
aggregate.uploads += 1;
|
|
1202
|
+
this.#farBoundsStale(aggregate);
|
|
1203
|
+
}
|
|
1204
|
+
|
|
1205
|
+
/**
|
|
1206
|
+
* Zero one segment's records: the run is drawn by the near ring now, not the far mesh. Each record
|
|
1207
|
+
* keeps a homogeneous `w` of 1 while its xyz/scale terms collapse to 0, so the instance projects
|
|
1208
|
+
* to the origin and draws nothing. An all-zero record would leave `w = 0`, and Three's
|
|
1209
|
+
* `Box3.applyMatrix4` divides by it, so `computeBoundingBox` over the shared buffer would return
|
|
1210
|
+
* NaN and every caster in the aggregate would be dropped by the shadow levels.
|
|
1211
|
+
*/
|
|
1212
|
+
#zeroFarSegment(aggregate: IFarAggregate, segment: IFarSegment): void {
|
|
1213
|
+
const array = aggregate.mesh.instanceMatrix.array as Float32Array;
|
|
1214
|
+
const from = segment.start * 16;
|
|
1215
|
+
const to = (segment.start + segment.count) * 16;
|
|
1216
|
+
array.fill(0, from, to);
|
|
1217
|
+
for (let at = from; at < to; at += 16) array[at + 15] = 1;
|
|
1218
|
+
aggregate.mesh.instanceMatrix.needsUpdate = true;
|
|
1219
|
+
aggregate.uploads += 1;
|
|
1220
|
+
this.#farBoundsStale(aggregate);
|
|
1221
|
+
}
|
|
1222
|
+
|
|
1223
|
+
/**
|
|
1224
|
+
* A far matrix write changes the mesh's instance extent, so drop the cached pair and let Three
|
|
1225
|
+
* rebuild it on the next read; this is the native `null` convention `computeBoundingBox` honors.
|
|
1226
|
+
*/
|
|
1227
|
+
#farBoundsStale(aggregate: IFarAggregate): void {
|
|
1228
|
+
aggregate.mesh.boundingBox = null;
|
|
1229
|
+
aggregate.mesh.boundingSphere = null;
|
|
1230
|
+
}
|
|
1231
|
+
|
|
1232
|
+
/** The near ring has attached this run's full representation; the far mesh stops drawing it. */
|
|
1233
|
+
disableFar(run: IWorldRun): void {
|
|
1234
|
+
const aggregate = this.#farSegments.get(run);
|
|
1235
|
+
if (aggregate === undefined) return;
|
|
1236
|
+
const segment = aggregate.segments.get(run);
|
|
1237
|
+
if (segment === undefined || segment.live === false) return;
|
|
1238
|
+
this.#zeroFarSegment(aggregate, segment);
|
|
1239
|
+
segment.live = false;
|
|
1240
|
+
}
|
|
1241
|
+
|
|
1242
|
+
/** This run is leaving the ring; the far mesh draws it again before the near batches are cleared. */
|
|
1243
|
+
restoreFar(run: IWorldRun): void {
|
|
1244
|
+
const aggregate = this.#farSegments.get(run);
|
|
1245
|
+
if (aggregate === undefined) return;
|
|
1246
|
+
const segment = aggregate.segments.get(run);
|
|
1247
|
+
if (segment === undefined || segment.live === true) return;
|
|
1248
|
+
this.#writeFarSegment(aggregate, segment);
|
|
1249
|
+
segment.live = true;
|
|
1250
|
+
}
|
|
1251
|
+
|
|
1252
|
+
/**
|
|
1253
|
+
* Hand over every run of an aggregate a resident cell already draws. A run is near-ready exactly
|
|
1254
|
+
* when the cell holds one of its batches; the whole job is attached in one swap, so presence is the
|
|
1255
|
+
* answer. This is the build-time half of the atomic handoff; `#swap` is the per-frame half.
|
|
1256
|
+
*/
|
|
1257
|
+
#syncFarSegments(aggregate: IFarAggregate): void {
|
|
1258
|
+
for (const segment of aggregate.segments.values()) {
|
|
1259
|
+
if (segment.live === false) continue;
|
|
1260
|
+
const resident = this.#host.residentCell(cellKey(segment.cell.x, segment.cell.z));
|
|
1261
|
+
if (resident === undefined) continue;
|
|
1262
|
+
if (!resident.batches.some((entry) => entry.run === segment.run)) continue;
|
|
1263
|
+
this.#zeroFarSegment(aggregate, segment);
|
|
1264
|
+
segment.live = false;
|
|
1265
|
+
}
|
|
1266
|
+
}
|
|
1267
|
+
|
|
1268
|
+
/** An aggregate's live and near-owned instance counts. */
|
|
1269
|
+
#farSplit(aggregate: IFarAggregate): { live: number; nearOwned: number } {
|
|
1270
|
+
let live = 0;
|
|
1271
|
+
let nearOwned = 0;
|
|
1272
|
+
for (const segment of aggregate.segments.values()) {
|
|
1273
|
+
if (segment.live) live += segment.count;
|
|
1274
|
+
else nearOwned += segment.count;
|
|
1275
|
+
}
|
|
1276
|
+
return { live, nearOwned };
|
|
1277
|
+
}
|
|
1278
|
+
|
|
1279
|
+
/** The far block {@link stats} reports: aggregates, physical instances/bytes and their split. */
|
|
1280
|
+
#farStats(): IWorldCellsStats["impostor"]["far"] {
|
|
1281
|
+
let instances = 0;
|
|
1282
|
+
let live = 0;
|
|
1283
|
+
let nearOwned = 0;
|
|
1284
|
+
let uploads = 0;
|
|
1285
|
+
for (const aggregate of this.#far.values()) {
|
|
1286
|
+
instances += aggregate.capacity;
|
|
1287
|
+
uploads += aggregate.uploads;
|
|
1288
|
+
const split = this.#farSplit(aggregate);
|
|
1289
|
+
live += split.live;
|
|
1290
|
+
nearOwned += split.nearOwned;
|
|
1291
|
+
}
|
|
1292
|
+
return {
|
|
1293
|
+
aggregates: this.#far.size,
|
|
1294
|
+
bytes: this.#farBytes,
|
|
1295
|
+
instances,
|
|
1296
|
+
live,
|
|
1297
|
+
nearOwned,
|
|
1298
|
+
uploads,
|
|
1299
|
+
};
|
|
1300
|
+
}
|
|
1301
|
+
|
|
1302
|
+
/** Dispose every far aggregate: its own mesh and surface, and its borrowed atlas user. */
|
|
1303
|
+
#drainFar(): void {
|
|
1304
|
+
for (const aggregate of this.#far.values()) {
|
|
1305
|
+
aggregate.mesh.removeFromParent();
|
|
1306
|
+
aggregate.mesh.dispose();
|
|
1307
|
+
aggregate.surface.dispose();
|
|
1308
|
+
aggregate.record.users = Math.max(0, aggregate.record.users - 1);
|
|
1309
|
+
}
|
|
1310
|
+
this.#far.clear();
|
|
1311
|
+
this.#farSegments.clear();
|
|
1312
|
+
this.#farInstances = 0;
|
|
1313
|
+
this.#farBytes = 0;
|
|
1314
|
+
}
|
|
1315
|
+
|
|
1316
|
+
/** Retry the handoffs a frame's fresh-mesh allowance deferred; one bounded pass per update. */
|
|
1317
|
+
retryWide(): void {
|
|
1318
|
+
if (this.#wideRetry.size === 0) return;
|
|
1319
|
+
const ids = [...this.#wideRetry];
|
|
1320
|
+
this.#wideRetry.clear();
|
|
1321
|
+
for (const id of ids) {
|
|
1322
|
+
const asset = this.#host.asset(id);
|
|
1323
|
+
if (asset === undefined || asset.impostor === undefined) continue;
|
|
1324
|
+
this.#host.retargetWideCasters(asset);
|
|
1325
|
+
}
|
|
1326
|
+
}
|
|
1327
|
+
|
|
1328
|
+
/** The impostor block {@link stats} reports: assets landed, bakes pending, atlas bytes, terminal tris. */
|
|
1329
|
+
impostorStats(): IWorldCellsStats["impostor"] {
|
|
1330
|
+
let assets = 0;
|
|
1331
|
+
let terminalTriangles = 0;
|
|
1332
|
+
for (const asset of this.#host.assets()) {
|
|
1333
|
+
if (asset.impostor === undefined) continue;
|
|
1334
|
+
assets += 1;
|
|
1335
|
+
terminalTriangles += levelTriangles(asset.impostor.part.geometry);
|
|
1336
|
+
}
|
|
1337
|
+
return {
|
|
1338
|
+
assets,
|
|
1339
|
+
atlasBytes: this.#impostorRecordBytes,
|
|
1340
|
+
budgetBytes: this.#impostorBudgetBytes,
|
|
1341
|
+
drawn: this.#host.drawnImpostorInstances() + this.#farStats().live,
|
|
1342
|
+
far: this.#farStats(),
|
|
1343
|
+
pending: this.#impostorQueue.length + (this.#impostorBaking === undefined ? 0 : 1),
|
|
1344
|
+
terminalTriangles,
|
|
1345
|
+
};
|
|
1346
|
+
}
|
|
1347
|
+
|
|
1348
|
+
/** Drop queued/baking work for an asset whose source geometry is about to be released. */
|
|
1349
|
+
cancelImpostor(asset: IAssetState): void {
|
|
1350
|
+
this.#impostorQueued.delete(asset.id);
|
|
1351
|
+
const at = this.#impostorQueue.indexOf(asset);
|
|
1352
|
+
if (at >= 0) this.#impostorQueue.splice(at, 1);
|
|
1353
|
+
if (this.#impostorBaking === asset) {
|
|
1354
|
+
// Before the borrowed source geometry is released: the baker stages it, and a view drawn after
|
|
1355
|
+
// the teardown reads a disposed buffer.
|
|
1356
|
+
this.#baker.abort();
|
|
1357
|
+
this.#impostorBaking = undefined;
|
|
1358
|
+
this.#impostorReservedBytes = 0;
|
|
1359
|
+
}
|
|
1360
|
+
}
|
|
1361
|
+
|
|
1362
|
+
/** Release an asset's terminal level and give its atlas back to the cache; see `#release`. */
|
|
1363
|
+
releaseImpostor(asset: IAssetState): void {
|
|
1364
|
+
const impostor = asset.impostor;
|
|
1365
|
+
if (impostor === undefined) return;
|
|
1366
|
+
asset.impostor = undefined;
|
|
1367
|
+
// Marked first, so `#releaseParts` skips the part whose geometry and material the surface owns.
|
|
1368
|
+
this.#host.markReleasedPart(impostor.part);
|
|
1369
|
+
dropPooledFor(impostor.part.geometry, impostor.part.material);
|
|
1370
|
+
impostor.surface.dispose();
|
|
1371
|
+
impostor.record.users = Math.max(0, impostor.record.users - 1);
|
|
1372
|
+
this.#evictImpostors();
|
|
1373
|
+
}
|
|
1374
|
+
|
|
1375
|
+
/**
|
|
1376
|
+
* Drop the oldest inactive atlases until the cache is back under budget; active ones are kept.
|
|
1377
|
+
*
|
|
1378
|
+
* `reserve` is the declared bytes of a bake about to start: the caller asks whether evicting
|
|
1379
|
+
* inactive records can make room for it. A record with a live user is never dropped, so a full
|
|
1380
|
+
* cache of active atlases simply leaves the reservation unmet and the caller refuses the bake.
|
|
1381
|
+
*/
|
|
1382
|
+
#evictImpostors(reserve = 0): void {
|
|
1383
|
+
if (this.#impostorRecordBytes + reserve <= this.#impostorBudgetBytes) return;
|
|
1384
|
+
for (const [key, record] of [...this.#impostorRecords]) {
|
|
1385
|
+
if (this.#impostorRecordBytes + reserve <= this.#impostorBudgetBytes) break;
|
|
1386
|
+
if (record.users > 0) continue;
|
|
1387
|
+
this.#impostorRecords.delete(key);
|
|
1388
|
+
this.#impostorRecordBytes -= record.bytes;
|
|
1389
|
+
record.atlas.dispose();
|
|
1390
|
+
}
|
|
1391
|
+
}
|
|
1392
|
+
|
|
1393
|
+
/** Dispose every cached atlas and any in-flight bake; the world's teardown path calls it once. */
|
|
1394
|
+
drainImpostors(): void {
|
|
1395
|
+
// Far-only sources no cell run owns would otherwise never reach `#evict`; release them here so
|
|
1396
|
+
// their geometry goes the way every near asset's does.
|
|
1397
|
+
for (const id of [...this.#farTemp]) this.#host.release(id);
|
|
1398
|
+
this.#farTemp.clear();
|
|
1399
|
+
// Deferred far cohorts own a surface and pin an atlas user; release both before the records are
|
|
1400
|
+
// disposed below, so no surface is left pointing at a disposed atlas.
|
|
1401
|
+
for (const entry of this.#farRetry.values()) {
|
|
1402
|
+
entry.surface.dispose();
|
|
1403
|
+
entry.record.users = Math.max(0, entry.record.users - 1);
|
|
1404
|
+
}
|
|
1405
|
+
this.#farRetry.clear();
|
|
1406
|
+
this.#farSeen.clear();
|
|
1407
|
+
// The far aggregates own surfaces over these atlases and hold a user on their records; they go
|
|
1408
|
+
// first, so no far surface is left pointing at an atlas disposed below it.
|
|
1409
|
+
this.#drainFar();
|
|
1410
|
+
this.#impostorQueue.length = 0;
|
|
1411
|
+
this.#impostorQueued.clear();
|
|
1412
|
+
this.#impostorBaking = undefined;
|
|
1413
|
+
this.#impostorReservedBytes = 0;
|
|
1414
|
+
this.#baker.dispose();
|
|
1415
|
+
for (const record of this.#impostorRecords.values()) record.atlas.dispose();
|
|
1416
|
+
this.#impostorRecords.clear();
|
|
1417
|
+
this.#impostorRecordBytes = 0;
|
|
1418
|
+
}
|
|
1419
|
+
|
|
1420
|
+
/**
|
|
1421
|
+
* `TN_WORLD_IMPOSTOR`, one bounded line per asset: its terminal level, the metres it takes over at,
|
|
1422
|
+
* the views the atlas holds, its GPU bytes, and — when the world can name it — why it did not land.
|
|
1423
|
+
*/
|
|
1424
|
+
#reportImpostor(asset: IAssetState, reason: string): void {
|
|
1425
|
+
if (this.#impostorReported.has(asset.id)) return;
|
|
1426
|
+
this.#impostorReported.add(asset.id);
|
|
1427
|
+
const impostor = asset.impostor;
|
|
1428
|
+
const atlas = impostor?.record.atlas ?? this.#baker.pending?.atlas;
|
|
1429
|
+
console.info(
|
|
1430
|
+
`${WORLD_IMPOSTOR_MARKER} asset=${asset.id} level=${String(asset.levels.length - 1)} ` +
|
|
1431
|
+
`switch=${(asset.distances.at(-1) ?? 0).toFixed(1)} ` +
|
|
1432
|
+
`views=${String(atlas === undefined ? 0 : IMPOSTOR_VIEWS)} ` +
|
|
1433
|
+
`bytes=${String(atlas?.bytes ?? 0)} reason=${reason}`,
|
|
1434
|
+
);
|
|
1435
|
+
}
|
|
1436
|
+
}
|
|
1437
|
+
|
|
1438
|
+
export const PLACEMENT_RECORD_BYTES = 32;
|
|
1439
|
+
|
|
1440
|
+
export const PLACEMENT_RECORD_FLOATS = 8;
|
|
1441
|
+
|
|
1442
|
+
/**
|
|
1443
|
+
* The distance a `maxDistance` prop actually culls at, one eighth short of itself: the slack
|
|
1444
|
+
* `#addPlacements` leaves, so a follow point that has not moved a whole eighth of the cull distance
|
|
1445
|
+
* cannot have culled a placement it had not already culled.
|
|
1446
|
+
*/
|
|
1447
|
+
export function cullDistance(maxDistance: number | undefined): number | undefined {
|
|
1448
|
+
return maxDistance === undefined ? undefined : maxDistance - maxDistance / 8;
|
|
1449
|
+
}
|