@ignifx/core 0.2.0 → 0.3.0

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 (37) hide show
  1. package/dist/async-pipelines-CI5uT5iZ.js +26 -0
  2. package/dist/async-pipelines-CI5uT5iZ.js.map +1 -0
  3. package/dist/color-DrR6GFTd.js +351 -0
  4. package/dist/color-DrR6GFTd.js.map +1 -0
  5. package/dist/effect-task-CMbuO6Kb.js +205 -0
  6. package/dist/effect-task-CMbuO6Kb.js.map +1 -0
  7. package/dist/environment-C_JfuAjj.js +224 -0
  8. package/dist/environment-C_JfuAjj.js.map +1 -0
  9. package/dist/ignifx-error-R1ma_Lzv.js +544 -0
  10. package/dist/ignifx-error-R1ma_Lzv.js.map +1 -0
  11. package/dist/index.d.ts +3778 -1658
  12. package/dist/index.d.ts.map +1 -1
  13. package/dist/index.js +6349 -5585
  14. package/dist/index.js.map +1 -1
  15. package/dist/instanced-mesh-instance-Cgx1H87p.js +701 -0
  16. package/dist/instanced-mesh-instance-Cgx1H87p.js.map +1 -0
  17. package/dist/material-plugin-CTaWZXEk.js +485 -0
  18. package/dist/material-plugin-CTaWZXEk.js.map +1 -0
  19. package/dist/math-utils-BcDnL-gi.js +277 -0
  20. package/dist/math-utils-BcDnL-gi.js.map +1 -0
  21. package/dist/mesh-CnK_PX46.js +811 -0
  22. package/dist/mesh-CnK_PX46.js.map +1 -0
  23. package/dist/post-effect-C42XJFmo.js +155 -0
  24. package/dist/post-effect-C42XJFmo.js.map +1 -0
  25. package/dist/post-effect-compiler-DTlkT1si.js +311 -0
  26. package/dist/post-effect-compiler-DTlkT1si.js.map +1 -0
  27. package/dist/shader-declaration-5q__jycG.js +165 -0
  28. package/dist/shader-declaration-5q__jycG.js.map +1 -0
  29. package/dist/shader-material-DssOqsvZ.js +1009 -0
  30. package/dist/shader-material-DssOqsvZ.js.map +1 -0
  31. package/dist/shader-material-Xk7Oc9UG.js +207 -0
  32. package/dist/shader-material-Xk7Oc9UG.js.map +1 -0
  33. package/dist/shader-pragma-CNAK4SIb.js +685 -0
  34. package/dist/shader-pragma-CNAK4SIb.js.map +1 -0
  35. package/dist/surface-shader-C2HtysNN.js +1397 -0
  36. package/dist/surface-shader-C2HtysNN.js.map +1 -0
  37. package/package.json +1 -1
@@ -0,0 +1,811 @@
1
+ import { addToScene, cloneTransformNode, createBox, createCapsule, createCylinder, createGround, createMeshFromData, createPlane, createSphere, createTorus, createTransformNode, removeFromScene, setParent, setSubtreeVisible, updateMeshColors, updateMeshNormals, updateMeshPositions, updateMeshUvs } from "@babylonjs/lite";
2
+ //#region src/lite/node.ts
3
+ /** The single key ignifx owns inside Lite's open `metadata` record. */
4
+ const METADATA_KEY = "ignifx";
5
+ /** Number of elements in a 4x4 matrix. */
6
+ const MATRIX_LENGTH = 16;
7
+ /**
8
+ * Creates a pure transform node at the origin with an identity rotation and unit scale.
9
+ *
10
+ * @remarks
11
+ * The node is deliberately **not** added to any Lite scene: a transform node is only a matrix
12
+ * provider, and `worldMatrix` is valid the moment the node exists (see rule 5 in the module
13
+ * documentation). Renderable Lite objects created by components are parented under it and added
14
+ * with `addToScene` separately.
15
+ *
16
+ * @param name - A human-readable name; Lite never uses it for lookup and it need not be unique.
17
+ * @returns A fresh, unparented transform node.
18
+ *
19
+ * @example
20
+ * ```ts
21
+ * const node = createNode("Player");
22
+ * node.position.set(1, 2, 3);
23
+ * ```
24
+ *
25
+ * @internal
26
+ */
27
+ function createNode(name) {
28
+ return createTransformNode(name);
29
+ }
30
+ /**
31
+ * Releases a pure transform node.
32
+ *
33
+ * @remarks
34
+ * Lite requires nothing to release a transform node that was never added to a scene: verified in
35
+ * `lib/scene/transform-node.js` and `lib/scene/scene-node.js`, the node is a plain object holding
36
+ * three observable values, one `Float32Array` for the cached world matrix, and closures — no GPU
37
+ * resource, no ref count, no scene registry. (Reference counting in `lib/resource/ref-count.js`
38
+ * applies to meshes and their GPU buffers only, and `disposeScene` never walks transform nodes.)
39
+ *
40
+ * What *does* need doing is breaking the parent link: a linked parent keeps a reference to this
41
+ * node's world-matrix state so it can invalidate it, so a node dropped while still parented is
42
+ * retained by its parent. This function therefore unlinks the node and drops the ignifx tag. It
43
+ * leaves the node's own `children` alone: the kernel destroys children before parents
44
+ * (`docs/architecture/01-lifecycle-and-time.md` §3 step 9), so each child unlinks itself first.
45
+ *
46
+ * @param node - A node from {@link createNode}.
47
+ *
48
+ * @internal
49
+ */
50
+ function disposeNode(node) {
51
+ linkParent(node, null);
52
+ const metadata = node.metadata;
53
+ if (metadata !== void 0) delete metadata[METADATA_KEY];
54
+ }
55
+ /**
56
+ * Links `child` under `parent`, **keeping the child's local values** — its world transform moves
57
+ * with the new parent. This is `setParent(parent, { worldPositionStays: false })` in
58
+ * `docs/architecture/02-scene-graph.md` §5.1.
59
+ *
60
+ * @remarks
61
+ * Lite has no public helper for this case (its own `setParent` preserves the world transform), so
62
+ * the adapter does the linking itself: it assigns `child.parent`, which is the setter that
63
+ * re-registers the child's world-matrix state with the new parent and invalidates the subtree, and
64
+ * maintains the `children` arrays on both the old and the new parent so tree traversal stays
65
+ * consistent. Passing the parent the child already has is a no-op.
66
+ *
67
+ * @param child - The node to move.
68
+ * @param parent - The new parent, or `null` to detach the child to world space.
69
+ *
70
+ * @example
71
+ * ```ts
72
+ * linkParent(child, parent); // child keeps localPosition; its world position changes
73
+ * ```
74
+ *
75
+ * @internal
76
+ */
77
+ function linkParent(child, parent) {
78
+ const previous = child.parent;
79
+ if (previous === parent) return;
80
+ const previousChildren = childrenOf(previous);
81
+ if (previousChildren !== null) {
82
+ const index = previousChildren.indexOf(child);
83
+ if (index >= 0) previousChildren.splice(index, 1);
84
+ }
85
+ child.parent = parent;
86
+ if (parent !== null && !parent.children.includes(child)) parent.children.push(child);
87
+ }
88
+ /**
89
+ * Reparents `child` under `parent` **keeping its world transform**, by delegating to Lite's own
90
+ * `setParent`. This is `setParent(parent, { worldPositionStays: true })`, the ignifx default
91
+ * (`docs/architecture/02-scene-graph.md` §5.1).
92
+ *
93
+ * @remarks
94
+ * Lite snapshots the child's world matrix, relinks the node (maintaining both `children` arrays),
95
+ * then decomposes `inverse(parentWorld) × childWorld` back into local TRS. Two documented caveats
96
+ * carry straight through to ignifx:
97
+ *
98
+ * - **Singular parent matrices.** When the parent's world matrix has a collapsed axis it cannot be
99
+ * inverted, so no local transform can reproduce the child's world. Lite then keeps the parent
100
+ * link and copies the child's world *position* into its local position, leaving rotation and
101
+ * scale uncompensated. Non-uniform-but-invertible parents are fine; zero scale on any axis is
102
+ * not.
103
+ * - **Canonical, not sign-faithful, decomposition.** The local TRS comes from `mat4Decompose`,
104
+ * which folds a reflection into a negative Y scale. The world matrix is reproduced exactly, but a
105
+ * child that had a negative X scale comes back with a negative Y scale and a different rotation.
106
+ *
107
+ * A third caveat in Lite's TSDoc — that `child.parent` links are only established by `addToScene`,
108
+ * so a node from a freshly loaded asset must have its container added before it is reparented —
109
+ * does not apply to nodes ignifx creates, because {@link linkParent} establishes the link itself.
110
+ *
111
+ * @param child - The node to move.
112
+ * @param parent - The new parent, or `null` to detach the child to world space.
113
+ *
114
+ * @internal
115
+ */
116
+ function reparentKeepingWorld(child, parent) {
117
+ setParent(child, parent);
118
+ }
119
+ /**
120
+ * Copies a node's world matrix into `out`.
121
+ *
122
+ * @remarks
123
+ * Allocation-free on the ignifx side, which is why the destination is a parameter: Lite's
124
+ * `worldMatrix` getter may recompute up the parent chain, and the object it returns is Lite's own
125
+ * cache — never hold on to it. Lite documents `Mat4` as opaque ("callers MUST NOT depend on the
126
+ * underlying storage"); it is a `Float32Array` in 1.27.0 (`lib/math/_matrix-allocator.js`), so
127
+ * copying element by element is the only supported read.
128
+ *
129
+ * @param node - The node to read.
130
+ * @param out - A sink of at least 16 elements, written in column-major order.
131
+ * @returns `out`, for chaining.
132
+ *
133
+ * @internal
134
+ */
135
+ function readWorldMatrix(node, out) {
136
+ const matrix = node.worldMatrix;
137
+ for (let index = 0; index < MATRIX_LENGTH; index += 1) out[index] = matrix[index] ?? 0;
138
+ return out;
139
+ }
140
+ /**
141
+ * Reads a node's world-matrix version — the counter that increases whenever the node's world
142
+ * matrix is invalidated, by its own TRS or by any ancestor's.
143
+ *
144
+ * @remarks
145
+ * Snapshot it to detect movement without comparing matrices; systems that maintain acceleration
146
+ * structures do exactly that (`docs/architecture/02-scene-graph.md` §9). The counter is
147
+ * monotonically increasing but not a change *count*: it moves on invalidation, not on
148
+ * recomputation, and a bulk `position.set(...)` bumps it even when the values are unchanged.
149
+ *
150
+ * @param node - The node to read.
151
+ * @returns The current version.
152
+ *
153
+ * @internal
154
+ */
155
+ function worldMatrixVersion(node) {
156
+ return node.worldMatrixVersion;
157
+ }
158
+ /**
159
+ * Shows or hides **one** node, without touching its subtree.
160
+ *
161
+ * @remarks
162
+ * Lite's `visible` is per node — the renderer reads each node's own flag, and `setSubtreeVisible`
163
+ * is only a bulk helper that materialises a cascade at write time. ignifx already materialises
164
+ * `activeInHierarchy` over the subtree itself, so it writes one flag per entity: correct for a
165
+ * subtree that mixes active and inactive entities, and linear rather than quadratic.
166
+ *
167
+ * @param node - The node to show or hide.
168
+ * @param visible - `true` to show it, `false` to hide it.
169
+ *
170
+ * @internal
171
+ */
172
+ function setNodeSelfVisible(node, visible) {
173
+ node.visible = visible;
174
+ }
175
+ /**
176
+ * Writes the ignifx identity into a node's Lite metadata bag, under the single `ignifx` key.
177
+ *
178
+ * @remarks
179
+ * `LiteMetadata` is an open record (`{ gltf?: GltfMetadata; [key: string]: unknown }`), so the tag
180
+ * coexists with the `gltf.extras` a glTF load writes. The metadata object is created on demand;
181
+ * nodes ignifx never tags keep `metadata` undefined.
182
+ *
183
+ * @param node - The node to tag.
184
+ * @param tag - The owning entity, and the component that created the node when it is not the
185
+ * entity's own transform.
186
+ *
187
+ * @internal
188
+ */
189
+ function tagNode(node, tag) {
190
+ const metadata = node.metadata ??= {};
191
+ metadata[METADATA_KEY] = tag;
192
+ }
193
+ /**
194
+ * Reads the ignifx identity back from a node.
195
+ *
196
+ * @param node - The node to read; it may be any Lite node, including one ignifx never created.
197
+ * @returns The tag {@link tagNode} wrote, or `null` when the node carries none.
198
+ *
199
+ * @internal
200
+ */
201
+ function readNodeTag(node) {
202
+ const metadata = node.metadata;
203
+ if (metadata === void 0) return null;
204
+ const value = metadata[METADATA_KEY];
205
+ if (typeof value !== "object" || value === null || !("entity" in value)) return null;
206
+ const entity = value.entity;
207
+ if (typeof entity !== "number") return null;
208
+ const component = "component" in value ? value.component : void 0;
209
+ return typeof component === "number" ? {
210
+ entity,
211
+ component
212
+ } : { entity };
213
+ }
214
+ /**
215
+ * The `children` array of a world-matrix provider, when it has one.
216
+ *
217
+ * @remarks
218
+ * `SceneNode.parent` is typed as the minimal {@link IWorldMatrixProvider}, which declares no
219
+ * `children`, but every parent ignifx links is a scene node. Lite's own `setParent` solves this the
220
+ * same way (`lib/scene/set-parent.js`), and the array check keeps a non-node provider — a camera,
221
+ * say — from being treated as a tree node.
222
+ *
223
+ * @param provider - The candidate parent.
224
+ * @returns The provider's children, or `null` when it is not a tree node.
225
+ */
226
+ function childrenOf(provider) {
227
+ if (provider === null || !("children" in provider)) return null;
228
+ const children = provider.children;
229
+ return Array.isArray(children) ? children : null;
230
+ }
231
+ /**
232
+ * The node's local position as a live, writable view.
233
+ *
234
+ * @remarks
235
+ * Zero-copy: the returned object *is* Lite's `ObservableVec3` over the node's TRS, so `.x += 1`,
236
+ * `.set(x, y, z)`, and `.copyFrom(v)` write straight through and invalidate the subtree's world
237
+ * matrices (`docs/architecture/02-scene-graph.md` §5). Never hold it past the node's lifetime.
238
+ *
239
+ * @param node - The node to view.
240
+ * @returns The live local position.
241
+ *
242
+ * @internal
243
+ */
244
+ function localPosition(node) {
245
+ return node.position;
246
+ }
247
+ /**
248
+ * The node's local rotation as a live, writable view.
249
+ *
250
+ * @param node - The node to view.
251
+ * @returns The live local rotation quaternion.
252
+ *
253
+ * @internal
254
+ */
255
+ function localRotation(node) {
256
+ return node.rotationQuaternion;
257
+ }
258
+ /**
259
+ * The node's local scale as a live, writable view.
260
+ *
261
+ * @param node - The node to view.
262
+ * @returns The live local scale.
263
+ *
264
+ * @internal
265
+ */
266
+ function localScale(node) {
267
+ return node.scaling;
268
+ }
269
+ /**
270
+ * Renames a node.
271
+ *
272
+ * @remarks
273
+ * Lite never uses the name for lookup, so this is purely for debugging and for the names that show
274
+ * up in Lite-side tooling; ignifx keeps `Entity.name` as the source of truth and mirrors it here.
275
+ *
276
+ * @param node - The node to rename.
277
+ * @param name - The new name.
278
+ *
279
+ * @internal
280
+ */
281
+ function setNodeName(node, name) {
282
+ node.name = name;
283
+ }
284
+ /**
285
+ * The parent a node is currently linked to, when that parent is itself a scene node.
286
+ *
287
+ * @param node - The node to read.
288
+ * @returns The parent node, or `null` when the node is unparented or its parent is a bare
289
+ * world-matrix provider such as a camera.
290
+ *
291
+ * @internal
292
+ */
293
+ function parentNode(node) {
294
+ const parent = node.parent;
295
+ if (parent === null || !("children" in parent)) return null;
296
+ return parent;
297
+ }
298
+ //#endregion
299
+ //#region src/lite/gpu/mesh.ts
300
+ /**
301
+ * Creates a box template.
302
+ *
303
+ * @param engine - The engine that owns the GPU buffers.
304
+ * @param options - A uniform size, or per-axis dimensions.
305
+ * @returns The mesh. It belongs to no scene yet.
306
+ *
307
+ * @example
308
+ * ```ts
309
+ * const template = createBoxMesh(engine, { size: 2 });
310
+ * const instance = cloneMeshUnderNode(template, entityNode);
311
+ * addMeshToScene(scene, instance);
312
+ * ```
313
+ *
314
+ * @internal
315
+ */
316
+ function createBoxMesh(engine, options) {
317
+ return createBox(engine, options);
318
+ }
319
+ /**
320
+ * Creates a sphere template.
321
+ *
322
+ * @param engine - The engine that owns the GPU buffers.
323
+ * @param options - Segment count and diameters.
324
+ * @returns The mesh.
325
+ *
326
+ * @internal
327
+ */
328
+ function createSphereMesh(engine, options) {
329
+ return createSphere(engine, options);
330
+ }
331
+ /**
332
+ * Creates a plane template in the XY plane.
333
+ *
334
+ * @param engine - The engine that owns the GPU buffers.
335
+ * @param options - Size, or width and height.
336
+ * @returns The mesh.
337
+ *
338
+ * @internal
339
+ */
340
+ function createPlaneMesh(engine, options) {
341
+ return createPlane(engine, options);
342
+ }
343
+ /**
344
+ * Creates a subdivided ground template in the XZ plane.
345
+ *
346
+ * @param engine - The engine that owns the GPU buffers.
347
+ * @param options - Width, height, subdivisions, and UV scale.
348
+ * @returns The mesh.
349
+ *
350
+ * @internal
351
+ */
352
+ function createGroundMesh(engine, options) {
353
+ return createGround(engine, options);
354
+ }
355
+ /**
356
+ * Creates a cylinder template along the Y axis.
357
+ *
358
+ * @param engine - The engine that owns the GPU buffers.
359
+ * @param options - Height, diameters, and tessellation.
360
+ * @returns The mesh.
361
+ *
362
+ * @internal
363
+ */
364
+ function createCylinderMesh(engine, options) {
365
+ return createCylinder(engine, options);
366
+ }
367
+ /**
368
+ * Creates a capsule template along the Y axis.
369
+ *
370
+ * @remarks
371
+ * `height` is the **total** height including both caps (`index.d.ts` 1523), which is the same
372
+ * convention `@ignifx/physics`'s capsule collider uses, so a renderer and a collider built from one
373
+ * pair of numbers line up.
374
+ *
375
+ * @param engine - The engine that owns the GPU buffers.
376
+ * @param options - Height, radius, and tessellation.
377
+ * @returns The mesh.
378
+ *
379
+ * @internal
380
+ */
381
+ function createCapsuleMesh(engine, options) {
382
+ return createCapsule(engine, options);
383
+ }
384
+ /**
385
+ * Creates a torus template in the XZ plane.
386
+ *
387
+ * @param engine - The engine that owns the GPU buffers.
388
+ * @param options - Diameter, thickness, and tessellation.
389
+ * @returns The mesh.
390
+ *
391
+ * @internal
392
+ */
393
+ function createTorusMesh(engine, options) {
394
+ return createTorus(engine, options);
395
+ }
396
+ /**
397
+ * Creates a mesh from raw vertex data.
398
+ *
399
+ * @remarks
400
+ * Lite keeps a reference to the arrays that are handed in — it does not copy them — and uses them
401
+ * for CPU ray picking and bounds (`lib/mesh/mesh-factories.js`). Callers must not mutate them
402
+ * afterwards.
403
+ *
404
+ * @param engine - The engine that owns the GPU buffers.
405
+ * @param name - A debug name.
406
+ * @param positions - Three floats per vertex.
407
+ * @param normals - Three floats per vertex.
408
+ * @param indices - Three indices per triangle.
409
+ * @param uvs - Two floats per vertex, or omitted.
410
+ * @param uvs2 - Two floats per vertex for the second UV set, or omitted.
411
+ * @param tangents - Four floats per vertex, or omitted.
412
+ * @param colors - Four floats per vertex, or omitted.
413
+ * @returns The mesh.
414
+ *
415
+ * @internal
416
+ */
417
+ function createMeshFromGeometry(engine, name, positions, normals, indices, uvs, uvs2, tangents, colors) {
418
+ return createMeshFromData(engine, name, positions, normals, indices, uvs, uvs2, tangents, colors);
419
+ }
420
+ /**
421
+ * Re-uploads part of a mesh's position buffer.
422
+ *
423
+ * @remarks
424
+ * A no-op range is accepted; an out-of-range one, or a mesh whose GPU geometry has co-owners,
425
+ * throws a Lite error (see the module note). It does **not** refresh the CPU picking geometry or
426
+ * the bounds.
427
+ *
428
+ * @param engine - The engine that owns the buffer.
429
+ * @param mesh - The mesh to update.
430
+ * @param positions - Three floats per vertex, read from index 0.
431
+ * @param vertexOffset - The first destination vertex to overwrite.
432
+ * @param vertexCount - How many vertices to write.
433
+ *
434
+ * @internal
435
+ */
436
+ function updateMeshPositions$1(engine, mesh, positions, vertexOffset, vertexCount) {
437
+ updateMeshPositions(engine, mesh, positions, vertexOffset, vertexCount);
438
+ }
439
+ /**
440
+ * Re-uploads part of a mesh's normal buffer.
441
+ *
442
+ * @param engine - The engine that owns the buffer.
443
+ * @param mesh - The mesh to update.
444
+ * @param normals - Three floats per vertex.
445
+ * @param vertexOffset - The first destination vertex to overwrite.
446
+ * @param vertexCount - How many vertices to write.
447
+ *
448
+ * @internal
449
+ */
450
+ function updateMeshNormals$1(engine, mesh, normals, vertexOffset, vertexCount) {
451
+ updateMeshNormals(engine, mesh, normals, vertexOffset, vertexCount);
452
+ }
453
+ /**
454
+ * Re-uploads part of a mesh's UV buffer.
455
+ *
456
+ * @remarks
457
+ * Lite makes it a no-op when the mesh was created without UVs, rather than an error.
458
+ *
459
+ * @param engine - The engine that owns the buffer.
460
+ * @param mesh - The mesh to update.
461
+ * @param uvs - Two floats per vertex.
462
+ * @param vertexOffset - The first destination vertex to overwrite.
463
+ * @param vertexCount - How many vertices to write.
464
+ *
465
+ * @internal
466
+ */
467
+ function updateMeshUvs$1(engine, mesh, uvs, vertexOffset, vertexCount) {
468
+ updateMeshUvs(engine, mesh, uvs, vertexOffset, vertexCount);
469
+ }
470
+ /**
471
+ * Re-uploads part of a mesh's vertex-colour buffer.
472
+ *
473
+ * @remarks
474
+ * The colour attribute is `vec4`, and Lite makes the call a no-op when the mesh was created without
475
+ * colours.
476
+ *
477
+ * @param engine - The engine that owns the buffer.
478
+ * @param mesh - The mesh to update.
479
+ * @param colors - Four floats per vertex.
480
+ * @param vertexOffset - The first destination vertex to overwrite.
481
+ * @param vertexCount - How many vertices to write.
482
+ *
483
+ * @internal
484
+ */
485
+ function updateMeshColors$1(engine, mesh, colors, vertexOffset, vertexCount) {
486
+ updateMeshColors(engine, mesh, colors, vertexOffset, vertexCount);
487
+ }
488
+ /**
489
+ * Writes a mesh's object-local bounding box.
490
+ *
491
+ * @remarks
492
+ * `Mesh.boundMin`/`boundMax` are declared consumer-writable, and writing them is the only way to
493
+ * keep the shadow fit, the thin-instance culler and the Havok shape extents honest after a partial
494
+ * vertex update — none of the partial updaters recomputes them. The existing arrays are mutated in
495
+ * place when they are there, so repeated sculpting allocates nothing.
496
+ *
497
+ * @param mesh - The mesh to re-bound.
498
+ * @param minX - The smallest X.
499
+ * @param minY - The smallest Y.
500
+ * @param minZ - The smallest Z.
501
+ * @param maxX - The largest X.
502
+ * @param maxY - The largest Y.
503
+ * @param maxZ - The largest Z.
504
+ *
505
+ * @internal
506
+ */
507
+ function setMeshBounds(mesh, minX, minY, minZ, maxX, maxY, maxZ) {
508
+ const boundMin = mesh.boundMin;
509
+ if (boundMin === void 0) mesh.boundMin = [
510
+ minX,
511
+ minY,
512
+ minZ
513
+ ];
514
+ else {
515
+ boundMin[0] = minX;
516
+ boundMin[1] = minY;
517
+ boundMin[2] = minZ;
518
+ }
519
+ const boundMax = mesh.boundMax;
520
+ if (boundMax === void 0) mesh.boundMax = [
521
+ maxX,
522
+ maxY,
523
+ maxZ
524
+ ];
525
+ else {
526
+ boundMax[0] = maxX;
527
+ boundMax[1] = maxY;
528
+ boundMax[2] = maxZ;
529
+ }
530
+ }
531
+ /**
532
+ * Gives a cloned mesh bounding-box arrays of its own.
533
+ *
534
+ * @remarks
535
+ * `cloneMeshNode` shallow-spreads the template (`lib/scene/transform-node.js`), so a clone starts
536
+ * out sharing the template's `boundMin`/`boundMax` arrays and {@link setMeshBounds} — which mutates
537
+ * in place — would write through to the template and to every other clone. Any caller that re-bounds
538
+ * one clone alone has to call this first.
539
+ *
540
+ * @param mesh - The clone.
541
+ *
542
+ * @internal
543
+ */
544
+ function detachMeshBounds(mesh) {
545
+ const boundMin = mesh.boundMin;
546
+ if (boundMin !== void 0) mesh.boundMin = [
547
+ boundMin[0],
548
+ boundMin[1],
549
+ boundMin[2]
550
+ ];
551
+ const boundMax = mesh.boundMax;
552
+ if (boundMax !== void 0) mesh.boundMax = [
553
+ boundMax[0],
554
+ boundMax[1],
555
+ boundMax[2]
556
+ ];
557
+ }
558
+ /**
559
+ * Recomputes a mesh's object-local bounding box from a position array and writes it.
560
+ *
561
+ * @remarks
562
+ * The partial vertex updaters leave `boundMin`/`boundMax` alone (see the module note), and every
563
+ * consumer that fits a shadow cascade, culls a thin instance, or measures a Havok shape reads them.
564
+ * One linear pass, no allocation. A position array too short to hold one vertex leaves the bounds
565
+ * as they were.
566
+ *
567
+ * @param mesh - The mesh to re-bound.
568
+ * @param positions - Three floats per vertex.
569
+ *
570
+ * @internal
571
+ */
572
+ function recomputeMeshBounds(mesh, positions) {
573
+ if (positions.length < 3) return;
574
+ let minX = Number.POSITIVE_INFINITY;
575
+ let minY = Number.POSITIVE_INFINITY;
576
+ let minZ = Number.POSITIVE_INFINITY;
577
+ let maxX = Number.NEGATIVE_INFINITY;
578
+ let maxY = Number.NEGATIVE_INFINITY;
579
+ let maxZ = Number.NEGATIVE_INFINITY;
580
+ for (let index = 0; index + 2 < positions.length; index += 3) {
581
+ const x = positions[index] ?? 0;
582
+ const y = positions[index + 1] ?? 0;
583
+ const z = positions[index + 2] ?? 0;
584
+ minX = x < minX ? x : minX;
585
+ minY = y < minY ? y : minY;
586
+ minZ = z < minZ ? z : minZ;
587
+ maxX = x > maxX ? x : maxX;
588
+ maxY = y > maxY ? y : maxY;
589
+ maxZ = z > maxZ ? z : maxZ;
590
+ }
591
+ setMeshBounds(mesh, minX, minY, minZ, maxX, maxY, maxZ);
592
+ }
593
+ /**
594
+ * Clones a template — mesh or transform-node subtree — and parents the clone under an entity node.
595
+ *
596
+ * @remarks
597
+ * The clone shares the template's GPU buffers (see the module note). Cloning a mesh whose buffers
598
+ * were already released throws, which is Lite's way of telling you the template outlived its asset.
599
+ *
600
+ * Only the `parent` link is written; the clone is deliberately **not** pushed into the parent's
601
+ * `children` array, for the same reason cameras and lights are not (`./camera.ts`): ignifx
602
+ * transform nodes are never added to a Lite scene, so nothing in Lite walks their children, and
603
+ * `removeFromScene` nulls a removed mesh's `parent` without touching the array it was listed in —
604
+ * so maintaining it would only create a stale entry to clean up.
605
+ *
606
+ * @param template - The mesh or subtree to clone.
607
+ * @param parent - The entity's transform node, or `null` for world space.
608
+ * @returns The cloned root. Add it to the scene with {@link addMeshToScene}.
609
+ *
610
+ * @internal
611
+ */
612
+ function cloneMeshUnderNode(template, parent) {
613
+ const clone = cloneTransformNode(template);
614
+ clone.parent = parent;
615
+ return clone;
616
+ }
617
+ /**
618
+ * Adds a mesh — or a transform-node subtree containing meshes — to a render scene.
619
+ *
620
+ * @remarks
621
+ * `addToScene` recurses into `children` and re-parents each one, so a whole instantiated model goes
622
+ * in with one call. When the scene is already registered, the mesh joins Lite's runtime
623
+ * material-swap queue and appears once its material family's renderable has been rebuilt
624
+ * (`docs/architecture/07-rendering.md` §1.1 and ADR-0014).
625
+ *
626
+ * @param scene - The render scene.
627
+ * @param node - The mesh or subtree root to add.
628
+ *
629
+ * @internal
630
+ */
631
+ function addMeshToScene(scene, node) {
632
+ addToScene(scene, node);
633
+ }
634
+ /**
635
+ * Removes a mesh — and everything under it — from a render scene, releasing its GPU buffers when it
636
+ * has left its last scene.
637
+ *
638
+ * @remarks
639
+ * This is destruction, not hiding: use {@link setMeshSubtreeVisible} to hide.
640
+ *
641
+ * @param scene - The render scene.
642
+ * @param node - The mesh or subtree root to remove.
643
+ *
644
+ * @internal
645
+ */
646
+ function removeMeshFromScene(scene, node) {
647
+ removeFromScene(scene, node);
648
+ }
649
+ /**
650
+ * Shows or hides a mesh and everything under it.
651
+ *
652
+ * @param node - The subtree root.
653
+ * @param visible - `true` to show it, `false` to hide it.
654
+ *
655
+ * @internal
656
+ */
657
+ function setMeshSubtreeVisible(node, visible) {
658
+ setSubtreeVisible(node, visible);
659
+ }
660
+ /**
661
+ * Assigns a mesh's material.
662
+ *
663
+ * @remarks
664
+ * `Mesh.material` is an accessor once the mesh has joined a scene: writing it queues a material
665
+ * swap on every scene the mesh belongs to (`lib/scene/mesh-scene-registry.js`,
666
+ * `installMaterialSetter`). Assigning the material the mesh already has is a no-op.
667
+ *
668
+ * @param mesh - The mesh to change.
669
+ * @param material - The material to draw it with.
670
+ *
671
+ * @internal
672
+ */
673
+ function setMeshMaterial(mesh, material) {
674
+ mesh.material = material;
675
+ }
676
+ /**
677
+ * Sets whether a mesh is darkened by shadow maps.
678
+ *
679
+ * @param mesh - The mesh to change.
680
+ * @param receiveShadows - `true` to sample shadow maps on this mesh.
681
+ *
682
+ * @internal
683
+ */
684
+ function setMeshReceiveShadows(mesh, receiveShadows) {
685
+ mesh.receiveShadows = receiveShadows;
686
+ }
687
+ /**
688
+ * Sets a mesh's sort key within its phase. Lower values are drawn first.
689
+ *
690
+ * @param mesh - The mesh to change.
691
+ * @param renderOrder - The sort key; it only orders within the opaque or the transparent phase.
692
+ *
693
+ * @internal
694
+ */
695
+ function setMeshRenderOrder(mesh, renderOrder) {
696
+ mesh.renderOrder = renderOrder;
697
+ }
698
+ /**
699
+ * Sets whether picking considers a mesh at all.
700
+ *
701
+ * @remarks
702
+ * `pickable === false` removes the mesh from both the GPU picker's candidate list and the CPU ray
703
+ * test, so it neither occludes nor returns a hit (`index.d.ts` 7214, `lib/picking/ray-pick.js`).
704
+ *
705
+ * @param mesh - The mesh to change.
706
+ * @param pickable - `true` to allow picking.
707
+ *
708
+ * @internal
709
+ */
710
+ function setMeshPickable(mesh, pickable) {
711
+ mesh.pickable = pickable;
712
+ }
713
+ /**
714
+ * Gives a mesh the string id Lite's light include/exclude sets match on.
715
+ *
716
+ * @param mesh - The mesh to name.
717
+ * @param id - The id. It should be unique within the scene.
718
+ *
719
+ * @internal
720
+ */
721
+ function setMeshId(mesh, id) {
722
+ mesh.id = id;
723
+ }
724
+ /**
725
+ * Replaces the materials of every mesh in a subtree whose current material carries one of the given
726
+ * names.
727
+ *
728
+ * @remarks
729
+ * `Material.name` is "populated by loaders from the source asset (e.g. the glTF material name) so
730
+ * callers can look a material up by name" (`index.d.ts`), which is the identifier
731
+ * `docs/architecture/07-rendering.md` §2.4 means by "by material name". Assigning `Mesh.material`
732
+ * queues a material swap on every scene the mesh belongs to; assigning the material a mesh already
733
+ * has is a no-op, so re-running this is cheap.
734
+ *
735
+ * @param node - The subtree root.
736
+ * @param overrides - Source material name to replacement material.
737
+ * @returns How many meshes were re-materialled.
738
+ *
739
+ * @internal
740
+ */
741
+ function overrideSubtreeMaterials(node, overrides) {
742
+ let changed = 0;
743
+ if ("material" in node) {
744
+ const mesh = node;
745
+ const name = mesh.material.name;
746
+ const replacement = name === void 0 ? void 0 : overrides.get(name);
747
+ if (replacement !== void 0 && replacement !== mesh.material) {
748
+ mesh.material = replacement;
749
+ changed += 1;
750
+ }
751
+ }
752
+ const children = node.children;
753
+ for (let index = 0; index < children.length; index += 1) {
754
+ const child = children[index];
755
+ if (child !== void 0) changed += overrideSubtreeMaterials(child, overrides);
756
+ }
757
+ return changed;
758
+ }
759
+ /**
760
+ * Releases a template mesh's GPU buffers.
761
+ *
762
+ * @remarks
763
+ * Lite exports no mesh disposer: a mesh's buffers are freed only when it leaves its last scene
764
+ * (`lib/scene/scene-remove.js`). A template that was never added to a scene therefore has to be
765
+ * added and removed to be released, which is exactly what this does. Two consequences the caller
766
+ * must respect:
767
+ *
768
+ * 1. The template must carry no material, or the round trip will build and immediately tear down a
769
+ * renderable for it. Templates created by the factories above start with none.
770
+ * 2. Any clone still alive keeps the shared buffers: the reference count only reaches zero when the
771
+ * last co-owner has gone. Releasing the template while clones are in a scene is safe, but the
772
+ * template can no longer be cloned afterwards.
773
+ *
774
+ * @param scene - Any scene on the template's engine; it is used only as the round trip's vehicle.
775
+ * @param template - The template to release.
776
+ *
777
+ * @internal
778
+ */
779
+ function disposeMeshTemplate(scene, template) {
780
+ addToScene(scene, template);
781
+ removeFromScene(scene, template);
782
+ }
783
+ /**
784
+ * Collects every mesh in a subtree — the root included — in depth-first order.
785
+ *
786
+ * @remarks
787
+ * A scene node that carries `material` is a mesh: the same structural test
788
+ * {@link overrideSubtreeMaterials} and Lite's own scene walk use (`index.d.ts` 7156 declares
789
+ * `material` on `Mesh` and nowhere on `SceneNode`, 10104).
790
+ *
791
+ * Call it **once**, when the subtree is instantiated. The clone tree `instantiateContainer` built
792
+ * never changes shape afterwards, so walking it again every frame would put a recursion on the
793
+ * render path for an answer that cannot have moved (coding standards §7).
794
+ *
795
+ * @param node - The subtree root.
796
+ * @param out - The list the meshes are appended to; it is not cleared first.
797
+ *
798
+ * @internal
799
+ */
800
+ function collectSubtreeMeshes(node, out) {
801
+ if ("material" in node) out.push(node);
802
+ const children = node.children;
803
+ for (let index = 0; index < children.length; index += 1) {
804
+ const child = children[index];
805
+ if (child !== void 0) collectSubtreeMeshes(child, out);
806
+ }
807
+ }
808
+ //#endregion
809
+ export { linkParent as A, tagNode as B, setMeshSubtreeVisible as C, updateMeshUvs$1 as D, updateMeshPositions$1 as E, readNodeTag as F, readWorldMatrix as I, reparentKeepingWorld as L, localRotation as M, localScale as N, createNode as O, parentNode as P, setNodeName as R, setMeshRenderOrder as S, updateMeshNormals$1 as T, worldMatrixVersion as V, setMeshBounds as _, createCapsuleMesh as a, setMeshPickable as b, createMeshFromGeometry as c, createTorusMesh as d, detachMeshBounds as f, removeMeshFromScene as g, recomputeMeshBounds as h, createBoxMesh as i, localPosition as j, disposeNode as k, createPlaneMesh as l, overrideSubtreeMaterials as m, cloneMeshUnderNode as n, createCylinderMesh as o, disposeMeshTemplate as p, collectSubtreeMeshes as r, createGroundMesh as s, addMeshToScene as t, createSphereMesh as u, setMeshId as v, updateMeshColors$1 as w, setMeshReceiveShadows as x, setMeshMaterial as y, setNodeSelfVisible as z };
810
+
811
+ //# sourceMappingURL=mesh-CnK_PX46.js.map