@threenative/core 0.3.10 → 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.
Files changed (158) hide show
  1. package/capabilities.json +1096 -26
  2. package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
  3. package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-CWuFRT7G.d.ts} +1 -1
  4. package/dist/chunk-2Z44XSI2.js +35 -0
  5. package/dist/chunk-5O73CDMR.js +1849 -0
  6. package/dist/chunk-6KLNISRJ.js +153 -0
  7. package/dist/chunk-7UUT3TY5.js +133 -0
  8. package/dist/chunk-CFGTPFUH.js +231 -0
  9. package/dist/chunk-DBELTTTM.js +615 -0
  10. package/dist/chunk-GMHATRPW.js +7701 -0
  11. package/dist/chunk-GXY7B3JG.js +46 -0
  12. package/dist/chunk-KIRUKTBQ.js +187 -0
  13. package/dist/chunk-N5LRP4BR.js +220 -0
  14. package/dist/chunk-OKXUCASC.js +2238 -0
  15. package/dist/chunk-QWJEMUUT.js +94 -0
  16. package/dist/chunk-VAZM36TV.js +497 -0
  17. package/dist/{game-DzMcitDO.d.ts → game-D7pAzZUY.d.ts} +15 -3
  18. package/dist/hot.d.ts +3 -3
  19. package/dist/hot.js +2 -46
  20. package/dist/index.d.ts +329 -302
  21. package/dist/index.js +10565 -22533
  22. package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-B6BMqS1r.d.ts} +33 -3
  23. package/dist/playtest.d.ts +3 -3
  24. package/dist/playtest.js +24 -75
  25. package/dist/react-css.js +1 -215
  26. package/dist/react.d.ts +2 -2
  27. package/dist/{renderer-rZm0hVqq.d.ts → renderer-DvFVoAgj.d.ts} +13 -4
  28. package/dist/spells/index.d.ts +643 -0
  29. package/dist/spells/index.js +1558 -0
  30. package/dist/spells/ultra/index.d.ts +1600 -0
  31. package/dist/spells/ultra/index.js +6804 -0
  32. package/dist/terrain-jobs-worker.js +1 -123
  33. package/dist/two-sided-foliage-W523J3UM.js +1 -0
  34. package/dist/ui-layer.js +5 -384
  35. package/dist/worker.js +4 -41
  36. package/dist/world.d.ts +725 -259
  37. package/dist/world.js +16714 -18284
  38. package/mcp/animation-server.mjs +1 -1
  39. package/mcp/animation.mjs +2 -3
  40. package/mcp/engine-server.mjs +142 -47
  41. package/mcp/servers.mjs +9 -2
  42. package/mcp/terrain.mjs +8 -0
  43. package/package.json +14 -6
  44. package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
  45. package/patches/three@0.187.0.patch +2004 -407
  46. package/src/assets.ts +9 -2
  47. package/src/card-lod.ts +152 -0
  48. package/src/compressed-texture-preparation.ts +1008 -0
  49. package/src/frame-budget.ts +31 -20
  50. package/src/game-dev-tools.ts +93 -0
  51. package/src/game-frame-loop.ts +995 -0
  52. package/src/game-renderer-metrics.ts +77 -0
  53. package/src/game-startup.ts +1001 -0
  54. package/src/game-validate.ts +70 -0
  55. package/src/game.ts +253 -1935
  56. package/src/index.ts +27 -2
  57. package/src/launch-diagnostics.ts +22 -12
  58. package/src/look/ao-admission.ts +24 -0
  59. package/src/look/filmic-tone-mapping.ts +15 -13
  60. package/src/look/look-diagnostics.ts +3 -3
  61. package/src/look/quality.ts +10 -5
  62. package/src/look/world-environment.ts +76 -9
  63. package/src/loop.ts +29 -0
  64. package/src/model-lod.ts +42 -3
  65. package/src/particle-kinds.ts +515 -0
  66. package/src/picking.ts +17 -3
  67. package/src/playtest.ts +27 -1
  68. package/src/projection-apply.ts +4 -1
  69. package/src/projection-plan.ts +9 -6
  70. package/src/render/mesh-pool.ts +1 -1
  71. package/src/render/resolution-subrect.ts +2 -0
  72. package/src/render/rough-diffuse.ts +46 -12
  73. package/src/render/soft-shadow.ts +27 -12
  74. package/src/render/virtual-shadow-adaptive.ts +55 -0
  75. package/src/render/virtual-shadow-casters.ts +175 -0
  76. package/src/render/virtual-shadow-layers.ts +76 -0
  77. package/src/render/virtual-shadow-level.ts +224 -0
  78. package/src/render/virtual-shadow-markers.ts +193 -0
  79. package/src/render/virtual-shadow-options.ts +370 -0
  80. package/src/render/virtual-shadow-pages.ts +5 -0
  81. package/src/render/virtual-shadow.ts +213 -992
  82. package/src/render/world-impostor-surface.ts +293 -34
  83. package/src/render-camera-cull.ts +32 -1
  84. package/src/render-pass-budget.ts +34 -7
  85. package/src/renderProjection.ts +22 -0
  86. package/src/renderer.ts +92 -37
  87. package/src/snow-field.ts +1 -1
  88. package/src/spells/cast-pool.ts +361 -0
  89. package/src/spells/index.ts +177 -0
  90. package/src/spells/mechanisms.ts +295 -0
  91. package/src/spells/reaction-field.ts +415 -0
  92. package/src/spells/spell-lights.ts +139 -0
  93. package/src/spells/spell-world.ts +187 -0
  94. package/src/spells/spell.ts +397 -0
  95. package/src/spells/spells.ts +283 -0
  96. package/src/spells/ultra/engine/camera.ts +184 -0
  97. package/src/spells/ultra/engine/quality.ts +96 -0
  98. package/src/spells/ultra/index.ts +52 -0
  99. package/src/spells/ultra/main.ts +305 -0
  100. package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
  101. package/src/spells/ultra/spells/cast.ts +233 -0
  102. package/src/spells/ultra/spells/fire.ts +1267 -0
  103. package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
  104. package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
  105. package/src/spells/ultra/vfx/FxTarget.ts +61 -0
  106. package/src/spells/ultra/vfx/GroundField.ts +1399 -0
  107. package/src/spells/ultra/vfx/Particles.ts +1475 -0
  108. package/src/spells/ultra/vfx/Ribbons.ts +645 -0
  109. package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
  110. package/src/spells/ultra/vfx/Volumes.ts +489 -0
  111. package/src/spells/ultra/vfx/common.ts +1195 -0
  112. package/src/spells/ultra/vfx/noise.ts +441 -0
  113. package/src/startup-readiness.ts +128 -34
  114. package/src/version.ts +1 -1
  115. package/src/warmup.ts +56 -8
  116. package/src/water-surface.ts +9 -3
  117. package/src/world-bundle-safety.ts +401 -0
  118. package/src/world-cell-batches.ts +1216 -0
  119. package/src/world-cell-chunks.ts +1132 -0
  120. package/src/world-cell-data.ts +995 -0
  121. package/src/world-cell-impostors.ts +1449 -0
  122. package/src/world-cell-lod-bias.ts +151 -0
  123. package/src/world-cell-models.ts +1074 -0
  124. package/src/world-cell-options.ts +189 -0
  125. package/src/world-cell-placements.ts +694 -0
  126. package/src/world-cell-prewarm.ts +557 -0
  127. package/src/world-cell-readiness.ts +357 -0
  128. package/src/world-cell-render-bundles.ts +459 -0
  129. package/src/world-cell-render-gpu-dress.ts +714 -0
  130. package/src/world-cell-render-main-cull.ts +484 -0
  131. package/src/world-cell-render-shadow-claims.ts +198 -0
  132. package/src/world-cell-render-util.ts +246 -0
  133. package/src/world-cell-render.ts +1493 -0
  134. package/src/world-cell-residency.ts +745 -0
  135. package/src/world-cells.ts +1318 -10418
  136. package/src/world-chunk-shadow.ts +308 -0
  137. package/src/world-collar.ts +315 -0
  138. package/src/world-gpu-flags.ts +163 -0
  139. package/src/world-gpu-readback.ts +881 -0
  140. package/src/world-gpu-reference.ts +510 -0
  141. package/src/world-gpu-scene.ts +214 -2264
  142. package/src/world-gpu-shadow.ts +190 -0
  143. package/src/world-gpu-types.ts +381 -0
  144. package/src/world-gpu-validation.ts +518 -0
  145. package/src/world-heightfield.ts +802 -0
  146. package/src/world-load-limiter.ts +106 -0
  147. package/src/world-noise.ts +241 -0
  148. package/src/world-package.ts +42 -0
  149. package/src/world-region.ts +1 -1
  150. package/src/world-terrain-splat.ts +365 -149
  151. package/src/world-tile-budget.ts +256 -0
  152. package/src/world-tile-geometry.ts +469 -0
  153. package/src/world-tile-lod.ts +408 -0
  154. package/src/world-tile-observation.ts +566 -0
  155. package/src/world-tile-stitch.ts +166 -0
  156. package/src/world-tiles.ts +170 -1745
  157. package/src/world-water-bodies.ts +359 -0
  158. 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
+ }