@threenative/core 0.3.11 → 0.3.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (157) 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 +10566 -22552
  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-pass-budget.ts +34 -7
  84. package/src/renderProjection.ts +22 -0
  85. package/src/renderer.ts +92 -37
  86. package/src/snow-field.ts +1 -1
  87. package/src/spells/cast-pool.ts +361 -0
  88. package/src/spells/index.ts +177 -0
  89. package/src/spells/mechanisms.ts +295 -0
  90. package/src/spells/reaction-field.ts +415 -0
  91. package/src/spells/spell-lights.ts +139 -0
  92. package/src/spells/spell-world.ts +187 -0
  93. package/src/spells/spell.ts +397 -0
  94. package/src/spells/spells.ts +283 -0
  95. package/src/spells/ultra/engine/camera.ts +184 -0
  96. package/src/spells/ultra/engine/quality.ts +96 -0
  97. package/src/spells/ultra/index.ts +52 -0
  98. package/src/spells/ultra/main.ts +305 -0
  99. package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
  100. package/src/spells/ultra/spells/cast.ts +233 -0
  101. package/src/spells/ultra/spells/fire.ts +1267 -0
  102. package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
  103. package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
  104. package/src/spells/ultra/vfx/FxTarget.ts +61 -0
  105. package/src/spells/ultra/vfx/GroundField.ts +1399 -0
  106. package/src/spells/ultra/vfx/Particles.ts +1475 -0
  107. package/src/spells/ultra/vfx/Ribbons.ts +645 -0
  108. package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
  109. package/src/spells/ultra/vfx/Volumes.ts +489 -0
  110. package/src/spells/ultra/vfx/common.ts +1195 -0
  111. package/src/spells/ultra/vfx/noise.ts +441 -0
  112. package/src/startup-readiness.ts +128 -34
  113. package/src/version.ts +1 -1
  114. package/src/warmup.ts +56 -8
  115. package/src/water-surface.ts +9 -3
  116. package/src/world-bundle-safety.ts +401 -0
  117. package/src/world-cell-batches.ts +1216 -0
  118. package/src/world-cell-chunks.ts +1132 -0
  119. package/src/world-cell-data.ts +995 -0
  120. package/src/world-cell-impostors.ts +1449 -0
  121. package/src/world-cell-lod-bias.ts +151 -0
  122. package/src/world-cell-models.ts +1074 -0
  123. package/src/world-cell-options.ts +189 -0
  124. package/src/world-cell-placements.ts +694 -0
  125. package/src/world-cell-prewarm.ts +557 -0
  126. package/src/world-cell-readiness.ts +357 -0
  127. package/src/world-cell-render-bundles.ts +459 -0
  128. package/src/world-cell-render-gpu-dress.ts +714 -0
  129. package/src/world-cell-render-main-cull.ts +484 -0
  130. package/src/world-cell-render-shadow-claims.ts +198 -0
  131. package/src/world-cell-render-util.ts +246 -0
  132. package/src/world-cell-render.ts +1493 -0
  133. package/src/world-cell-residency.ts +745 -0
  134. package/src/world-cells.ts +1318 -10418
  135. package/src/world-chunk-shadow.ts +308 -0
  136. package/src/world-collar.ts +315 -0
  137. package/src/world-gpu-flags.ts +163 -0
  138. package/src/world-gpu-readback.ts +881 -0
  139. package/src/world-gpu-reference.ts +510 -0
  140. package/src/world-gpu-scene.ts +214 -2264
  141. package/src/world-gpu-shadow.ts +190 -0
  142. package/src/world-gpu-types.ts +381 -0
  143. package/src/world-gpu-validation.ts +518 -0
  144. package/src/world-heightfield.ts +802 -0
  145. package/src/world-load-limiter.ts +106 -0
  146. package/src/world-noise.ts +241 -0
  147. package/src/world-package.ts +42 -0
  148. package/src/world-region.ts +1 -1
  149. package/src/world-terrain-splat.ts +365 -149
  150. package/src/world-tile-budget.ts +256 -0
  151. package/src/world-tile-geometry.ts +469 -0
  152. package/src/world-tile-lod.ts +408 -0
  153. package/src/world-tile-observation.ts +566 -0
  154. package/src/world-tile-stitch.ts +166 -0
  155. package/src/world-tiles.ts +170 -1745
  156. package/src/world-water-bodies.ts +359 -0
  157. package/src/world.ts +35 -741
@@ -0,0 +1,357 @@
1
+ import { Box3, type Camera, Frustum, Matrix4, type Object3D, Quaternion, Vector3 } from "three";
2
+ import type { IRendererLike } from "./renderer.js";
3
+ import {
4
+ type IResidentCell,
5
+ type ISpawnWaiter,
6
+ type IWorldRegionReadiness,
7
+ cellKey,
8
+ } from "./world-cell-data.js";
9
+ import { PLACEMENT_RECORD_FLOATS, cullDistance } from "./world-cell-impostors.js";
10
+ import type { IAssetState } from "./world-cell-models.js";
11
+ import type { CellPrewarm } from "./world-cell-prewarm.js";
12
+ import { type IWorldAsset, type IWorldCell, cellPlacements } from "./world-package.js";
13
+ import type { TerrainTiles } from "./world-tiles.js";
14
+
15
+ const _readinessPosition = new Vector3();
16
+
17
+ /**
18
+ * What the spawn and view gates ask their world for. Every member is a read; the two gates settle
19
+ * themselves, and `update` and `dispose` only tell them when to look.
20
+ */
21
+ export interface ICellReadinessHost {
22
+ released(): boolean;
23
+ cells(): readonly IWorldCell[];
24
+ /** The world grid's origin and cell side. */
25
+ extent(): { readonly cellSize: number; readonly minX: number; readonly minZ: number };
26
+ extentBounds(): Box3;
27
+ placements(): ArrayBuffer;
28
+ placementReach(): Float32Array | undefined;
29
+ canonical(id: string): string;
30
+ /** The loaded asset state, which is where a failed model is counted. */
31
+ asset(id: string): IAssetState | undefined;
32
+ /** The package's own asset definition, which carries the authored bounds. */
33
+ manifestAsset(id: string): IWorldAsset | undefined;
34
+ terrain(): TerrainTiles | undefined;
35
+ terrainHeights(): readonly [number, number];
36
+ loaded(cell: IResidentCell): boolean;
37
+ resident(key: string): IResidentCell | undefined;
38
+ /** Whether a build for this cell is still queued, so its content is not finished. */
39
+ buildQueued(cell: IResidentCell): boolean;
40
+ gpuOn(): boolean;
41
+ shadowMoved(): boolean;
42
+ refilterOwed(): boolean;
43
+ prewarm(): CellPrewarm;
44
+ renderer(): IRendererLike | undefined;
45
+ root(): Object3D;
46
+ }
47
+
48
+ /**
49
+ * The two readiness questions a streamed world answers, and the spawn gate built on them.
50
+ *
51
+ * `readinessAt` is the one authority for "the spawn's data is loaded"; `terrainReadinessInView` is
52
+ * the same question for terrain alone, which is what a camera-based gate reads. The spawn waiters
53
+ * are one set observed by the update that already walks residency, so a world nobody waits on scans
54
+ * nothing.
55
+ *
56
+ * The view cache is keyed on the camera's projection, transform, focus point and the GPU scene's own
57
+ * switch, and on `placementReach`'s contents: package placements and bounds are immutable, so a
58
+ * camera that has not moved asks the same cells the same question.
59
+ */
60
+ export class CellReadiness {
61
+ readonly #host: ICellReadinessHost;
62
+ readonly #visible = new Map<IWorldCell, boolean>();
63
+ #view: number[] = [];
64
+ #reach: Float32Array | undefined;
65
+ readonly #frustum = new Frustum();
66
+ readonly #projection = new Matrix4();
67
+ /** Games waiting on `whenSpawnReady`, settled by the update that follows admissions or by dispose. */
68
+ readonly #waiters = new Set<ISpawnWaiter>();
69
+ /** Borrowed scratch for one position: consume it before the next query. */
70
+ readonly #cameraPosition = _readinessPosition;
71
+ readonly #position = new Vector3();
72
+ readonly #rotation = new Quaternion();
73
+ readonly #scale = new Vector3();
74
+ readonly #matrix = new Matrix4();
75
+ readonly #recordBounds = new Box3();
76
+ /** The world grid, read once: a package's origin and cell side do not change for a world's life. */
77
+ #grid: { readonly cellSize: number; readonly minX: number; readonly minZ: number } | undefined;
78
+ /** The authored bounds' centre, placed: the source sphere's centre. See `#cellInView`. */
79
+ readonly #sourceCentre = new Vector3();
80
+
81
+ constructor(host: ICellReadinessHost) {
82
+ this.#host = host;
83
+ }
84
+
85
+ /** Borrowed scratch box: consume its transformed volume before the next bounds query. */
86
+ #boundsAt(bounds: IWorldAsset["bounds"], matrix: Matrix4): Box3 {
87
+ this.#recordBounds.min.fromArray(bounds.min);
88
+ this.#recordBounds.max.fromArray(bounds.max);
89
+ return this.#recordBounds.applyMatrix4(matrix);
90
+ }
91
+
92
+ /** Completed content intersecting a square around a fixed spawn, in world metres. */
93
+ at(
94
+ position: Camera | { readonly x: number; readonly z: number },
95
+ radius = 0,
96
+ ): IWorldRegionReadiness {
97
+ this.#grid ??= this.#host.extent();
98
+ const { cellSize, minX, minZ } = this.#grid;
99
+ const camera = "isCamera" in position && position.isCamera ? position : undefined;
100
+ if (camera !== undefined) {
101
+ camera.updateMatrixWorld(true);
102
+ if (
103
+ ![...camera.projectionMatrix.elements, ...camera.matrixWorldInverse.elements].every(
104
+ Number.isFinite,
105
+ )
106
+ )
107
+ throw new Error("WorldCells readiness requires a finite camera projection and transform.");
108
+ this.#frustum.setFromProjectionMatrix(
109
+ this.#projection.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse),
110
+ camera.coordinateSystem,
111
+ );
112
+ }
113
+ const point = camera
114
+ ? camera.getWorldPosition(this.#cameraPosition)
115
+ : (position as { readonly x: number; readonly z: number });
116
+ if (
117
+ !Number.isFinite(point.x) ||
118
+ !Number.isFinite(point.z) ||
119
+ !Number.isFinite(radius) ||
120
+ radius < 0
121
+ )
122
+ throw new Error("WorldCells readiness requires finite coordinates and a nonnegative radius.");
123
+ if (camera !== undefined) {
124
+ const reach = this.#host.placementReach();
125
+ const view = [
126
+ ...camera.projectionMatrix.elements,
127
+ ...camera.matrixWorldInverse.elements,
128
+ point.x,
129
+ (point as Vector3).y,
130
+ point.z,
131
+ camera.coordinateSystem,
132
+ Number(this.#host.gpuOn()),
133
+ ];
134
+ // Package placements/bounds are immutable; reach is compared too so edits cannot go stale.
135
+ if (
136
+ !view.every((value, index) => value === this.#view[index]) ||
137
+ reach?.some((value, index) => value !== this.#reach?.[index])
138
+ ) {
139
+ this.#visible.clear();
140
+ this.#view = view;
141
+ if (reach !== undefined) {
142
+ this.#reach ??= new Float32Array(reach.length);
143
+ this.#reach.set(reach);
144
+ }
145
+ }
146
+ }
147
+ const lowX = Math.floor((point.x - radius - minX) / cellSize);
148
+ const highX = Math.floor((point.x + radius - minX) / cellSize);
149
+ const lowZ = Math.floor((point.z - radius - minZ) / cellSize);
150
+ const highZ = Math.floor((point.z + radius - minZ) / cellSize);
151
+ let requiredCells = 0;
152
+ let loadedCells = 0;
153
+ let failures = 0;
154
+ let requiredTerrainTiles = 0;
155
+ let loadedTerrainTiles = 0;
156
+ for (const cell of this.#host.cells()) {
157
+ if (camera === undefined) {
158
+ if (cell.x < lowX || cell.x > highX || cell.z < lowZ || cell.z > highZ) continue;
159
+ } else if (!this.#cellInView(cell, point as Vector3)) continue;
160
+ requiredCells++;
161
+ const resident = this.#host.resident(cellKey(cell.x, cell.z));
162
+ if (
163
+ resident &&
164
+ this.#host.loaded(resident) &&
165
+ (camera === undefined || !this.#host.buildQueued(resident))
166
+ )
167
+ loadedCells++;
168
+ if (resident?.chunkFailed) failures++;
169
+ for (const run of cell.runs)
170
+ if (this.#host.asset(this.#host.canonical(run.asset))?.failed) failures++;
171
+ }
172
+ if (camera !== undefined) {
173
+ const terrain = this.#host
174
+ .terrain()
175
+ ?.readinessInView(camera, this.#host.terrainHeights()) ?? {
176
+ required: 0,
177
+ loaded: 0,
178
+ };
179
+ requiredTerrainTiles = terrain.required;
180
+ loadedTerrainTiles = terrain.loaded;
181
+ } else {
182
+ const terrain = this.#host.terrain()?.readinessAt(point, radius) ?? {
183
+ required: 0,
184
+ loaded: 0,
185
+ };
186
+ requiredTerrainTiles = terrain.required;
187
+ loadedTerrainTiles = terrain.loaded;
188
+ }
189
+ return {
190
+ requiredCells,
191
+ loadedCells,
192
+ requiredTerrainTiles,
193
+ loadedTerrainTiles,
194
+ failures,
195
+ cancelled: this.#host.released(),
196
+ ready:
197
+ !this.#host.released() &&
198
+ failures === 0 &&
199
+ loadedCells === requiredCells &&
200
+ loadedTerrainTiles === requiredTerrainTiles &&
201
+ (camera === undefined || (!this.#host.shadowMoved() && !this.#host.refilterOwed())),
202
+ };
203
+ }
204
+ /** Use the same authored placement bounds and distance test as admission, even before residency. */
205
+ #cellInView(cell: IWorldCell, eye: Vector3): boolean {
206
+ const cached = this.#visible.get(cell);
207
+ if (cached !== undefined) return cached;
208
+ this.#visible.set(cell, false);
209
+ if (this.#host.terrain() !== undefined || (cell.chunks?.length ?? 0) > 0) {
210
+ this.#grid ??= this.#host.extent();
211
+ const { cellSize, minX, minZ } = this.#grid;
212
+ const box = this.#recordBounds;
213
+ box.min.set(
214
+ minX + cell.x * cellSize,
215
+ this.#host.extentBounds().min.y,
216
+ minZ + cell.z * cellSize,
217
+ );
218
+ box.max.set(
219
+ minX + (cell.x + 1) * cellSize,
220
+ this.#host.extentBounds().max.y,
221
+ minZ + (cell.z + 1) * cellSize,
222
+ );
223
+ if (this.#frustum.intersectsBox(box)) {
224
+ this.#visible.set(cell, true);
225
+ return true;
226
+ }
227
+ }
228
+ for (const run of cell.runs) {
229
+ const asset = this.#host.manifestAsset(this.#host.canonical(run.asset));
230
+ if (asset === undefined) continue;
231
+ const records = cellPlacements(this.#host.placements(), run);
232
+ for (let index = 0; index < run.count; index++) {
233
+ const at = index * PLACEMENT_RECORD_FLOATS;
234
+ this.#position.fromArray(records, at);
235
+ const distance =
236
+ this.#host.placementReach() === undefined
237
+ ? Math.hypot(this.#position.x - eye.x, this.#position.z - eye.z)
238
+ : this.#position.distanceTo(eye);
239
+ const reach = this.#host.placementReach()?.[run.offset + index];
240
+ if (reach !== undefined && distance > reach) continue;
241
+ this.#rotation.fromArray(records, at + 3);
242
+ this.#scale.setScalar(records[at + 7] as number);
243
+ this.#matrix.compose(this.#position, this.#rotation, this.#scale);
244
+ const box = this.#boundsAt(asset.bounds, this.#matrix);
245
+ const inner = cullDistance(asset.maxDistance);
246
+ const centre = box.getCenter(this.#sourceCentre);
247
+ const drawDistance = this.#host.gpuOn()
248
+ ? Math.hypot(centre.x - eye.x, centre.z - eye.z)
249
+ : distance;
250
+ if (inner !== undefined && drawDistance > inner) continue;
251
+ if (this.#frustum.intersectsBox(box)) {
252
+ this.#visible.set(cell, true);
253
+ return true;
254
+ }
255
+ }
256
+ }
257
+ return false;
258
+ }
259
+
260
+ /** Terrain data needed by the current camera, including visible tiles not yet admitted. */
261
+ terrainReadinessInView(camera: Camera): { required: number; loaded: number } {
262
+ return (
263
+ this.#host.terrain()?.readinessInView(camera, this.#host.terrainHeights()) ?? {
264
+ required: 0,
265
+ loaded: 0,
266
+ }
267
+ );
268
+ }
269
+
270
+ /** Visible CPU scatter batches still awaiting a nonempty main-camera backend submission. */
271
+ pendingCpuDrawsInView(camera: Camera): number {
272
+ return this.#host
273
+ .prewarm()
274
+ .pendingCpuDrawsInView(this.#host.root(), camera, this.#host.renderer());
275
+ }
276
+
277
+ /**
278
+ * Resolves when the content a fixed spawn needs has finished loading.
279
+ *
280
+ * The one-shot gate a streamed game waits on before it releases its loading screen. Readiness is
281
+ * `readinessAt` and nothing else, so there is one authority for "the spawn's data is loaded": every
282
+ * required cell and terrain tile in `radius` loaded with no failure. The position is snapshotted
283
+ * here, so a caller may keep mutating the object it passed; `update` observes the held waiters
284
+ * right after the frame's admissions, so a region an update admits settles its waiter in it.
285
+ *
286
+ * Fail closed: malformed coordinates, a negative radius or an unsupported timer deadline reject
287
+ * before a waiter is armed. A failed asset and a torn-down world reject with their own named
288
+ * error, and the deadline rejects with the budget it named. Every settlement removes the waiter
289
+ * and clears its timer, so a settled waiter holds neither the deadline nor the world, and a
290
+ * region evicted after its waiter resolved changes nothing.
291
+ */
292
+ whenSpawnReady(
293
+ position: { readonly x: number; readonly z: number },
294
+ radius = 0,
295
+ timeoutMs = 120_000,
296
+ ): Promise<IWorldRegionReadiness> {
297
+ if (
298
+ !Number.isFinite(position.x) ||
299
+ !Number.isFinite(position.z) ||
300
+ !Number.isFinite(radius) ||
301
+ radius < 0
302
+ )
303
+ return Promise.reject(
304
+ new Error(
305
+ "WorldCells spawn readiness requires finite coordinates and a nonnegative radius.",
306
+ ),
307
+ );
308
+ if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2 ** 31 - 1)
309
+ return Promise.reject(
310
+ new Error("WorldCells spawn readiness requires a timeout in (0, 2147483647] ms."),
311
+ );
312
+ if (this.#host.released()) return Promise.reject(new Error("WorldCells disposed"));
313
+ const snapshot = { x: position.x, z: position.z };
314
+ const immediate = this.at(snapshot, radius);
315
+ if (immediate.failures > 0)
316
+ return Promise.reject(new Error("WorldCells spawn assets failed to load"));
317
+ if (immediate.ready) return Promise.resolve(immediate);
318
+ return new Promise<IWorldRegionReadiness>((resolve, reject) => {
319
+ const waiter: ISpawnWaiter = {
320
+ position: snapshot,
321
+ radius,
322
+ resolve,
323
+ reject,
324
+ timer: setTimeout(() => {
325
+ this.#waiters.delete(waiter);
326
+ reject(new Error(`WorldCells spawn exceeded ${String(timeoutMs)} ms`));
327
+ }, timeoutMs),
328
+ };
329
+ this.#waiters.add(waiter);
330
+ });
331
+ }
332
+
333
+ /** Settle the waiters this frame's admissions can answer; a non-Disposed, non-Failed region waits. */
334
+ settleWaiters(): void {
335
+ if (this.#waiters.size === 0) return;
336
+ for (const waiter of this.#waiters) {
337
+ const readiness = this.at(waiter.position, waiter.radius);
338
+ if (readiness.failures > 0) {
339
+ this.#waiters.delete(waiter);
340
+ clearTimeout(waiter.timer);
341
+ waiter.reject(new Error("WorldCells spawn assets failed to load"));
342
+ } else if (readiness.ready) {
343
+ this.#waiters.delete(waiter);
344
+ clearTimeout(waiter.timer);
345
+ waiter.resolve(readiness);
346
+ }
347
+ }
348
+ }
349
+ /** Reject every waiter a teardown found: a world torn down mid-wait answers its games. */
350
+ cancelWaiters(): void {
351
+ for (const waiter of this.#waiters) {
352
+ clearTimeout(waiter.timer);
353
+ waiter.reject(new Error("WorldCells spawn cancelled"));
354
+ }
355
+ this.#waiters.clear();
356
+ }
357
+ }