@threenative/core 0.3.11 → 0.3.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (236) hide show
  1. package/README.md +1 -1
  2. package/capabilities.json +1988 -204
  3. package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
  4. package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
  5. package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
  6. package/dist/chunk-4SRAQFTU.js +133 -0
  7. package/dist/chunk-CFGTPFUH.js +231 -0
  8. package/dist/chunk-DIPIJICH.js +8916 -0
  9. package/dist/chunk-EEABDLUC.js +2237 -0
  10. package/dist/chunk-EFWZWLPY.js +1895 -0
  11. package/dist/chunk-GXY7B3JG.js +46 -0
  12. package/dist/chunk-GYUZJQ7U.js +280 -0
  13. package/dist/chunk-H4J6IAJE.js +504 -0
  14. package/dist/chunk-KIRUKTBQ.js +187 -0
  15. package/dist/chunk-QWJEMUUT.js +94 -0
  16. package/dist/chunk-SV4QVUTQ.js +31 -0
  17. package/dist/chunk-U4YHUKKL.js +615 -0
  18. package/dist/chunk-VP43GIWW.js +18 -0
  19. package/dist/chunk-XDTZ4QMO.js +160 -0
  20. package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
  21. package/dist/{game-DzMcitDO.d.ts → game-k8K3hZai.d.ts} +85 -9
  22. package/dist/hot.d.ts +5 -4
  23. package/dist/hot.js +5 -52
  24. package/dist/index.d.ts +633 -1351
  25. package/dist/index.js +12873 -23068
  26. package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-DPTzeCcD.d.ts} +35 -3
  27. package/dist/playtest.d.ts +5 -4
  28. package/dist/playtest.js +25 -75
  29. package/dist/quality-BYqKGAwo.d.ts +868 -0
  30. package/dist/react-css.js +1 -215
  31. package/dist/react.d.ts +3 -2
  32. package/dist/render-environment.d.ts +170 -0
  33. package/dist/render-environment.js +352 -0
  34. package/dist/{renderer-rZm0hVqq.d.ts → renderer-BtOSseYf.d.ts} +42 -35
  35. package/dist/spells/index.d.ts +643 -0
  36. package/dist/spells/index.js +1558 -0
  37. package/dist/spells/ultra/index.d.ts +1600 -0
  38. package/dist/spells/ultra/index.js +6804 -0
  39. package/dist/terrain-jobs-worker.js +1 -123
  40. package/dist/two-sided-foliage-W523J3UM.js +1 -0
  41. package/dist/ui-layer.js +6 -384
  42. package/dist/worker.js +13 -43
  43. package/dist/world.d.ts +988 -268
  44. package/dist/world.js +17464 -18290
  45. package/mcp/animation-server.mjs +1 -1
  46. package/mcp/animation.mjs +2 -3
  47. package/mcp/engine-server.mjs +245 -52
  48. package/mcp/servers.mjs +10 -3
  49. package/mcp/terrain.mjs +8 -0
  50. package/package.json +19 -7
  51. package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
  52. package/patches/three@0.187.0.patch +2004 -407
  53. package/src/animation-batch.ts +193 -0
  54. package/src/animation-layers.ts +7 -3
  55. package/src/animation.ts +209 -29
  56. package/src/asset-cache.ts +3 -3
  57. package/src/asset-memo.ts +202 -0
  58. package/src/assets.ts +437 -125
  59. package/src/auto-batch.ts +190 -44
  60. package/src/card-lod.ts +152 -0
  61. package/src/compressed-texture-preparation.ts +1008 -0
  62. package/src/compute-driven.ts +1 -1
  63. package/src/config.ts +8 -0
  64. package/src/debug.ts +103 -22
  65. package/src/dev-global.ts +54 -0
  66. package/src/engine-hooks.ts +37 -0
  67. package/src/frame-budget.ts +50 -23
  68. package/src/game-boot-phase.ts +269 -0
  69. package/src/game-dev-tools.ts +86 -0
  70. package/src/game-frame-loop.ts +958 -0
  71. package/src/game-renderer-metrics.ts +77 -0
  72. package/src/game-startup.ts +1076 -0
  73. package/src/game-ui.ts +84 -0
  74. package/src/game-validate.ts +70 -0
  75. package/src/game.ts +198 -2264
  76. package/src/gamepad-mappings.ts +269 -0
  77. package/src/generated/console-markers.ts +13 -0
  78. package/src/geometry-capture.ts +28 -4
  79. package/src/gpu-readings.ts +98 -0
  80. package/src/gpu-scene-bvh.ts +149 -36
  81. package/src/hot.ts +4 -7
  82. package/src/index.ts +141 -9
  83. package/src/input.ts +237 -25
  84. package/src/instanced-batch-lod.ts +3 -8
  85. package/src/interpolation.ts +171 -40
  86. package/src/launch-diagnostics.ts +22 -12
  87. package/src/look/ao-admission.ts +25 -0
  88. package/src/look/auto-exposure.ts +5 -16
  89. package/src/look/default-tone-mapping.ts +41 -5
  90. package/src/look/filmic-tone-mapping.ts +15 -13
  91. package/src/look/local-exposure.ts +2 -7
  92. package/src/look/look-diagnostics.ts +3 -3
  93. package/src/look/quad-pass.ts +21 -0
  94. package/src/look/quality.ts +14 -5
  95. package/src/look/unreal-bloom.ts +4 -13
  96. package/src/look/world-environment.ts +113 -103
  97. package/src/loop.ts +29 -0
  98. package/src/merge-parts.ts +20 -24
  99. package/src/model-lod.ts +139 -17
  100. package/src/particle-kinds.ts +515 -0
  101. package/src/particle-significance.ts +12 -0
  102. package/src/particles.ts +19 -10
  103. package/src/picking.ts +17 -3
  104. package/src/platform.ts +23 -4
  105. package/src/playtest.ts +27 -1
  106. package/src/profiling/FrameStages.ts +5 -6
  107. package/src/profiling/Spans.ts +3 -17
  108. package/src/profiling/debug-telemetry.ts +2 -6
  109. package/src/profiling/render-list-validate.ts +6 -15
  110. package/src/projection-apply.ts +4 -1
  111. package/src/projection-marker.ts +2 -1
  112. package/src/projection-plan.ts +9 -6
  113. package/src/quiet-markers.ts +3 -10
  114. package/src/render/cpu-bvh.ts +100 -0
  115. package/src/render/depth-pyramid.ts +6 -14
  116. package/src/render/environment/environmentContribution.ts +202 -0
  117. package/src/render/environment/environmentRadiance.ts +44 -0
  118. package/src/render/environment/environmentSampleCache.ts +56 -0
  119. package/src/render/environment/environmentSampling.ts +201 -0
  120. package/src/render/environment/environmentSnapshot.ts +71 -0
  121. package/src/render/environment/gate.ts +57 -0
  122. package/src/render/mesh-pool.ts +4 -20
  123. package/src/render/probe-trace.ts +872 -0
  124. package/src/render/probe-volume.ts +780 -34
  125. package/src/render/radiance-cache.ts +17 -0
  126. package/src/render/resolution-subrect.ts +2 -0
  127. package/src/render/rough-diffuse.ts +46 -12
  128. package/src/render/soft-shadow.ts +27 -12
  129. package/src/render/virtual-shadow-adaptive.ts +55 -0
  130. package/src/render/virtual-shadow-casters.ts +175 -0
  131. package/src/render/virtual-shadow-layers.ts +76 -0
  132. package/src/render/virtual-shadow-level.ts +224 -0
  133. package/src/render/virtual-shadow-markers.ts +193 -0
  134. package/src/render/virtual-shadow-options.ts +370 -0
  135. package/src/render/virtual-shadow-pages.ts +5 -0
  136. package/src/render/virtual-shadow-partial.ts +13 -0
  137. package/src/render/virtual-shadow.ts +231 -1008
  138. package/src/render/world-impostor-surface.ts +402 -40
  139. package/src/render/world-impostor.ts +5 -2
  140. package/src/render-camera-cull.ts +98 -3
  141. package/src/render-environment.ts +41 -0
  142. package/src/render-pass-budget.ts +34 -7
  143. package/src/renderProjection.ts +22 -0
  144. package/src/renderer-config.ts +36 -0
  145. package/src/renderer-facts.ts +37 -0
  146. package/src/renderer.ts +144 -65
  147. package/src/resolution-scaler.ts +3 -2
  148. package/src/scene-entry-inspectors.ts +61 -0
  149. package/src/snow-field.ts +2 -1
  150. package/src/spells/cast-pool.ts +361 -0
  151. package/src/spells/index.ts +177 -0
  152. package/src/spells/mechanisms.ts +295 -0
  153. package/src/spells/reaction-field.ts +415 -0
  154. package/src/spells/spell-lights.ts +139 -0
  155. package/src/spells/spell-world.ts +187 -0
  156. package/src/spells/spell.ts +397 -0
  157. package/src/spells/spells.ts +283 -0
  158. package/src/spells/ultra/engine/camera.ts +184 -0
  159. package/src/spells/ultra/engine/quality.ts +96 -0
  160. package/src/spells/ultra/index.ts +52 -0
  161. package/src/spells/ultra/main.ts +305 -0
  162. package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
  163. package/src/spells/ultra/spells/cast.ts +233 -0
  164. package/src/spells/ultra/spells/fire.ts +1267 -0
  165. package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
  166. package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
  167. package/src/spells/ultra/vfx/FxTarget.ts +61 -0
  168. package/src/spells/ultra/vfx/GroundField.ts +1399 -0
  169. package/src/spells/ultra/vfx/Particles.ts +1475 -0
  170. package/src/spells/ultra/vfx/Ribbons.ts +645 -0
  171. package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
  172. package/src/spells/ultra/vfx/Volumes.ts +489 -0
  173. package/src/spells/ultra/vfx/common.ts +1195 -0
  174. package/src/spells/ultra/vfx/noise.ts +441 -0
  175. package/src/startup-offscreen-bytes.ts +78 -0
  176. package/src/startup-readiness.ts +128 -34
  177. package/src/static-transform.ts +25 -19
  178. package/src/streamed-textures.ts +112 -0
  179. package/src/streaming.ts +68 -4
  180. package/src/texture-streaming.ts +331 -0
  181. package/src/version.ts +1 -1
  182. package/src/warmup.ts +56 -8
  183. package/src/water-surface.ts +9 -3
  184. package/src/worker.ts +12 -2
  185. package/src/world-bundle-safety.ts +446 -0
  186. package/src/world-cell-batches.ts +1178 -0
  187. package/src/world-cell-chunks.ts +1128 -0
  188. package/src/world-cell-data.ts +995 -0
  189. package/src/world-cell-impostors.ts +1461 -0
  190. package/src/world-cell-lod-bias.ts +151 -0
  191. package/src/world-cell-models.ts +1074 -0
  192. package/src/world-cell-options.ts +177 -0
  193. package/src/world-cell-placements.ts +798 -0
  194. package/src/world-cell-prewarm.ts +592 -0
  195. package/src/world-cell-readiness.ts +357 -0
  196. package/src/world-cell-records.ts +401 -0
  197. package/src/world-cell-render-bundles.ts +459 -0
  198. package/src/world-cell-render-gpu-dress.ts +710 -0
  199. package/src/world-cell-render-main-cull.ts +540 -0
  200. package/src/world-cell-render-shadow-claims.ts +198 -0
  201. package/src/world-cell-render-util.ts +259 -0
  202. package/src/world-cell-render.ts +1501 -0
  203. package/src/world-cell-residency.ts +754 -0
  204. package/src/world-cell-stale.ts +238 -0
  205. package/src/world-cells.ts +1335 -10418
  206. package/src/world-chunk-shadow.ts +308 -0
  207. package/src/world-collar.ts +315 -0
  208. package/src/world-gpu-flags.ts +131 -0
  209. package/src/world-gpu-readback.ts +881 -0
  210. package/src/world-gpu-reference.ts +524 -0
  211. package/src/world-gpu-scene.ts +256 -2286
  212. package/src/world-gpu-shadow.ts +203 -0
  213. package/src/world-gpu-types.ts +409 -0
  214. package/src/world-gpu-validation.ts +518 -0
  215. package/src/world-heightfield.ts +802 -0
  216. package/src/world-load-limiter.ts +111 -0
  217. package/src/world-model-sections.ts +80 -0
  218. package/src/world-noise.ts +241 -0
  219. package/src/world-package.ts +42 -0
  220. package/src/world-region.ts +1 -1
  221. package/src/world-river-ribbon.ts +282 -0
  222. package/src/world-root-frame.ts +39 -0
  223. package/src/world-shore-field.ts +91 -0
  224. package/src/world-static-pose.ts +163 -0
  225. package/src/world-surface-sampler.ts +48 -0
  226. package/src/world-terrain-splat.ts +361 -153
  227. package/src/world-tile-budget.ts +249 -0
  228. package/src/world-tile-geometry.ts +469 -0
  229. package/src/world-tile-lod.ts +408 -0
  230. package/src/world-tile-observation.ts +566 -0
  231. package/src/world-tile-stitch.ts +166 -0
  232. package/src/world-tiles.ts +247 -1755
  233. package/src/world-validate.ts +6 -14
  234. package/src/world-warm.ts +51 -0
  235. package/src/world-water-bodies.ts +359 -0
  236. package/src/world.ts +48 -741
@@ -0,0 +1,754 @@
1
+ import { type Box3, type Matrix4, Vector3 } from "three";
2
+ import type { Camera } from "three";
3
+ import type { IRendererLike } from "./renderer.js";
4
+ import type { CellChunks } from "./world-cell-chunks.js";
5
+ import type {
6
+ IBuildJob,
7
+ IResidentCell,
8
+ IWorldCellsBudget,
9
+ IWorldCellsFollow,
10
+ } from "./world-cell-data.js";
11
+ import { cellKey } from "./world-cell-data.js";
12
+ import { PLACEMENT_RECORD_BYTES } from "./world-cell-impostors.js";
13
+ import type { CellImpostors } from "./world-cell-impostors.js";
14
+ import type { IAssetState } from "./world-cell-models.js";
15
+ import type { CellModels } from "./world-cell-models.js";
16
+ import { ADMISSION_SLICE_PLACEMENTS, SETTLED_FOLLOW_METRES } from "./world-cell-options.js";
17
+ import {
18
+ type CellPlacements,
19
+ newBatches,
20
+ newBoxes,
21
+ publishCount,
22
+ } from "./world-cell-placements.js";
23
+ import type { CellPrewarm } from "./world-cell-prewarm.js";
24
+ import type { CellRender } from "./world-cell-render.js";
25
+ import type { IWorldCell, IWorldRun } from "./world-package.js";
26
+ import { localPoint } from "./world-root-frame.js";
27
+ import {
28
+ type IAdmissionBudget,
29
+ type IWorldTilesLodView,
30
+ TerrainTileBudgetError,
31
+ } from "./world-tiles.js";
32
+ import type { TerrainTiles } from "./world-tiles.js";
33
+
34
+ /** Bytes one resident cell pays for a record: see `#admit`. */
35
+ const LOD_RANGE_RECORD_BYTES = 16;
36
+
37
+ /** The five collaborators a residency pass drives, as one read. */
38
+ interface ICellResidencyParts {
39
+ readonly render: CellRender;
40
+ readonly chunks: CellChunks;
41
+ readonly models: CellModels;
42
+ readonly impostor: CellImpostors;
43
+ readonly prewarm: CellPrewarm;
44
+ readonly placements: CellPlacements;
45
+ readonly terrain: TerrainTiles | undefined;
46
+ }
47
+
48
+ /**
49
+ * What a residency pass asks its world for. The pass owns the ring, the build queue and the counters
50
+ * below; every other number is the world's, read through this interface.
51
+ */
52
+ export interface ICellResidencyHost {
53
+ released(): boolean;
54
+ cells(): readonly IWorldCell[];
55
+ /** The world grid's origin and cell side. */
56
+ extent(): { readonly cellSize: number; readonly minX: number; readonly minZ: number };
57
+ ring(): number;
58
+ budgets(): IWorldCellsBudget;
59
+ follow(): IWorldCellsFollow;
60
+ /** The world's clock: admission pricing and the prefetch lookahead read it. */
61
+ now(): number;
62
+ /** Seconds the ring is led by the follow point's smoothed velocity. */
63
+ prefetchSeconds(): number;
64
+ lodHysteresis(): number;
65
+ /** `camera` or `follow`: where the LOD eye is measured from. */
66
+ lodFrom(): "camera" | "follow";
67
+ /** The world root's own `matrixWorld`: the frame its placements are recorded in. */
68
+ root(): Matrix4;
69
+ asset(id: string): IAssetState | undefined;
70
+ canonical(id: string): string;
71
+ parts(): ICellResidencyParts;
72
+ /** Hands one finished build's shadow bounds to the game's publication hook. */
73
+ published(bounds: Box3): void;
74
+ addFailures(count: number): void;
75
+ }
76
+
77
+ /**
78
+ * The resident ring, the build queue that fills it, and the counters both report.
79
+ *
80
+ * One pass decides which cells are wanted around the follow point and admits what the budgets allow;
81
+ * the queue that follows spends one admission budget on the cell-asset builds it left, nearest cell
82
+ * first, and each build is taken to completion, so a cell draws whole levels. Eviction returns
83
+ * a cell's records to the far aggregate, drops its queued work and releases what it held.
84
+ *
85
+ * The residency decision itself runs only when the follow point moved or something is pending; see
86
+ * `stale`, which is what keeps a standing world from re-deriving the set it already holds.
87
+ */
88
+ export class CellResidency {
89
+ readonly #host: ICellResidencyHost;
90
+ readonly #resident = new Map<string, IResidentCell>();
91
+ /** Cell-asset builds waiting for budget, in admission order: nearest cell first. */
92
+ #jobs: IBuildJob[] = [];
93
+ /** The (cell, run) pairs already queued, so a refilter cannot queue itself twice. */
94
+ readonly #queued = new Set<IWorldRun>();
95
+ readonly #pressure = { cells: 0, instances: 0, bytes: 0 };
96
+ #instances = 0;
97
+ #bytes = 0;
98
+ #evictions = 0;
99
+ /** Completed admission steps; queued, refused and discarded work does not count. */
100
+ #admissionCompletedUnits = 0;
101
+ /** The follow point the last full residency pass ran for; see `stale`. */
102
+ readonly #residencyPoint = new Vector3(Number.NaN, 0, Number.NaN);
103
+ /** No pass has run yet: a fresh world owes its first ring whatever the follow point reads. */
104
+ #passed = false;
105
+ /** Actual cell at the last residency pass; only a jump reclaims retained hysteresis. */
106
+ #residencyCell: { readonly x: number; readonly z: number } | undefined;
107
+ /** Bumped by every admission and eviction, so a residency change owes a refilter that update. */
108
+ #residencyEpoch = 0;
109
+ /** Smoothed follow velocity (m/s) and the sample it was last updated from. */
110
+ #velocityX = 0;
111
+ #velocityZ = 0;
112
+ #lastSample: { readonly x: number; readonly z: number; readonly t: number } | undefined;
113
+ /** The point levels and `maxDistance` are measured from this update; see `updateEye`. */
114
+ readonly #eye = new Vector3();
115
+ /** The follow point `updateEye` pulls the camera toward. */
116
+ readonly #eyeFollow = new Vector3();
117
+ #generation = 0;
118
+ /** The world grid, read once: a package's origin and cell side do not change for a world's life. */
119
+ #grid: { readonly cellSize: number; readonly minX: number; readonly minZ: number } | undefined;
120
+
121
+ constructor(host: ICellResidencyHost) {
122
+ this.#host = host;
123
+ }
124
+
125
+ /** The resident ring, by cell key. */
126
+ get resident(): ReadonlyMap<string, IResidentCell> {
127
+ return this.#resident;
128
+ }
129
+ /** The LOD eye: where this update's levels and `maxDistance` are measured from. */
130
+ get eye(): Vector3 {
131
+ return this.#eye;
132
+ }
133
+ /** Builds waiting for budget. */
134
+ get queuedBuilds(): number {
135
+ return this.#jobs.length;
136
+ }
137
+ get instances(): number {
138
+ return this.#instances;
139
+ }
140
+ get bytes(): number {
141
+ return this.#bytes;
142
+ }
143
+ get residencyEpoch(): number {
144
+ return this.#residencyEpoch;
145
+ }
146
+ /** Whether a build for this cell is still queued, so its content is not finished. */
147
+ hasBuild(cell: IResidentCell): boolean {
148
+ return this.#jobs.some((job) => job.cell === cell);
149
+ }
150
+
151
+ /** The counters a world reports; see `IWorldCellsStats`. */
152
+ counters(): {
153
+ readonly admissionCompletedUnits: number;
154
+ readonly bytes: number;
155
+ readonly evictions: number;
156
+ readonly instances: number;
157
+ readonly pressure: {
158
+ readonly cells: number;
159
+ readonly instances: number;
160
+ readonly bytes: number;
161
+ };
162
+ readonly residentCells: number;
163
+ } {
164
+ return {
165
+ admissionCompletedUnits: this.#admissionCompletedUnits,
166
+ bytes: this.#bytes,
167
+ evictions: this.#evictions,
168
+ instances: this.#instances,
169
+ pressure: { ...this.#pressure },
170
+ residentCells: this.#resident.size,
171
+ };
172
+ }
173
+
174
+ /**
175
+ * One residency pass: the terrain ring follows, then the wanted cells are admitted against the
176
+ * budgets, each one led by the follow point's own lookahead.
177
+ */
178
+ pass(
179
+ x: number,
180
+ z: number,
181
+ budget: IAdmissionBudget,
182
+ renderer: IRendererLike | undefined,
183
+ camera: Camera | undefined,
184
+ terrainView: IWorldTilesLodView | undefined,
185
+ ): void {
186
+ this.#grid ??= this.#host.extent();
187
+ const { cellSize, minX, minZ } = this.#grid;
188
+ this.#passed = true;
189
+ this.#residencyPoint.set(x, this.#host.parts().placements.followY(), z);
190
+ try {
191
+ this.#host.parts().terrain?.follow({ x, z }, budget, terrainView);
192
+ this.#host.parts().terrain?.process(renderer, camera, undefined, terrainView);
193
+ } catch (error) {
194
+ if (!(error instanceof TerrainTileBudgetError)) throw error;
195
+ this.#pressure.bytes += 1;
196
+ }
197
+ const ahead = this.ahead(x, z);
198
+ this.#pass(
199
+ {
200
+ x: Math.floor((ahead.x - minX) / cellSize),
201
+ z: Math.floor((ahead.z - minZ) / cellSize),
202
+ },
203
+ ahead.x,
204
+ ahead.z,
205
+ );
206
+ }
207
+
208
+ /** Evict every resident cell, for a teardown that has already disposed the rest of the world. */
209
+ evictAll(): void {
210
+ for (const cell of [...this.#resident.values()]) this.evict(cell);
211
+ }
212
+
213
+ /**
214
+ * Does this update have to run the residency pass, or is the follow point still inside the half
215
+ * metre it last moved less than and the world holding still?
216
+ *
217
+ * "Still" is every kind of work the pass exists to hand on: a model load in flight or queued, a
218
+ * cell build in `#jobs` (which is also what queues refilters), a prewarm mint owed or in flight, a
219
+ * terrain admission or collider the admission budget refused, and a companion that has not been
220
+ * rebuilt since the follow point last moved. A world standing still on a loaded ring answers none
221
+ * of those, so the pass is skipped; the first update after anything changes is a full pass again.
222
+ */
223
+ stale(x: number, z: number): boolean {
224
+ if (!this.#passed) return true;
225
+ if (
226
+ Math.hypot(
227
+ x - this.#residencyPoint.x,
228
+ this.#host.parts().placements.followY() - this.#residencyPoint.y,
229
+ z - this.#residencyPoint.z,
230
+ ) >= SETTLED_FOLLOW_METRES
231
+ )
232
+ return true;
233
+ return (
234
+ this.#host.parts().models.loadsInFlight > 0 ||
235
+ this.#host.parts().models.loadsQueued > 0 ||
236
+ this.#jobs.length > 0 ||
237
+ this.#host.parts().placements.owed ||
238
+ this.#host.parts().prewarm.queued > 0 ||
239
+ this.#host.parts().prewarm.pending > 0 ||
240
+ this.#host.parts().render.shadowMoved === true ||
241
+ (this.#host.parts().terrain?.deferredAdmissions ?? 0) > 0
242
+ );
243
+ }
244
+
245
+ /**
246
+ * The LOD eye: the render camera's world position, or `follow` before a camera has reached
247
+ * `update` or under `lodFrom: "follow"`. Height counts only where `placementReach` makes the
248
+ * distances 3D, exactly as `#followY` does for the follow point. The camera's offset from
249
+ * `follow` counts only past the world's first gate: an orbit or chase camera inside it grades
250
+ * exactly as `follow` does, so turning in place swaps no level and pays no CPU rebuild, and a
251
+ * camera far off grades from a point at most that gate short of it. Continuous, so a camera
252
+ * resting near the gate does not flip the eye between the two.
253
+ */
254
+ updateEye(): void {
255
+ // The camera and the player are in world space; the placements the eye grades are in the root's
256
+ // own frame, so both points are read there before the pull below measures between them.
257
+ const root = this.#host.root();
258
+ const follow = localPoint(
259
+ this.#eyeFollow.set(
260
+ this.#host.follow().position.x,
261
+ this.#host.parts().placements.followY(),
262
+ this.#host.follow().position.z,
263
+ ),
264
+ root,
265
+ );
266
+ const camera = this.#host.lodFrom() === "camera" ? this.#host.parts().chunks.camera : undefined;
267
+ if (camera === undefined) {
268
+ this.#eye.copy(follow);
269
+ return;
270
+ }
271
+ localPoint(this.#eye.setFromMatrixPosition(camera.matrixWorld), root);
272
+ if (this.#host.parts().placements.placementReach === undefined) this.#eye.y = 0;
273
+ const inside = this.#host.parts().placements.firstGate;
274
+ const offset = this.#eye.distanceTo(follow);
275
+ this.#eye.lerp(follow, offset > inside ? inside / offset : 1);
276
+ }
277
+
278
+ /**
279
+ * Where the ring centres: the follow point led by its smoothed velocity. Samples closer than a
280
+ * few milliseconds are the same frame and move nothing; a jump longer than the ring is a teleport
281
+ * and resets the velocity rather than reading as speed.
282
+ */
283
+ ahead(x: number, z: number): { x: number; z: number } {
284
+ this.#grid ??= this.#host.extent();
285
+ const { cellSize } = this.#grid;
286
+ if (this.#host.prefetchSeconds() === 0) return { x, z };
287
+ const now = this.#host.now();
288
+ const last = this.#lastSample;
289
+ if (last === undefined) {
290
+ this.#lastSample = { t: now, x, z };
291
+ } else {
292
+ const seconds = (now - last.t) / 1000;
293
+ if (seconds >= 0.004) {
294
+ const dx = x - last.x;
295
+ const dz = z - last.z;
296
+ if (Math.hypot(dx, dz) > cellSize * this.#host.ring()) {
297
+ this.#velocityX = 0;
298
+ this.#velocityZ = 0;
299
+ } else {
300
+ // ~0.25 s smoothing, so one jittery frame does not swing the ring.
301
+ const blend = Math.min(1, seconds / 0.25);
302
+ this.#velocityX += (dx / seconds - this.#velocityX) * blend;
303
+ this.#velocityZ += (dz / seconds - this.#velocityZ) * blend;
304
+ }
305
+ this.#lastSample = { t: now, x, z };
306
+ }
307
+ }
308
+ let leadX = this.#velocityX * this.#host.prefetchSeconds();
309
+ let leadZ = this.#velocityZ * this.#host.prefetchSeconds();
310
+ const limit = cellSize * this.#host.ring() * 0.75;
311
+ const length = Math.hypot(leadX, leadZ);
312
+ if (length > limit) {
313
+ leadX *= limit / length;
314
+ leadZ *= limit / length;
315
+ }
316
+ return { x: x + leadX, z: z + leadZ };
317
+ }
318
+
319
+ #pass(followCell: { x: number; z: number }, x: number, z: number): void {
320
+ this.#grid ??= this.#host.extent();
321
+ const { cellSize, minX, minZ } = this.#grid;
322
+ const wanted: Array<{ cell: IWorldCell; distance: number }> = [];
323
+ for (const cell of this.#host.cells()) {
324
+ if (
325
+ Math.max(Math.abs(cell.x - followCell.x), Math.abs(cell.z - followCell.z)) >
326
+ this.#host.ring()
327
+ )
328
+ continue;
329
+ const centerX = minX + (cell.x + 0.5) * cellSize;
330
+ const centerZ = minZ + (cell.z + 0.5) * cellSize;
331
+ wanted.push({ cell, distance: Math.hypot(x - centerX, z - centerZ) });
332
+ }
333
+ wanted.sort((a, b) => a.distance - b.distance || a.cell.z - b.cell.z || a.cell.x - b.cell.x);
334
+
335
+ for (const resident of [...this.#resident.values()]) {
336
+ if (
337
+ Math.max(Math.abs(resident.x - followCell.x), Math.abs(resident.z - followCell.z)) >
338
+ this.#host.ring() + 1
339
+ )
340
+ this.evict(resident);
341
+ }
342
+ // A follow point that crossed more than one cell in one pass jumped (a teleport, a review
343
+ // camera). Only then does the hysteresis ring yield. Read off the follow point itself, not the
344
+ // lookahead `followCell`: that leads by up to 1.5 cells, so a walk that stopped and started moved
345
+ // it by two, and yielding there evicted and re-admitted a whole row each time.
346
+ const here = {
347
+ x: Math.floor((this.#host.follow().position.x - minX) / cellSize),
348
+ z: Math.floor((this.#host.follow().position.z - minZ) / cellSize),
349
+ };
350
+ const last = this.#residencyCell;
351
+ const jumped =
352
+ last !== undefined && Math.max(Math.abs(last.x - here.x), Math.abs(last.z - here.z)) > 1;
353
+ this.#residencyCell = here;
354
+
355
+ for (const candidate of wanted) {
356
+ const key = cellKey(candidate.cell.x, candidate.cell.z);
357
+ if (this.#resident.has(key)) continue;
358
+ const instances = candidate.cell.runs.reduce((total, run) => total + run.count, 0);
359
+ const rangeRoots =
360
+ this.#host.lodHysteresis() > 0 && !this.#host.parts().render.gpuOn ? instances : 0;
361
+ // One 16 B range record per root, which is what the batch allocates for them
362
+ // (`capacity * LOD_RANGE_STRIDE` in world-cell-batches.ts); the repack scratch that copies
363
+ // them is one shared pool, not a second record per cell.
364
+ const bytes = instances * PLACEMENT_RECORD_BYTES + rangeRoots * LOD_RANGE_RECORD_BYTES;
365
+ // After a jump, a cell the one-ring hysteresis above kept is not wanted, so it yields its share
366
+ // of the budgets to one that is. Without this the budgets stayed full of the ring the camera
367
+ // jumped from and the cells around it were refused until it moved again.
368
+ while (
369
+ jumped &&
370
+ (this.#resident.size >= this.#host.budgets().residentCells ||
371
+ this.#instances + this.#host.parts().impostor.farInstances + instances >
372
+ this.#host.budgets().instances ||
373
+ this.#bytes +
374
+ this.#host.parts().impostor.farBytes +
375
+ this.#host.parts().chunks.bytes +
376
+ bytes >
377
+ this.#host.budgets().bytes)
378
+ ) {
379
+ const spare = this.#farthestUnwanted(followCell);
380
+ if (spare === undefined) break;
381
+ this.evict(spare);
382
+ }
383
+ if (this.#resident.size >= this.#host.budgets().residentCells) {
384
+ this.#pressure.cells += 1;
385
+ continue;
386
+ }
387
+ // The retained far aggregates are physical allocations the renderer holds too, so they are
388
+ // charged against the same declared limits as the near ring: admitting a cell over the top of
389
+ // them would put the world past `budgets.instances`/`budgets.bytes` with the far half invisible
390
+ // to this check. See `#farBudgetRefuses`, the far half of the same total.
391
+ if (
392
+ this.#instances + this.#host.parts().impostor.farInstances + instances >
393
+ this.#host.budgets().instances
394
+ ) {
395
+ this.#pressure.instances += 1;
396
+ continue;
397
+ }
398
+ if (
399
+ this.#bytes +
400
+ this.#host.parts().impostor.farBytes +
401
+ this.#host.parts().chunks.bytes +
402
+ bytes >
403
+ this.#host.budgets().bytes
404
+ ) {
405
+ this.#pressure.bytes += 1;
406
+ continue;
407
+ }
408
+ this.#admit(candidate.cell, instances, bytes);
409
+ }
410
+ }
411
+
412
+ /** The resident cell farthest outside the wanted ring, or none when every resident is wanted. */
413
+ #farthestUnwanted(followCell: { x: number; z: number }): IResidentCell | undefined {
414
+ let farthest: IResidentCell | undefined;
415
+ let reach = this.#host.ring();
416
+ for (const resident of this.#resident.values()) {
417
+ const away = Math.max(
418
+ Math.abs(resident.x - followCell.x),
419
+ Math.abs(resident.z - followCell.z),
420
+ );
421
+ if (away > reach) {
422
+ reach = away;
423
+ farthest = resident;
424
+ }
425
+ }
426
+ return farthest;
427
+ }
428
+
429
+ #admit(cell: IWorldCell, instances: number, bytes: number): void {
430
+ const state: IResidentCell = {
431
+ mainChunkMeshes: [],
432
+ chunkInstances: new Map(),
433
+ completedRuns: new Set(),
434
+ chunksLoaded: (cell.chunks?.length ?? 0) === 0,
435
+ chunkFailed: false,
436
+ batches: [],
437
+ bytes,
438
+ cell,
439
+ chunks: [],
440
+ filterFar: Number.NEGATIVE_INFINITY,
441
+ filterNear: Number.POSITIVE_INFINITY,
442
+ generation: this.#generation++,
443
+ instances,
444
+ key: cellKey(cell.x, cell.z),
445
+ retainedModelPaths: [],
446
+ x: cell.x,
447
+ z: cell.z,
448
+ };
449
+ this.#resident.set(state.key, state);
450
+ this.#host.parts().render.cullResident(cell);
451
+ this.#residencyEpoch += 1;
452
+ this.#instances += instances;
453
+ this.#bytes += bytes;
454
+ for (const run of cell.runs) this.#host.parts().models.acquire(run, state);
455
+ if (cell.chunks !== undefined && cell.chunks.length > 0)
456
+ this.#host.parts().chunks.startChunkLoad(state);
457
+ }
458
+
459
+ /**
460
+ * Ask for one cell-asset run to be built, and do not build it yet.
461
+ *
462
+ * Admission is the only thing in this class that has no frame-time ceiling, so it is the only
463
+ * thing that became a queue: the cell keeps its residency slot from `#admit`, the work waits for
464
+ * a frame with budget in it, and a game that outruns the backlog sees it as `admission.backlog`
465
+ * rather than as a frozen frame. A run already queued is not queued twice, which is what stops a
466
+ * refilter — stale for as many frames as it waits — from stacking a second copy of itself.
467
+ *
468
+ * `replaced` is a refilter's outgoing batches, captured now and kept drawn until the replacement
469
+ * is attached, so a rebuild that waits three frames shows the old level for those three frames
470
+ * instead of a hole.
471
+ */
472
+ queueBuild(
473
+ asset: IAssetState,
474
+ cell: IResidentCell,
475
+ run: IWorldRun,
476
+ replace = false,
477
+ force = false,
478
+ ): void {
479
+ // Keyed on the run, not the asset: one cell can hold two runs of the same canonical asset —
480
+ // two names for one model — and each has its own records to build. A token per asset made the
481
+ // second run a no-op and dropped its placements on the floor.
482
+ if (this.#queued.has(run)) return;
483
+ // A cell that already draws this run is not built again, which is where an adopted asset's
484
+ // second acquire over a still-resident cell lands.
485
+ if (!replace && cell.batches.some((entry) => entry.asset === asset.id && entry.run === run))
486
+ return;
487
+ this.#queued.add(run);
488
+ this.#jobs.push({
489
+ asset,
490
+ batches: undefined,
491
+ boxes: undefined,
492
+ placed: undefined,
493
+ lodRanges: undefined,
494
+ cell,
495
+ force,
496
+ gpuByLevel: undefined,
497
+ filterY: this.#host.parts().placements.followY(),
498
+ filterX: this.#host.follow().position.x,
499
+ filterZ: this.#host.follow().position.z,
500
+ lodX: this.#eye.x,
501
+ lodY: this.#eye.y,
502
+ lodZ: this.#eye.z,
503
+ fresh: [],
504
+ replacement: replace,
505
+ next: 0,
506
+ published: 0,
507
+ records: undefined,
508
+ replaced: replace
509
+ ? cell.batches.filter((entry) => entry.asset === asset.id && entry.run === run)
510
+ : [],
511
+ roots: undefined,
512
+ run,
513
+ sources: undefined,
514
+ });
515
+ }
516
+
517
+ /**
518
+ * Spend the frame's budget on queued builds, one unit each, and stop when it is gone.
519
+ *
520
+ * The queue is served in admission order, which is nearest cell first, and a build is taken to
521
+ * completion before the next one starts: the units of one run are cheaper together than the
522
+ * per-frame bookkeeping of interleaving them, and the cell behind it is the same distance away.
523
+ * A build whose cell or asset has gone is dropped rather than resumed — there is nothing left to
524
+ * draw it into — and a frame that runs out of budget leaves the rest of the queue for the next.
525
+ */
526
+ drain(budget: IAdmissionBudget): void {
527
+ const index = 0;
528
+ while (index < this.#jobs.length) {
529
+ this.#frontNearest();
530
+ const job = this.#jobs[index] as IBuildJob;
531
+ if (this.#resident.get(job.cell.key) !== job.cell || job.asset.levels.length === 0) {
532
+ this.#forget(index, job);
533
+ continue;
534
+ }
535
+ let finished = false;
536
+ if (
537
+ !budget.admit(() => {
538
+ finished = this.#step(job);
539
+ })
540
+ )
541
+ break;
542
+ // Out of fresh meshes this frame: later jobs would only stall the same way.
543
+ if (this.#host.parts().render.meshStalled) break;
544
+ // A finished build leaves the queue at this index, so the next one is served without a skip.
545
+ if (finished) {
546
+ for (const entry of job.fresh)
547
+ if (entry.batch.count > 0 && entry.shadowBounds !== undefined)
548
+ this.#host.published(entry.shadowBounds);
549
+ job.cell.completedRuns.add(job.run);
550
+ this.#forget(index, job);
551
+ // A camera that moved during this bounded build may already have consumed the global
552
+ // refilter step before these batches existed. Owe one pass after publication, even if
553
+ // it now stands still, so the coherent old snapshot can converge to the latest pose.
554
+ if (
555
+ Math.hypot(
556
+ this.#host.follow().position.x - job.filterX,
557
+ this.#host.parts().placements.followY() - job.filterY,
558
+ this.#host.follow().position.z - job.filterZ,
559
+ ) >= this.#host.parts().placements.stepMetres()
560
+ )
561
+ this.#host.parts().placements.owe();
562
+ }
563
+ }
564
+ }
565
+
566
+ /**
567
+ * Put the unstarted build nearest the follow point at the front, unless a build is mid-way.
568
+ * Each model's load queues every resident cell at once, so append order is load order: the
569
+ * spawn cell of the last model to load waited behind the whole ring.
570
+ */
571
+ #frontNearest(): void {
572
+ this.#grid ??= this.#host.extent();
573
+ const { cellSize, minX, minZ } = this.#grid;
574
+ const front = this.#jobs[0];
575
+ if (front === undefined || front.next > 0 || front.batches !== undefined) return;
576
+ const { x, z } = this.#host.follow().position;
577
+ let nearest = 0;
578
+ let best = Number.POSITIVE_INFINITY;
579
+ for (let i = 0; i < this.#jobs.length; i++) {
580
+ const job = this.#jobs[i] as IBuildJob;
581
+ if (job.next > 0 || job.batches !== undefined) continue;
582
+ const d = Math.hypot(
583
+ minX + (job.cell.x + 0.5) * cellSize - x,
584
+ minZ + (job.cell.z + 0.5) * cellSize - z,
585
+ );
586
+ if (d < best) {
587
+ best = d;
588
+ nearest = i;
589
+ }
590
+ }
591
+ if (nearest > 0) this.#jobs.unshift(...this.#jobs.splice(nearest, 1));
592
+ }
593
+
594
+ #forget(index: number, job: IBuildJob): void {
595
+ this.#jobs.splice(index, 1);
596
+ this.#queued.delete(job.run);
597
+ }
598
+
599
+ /** Placement slices and meshes left to publish, plus the terrain's outstanding admission. */
600
+ backlog(): number {
601
+ let units = this.#host.parts().terrain?.deferredAdmissions ?? 0;
602
+ for (const job of this.#jobs) {
603
+ const meshes = job.batches === undefined ? 0 : publishCount(job.batches);
604
+ units +=
605
+ Math.ceil(Math.max(0, job.run.count - job.next) / ADMISSION_SLICE_PLACEMENTS) +
606
+ Math.max(0, meshes - job.published);
607
+ }
608
+ return units;
609
+ }
610
+
611
+ /**
612
+ * One unit of one build: a slice of placements, or one mesh built, or the swap that attaches the
613
+ * finished batch and retires what a refilter replaced. `true` means the job is done.
614
+ */
615
+ #step(job: IBuildJob): boolean {
616
+ // A queued run may wait behind admission or fresh-mesh work while the camera moves.
617
+ // Take its filter snapshot when the first placement slice actually starts, then keep
618
+ // that snapshot for every slice so one publication never mixes different camera poses.
619
+ if (job.next === 0 && job.batches === undefined) {
620
+ job.filterX = this.#host.follow().position.x;
621
+ job.filterY = this.#host.parts().placements.followY();
622
+ job.filterZ = this.#host.follow().position.z;
623
+ job.lodX = this.#eye.x;
624
+ job.lodY = this.#eye.y;
625
+ job.lodZ = this.#eye.z;
626
+ }
627
+ if (job.next < job.run.count) {
628
+ job.batches ??= newBatches(job.asset);
629
+ if (this.#host.lodHysteresis() > 0 && job.asset.distances.length > 1)
630
+ job.lodRanges ??= job.batches.map((levels) => levels.map(() => []));
631
+ // One box per `(level, part)` beside the batches it measures, so the swap that hands the
632
+ // records to the renderer can name where they are; see `#addPlacements`.
633
+ job.boxes ??= newBoxes(job.batches);
634
+ const end = Math.min(job.next + ADMISSION_SLICE_PLACEMENTS, job.run.count);
635
+ this.#host.parts().placements.addPlacements(job, job.next, end);
636
+ job.next = end;
637
+ this.#admissionCompletedUnits += 1;
638
+ return false;
639
+ }
640
+ const batches = job.batches;
641
+ // A run with nothing placed in it publishes nothing, exactly as an unbounded build would.
642
+ if (batches === undefined) return true;
643
+ if (job.published < publishCount(batches)) {
644
+ const published = job.published;
645
+ this.#host.parts().placements.buildOne(job, batches);
646
+ if (job.published > published) this.#admissionCompletedUnits += 1;
647
+ return false;
648
+ }
649
+ const swapped = this.#host.parts().render.swap(job);
650
+ if (swapped) this.#admissionCompletedUnits += 1;
651
+ return swapped;
652
+ }
653
+
654
+ /**
655
+ * Rebuild every resident run once, so a scene that came up after the ring was built is given the
656
+ * source records it was built without.
657
+ *
658
+ * `WorldCells.update` can be called before it has a renderer, and a renderer that is not WebGPU
659
+ * never turns the scene on at all; either way the cells that were swapped in while it was off hold
660
+ * placements the dispatches have never heard of, and nothing else in the class would ever hand them
661
+ * over. One rebuild of the ring is the whole fix, and it is the same build every first-seen asset
662
+ * takes: `replace` keeps the old batches drawn until each new one is attached, so the rebuild is
663
+ * not a frame of holes.
664
+ */
665
+ seedGpuSources(): void {
666
+ // A pending build may already have consumed CPU-only slices. Restart it before any swap can
667
+ // publish a partial source list; its outgoing batches keep drawing until the new build lands.
668
+ const pending = this.#jobs;
669
+ this.#jobs = [];
670
+ for (const job of pending) {
671
+ this.#queued.delete(job.run);
672
+ for (const entry of job.fresh) this.#host.parts().render.clearSegment(entry);
673
+ this.queueBuild(job.asset, job.cell, job.run, true, job.force);
674
+ }
675
+ for (const cell of this.#resident.values())
676
+ for (const batch of cell.batches) {
677
+ const asset = this.#host.parts().models.asset(batch.asset);
678
+ if (asset === undefined || asset.levels.length === 0) continue;
679
+ // One rebuild per run, not per batch: a run's placements are one build, and queueing it per
680
+ // batch would rebuild the same placements once per level and part.
681
+ this.queueBuild(asset, cell, batch.run, true);
682
+ }
683
+ }
684
+
685
+ cellLive(cell: IResidentCell, generation: number): boolean {
686
+ return (
687
+ !this.#host.released() &&
688
+ this.#resident.get(cell.key) === cell &&
689
+ cell.generation === generation
690
+ );
691
+ }
692
+
693
+ evict(cell: IResidentCell): void {
694
+ this.#host.parts().chunks.evictProxy(cell);
695
+ this.#residencyEpoch += 1;
696
+ // Every run this cell held goes back to the far mesh BEFORE the near batches below are cleared:
697
+ // the far mesh owns the ORIGINAL roots and this is the same synchronous block, so no frame draws
698
+ // the cell twice or not at all. Skipped at teardown, where the far aggregates are drained whole.
699
+ if (!this.#host.released())
700
+ for (const run of cell.cell.runs) this.#host.parts().impostor.restoreFar(run);
701
+ // Work queued for a cell that has left is dropped, not resumed: a later frame would build
702
+ // batches into a graph that no longer holds the cell, and the residency slot is already gone.
703
+ this.#jobs = this.#jobs.filter((job) => {
704
+ if (job.cell !== cell) return true;
705
+ this.#queued.delete(job.run);
706
+ // A swap that ran out of fresh meshes leaves its claims in `fresh`, which is not in
707
+ // `cell.batches` until the swap completes. Dropping the job without handing those blocks back
708
+ // keeps them reserved and unwritten, so `mesh.count` never falls to zero, the asset's release
709
+ // retires a batch that still counts records and drops the key outright, and the walk back
710
+ // mints a second mesh for it.
711
+ for (const entry of job.fresh) this.#host.parts().render.clearSegment(entry);
712
+ return false;
713
+ });
714
+ for (const entry of cell.batches) this.#host.parts().render.clearSegment(entry);
715
+ // The same invalidation `#swap` makes, for the eviction path: the records that just left the
716
+ // ring are ground the levels were drawing, and they are named one batch at a time.
717
+ // Each placement's own box when the cell kept the list, so an evicted neighbour does not redraw
718
+ // the finest level under the player; the batch union otherwise.
719
+ if (cell.placed !== undefined && cell.placed.size > 0)
720
+ for (const placed of cell.placed.values())
721
+ this.#host.parts().render.tellPlacementChanges(placed, []);
722
+ else
723
+ this.#host
724
+ .parts()
725
+ .render.shadowRecordsMoved(this.#host.parts().render.changedBounds(cell.batches));
726
+ cell.batches.length = 0;
727
+ cell.placed?.clear();
728
+ // The cell's record of those chunks goes with them, so a replay can never draw a cell the world
729
+ // has released — before they leave the group, which is where it counts what it holds. See
730
+ // `#addChunk`.
731
+ this.#host.parts().render.dropChunkBundles(cell);
732
+ for (const chunk of cell.chunks) {
733
+ chunk.removeFromParent();
734
+ this.#host.addFailures(this.#host.parts().models.disposeLoaded(chunk));
735
+ }
736
+ cell.chunks.length = 0;
737
+ // The cell's chunk sources go back to the loader here, on the last cell that named them, exactly
738
+ // as an asset's levels do in `#release`. Run even at teardown: the loader is never cleared, so a
739
+ // path this world asked for must be handed back however the world leaves.
740
+ this.#host.parts().models.releaseModelPaths(cell.retainedModelPaths);
741
+ this.#resident.delete(cell.key);
742
+ this.#host.parts().render.cullEvicted(cell);
743
+ this.#instances -= cell.instances;
744
+ this.#bytes -= cell.bytes;
745
+ this.#evictions += 1;
746
+ // Room just freed: retry the far aggregates a full budget refused, so a species held back while
747
+ // the ring was tight appears without another scan. Skipped at teardown, where the far half drains.
748
+ if (!this.#host.released()) this.#host.parts().impostor.retryFar();
749
+ // One per run, so the canonical's refcount reaches zero exactly when the last run naming any
750
+ // member of its group has left the ring.
751
+ for (const run of cell.cell.runs)
752
+ this.#host.parts().models.release(this.#host.canonical(run.asset));
753
+ }
754
+ }