@threenative/core 0.3.13 → 0.3.16

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 (60) hide show
  1. package/capabilities.json +1008 -83
  2. package/dist/{chunk-4SRAQFTU.js → chunk-2GPHICV6.js} +1 -1
  3. package/dist/{chunk-EEABDLUC.js → chunk-5C4TCWI3.js} +2 -2
  4. package/dist/{chunk-DIPIJICH.js → chunk-FQURMC2F.js} +122 -18
  5. package/dist/{chunk-EFWZWLPY.js → chunk-OMGIYWW7.js} +400 -13
  6. package/dist/{chunk-SV4QVUTQ.js → chunk-QAQHYOWY.js} +1 -1
  7. package/dist/{chunk-GYUZJQ7U.js → chunk-VQRPEOKY.js} +4 -1
  8. package/dist/hot.js +10 -2
  9. package/dist/index.d.ts +608 -16
  10. package/dist/index.js +2037 -633
  11. package/dist/{model-lod-DPTzeCcD.d.ts → model-lod-B921F6kQ.d.ts} +0 -10
  12. package/dist/playtest.js +3 -3
  13. package/dist/{quality-BYqKGAwo.d.ts → quality-BADStsTn.d.ts} +2 -2
  14. package/dist/render-environment.d.ts +1 -1
  15. package/dist/ui-layer.js +2 -2
  16. package/dist/worker.js +2 -2
  17. package/dist/world.d.ts +14 -4
  18. package/dist/world.js +179 -36
  19. package/mcp/animation-server.mjs +1 -1
  20. package/mcp/engine-server.mjs +44 -17
  21. package/mcp/servers.mjs +4 -4
  22. package/package.json +6 -6
  23. package/patches/three@0.187.0-prd269-upgrade.patch +126 -2
  24. package/patches/three@0.187.0.patch +108 -21
  25. package/scripts/ensure-mcp.mjs +6 -1
  26. package/src/clustered-batch.ts +146 -3
  27. package/src/clustered-mesh.ts +548 -20
  28. package/src/debug.ts +16 -0
  29. package/src/displaced-surface.ts +428 -0
  30. package/src/engine-hooks.ts +29 -0
  31. package/src/frame-budget.ts +16 -0
  32. package/src/generated/console-markers.ts +1 -0
  33. package/src/grass-field.ts +628 -0
  34. package/src/grounding.ts +19 -10
  35. package/src/hot.ts +18 -2
  36. package/src/index.ts +112 -0
  37. package/src/instanced-batch-lod.ts +54 -0
  38. package/src/model-lod.ts +77 -1
  39. package/src/pose-measure.ts +27 -2
  40. package/src/render/material-key.ts +21 -1
  41. package/src/render/screen-probe-gather.ts +303 -0
  42. package/src/render/short-range-ao.ts +274 -0
  43. package/src/render/world-impostor-surface.ts +98 -3
  44. package/src/render-camera-cull.ts +9 -3
  45. package/src/renderer.ts +26 -4
  46. package/src/scatter-field.ts +497 -0
  47. package/src/startup-offscreen-bytes.ts +11 -5
  48. package/src/state.ts +16 -3
  49. package/src/static-transform.ts +109 -6
  50. package/src/tile-ring.ts +294 -0
  51. package/src/version.ts +1 -1
  52. package/src/warmup.ts +15 -2
  53. package/src/world-cell-batches.ts +4 -0
  54. package/src/world-cell-data.ts +7 -0
  55. package/src/world-cell-models.ts +36 -8
  56. package/src/world-cell-render-gpu-dress.ts +4 -2
  57. package/src/world-cell-render-util.ts +2 -2
  58. package/src/world-cells.ts +1 -1
  59. package/src/world-river-ribbon.ts +13 -22
  60. package/src/world-water-bodies.ts +113 -3
@@ -17,10 +17,11 @@ import {
17
17
  import {
18
18
  type ITemporalLod,
19
19
  advanceTemporalLod,
20
+ syncLodCollapse,
20
21
  worldLodMaterial,
21
22
  } from "./render/world-impostor-surface.js";
22
23
  import type { IRendererLike } from "./renderer.js";
23
- import { markStatic } from "./static-transform.js";
24
+ import { markEngineStatic } from "./static-transform.js";
24
25
  import type { ICasterScaleMesh, SharedBatch } from "./world-cell-batches.js";
25
26
  import { levelTriangles } from "./world-cell-chunks.js";
26
27
  import type { IAssetPart, IBatchShape, ICellBatch, IKeyDescriptor } from "./world-cell-data.js";
@@ -244,6 +245,7 @@ export class CellGpuDress {
244
245
  updateLodEye(x: number, y: number, z: number): void {
245
246
  this.#lodEye.value.set(x, y, z);
246
247
  this.#lodClock.value = (performance.now() - this.#lodClockOrigin) / 1000;
248
+ syncLodCollapse();
247
249
  if (this.#host.lodTransition() !== "temporal") return;
248
250
  advanceTemporalLod(this.#temporalLod, this.#lodEye.value, this.#lodClock.value);
249
251
  this.#lodAlpha.value = this.#temporalLod.alpha;
@@ -302,7 +304,7 @@ export class CellGpuDress {
302
304
  // rebound one and the three roles. Static here is only safe because every write announces
303
305
  // itself: `instanceMatrix.needsUpdate` bumps the attribute's version, which is what a settled
304
306
  // draw watches to know it still has to scan.
305
- markStatic(mesh);
307
+ markEngineStatic(mesh);
306
308
  if (role !== "main") {
307
309
  mesh.layers.set(
308
310
  role === "cluster"
@@ -2,7 +2,7 @@ import { BufferGeometry, InstancedMesh, type Material, type Mesh, type Object3D
2
2
  import {
3
3
  composeSilencedByFreeze,
4
4
  isStatic,
5
- markStatic,
5
+ markEngineStatic,
6
6
  worldSilencedByFreeze,
7
7
  } from "./static-transform.js";
8
8
  import type { SharedBatch } from "./world-cell-batches.js";
@@ -210,7 +210,7 @@ export function freshMeshFor(
210
210
  next.matrixWorldAutoUpdate = old.matrixWorldAutoUpdate || worldSilencedByFreeze(old);
211
211
  // A dressed batch is frozen, and the freeze is keyed by the object: a replacement that did not
212
212
  // re-arm it would compose its own world matrix every walk forever.
213
- if (isStatic(old)) markStatic(next);
213
+ if (isStatic(old)) markEngineStatic(next);
214
214
  return next;
215
215
  }
216
216
 
@@ -194,7 +194,7 @@ async function fetchOk(url: string): Promise<Response> {
194
194
  * @constraint SkinnedMesh parts are skipped; an instanced copy would draw one rest pose
195
195
  * @constraint a baked chain's switch distances are measured against `autoLod` (default 4 px of error over 60° and 1080 raster rows), because an instanced draw cannot select a level per instance; an asset with nonempty authored `lods` never consults it; explicit empty lists enroll only unchanged static geometry/material parts
196
196
  * @constraint eligible static sources can use cooked HLOD (chunk-only alongside GPU scatter, whole-cell on CPU) after compilation and an observed main-context backend submission; projected-error hysteresis requires actual source triangle reduction and no extra material draws, unsupported or shared source stays resident, and collision/shadow paths retain source representations; stats().hlod counts lifecycle and charged resources, not GPU timing or physical allocation
197
- * @override `hlod: false` keeps source rendering; ring, budgets, terrain tile size/resolution, terrain stream and collider radius, `transparentScatter`, `clusterSize` and `shadows.invalidate`, load `concurrency`, `rebuildsPerUpdate`, `admissionBudgetMs` and the package's per-asset maxDistance; `impostorFar: "always"` keeps the far aggregate the near ring's guaranteed radius made unnecessary
197
+ * @override `hlod: false` keeps source rendering; `partMaterial` gives a part the game's own surface (a swaying tree); ring, budgets, terrain tile size/resolution, terrain stream and collider radius, `transparentScatter`, `clusterSize` and `shadows.invalidate`, load `concurrency`, `rebuildsPerUpdate`, `admissionBudgetMs` and the package's per-asset maxDistance; `impostorFar: "always"` keeps the far aggregate the near ring's guaranteed radius made unnecessary
198
198
  * @constraint `prewarmed` resolves once every prewarmed shared batch has been drawn; a game with a loading screen waits on it, and `stats().pendingPrewarm` is the same gate as a number
199
199
  * @constraint every `asset:level:part` is one InstancedMesh for the main pass, plus one caster InstancedMesh per world-grid square of `clusterSize` on the shadow caster layer, so the main pass draws one mesh per key and a shadow level submits only the squares it covers
200
200
  * @constraint two definitions the asset loader resolves to one model — the same cooked `glb`, the same `lods` at the same distances, the same `maxDistance` and bounds — are one asset under the lexicographically smallest id: one model load, one set of `asset:level:part` keys, one prewarm and one refcount, released when the last cell holding any member of the group leaves the ring; `TN_WORLD_ASSET_ALIAS` reports how many of the package's assets are really distinct
@@ -1,6 +1,6 @@
1
1
  import { BufferAttribute, BufferGeometry } from "three";
2
2
  import type { Heightfield } from "./world-heightfield.js";
3
- import { type IWaterLake, WATER_RIBBON_REACH, lakeReach } from "./world-water-bodies.js";
3
+ import { type IWaterLake, WATER_RIBBON_REACH, lakeDisc } from "./world-water-bodies.js";
4
4
 
5
5
  /** How a ribbon is cut; every value has the default `WaterBodies` and the Strata preview use. */
6
6
  export interface IRiverRibbonOptions {
@@ -206,13 +206,16 @@ export interface ILakeSurfaceOptions {
206
206
 
207
207
  /**
208
208
  * A lake's water surface: a level disc out to `lakeReach`, the footprint `WaterBodies` floods, with a
209
- * `metres` attribute (water depth over the ground). Only cells with water at a corner get triangles,
210
- * so the surface does not hover over dry hillside and the shore follows the ground's contour. The
209
+ * `metres` attribute (water depth over the ground). Only cells with a corner the seed's water reaches
210
+ * get triangles, so the surface does not hover over dry hillside, a hollow past the basin's rim (a
211
+ * river valley beyond the dam) stays dry instead of standing under a sheet that stops where the reach
212
+ * does, and the shore follows the ground's contour. The
211
213
  * rings pack towards the middle, so an irregular basin costs vertices where the camera sees them.
212
214
  * Returns `undefined` when the basin holds no water at its level.
213
215
  *
214
216
  * @situation draw a lake's water surface from the baked level and seed
215
217
  * @situation a lake's drawn water and the swimmer's water disagree
218
+ * @situation lake water ends in a straight edge over a valley past the basin's rim
216
219
  * @constraint the lake row and field come from the game's bake; the game's material shades the geometry
217
220
  * @example const geometry = lakeSurfaceGeometry({ ...lake, margin: 1.12 }, field, { maxDepth: 1.6 });
218
221
  */
@@ -231,28 +234,16 @@ export function lakeSurfaceGeometry(
231
234
  );
232
235
  if (!(packing > 0) || !(maxDepth > 0))
233
236
  throw new Error("TN_LAKE_SURFACE_INVALID: packing and maxDepth must be positive.");
234
- const reach = lakeReach(field, lake);
235
- if (!(reach > 0)) return undefined;
236
- const [cx = 0, cz = 0] = lake.at;
237
- const minX = field.origin.x - field.width / 2;
238
- const minZ = field.origin.z - field.depth / 2;
239
- const count = (rings - 1) * spokes + 1;
237
+ const disc = lakeDisc(field, lake, rings, spokes, packing);
238
+ if (disc === undefined) return undefined;
239
+ const count = disc.depths.length;
240
240
  const positions = new Float32Array(count * 3);
241
241
  const depths = new Float32Array(count);
242
- const place = (index: number, radius: number, spoke: number): void => {
243
- const angle = (spoke / spokes) * Math.PI * 2;
244
- const x = Math.max(minX, Math.min(minX + field.width, cx + Math.cos(angle) * radius));
245
- const z = Math.max(minZ, Math.min(minZ + field.depth, cz + Math.sin(angle) * radius));
246
- positions[index * 3] = x;
242
+ for (let index = 0; index < count; index += 1) {
243
+ positions[index * 3] = disc.positions[index * 2] as number;
247
244
  positions[index * 3 + 1] = lake.level;
248
- positions[index * 3 + 2] = z;
249
- depths[index] = Math.min(maxDepth, Math.max(0, lake.level - field.heightAt(x, z)));
250
- };
251
- place(0, 0, 0);
252
- for (let ring = 1; ring < rings; ring += 1) {
253
- const radius = reach * (ring / (rings - 1)) ** packing;
254
- for (let spoke = 0; spoke < spokes; spoke += 1)
255
- place(1 + (ring - 1) * spokes + spoke, radius, spoke);
245
+ positions[index * 3 + 2] = disc.positions[index * 2 + 1] as number;
246
+ depths[index] = Math.min(maxDepth, disc.depths[index] as number);
256
247
  }
257
248
  const depth = (index: number): number => depths[index] ?? 0;
258
249
  const indices: number[] = [];
@@ -83,6 +83,8 @@ interface IPool {
83
83
  readonly z: number;
84
84
  readonly radius2: number;
85
85
  readonly level: number;
86
+ readonly disc: ILakeDisc | undefined;
87
+ readonly field: Heightfield;
86
88
  }
87
89
 
88
90
  /** What stands at one (x, z): the water body covering it, its surface, and the river piece carrying it. */
@@ -155,6 +157,95 @@ export function waterlineRadius(
155
157
  return furthest;
156
158
  }
157
159
 
160
+ /**
161
+ * A lake's disc: `rings` rings of `spokes` vertices around its seed, out to `lakeReach`, packed towards
162
+ * the middle. Vertex 0 is the seed; ring `r` (1 to `rings - 1`) spoke `s` is `1 + (r - 1) * spokes + s`.
163
+ *
164
+ * `depths` is the water over the ground at each vertex, and it is zero where dry ground cuts the vertex
165
+ * off from the seed: a hollow beyond the basin's rim sits under the level too, but the lake does not
166
+ * reach it (a river valley past the dam would otherwise stand under a sheet of lake water that stops
167
+ * where the reach does, in a straight edge). Neighbours are the next spoke on a ring and the next ring
168
+ * on a spoke, so water crosses a ridge only where the ridge falls below the level.
169
+ */
170
+ export interface ILakeDisc {
171
+ readonly x: number;
172
+ readonly z: number;
173
+ readonly reach: number;
174
+ readonly rings: number;
175
+ readonly spokes: number;
176
+ readonly packing: number;
177
+ /** `[x, z]` per vertex, clamped to the field. */
178
+ readonly positions: Float32Array;
179
+ readonly depths: Float32Array;
180
+ }
181
+
182
+ export function lakeDisc(
183
+ field: Heightfield,
184
+ lake: IWaterLake,
185
+ rings = 44,
186
+ spokes = 88,
187
+ packing = 1.7,
188
+ ): ILakeDisc | undefined {
189
+ const reach = lakeReach(field, lake);
190
+ if (!(reach > 0)) return undefined;
191
+ const [cx = 0, cz = 0] = lake.at;
192
+ const minX = field.origin.x - field.width / 2;
193
+ const minZ = field.origin.z - field.depth / 2;
194
+ const count = (rings - 1) * spokes + 1;
195
+ const positions = new Float32Array(count * 2);
196
+ const raw = new Float32Array(count);
197
+ for (let index = 0; index < count; index += 1) {
198
+ const ring = index === 0 ? 0 : Math.floor((index - 1) / spokes) + 1;
199
+ const angle = (((index - 1) % spokes) / spokes) * Math.PI * 2;
200
+ const radius = index === 0 ? 0 : reach * (ring / (rings - 1)) ** packing;
201
+ const x = Math.max(minX, Math.min(minX + field.width, cx + Math.cos(angle) * radius));
202
+ const z = Math.max(minZ, Math.min(minZ + field.depth, cz + Math.sin(angle) * radius));
203
+ positions[index * 2] = x;
204
+ positions[index * 2 + 1] = z;
205
+ raw[index] = Math.max(0, lake.level - field.heightAt(x, z));
206
+ }
207
+ // Flood from the seed through wet vertices only.
208
+ const depths = new Float32Array(count);
209
+ const stack = [0];
210
+ depths[0] = raw[0] as number;
211
+ const visit = (index: number): void => {
212
+ if ((raw[index] as number) > 0 && depths[index] === 0) {
213
+ depths[index] = raw[index] as number;
214
+ stack.push(index);
215
+ }
216
+ };
217
+ while (stack.length > 0) {
218
+ const index = stack.pop() as number;
219
+ if (index === 0) {
220
+ for (let spoke = 0; spoke < spokes; spoke += 1) visit(1 + spoke);
221
+ continue;
222
+ }
223
+ const ring = Math.floor((index - 1) / spokes) + 1;
224
+ const spoke = (index - 1) % spokes;
225
+ const at = (r: number, s: number): number => (r === 0 ? 0 : 1 + (r - 1) * spokes + s);
226
+ visit(at(ring, (spoke + 1) % spokes));
227
+ visit(at(ring, (spoke + spokes - 1) % spokes));
228
+ visit(at(ring - 1, spoke));
229
+ if (ring + 1 < rings) visit(at(ring + 1, spoke));
230
+ }
231
+ return { x: cx, z: cz, reach, rings, spokes, packing, positions, depths };
232
+ }
233
+
234
+ /** Whether the disc cell holding (x, z) has a corner the seed's water reaches. */
235
+ function discReaches(disc: ILakeDisc, x: number, z: number): boolean {
236
+ const dx = x - disc.x;
237
+ const dz = z - disc.z;
238
+ const t = (Math.hypot(dx, dz) / disc.reach) ** (1 / disc.packing) * (disc.rings - 1);
239
+ const ring = Math.min(disc.rings - 2, Math.floor(t));
240
+ const turn = (Math.atan2(dz, dx) / (Math.PI * 2) + 1) % 1;
241
+ const spoke = Math.floor(turn * disc.spokes) % disc.spokes;
242
+ const at = (r: number, s: number): number => (r === 0 ? 0 : 1 + (r - 1) * disc.spokes + s);
243
+ const next = (spoke + 1) % disc.spokes;
244
+ return [at(ring, spoke), at(ring, next), at(ring + 1, spoke), at(ring + 1, next)].some(
245
+ (index) => (disc.depths[index] as number) > 0,
246
+ );
247
+ }
248
+
158
249
  /**
159
250
  * How far a lake's water reaches: the waterline its basin measures, `margin` times out, capped.
160
251
  *
@@ -272,7 +363,11 @@ export class WaterBodies {
272
363
  river === undefined ? Number.NEGATIVE_INFINITY : river.ha + (river.hb - river.ha) * along;
273
364
  let kind: WaterBodyKind | undefined = river === undefined ? undefined : "river";
274
365
  for (const pool of this.#pools)
275
- if ((x - pool.x) ** 2 + (z - pool.z) ** 2 <= pool.radius2 && pool.level > level) {
366
+ if (
367
+ (x - pool.x) ** 2 + (z - pool.z) ** 2 <= pool.radius2 &&
368
+ pool.level > level &&
369
+ !isolated(pool, x, z)
370
+ ) {
276
371
  level = pool.level;
277
372
  river = undefined;
278
373
  kind = "lake";
@@ -292,6 +387,20 @@ export class WaterBodies {
292
387
  }
293
388
  }
294
389
 
390
+ /** Ground under a lake's level that its water does not reach: a hollow past the basin's rim. */
391
+ function isolated(pool: IPool, x: number, z: number): boolean {
392
+ const disc = pool.disc;
393
+ if (disc === undefined || discReaches(disc, x, z)) return false;
394
+ const field = pool.field;
395
+ const minX = field.origin.x - field.width / 2;
396
+ const minZ = field.origin.z - field.depth / 2;
397
+ const ground = field.heightAt(
398
+ Math.max(minX, Math.min(minX + field.width, x)),
399
+ Math.max(minZ, Math.min(minZ + field.depth, z)),
400
+ );
401
+ return ground < pool.level;
402
+ }
403
+
295
404
  /** One row of river stations as straight pieces, each as wide as the channel stands over. */
296
405
  function buildReaches(ribbon: IWaterRibbon, into: IReach[]): void {
297
406
  const width = positive(ribbon.width, "ribbon width");
@@ -329,8 +438,9 @@ function poolOf(field: Heightfield | undefined, lake: IWaterLake): IPool {
329
438
  const [x = 0, z = 0] = lake.at;
330
439
  finite(x, "lake x");
331
440
  finite(z, "lake z");
332
- const radius = lakeReach(field, lake);
333
- return { level: lake.level, radius2: radius * radius, x, z };
441
+ const disc = lakeDisc(field, lake);
442
+ const radius = disc?.reach ?? 0;
443
+ return { level: lake.level, radius2: radius * radius, x, z, disc, field };
334
444
  }
335
445
 
336
446
  /**