@ignifx/core 0.7.0 → 0.8.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 (29) hide show
  1. package/dist/{color-CpvebMIh.js → color-DrR6GFTd.js} +3 -276
  2. package/dist/color-DrR6GFTd.js.map +1 -0
  3. package/dist/{environment-CTM7BAyb.js → environment-mr5wp69e.js} +3 -2
  4. package/dist/{environment-CTM7BAyb.js.map → environment-mr5wp69e.js.map} +1 -1
  5. package/dist/index.d.ts +17 -0
  6. package/dist/index.d.ts.map +1 -1
  7. package/dist/index.js +1023 -2557
  8. package/dist/index.js.map +1 -1
  9. package/dist/{instanced-mesh-instance-Cgx1H87p.js → instanced-mesh-instance-gguMoIeZ.js} +74 -10
  10. package/dist/instanced-mesh-instance-gguMoIeZ.js.map +1 -0
  11. package/dist/math-utils-BcDnL-gi.js +277 -0
  12. package/dist/math-utils-BcDnL-gi.js.map +1 -0
  13. package/dist/shader-declaration-5q__jycG.js.map +1 -1
  14. package/dist/{shader-material-CJxMJEUO.js → shader-material-BIG3UDyu.js} +3 -3
  15. package/dist/{shader-material-CJxMJEUO.js.map → shader-material-BIG3UDyu.js.map} +1 -1
  16. package/dist/{shader-material-F-CL4D70.js → shader-material-U6BKZ8D1.js} +2 -2
  17. package/dist/{shader-material-F-CL4D70.js.map → shader-material-U6BKZ8D1.js.map} +1 -1
  18. package/dist/{shader-pragma-D4HKC9vP.js → shader-pragma-tw6AKaQD.js} +24 -3
  19. package/dist/shader-pragma-tw6AKaQD.js.map +1 -0
  20. package/dist/{surface-shader-Chs7wOAE.js → surface-shader-DAWIDdaa.js} +6 -4
  21. package/dist/{surface-shader-Chs7wOAE.js.map → surface-shader-DAWIDdaa.js.map} +1 -1
  22. package/dist/vec3-B31o_KF_.js +2458 -0
  23. package/dist/vec3-B31o_KF_.js.map +1 -0
  24. package/package.json +1 -1
  25. package/dist/color-CpvebMIh.js.map +0 -1
  26. package/dist/instanced-mesh-instance-Cgx1H87p.js.map +0 -1
  27. package/dist/mesh-CnK_PX46.js +0 -811
  28. package/dist/mesh-CnK_PX46.js.map +0 -1
  29. package/dist/shader-pragma-D4HKC9vP.js.map +0 -1
@@ -0,0 +1,2458 @@
1
+ import { n as EPSILON, s as degToRad, u as lerp } from "./math-utils-BcDnL-gi.js";
2
+ import { addToScene, cloneTransformNode, createBox, createCapsule, createCylinder, createGround, createMeshFromData, createPlane, createSphere, createTorus, createTransformNode, removeFromScene, setParent, setSubtreeVisible, updateMeshColors, updateMeshNormals, updateMeshPositions, updateMeshUvs } from "@babylonjs/lite";
3
+ //#region src/math/mat4.ts
4
+ /**
5
+ * Allocates the 16-element column-major storage a matrix owns, pre-filled with zeroes.
6
+ *
7
+ * @returns Fresh, zeroed storage.
8
+ */
9
+ function allocateElements() {
10
+ return /* @__PURE__ */ new Float32Array(16);
11
+ }
12
+ /**
13
+ * The determinant of the upper-left 3×3 basis. Its sign says whether the matrix mirrors, which is
14
+ * how Babylon Lite decides the sign of the decomposed Y scale (`lib/math/mat4-decompose.js`).
15
+ *
16
+ * @param m - The matrix to measure.
17
+ * @returns The 3×3 determinant.
18
+ */
19
+ function basisDeterminant(m) {
20
+ const m0 = m[0] ?? 0;
21
+ const m1 = m[1] ?? 0;
22
+ const m2 = m[2] ?? 0;
23
+ const m4 = m[4] ?? 0;
24
+ const m5 = m[5] ?? 0;
25
+ const m6 = m[6] ?? 0;
26
+ const m8 = m[8] ?? 0;
27
+ const m9 = m[9] ?? 0;
28
+ const m10 = m[10] ?? 0;
29
+ return m0 * (m5 * m10 - m6 * m9) + m1 * (m6 * m8 - m4 * m10) + m2 * (m4 * m9 - m5 * m8);
30
+ }
31
+ /**
32
+ * Writes the unit quaternion of an orthonormal basis into `out`. Arguments are named row-major
33
+ * (`b<row><column>`), matching Babylon Lite's `_quatFromRotationBasis`
34
+ * (`lib/math/quat-from-rotation-matrix.js`), which this reproduces branch for branch.
35
+ *
36
+ * Shared with the quaternion module; not part of the public API.
37
+ *
38
+ * @param b00 - Row 0, column 0.
39
+ * @param b01 - Row 0, column 1.
40
+ * @param b02 - Row 0, column 2.
41
+ * @param b10 - Row 1, column 0.
42
+ * @param b11 - Row 1, column 1.
43
+ * @param b12 - Row 1, column 2.
44
+ * @param b20 - Row 2, column 0.
45
+ * @param b21 - Row 2, column 1.
46
+ * @param b22 - Row 2, column 2.
47
+ * @param out - The quaternion to write.
48
+ *
49
+ * @internal
50
+ */
51
+ function basisToQuatToRef(b00, b01, b02, b10, b11, b12, b20, b21, b22, out) {
52
+ const trace = b00 + b11 + b22;
53
+ if (trace > 0) {
54
+ const s = .5 / Math.sqrt(trace + 1);
55
+ out.set((b21 - b12) * s, (b02 - b20) * s, (b10 - b01) * s, .25 / s);
56
+ return;
57
+ }
58
+ if (b00 > b11 && b00 > b22) {
59
+ const s = 2 * Math.sqrt(1 + b00 - b11 - b22);
60
+ out.set(.25 * s, (b01 + b10) / s, (b02 + b20) / s, (b21 - b12) / s);
61
+ return;
62
+ }
63
+ if (b11 > b22) {
64
+ const s = 2 * Math.sqrt(1 + b11 - b00 - b22);
65
+ out.set((b01 + b10) / s, .25 * s, (b12 + b21) / s, (b02 - b20) / s);
66
+ return;
67
+ }
68
+ const s = 2 * Math.sqrt(1 + b22 - b00 - b11);
69
+ out.set((b02 + b20) / s, (b12 + b21) / s, .25 * s, (b10 - b01) / s);
70
+ }
71
+ /**
72
+ * A 4×4 transformation matrix stored column-major in a `Float32Array`, byte-compatible with WGSL's
73
+ * `mat4x4<f32>` and with Babylon Lite's `Mat4` (translation in slots 12/13/14).
74
+ *
75
+ * ignifx is left-handed, Y up, +Z forward (ADR-0011), so the projection helpers are the `LH`
76
+ * family and they use Lite's **reverse depth** convention: the near plane maps to 1 and the far
77
+ * plane to 0.
78
+ *
79
+ * Instance methods mutate the matrix and return `this`; `ToRef` statics write into their `out`
80
+ * matrix and allocate nothing, and are safe when `out` aliases an input. The remaining statics
81
+ * allocate a fresh matrix and say so.
82
+ *
83
+ * @example
84
+ * ```ts
85
+ * const world = new Mat4();
86
+ * Mat4.composeToRef(position, rotation, scale, world);
87
+ *
88
+ * const inverse = new Mat4();
89
+ * if (Mat4.invertToRef(world, inverse)) {
90
+ * Mat4.transformPointToRef(inverse, worldPoint, localPoint);
91
+ * }
92
+ * ```
93
+ *
94
+ * @public
95
+ */
96
+ var Mat4 = class Mat4 {
97
+ /**
98
+ * The 16 elements, column-major (`elements[column * 4 + row]`). This is the object to hand to
99
+ * anything that wants a {@link Mat4Like} — including Babylon Lite — and the buffer to upload to
100
+ * the GPU. It is never reallocated, so a reference to it stays valid for the matrix's lifetime.
101
+ */
102
+ elements;
103
+ /**
104
+ * Creates an identity matrix.
105
+ */
106
+ constructor() {
107
+ const e = allocateElements();
108
+ e[0] = 1;
109
+ e[5] = 1;
110
+ e[10] = 1;
111
+ e[15] = 1;
112
+ this.elements = e;
113
+ }
114
+ /**
115
+ * Resets this matrix to the identity.
116
+ *
117
+ * @returns This matrix.
118
+ */
119
+ identity() {
120
+ const e = this.elements;
121
+ e[0] = 1;
122
+ e[1] = 0;
123
+ e[2] = 0;
124
+ e[3] = 0;
125
+ e[4] = 0;
126
+ e[5] = 1;
127
+ e[6] = 0;
128
+ e[7] = 0;
129
+ e[8] = 0;
130
+ e[9] = 0;
131
+ e[10] = 1;
132
+ e[11] = 0;
133
+ e[12] = 0;
134
+ e[13] = 0;
135
+ e[14] = 0;
136
+ e[15] = 1;
137
+ return this;
138
+ }
139
+ /**
140
+ * Copies every element from another matrix.
141
+ *
142
+ * @param m - The matrix to read.
143
+ * @returns This matrix.
144
+ */
145
+ copyFrom(m) {
146
+ const e = this.elements;
147
+ for (let i = 0; i < 16; i++) e[i] = m[i] ?? 0;
148
+ return this;
149
+ }
150
+ /**
151
+ * Copies this matrix into a new one.
152
+ *
153
+ * @returns A new matrix. **Allocates.**
154
+ */
155
+ clone() {
156
+ return new Mat4().copyFrom(this.elements);
157
+ }
158
+ /**
159
+ * Post-multiplies this matrix by another (`this = this * m`), so `m`'s transform is applied first
160
+ * when the product acts on a column vector.
161
+ *
162
+ * @param m - The right-hand matrix.
163
+ * @returns This matrix.
164
+ */
165
+ multiply(m) {
166
+ Mat4.multiplyToRef(this.elements, m, this);
167
+ return this;
168
+ }
169
+ /**
170
+ * Inverts this matrix in place.
171
+ *
172
+ * @returns `true` on success. When the matrix is singular this returns `false` and leaves the
173
+ * matrix untouched.
174
+ */
175
+ invert() {
176
+ return Mat4.invertToRef(this.elements, this);
177
+ }
178
+ /**
179
+ * Transposes this matrix in place, swapping rows and columns.
180
+ *
181
+ * @returns This matrix.
182
+ */
183
+ transpose() {
184
+ Mat4.transposeToRef(this.elements, this);
185
+ return this;
186
+ }
187
+ /**
188
+ * The full 4×4 determinant of this matrix.
189
+ *
190
+ * @returns The determinant; zero means the matrix cannot be inverted.
191
+ */
192
+ determinant() {
193
+ return Mat4.determinant(this.elements);
194
+ }
195
+ /**
196
+ * Compares this matrix with another element by element, with a tolerance.
197
+ *
198
+ * @param m - The matrix to compare against.
199
+ * @param epsilon - The largest per-element difference still considered equal.
200
+ * @returns `true` when every element matches within `epsilon`.
201
+ */
202
+ equalsWithEpsilon(m, epsilon = EPSILON) {
203
+ return Mat4.equalsWithEpsilon(this.elements, m, epsilon);
204
+ }
205
+ /**
206
+ * Creates an identity matrix.
207
+ *
208
+ * @returns A new identity matrix. **Allocates.**
209
+ */
210
+ static identity() {
211
+ return new Mat4();
212
+ }
213
+ /**
214
+ * Creates a matrix holding a copy of another matrix's elements.
215
+ *
216
+ * @param m - The matrix to copy.
217
+ * @returns A new matrix. **Allocates.**
218
+ */
219
+ static from(m) {
220
+ return new Mat4().copyFrom(m);
221
+ }
222
+ /**
223
+ * Builds a translation-rotation-scale matrix, the same composition order Babylon Lite's
224
+ * `mat4Compose` uses (`translation * rotation * scale`).
225
+ *
226
+ * @param position - The translation, in metres.
227
+ * @param rotation - The rotation; assumed to be a unit quaternion.
228
+ * @param scale - The per-axis scale.
229
+ * @returns A new matrix. **Allocates.**
230
+ */
231
+ static compose(position, rotation, scale) {
232
+ return Mat4.composeToRef(position, rotation, scale, new Mat4());
233
+ }
234
+ /**
235
+ * Writes a translation-rotation-scale matrix into `out`.
236
+ *
237
+ * @param position - The translation, in metres.
238
+ * @param rotation - The rotation; assumed to be a unit quaternion.
239
+ * @param scale - The per-axis scale.
240
+ * @param out - The matrix to write.
241
+ * @returns `out`.
242
+ *
243
+ * @example
244
+ * ```ts
245
+ * Mat4.composeToRef(transform.localPosition, transform.localRotation, transform.localScale, local);
246
+ * ```
247
+ */
248
+ static composeToRef(position, rotation, scale, out) {
249
+ const qx = rotation.x;
250
+ const qy = rotation.y;
251
+ const qz = rotation.z;
252
+ const qw = rotation.w;
253
+ const sx = scale.x;
254
+ const sy = scale.y;
255
+ const sz = scale.z;
256
+ const xx = qx * qx;
257
+ const yy = qy * qy;
258
+ const zz = qz * qz;
259
+ const xy = qx * qy;
260
+ const xz = qx * qz;
261
+ const yz = qy * qz;
262
+ const wx = qw * qx;
263
+ const wy = qw * qy;
264
+ const wz = qw * qz;
265
+ const e = out.elements;
266
+ e[0] = (1 - 2 * (yy + zz)) * sx;
267
+ e[1] = 2 * (xy + wz) * sx;
268
+ e[2] = 2 * (xz - wy) * sx;
269
+ e[3] = 0;
270
+ e[4] = 2 * (xy - wz) * sy;
271
+ e[5] = (1 - 2 * (xx + zz)) * sy;
272
+ e[6] = 2 * (yz + wx) * sy;
273
+ e[7] = 0;
274
+ e[8] = 2 * (xz + wy) * sz;
275
+ e[9] = 2 * (yz - wx) * sz;
276
+ e[10] = (1 - 2 * (xx + yy)) * sz;
277
+ e[11] = 0;
278
+ e[12] = position.x;
279
+ e[13] = position.y;
280
+ e[14] = position.z;
281
+ e[15] = 1;
282
+ return out;
283
+ }
284
+ /**
285
+ * Splits an affine transformation-rotation-scale matrix back into its parts, using Babylon Lite's
286
+ * convention (`lib/math/mat4-decompose.js`): scales are the lengths of the basis columns, and a
287
+ * mirrored matrix (negative basis determinant) reports a **negative Y scale** rather than
288
+ * silently dropping the reflection. Shear is not detected.
289
+ *
290
+ * @param m - The matrix to split.
291
+ * @param outPosition - Receives the translation.
292
+ * @param outRotation - Receives the rotation as a unit quaternion.
293
+ * @param outScale - Receives the per-axis scale.
294
+ * @returns `true` on success; `false` when a basis column has (near) zero length, in which case
295
+ * the outputs are left untouched.
296
+ *
297
+ * @example
298
+ * ```ts
299
+ * Mat4.decomposeToRef(node.worldMatrix, position, rotation, scale);
300
+ * ```
301
+ */
302
+ static decomposeToRef(m, outPosition, outRotation, outScale) {
303
+ const m0 = m[0] ?? 0;
304
+ const m1 = m[1] ?? 0;
305
+ const m2 = m[2] ?? 0;
306
+ const m4 = m[4] ?? 0;
307
+ const m5 = m[5] ?? 0;
308
+ const m6 = m[6] ?? 0;
309
+ const m8 = m[8] ?? 0;
310
+ const m9 = m[9] ?? 0;
311
+ const m10 = m[10] ?? 0;
312
+ const sx = Math.hypot(m0, m1, m2);
313
+ const syAbs = Math.hypot(m4, m5, m6);
314
+ const sz = Math.hypot(m8, m9, m10);
315
+ if (sx <= 1e-8 || syAbs <= 1e-8 || sz <= 1e-8) return false;
316
+ const sy = basisDeterminant(m) < 0 ? -syAbs : syAbs;
317
+ const invSx = 1 / sx;
318
+ const invSy = 1 / sy;
319
+ const invSz = 1 / sz;
320
+ const tx = m[12] ?? 0;
321
+ const ty = m[13] ?? 0;
322
+ const tz = m[14] ?? 0;
323
+ basisToQuatToRef(m0 * invSx, m4 * invSy, m8 * invSz, m1 * invSx, m5 * invSy, m9 * invSz, m2 * invSx, m6 * invSy, m10 * invSz, outRotation);
324
+ const qx = outRotation.x;
325
+ const qy = outRotation.y;
326
+ const qz = outRotation.z;
327
+ const qw = outRotation.w;
328
+ const invLength = 1 / Math.hypot(qx, qy, qz, qw);
329
+ outRotation.set(qx * invLength, qy * invLength, qz * invLength, qw * invLength);
330
+ outPosition.set(tx, ty, tz);
331
+ outScale.set(sx, sy, sz);
332
+ return true;
333
+ }
334
+ /**
335
+ * Multiplies two matrices.
336
+ *
337
+ * @param a - The left-hand matrix.
338
+ * @param b - The right-hand matrix.
339
+ * @returns A new matrix holding `a * b`. **Allocates.**
340
+ */
341
+ static multiply(a, b) {
342
+ return Mat4.multiplyToRef(a, b, new Mat4());
343
+ }
344
+ /**
345
+ * Writes `a * b` into `out`. Acting on a column vector, `b` is applied first.
346
+ *
347
+ * @param a - The left-hand matrix.
348
+ * @param b - The right-hand matrix.
349
+ * @param out - The matrix to write; may alias `a` or `b`.
350
+ * @returns `out`.
351
+ */
352
+ static multiplyToRef(a, b, out) {
353
+ const a0 = a[0] ?? 0;
354
+ const a1 = a[1] ?? 0;
355
+ const a2 = a[2] ?? 0;
356
+ const a3 = a[3] ?? 0;
357
+ const a4 = a[4] ?? 0;
358
+ const a5 = a[5] ?? 0;
359
+ const a6 = a[6] ?? 0;
360
+ const a7 = a[7] ?? 0;
361
+ const a8 = a[8] ?? 0;
362
+ const a9 = a[9] ?? 0;
363
+ const a10 = a[10] ?? 0;
364
+ const a11 = a[11] ?? 0;
365
+ const a12 = a[12] ?? 0;
366
+ const a13 = a[13] ?? 0;
367
+ const a14 = a[14] ?? 0;
368
+ const a15 = a[15] ?? 0;
369
+ const b0 = b[0] ?? 0;
370
+ const b1 = b[1] ?? 0;
371
+ const b2 = b[2] ?? 0;
372
+ const b3 = b[3] ?? 0;
373
+ const b4 = b[4] ?? 0;
374
+ const b5 = b[5] ?? 0;
375
+ const b6 = b[6] ?? 0;
376
+ const b7 = b[7] ?? 0;
377
+ const b8 = b[8] ?? 0;
378
+ const b9 = b[9] ?? 0;
379
+ const b10 = b[10] ?? 0;
380
+ const b11 = b[11] ?? 0;
381
+ const b12 = b[12] ?? 0;
382
+ const b13 = b[13] ?? 0;
383
+ const b14 = b[14] ?? 0;
384
+ const b15 = b[15] ?? 0;
385
+ const e = out.elements;
386
+ e[0] = a0 * b0 + a4 * b1 + a8 * b2 + a12 * b3;
387
+ e[1] = a1 * b0 + a5 * b1 + a9 * b2 + a13 * b3;
388
+ e[2] = a2 * b0 + a6 * b1 + a10 * b2 + a14 * b3;
389
+ e[3] = a3 * b0 + a7 * b1 + a11 * b2 + a15 * b3;
390
+ e[4] = a0 * b4 + a4 * b5 + a8 * b6 + a12 * b7;
391
+ e[5] = a1 * b4 + a5 * b5 + a9 * b6 + a13 * b7;
392
+ e[6] = a2 * b4 + a6 * b5 + a10 * b6 + a14 * b7;
393
+ e[7] = a3 * b4 + a7 * b5 + a11 * b6 + a15 * b7;
394
+ e[8] = a0 * b8 + a4 * b9 + a8 * b10 + a12 * b11;
395
+ e[9] = a1 * b8 + a5 * b9 + a9 * b10 + a13 * b11;
396
+ e[10] = a2 * b8 + a6 * b9 + a10 * b10 + a14 * b11;
397
+ e[11] = a3 * b8 + a7 * b9 + a11 * b10 + a15 * b11;
398
+ e[12] = a0 * b12 + a4 * b13 + a8 * b14 + a12 * b15;
399
+ e[13] = a1 * b12 + a5 * b13 + a9 * b14 + a13 * b15;
400
+ e[14] = a2 * b12 + a6 * b13 + a10 * b14 + a14 * b15;
401
+ e[15] = a3 * b12 + a7 * b13 + a11 * b14 + a15 * b15;
402
+ return out;
403
+ }
404
+ /**
405
+ * Writes the inverse of `m` into `out`.
406
+ *
407
+ * @param m - The matrix to invert.
408
+ * @param out - The matrix to write; may alias `m`. Left untouched when the inverse does not exist.
409
+ * @returns `true` on success, `false` when `m` is singular. Returning a status rather than `null`
410
+ * keeps the call allocation-free (coding standards §7).
411
+ *
412
+ * @example
413
+ * ```ts
414
+ * if (!Mat4.invertToRef(world, worldToLocal)) {
415
+ * // degenerate scale — skip this entity
416
+ * }
417
+ * ```
418
+ */
419
+ static invertToRef(m, out) {
420
+ const a00 = m[0] ?? 0;
421
+ const a01 = m[1] ?? 0;
422
+ const a02 = m[2] ?? 0;
423
+ const a03 = m[3] ?? 0;
424
+ const a10 = m[4] ?? 0;
425
+ const a11 = m[5] ?? 0;
426
+ const a12 = m[6] ?? 0;
427
+ const a13 = m[7] ?? 0;
428
+ const a20 = m[8] ?? 0;
429
+ const a21 = m[9] ?? 0;
430
+ const a22 = m[10] ?? 0;
431
+ const a23 = m[11] ?? 0;
432
+ const a30 = m[12] ?? 0;
433
+ const a31 = m[13] ?? 0;
434
+ const a32 = m[14] ?? 0;
435
+ const a33 = m[15] ?? 0;
436
+ const b00 = a00 * a11 - a01 * a10;
437
+ const b01 = a00 * a12 - a02 * a10;
438
+ const b02 = a00 * a13 - a03 * a10;
439
+ const b03 = a01 * a12 - a02 * a11;
440
+ const b04 = a01 * a13 - a03 * a11;
441
+ const b05 = a02 * a13 - a03 * a12;
442
+ const b06 = a20 * a31 - a21 * a30;
443
+ const b07 = a20 * a32 - a22 * a30;
444
+ const b08 = a20 * a33 - a23 * a30;
445
+ const b09 = a21 * a32 - a22 * a31;
446
+ const b10 = a21 * a33 - a23 * a31;
447
+ const b11 = a22 * a33 - a23 * a32;
448
+ const determinant = b00 * b11 - b01 * b10 + b02 * b09 + b03 * b08 - b04 * b07 + b05 * b06;
449
+ if (Math.abs(determinant) < 1e-10) return false;
450
+ const inv = 1 / determinant;
451
+ const e = out.elements;
452
+ e[0] = (a11 * b11 - a12 * b10 + a13 * b09) * inv;
453
+ e[1] = (a02 * b10 - a01 * b11 - a03 * b09) * inv;
454
+ e[2] = (a31 * b05 - a32 * b04 + a33 * b03) * inv;
455
+ e[3] = (a22 * b04 - a21 * b05 - a23 * b03) * inv;
456
+ e[4] = (a12 * b08 - a10 * b11 - a13 * b07) * inv;
457
+ e[5] = (a00 * b11 - a02 * b08 + a03 * b07) * inv;
458
+ e[6] = (a32 * b02 - a30 * b05 - a33 * b01) * inv;
459
+ e[7] = (a20 * b05 - a22 * b02 + a23 * b01) * inv;
460
+ e[8] = (a10 * b10 - a11 * b08 + a13 * b06) * inv;
461
+ e[9] = (a01 * b08 - a00 * b10 - a03 * b06) * inv;
462
+ e[10] = (a30 * b04 - a31 * b02 + a33 * b00) * inv;
463
+ e[11] = (a21 * b02 - a20 * b04 - a23 * b00) * inv;
464
+ e[12] = (a11 * b07 - a10 * b09 - a12 * b06) * inv;
465
+ e[13] = (a00 * b09 - a01 * b07 + a02 * b06) * inv;
466
+ e[14] = (a31 * b01 - a30 * b03 - a32 * b00) * inv;
467
+ e[15] = (a20 * b03 - a21 * b01 + a22 * b00) * inv;
468
+ return true;
469
+ }
470
+ /**
471
+ * Writes the transpose of `m` into `out`.
472
+ *
473
+ * @param m - The matrix to transpose.
474
+ * @param out - The matrix to write; may alias `m`.
475
+ * @returns `out`.
476
+ */
477
+ static transposeToRef(m, out) {
478
+ const m0 = m[0] ?? 0;
479
+ const m1 = m[1] ?? 0;
480
+ const m2 = m[2] ?? 0;
481
+ const m3 = m[3] ?? 0;
482
+ const m4 = m[4] ?? 0;
483
+ const m5 = m[5] ?? 0;
484
+ const m6 = m[6] ?? 0;
485
+ const m7 = m[7] ?? 0;
486
+ const m8 = m[8] ?? 0;
487
+ const m9 = m[9] ?? 0;
488
+ const m10 = m[10] ?? 0;
489
+ const m11 = m[11] ?? 0;
490
+ const m12 = m[12] ?? 0;
491
+ const m13 = m[13] ?? 0;
492
+ const m14 = m[14] ?? 0;
493
+ const m15 = m[15] ?? 0;
494
+ const e = out.elements;
495
+ e[0] = m0;
496
+ e[1] = m4;
497
+ e[2] = m8;
498
+ e[3] = m12;
499
+ e[4] = m1;
500
+ e[5] = m5;
501
+ e[6] = m9;
502
+ e[7] = m13;
503
+ e[8] = m2;
504
+ e[9] = m6;
505
+ e[10] = m10;
506
+ e[11] = m14;
507
+ e[12] = m3;
508
+ e[13] = m7;
509
+ e[14] = m11;
510
+ e[15] = m15;
511
+ return out;
512
+ }
513
+ /**
514
+ * The full 4×4 determinant.
515
+ *
516
+ * @param m - The matrix to measure.
517
+ * @returns The determinant; zero means the matrix cannot be inverted.
518
+ */
519
+ static determinant(m) {
520
+ const a00 = m[0] ?? 0;
521
+ const a01 = m[1] ?? 0;
522
+ const a02 = m[2] ?? 0;
523
+ const a03 = m[3] ?? 0;
524
+ const a10 = m[4] ?? 0;
525
+ const a11 = m[5] ?? 0;
526
+ const a12 = m[6] ?? 0;
527
+ const a13 = m[7] ?? 0;
528
+ const a20 = m[8] ?? 0;
529
+ const a21 = m[9] ?? 0;
530
+ const a22 = m[10] ?? 0;
531
+ const a23 = m[11] ?? 0;
532
+ const a30 = m[12] ?? 0;
533
+ const a31 = m[13] ?? 0;
534
+ const a32 = m[14] ?? 0;
535
+ const a33 = m[15] ?? 0;
536
+ const b00 = a00 * a11 - a01 * a10;
537
+ const b01 = a00 * a12 - a02 * a10;
538
+ const b02 = a00 * a13 - a03 * a10;
539
+ const b03 = a01 * a12 - a02 * a11;
540
+ const b04 = a01 * a13 - a03 * a11;
541
+ const b05 = a02 * a13 - a03 * a12;
542
+ const b06 = a20 * a31 - a21 * a30;
543
+ const b07 = a20 * a32 - a22 * a30;
544
+ const b08 = a20 * a33 - a23 * a30;
545
+ const b09 = a21 * a32 - a22 * a31;
546
+ const b10 = a21 * a33 - a23 * a31;
547
+ return b00 * (a22 * a33 - a23 * a32) - b01 * b10 + b02 * b09 + b03 * b08 - b04 * b07 + b05 * b06;
548
+ }
549
+ /**
550
+ * Builds a pure translation matrix.
551
+ *
552
+ * @param x - Translation along X, in metres.
553
+ * @param y - Translation along Y, in metres.
554
+ * @param z - Translation along Z, in metres.
555
+ * @returns A new matrix. **Allocates.**
556
+ */
557
+ static translation(x, y, z) {
558
+ return Mat4.translationToRef(x, y, z, new Mat4());
559
+ }
560
+ /**
561
+ * Writes a pure translation matrix into `out`.
562
+ *
563
+ * @param x - Translation along X, in metres.
564
+ * @param y - Translation along Y, in metres.
565
+ * @param z - Translation along Z, in metres.
566
+ * @param out - The matrix to write.
567
+ * @returns `out`.
568
+ */
569
+ static translationToRef(x, y, z, out) {
570
+ const e = out.identity().elements;
571
+ e[12] = x;
572
+ e[13] = y;
573
+ e[14] = z;
574
+ return out;
575
+ }
576
+ /**
577
+ * Builds a pure scaling matrix.
578
+ *
579
+ * @param x - Scale along X.
580
+ * @param y - Scale along Y.
581
+ * @param z - Scale along Z.
582
+ * @returns A new matrix. **Allocates.**
583
+ */
584
+ static scaling(x, y, z) {
585
+ return Mat4.scalingToRef(x, y, z, new Mat4());
586
+ }
587
+ /**
588
+ * Writes a pure scaling matrix into `out`.
589
+ *
590
+ * @param x - Scale along X.
591
+ * @param y - Scale along Y.
592
+ * @param z - Scale along Z.
593
+ * @param out - The matrix to write.
594
+ * @returns `out`.
595
+ */
596
+ static scalingToRef(x, y, z, out) {
597
+ const e = out.identity().elements;
598
+ e[0] = x;
599
+ e[5] = y;
600
+ e[10] = z;
601
+ return out;
602
+ }
603
+ /**
604
+ * Builds a pure rotation matrix from a quaternion.
605
+ *
606
+ * @param q - The rotation; assumed to be a unit quaternion.
607
+ * @returns A new matrix. **Allocates.**
608
+ */
609
+ static fromQuat(q) {
610
+ return Mat4.fromQuatToRef(q, new Mat4());
611
+ }
612
+ /**
613
+ * Writes a pure rotation matrix into `out`.
614
+ *
615
+ * @param q - The rotation; assumed to be a unit quaternion.
616
+ * @param out - The matrix to write.
617
+ * @returns `out`.
618
+ */
619
+ static fromQuatToRef(q, out) {
620
+ return Mat4.composeToRef(ZERO_TRANSLATION, q, UNIT_SCALE, out);
621
+ }
622
+ /**
623
+ * Builds a left-handed view matrix that places the camera at `eye` looking at `target`.
624
+ *
625
+ * @param eye - The camera position, in metres.
626
+ * @param target - The point to look at, in metres.
627
+ * @param up - The camera's up direction.
628
+ * @returns A new matrix. **Allocates.**
629
+ */
630
+ static lookAtLH(eye, target, up) {
631
+ return Mat4.lookAtLHToRef(eye, target, up, new Mat4());
632
+ }
633
+ /**
634
+ * Writes a left-handed view matrix into `out`. Reproduces Babylon Lite's `mat4LookAtLHToRef`,
635
+ * including its degenerate-input behaviour: when `eye` and `target` coincide, or when `up` is
636
+ * parallel to the view direction, `out` becomes the identity.
637
+ *
638
+ * @param eye - The camera position, in metres.
639
+ * @param target - The point to look at, in metres.
640
+ * @param up - The camera's up direction.
641
+ * @param out - The matrix to write.
642
+ * @returns `out`.
643
+ */
644
+ static lookAtLHToRef(eye, target, up, out) {
645
+ const ex = eye.x;
646
+ const ey = eye.y;
647
+ const ez = eye.z;
648
+ let zx = target.x - ex;
649
+ let zy = target.y - ey;
650
+ let zz = target.z - ez;
651
+ const zLength = Math.hypot(zx, zy, zz);
652
+ if (zLength < 1e-10) return out.identity();
653
+ const invZ = 1 / zLength;
654
+ zx *= invZ;
655
+ zy *= invZ;
656
+ zz *= invZ;
657
+ let xx = up.y * zz - up.z * zy;
658
+ let xy = up.z * zx - up.x * zz;
659
+ let xz = up.x * zy - up.y * zx;
660
+ const xLength = Math.hypot(xx, xy, xz);
661
+ if (xLength < 1e-10) return out.identity();
662
+ const invX = 1 / xLength;
663
+ xx *= invX;
664
+ xy *= invX;
665
+ xz *= invX;
666
+ const yx = zy * xz - zz * xy;
667
+ const yy = zz * xx - zx * xz;
668
+ const yz = zx * xy - zy * xx;
669
+ const e = out.elements;
670
+ e[0] = xx;
671
+ e[1] = yx;
672
+ e[2] = zx;
673
+ e[3] = 0;
674
+ e[4] = xy;
675
+ e[5] = yy;
676
+ e[6] = zy;
677
+ e[7] = 0;
678
+ e[8] = xz;
679
+ e[9] = yz;
680
+ e[10] = zz;
681
+ e[11] = 0;
682
+ e[12] = -(xx * ex + xy * ey + xz * ez);
683
+ e[13] = -(yx * ex + yy * ey + yz * ez);
684
+ e[14] = -(zx * ex + zy * ey + zz * ez);
685
+ e[15] = 1;
686
+ return out;
687
+ }
688
+ /**
689
+ * Builds a left-handed perspective projection.
690
+ *
691
+ * @param fovDegrees - The vertical field of view, in degrees.
692
+ * @param aspect - The viewport's width divided by its height.
693
+ * @param near - The near plane distance, in metres.
694
+ * @param far - The far plane distance, in metres.
695
+ * @returns A new matrix. **Allocates.**
696
+ */
697
+ static perspectiveLH(fovDegrees, aspect, near, far) {
698
+ return Mat4.perspectiveLHToRef(fovDegrees, aspect, near, far, new Mat4());
699
+ }
700
+ /**
701
+ * Writes a left-handed perspective projection into `out`, matching Babylon Lite's
702
+ * `mat4PerspectiveLHToRef` — which is a **reverse-depth** projection: the near plane maps to
703
+ * clip-space depth 1 and the far plane to 0, the arrangement that keeps float depth precise.
704
+ *
705
+ * @param fovDegrees - The vertical field of view, in degrees.
706
+ * @param aspect - The viewport's width divided by its height.
707
+ * @param near - The near plane distance, in metres.
708
+ * @param far - The far plane distance, in metres.
709
+ * @param out - The matrix to write.
710
+ * @returns `out`.
711
+ */
712
+ static perspectiveLHToRef(fovDegrees, aspect, near, far, out) {
713
+ const cot = 1 / Math.tan(degToRad(fovDegrees) * .5);
714
+ const range = far - near;
715
+ const e = out.elements;
716
+ e[0] = cot / aspect;
717
+ e[1] = 0;
718
+ e[2] = 0;
719
+ e[3] = 0;
720
+ e[4] = 0;
721
+ e[5] = cot;
722
+ e[6] = 0;
723
+ e[7] = 0;
724
+ e[8] = 0;
725
+ e[9] = 0;
726
+ e[10] = -near / range;
727
+ e[11] = 1;
728
+ e[12] = 0;
729
+ e[13] = 0;
730
+ e[14] = far * near / range;
731
+ e[15] = 0;
732
+ return out;
733
+ }
734
+ /**
735
+ * Builds a centred left-handed orthographic projection.
736
+ *
737
+ * @param width - The view width, in metres.
738
+ * @param height - The view height, in metres.
739
+ * @param near - The near plane distance, in metres.
740
+ * @param far - The far plane distance, in metres.
741
+ * @returns A new matrix. **Allocates.**
742
+ */
743
+ static orthoLH(width, height, near, far) {
744
+ return Mat4.orthoLHToRef(width, height, near, far, new Mat4());
745
+ }
746
+ /**
747
+ * Writes a centred left-handed orthographic projection into `out`, with the same reverse-depth
748
+ * convention as {@link Mat4.perspectiveLHToRef}.
749
+ *
750
+ * @param width - The view width, in metres.
751
+ * @param height - The view height, in metres.
752
+ * @param near - The near plane distance, in metres.
753
+ * @param far - The far plane distance, in metres.
754
+ * @param out - The matrix to write.
755
+ * @returns `out`.
756
+ */
757
+ static orthoLHToRef(width, height, near, far, out) {
758
+ const halfWidth = width * .5;
759
+ const halfHeight = height * .5;
760
+ return Mat4.orthoOffCenterLHToRef(-halfWidth, halfWidth, -halfHeight, halfHeight, near, far, out);
761
+ }
762
+ /**
763
+ * Writes an off-centre left-handed orthographic projection into `out`, reproducing Babylon Lite's
764
+ * `mat4OrthoOffCenterLHToRef` (reverse depth).
765
+ *
766
+ * @param left - The left clip plane, in metres.
767
+ * @param right - The right clip plane, in metres.
768
+ * @param bottom - The bottom clip plane, in metres.
769
+ * @param top - The top clip plane, in metres.
770
+ * @param near - The near plane distance, in metres.
771
+ * @param far - The far plane distance, in metres.
772
+ * @param out - The matrix to write.
773
+ * @returns `out`.
774
+ */
775
+ static orthoOffCenterLHToRef(left, right, bottom, top, near, far, out) {
776
+ const range = far - near;
777
+ const e = out.elements;
778
+ e[0] = 2 / (right - left);
779
+ e[1] = 0;
780
+ e[2] = 0;
781
+ e[3] = 0;
782
+ e[4] = 0;
783
+ e[5] = 2 / (top - bottom);
784
+ e[6] = 0;
785
+ e[7] = 0;
786
+ e[8] = 0;
787
+ e[9] = 0;
788
+ e[10] = -1 / range;
789
+ e[11] = 0;
790
+ e[12] = (left + right) / (left - right);
791
+ e[13] = (top + bottom) / (bottom - top);
792
+ e[14] = far / range;
793
+ e[15] = 1;
794
+ return out;
795
+ }
796
+ /**
797
+ * Reads a matrix's translation.
798
+ *
799
+ * @param m - The matrix to read.
800
+ * @param out - The vector to write.
801
+ * @returns `out`.
802
+ */
803
+ static getTranslationToRef(m, out) {
804
+ out.set(m[12] ?? 0, m[13] ?? 0, m[14] ?? 0);
805
+ return out;
806
+ }
807
+ /**
808
+ * Reads a matrix's per-axis scale as the lengths of its basis columns, negating Y for a mirrored
809
+ * matrix exactly as {@link Mat4.decomposeToRef} does.
810
+ *
811
+ * @param m - The matrix to read.
812
+ * @param out - The vector to write.
813
+ * @returns `out`.
814
+ */
815
+ static getScaleToRef(m, out) {
816
+ const sx = Math.hypot(m[0] ?? 0, m[1] ?? 0, m[2] ?? 0);
817
+ const syAbs = Math.hypot(m[4] ?? 0, m[5] ?? 0, m[6] ?? 0);
818
+ const sz = Math.hypot(m[8] ?? 0, m[9] ?? 0, m[10] ?? 0);
819
+ out.set(sx, basisDeterminant(m) < 0 ? -syAbs : syAbs, sz);
820
+ return out;
821
+ }
822
+ /**
823
+ * Reads a matrix's rotation, dividing the scale out of the basis first.
824
+ *
825
+ * @param m - The matrix to read.
826
+ * @param out - The quaternion to write. Left untouched when a basis column has zero length.
827
+ * @returns `out`.
828
+ */
829
+ static getRotationToRef(m, out) {
830
+ const m0 = m[0] ?? 0;
831
+ const m1 = m[1] ?? 0;
832
+ const m2 = m[2] ?? 0;
833
+ const m4 = m[4] ?? 0;
834
+ const m5 = m[5] ?? 0;
835
+ const m6 = m[6] ?? 0;
836
+ const m8 = m[8] ?? 0;
837
+ const m9 = m[9] ?? 0;
838
+ const m10 = m[10] ?? 0;
839
+ const sx = Math.hypot(m0, m1, m2);
840
+ const syAbs = Math.hypot(m4, m5, m6);
841
+ const sz = Math.hypot(m8, m9, m10);
842
+ if (sx <= 1e-8 || syAbs <= 1e-8 || sz <= 1e-8) return out;
843
+ const invSx = 1 / sx;
844
+ const invSy = 1 / (basisDeterminant(m) < 0 ? -syAbs : syAbs);
845
+ const invSz = 1 / sz;
846
+ basisToQuatToRef(m0 * invSx, m4 * invSy, m8 * invSz, m1 * invSx, m5 * invSy, m9 * invSz, m2 * invSx, m6 * invSy, m10 * invSz, out);
847
+ const invLength = 1 / Math.hypot(out.x, out.y, out.z, out.w);
848
+ out.set(out.x * invLength, out.y * invLength, out.z * invLength, out.w * invLength);
849
+ return out;
850
+ }
851
+ /**
852
+ * Transforms a point by a matrix, applying translation and the perspective divide.
853
+ *
854
+ * @param m - The transformation.
855
+ * @param point - The point to transform, in metres.
856
+ * @param out - The vector to write; may alias `point`.
857
+ * @returns `out`.
858
+ */
859
+ static transformPointToRef(m, point, out) {
860
+ const x = point.x;
861
+ const y = point.y;
862
+ const z = point.z;
863
+ const rx = x * (m[0] ?? 0) + y * (m[4] ?? 0) + z * (m[8] ?? 0) + (m[12] ?? 0);
864
+ const ry = x * (m[1] ?? 0) + y * (m[5] ?? 0) + z * (m[9] ?? 0) + (m[13] ?? 0);
865
+ const rz = x * (m[2] ?? 0) + y * (m[6] ?? 0) + z * (m[10] ?? 0) + (m[14] ?? 0);
866
+ const invW = 1 / (x * (m[3] ?? 0) + y * (m[7] ?? 0) + z * (m[11] ?? 0) + (m[15] ?? 0));
867
+ out.set(rx * invW, ry * invW, rz * invW);
868
+ return out;
869
+ }
870
+ /**
871
+ * Transforms a direction by a matrix, ignoring translation. Note that this is the plain basis
872
+ * transform: a non-uniformly scaled matrix needs its inverse-transpose to keep normals correct.
873
+ *
874
+ * @param m - The transformation.
875
+ * @param direction - The direction to transform.
876
+ * @param out - The vector to write; may alias `direction`.
877
+ * @returns `out`.
878
+ */
879
+ static transformDirectionToRef(m, direction, out) {
880
+ const x = direction.x;
881
+ const y = direction.y;
882
+ const z = direction.z;
883
+ out.set(x * (m[0] ?? 0) + y * (m[4] ?? 0) + z * (m[8] ?? 0), x * (m[1] ?? 0) + y * (m[5] ?? 0) + z * (m[9] ?? 0), x * (m[2] ?? 0) + y * (m[6] ?? 0) + z * (m[10] ?? 0));
884
+ return out;
885
+ }
886
+ /**
887
+ * Compares two matrices element by element, with a tolerance.
888
+ *
889
+ * @param a - The first matrix.
890
+ * @param b - The second matrix.
891
+ * @param epsilon - The largest per-element difference still considered equal.
892
+ * @returns `true` when every element matches within `epsilon`.
893
+ */
894
+ static equalsWithEpsilon(a, b, epsilon = EPSILON) {
895
+ for (let i = 0; i < 16; i++) if (Math.abs((a[i] ?? 0) - (b[i] ?? 0)) > epsilon) return false;
896
+ return true;
897
+ }
898
+ };
899
+ /**
900
+ * The zero translation {@link Mat4.fromQuatToRef} composes with. Module-scope constant, frozen so it
901
+ * can never be written through.
902
+ */
903
+ const ZERO_TRANSLATION = Object.freeze({
904
+ x: 0,
905
+ y: 0,
906
+ z: 0
907
+ });
908
+ /**
909
+ * The unit scale {@link Mat4.fromQuatToRef} composes with.
910
+ */
911
+ const UNIT_SCALE = Object.freeze({
912
+ x: 1,
913
+ y: 1,
914
+ z: 1
915
+ });
916
+ /**
917
+ * A frozen identity matrix, for the common case of "no transform". It is a plain {@link Mat4Like}
918
+ * rather than a {@link Mat4} because a `Float32Array` cannot be frozen — pass it to anything that
919
+ * reads a matrix, and use `new Mat4()` when you need one you can write to.
920
+ *
921
+ * @example
922
+ * ```ts
923
+ * Mat4.transformPointToRef(MAT4_IDENTITY, point, out); // copies the point
924
+ * ```
925
+ *
926
+ * @public
927
+ */
928
+ const MAT4_IDENTITY = Object.freeze({
929
+ length: 16,
930
+ 0: 1,
931
+ 1: 0,
932
+ 2: 0,
933
+ 3: 0,
934
+ 4: 0,
935
+ 5: 1,
936
+ 6: 0,
937
+ 7: 0,
938
+ 8: 0,
939
+ 9: 0,
940
+ 10: 1,
941
+ 11: 0,
942
+ 12: 0,
943
+ 13: 0,
944
+ 14: 0,
945
+ 15: 1
946
+ });
947
+ //#endregion
948
+ //#region src/lite/node.ts
949
+ /** The single key ignifx owns inside Lite's open `metadata` record. */
950
+ const METADATA_KEY = "ignifx";
951
+ /** Number of elements in a 4x4 matrix. */
952
+ const MATRIX_LENGTH = 16;
953
+ /**
954
+ * Creates a pure transform node at the origin with an identity rotation and unit scale.
955
+ *
956
+ * @remarks
957
+ * The node is deliberately **not** added to any Lite scene: a transform node is only a matrix
958
+ * provider, and `worldMatrix` is valid the moment the node exists (see rule 5 in the module
959
+ * documentation). Renderable Lite objects created by components are parented under it and added
960
+ * with `addToScene` separately.
961
+ *
962
+ * @param name - A human-readable name; Lite never uses it for lookup and it need not be unique.
963
+ * @returns A fresh, unparented transform node.
964
+ *
965
+ * @example
966
+ * ```ts
967
+ * const node = createNode("Player");
968
+ * node.position.set(1, 2, 3);
969
+ * ```
970
+ *
971
+ * @internal
972
+ */
973
+ function createNode(name) {
974
+ return createTransformNode(name);
975
+ }
976
+ /**
977
+ * Releases a pure transform node.
978
+ *
979
+ * @remarks
980
+ * Lite requires nothing to release a transform node that was never added to a scene: verified in
981
+ * `lib/scene/transform-node.js` and `lib/scene/scene-node.js`, the node is a plain object holding
982
+ * three observable values, one `Float32Array` for the cached world matrix, and closures — no GPU
983
+ * resource, no ref count, no scene registry. (Reference counting in `lib/resource/ref-count.js`
984
+ * applies to meshes and their GPU buffers only, and `disposeScene` never walks transform nodes.)
985
+ *
986
+ * What *does* need doing is breaking the parent link: a linked parent keeps a reference to this
987
+ * node's world-matrix state so it can invalidate it, so a node dropped while still parented is
988
+ * retained by its parent. This function therefore unlinks the node and drops the ignifx tag. It
989
+ * leaves the node's own `children` alone: the kernel destroys children before parents
990
+ * (`docs/architecture/01-lifecycle-and-time.md` §3 step 9), so each child unlinks itself first.
991
+ *
992
+ * @param node - A node from {@link createNode}.
993
+ *
994
+ * @internal
995
+ */
996
+ function disposeNode(node) {
997
+ linkParent(node, null);
998
+ const metadata = node.metadata;
999
+ if (metadata !== void 0) delete metadata[METADATA_KEY];
1000
+ }
1001
+ /**
1002
+ * Links `child` under `parent`, **keeping the child's local values** — its world transform moves
1003
+ * with the new parent. This is `setParent(parent, { worldPositionStays: false })` in
1004
+ * `docs/architecture/02-scene-graph.md` §5.1.
1005
+ *
1006
+ * @remarks
1007
+ * Lite has no public helper for this case (its own `setParent` preserves the world transform), so
1008
+ * the adapter does the linking itself: it assigns `child.parent`, which is the setter that
1009
+ * re-registers the child's world-matrix state with the new parent and invalidates the subtree, and
1010
+ * maintains the `children` arrays on both the old and the new parent so tree traversal stays
1011
+ * consistent. Passing the parent the child already has is a no-op.
1012
+ *
1013
+ * @param child - The node to move.
1014
+ * @param parent - The new parent, or `null` to detach the child to world space.
1015
+ *
1016
+ * @example
1017
+ * ```ts
1018
+ * linkParent(child, parent); // child keeps localPosition; its world position changes
1019
+ * ```
1020
+ *
1021
+ * @internal
1022
+ */
1023
+ function linkParent(child, parent) {
1024
+ const previous = child.parent;
1025
+ if (previous === parent) return;
1026
+ const previousChildren = childrenOf(previous);
1027
+ if (previousChildren !== null) {
1028
+ const index = previousChildren.indexOf(child);
1029
+ if (index >= 0) previousChildren.splice(index, 1);
1030
+ }
1031
+ child.parent = parent;
1032
+ if (parent !== null && !parent.children.includes(child)) parent.children.push(child);
1033
+ }
1034
+ /**
1035
+ * Reparents `child` under `parent` **keeping its world transform**, by delegating to Lite's own
1036
+ * `setParent`. This is `setParent(parent, { worldPositionStays: true })`, the ignifx default
1037
+ * (`docs/architecture/02-scene-graph.md` §5.1).
1038
+ *
1039
+ * @remarks
1040
+ * Lite snapshots the child's world matrix, relinks the node (maintaining both `children` arrays),
1041
+ * then decomposes `inverse(parentWorld) × childWorld` back into local TRS. Two documented caveats
1042
+ * carry straight through to ignifx:
1043
+ *
1044
+ * - **Singular parent matrices.** When the parent's world matrix has a collapsed axis it cannot be
1045
+ * inverted, so no local transform can reproduce the child's world. Lite then keeps the parent
1046
+ * link and copies the child's world *position* into its local position, leaving rotation and
1047
+ * scale uncompensated. Non-uniform-but-invertible parents are fine; zero scale on any axis is
1048
+ * not.
1049
+ * - **Canonical, not sign-faithful, decomposition.** The local TRS comes from `mat4Decompose`,
1050
+ * which folds a reflection into a negative Y scale. The world matrix is reproduced exactly, but a
1051
+ * child that had a negative X scale comes back with a negative Y scale and a different rotation.
1052
+ *
1053
+ * A third caveat in Lite's TSDoc — that `child.parent` links are only established by `addToScene`,
1054
+ * so a node from a freshly loaded asset must have its container added before it is reparented —
1055
+ * does not apply to nodes ignifx creates, because {@link linkParent} establishes the link itself.
1056
+ *
1057
+ * @param child - The node to move.
1058
+ * @param parent - The new parent, or `null` to detach the child to world space.
1059
+ *
1060
+ * @internal
1061
+ */
1062
+ function reparentKeepingWorld(child, parent) {
1063
+ setParent(child, parent);
1064
+ }
1065
+ /**
1066
+ * Copies a node's world matrix into `out`.
1067
+ *
1068
+ * @remarks
1069
+ * Allocation-free on the ignifx side, which is why the destination is a parameter: Lite's
1070
+ * `worldMatrix` getter may recompute up the parent chain, and the object it returns is Lite's own
1071
+ * cache — never hold on to it. Lite documents `Mat4` as opaque ("callers MUST NOT depend on the
1072
+ * underlying storage"); it is a `Float32Array` in 1.27.0 (`lib/math/_matrix-allocator.js`), so
1073
+ * copying element by element is the only supported read.
1074
+ *
1075
+ * @param node - The node to read.
1076
+ * @param out - A sink of at least 16 elements, written in column-major order.
1077
+ * @returns `out`, for chaining.
1078
+ *
1079
+ * @internal
1080
+ */
1081
+ function readWorldMatrix(node, out) {
1082
+ const matrix = node.worldMatrix;
1083
+ for (let index = 0; index < MATRIX_LENGTH; index += 1) out[index] = matrix[index] ?? 0;
1084
+ return out;
1085
+ }
1086
+ /**
1087
+ * Reads a node's world-matrix version — the counter that increases whenever the node's world
1088
+ * matrix is invalidated, by its own TRS or by any ancestor's.
1089
+ *
1090
+ * @remarks
1091
+ * Snapshot it to detect movement without comparing matrices; systems that maintain acceleration
1092
+ * structures do exactly that (`docs/architecture/02-scene-graph.md` §9). The counter is
1093
+ * monotonically increasing but not a change *count*: it moves on invalidation, not on
1094
+ * recomputation, and a bulk `position.set(...)` bumps it even when the values are unchanged.
1095
+ *
1096
+ * @param node - The node to read.
1097
+ * @returns The current version.
1098
+ *
1099
+ * @internal
1100
+ */
1101
+ function worldMatrixVersion(node) {
1102
+ return node.worldMatrixVersion;
1103
+ }
1104
+ /**
1105
+ * Shows or hides **one** node, without touching its subtree.
1106
+ *
1107
+ * @remarks
1108
+ * Lite's `visible` is per node — the renderer reads each node's own flag, and `setSubtreeVisible`
1109
+ * is only a bulk helper that materialises a cascade at write time. ignifx already materialises
1110
+ * `activeInHierarchy` over the subtree itself, so it writes one flag per entity: correct for a
1111
+ * subtree that mixes active and inactive entities, and linear rather than quadratic.
1112
+ *
1113
+ * @param node - The node to show or hide.
1114
+ * @param visible - `true` to show it, `false` to hide it.
1115
+ *
1116
+ * @internal
1117
+ */
1118
+ function setNodeSelfVisible(node, visible) {
1119
+ node.visible = visible;
1120
+ }
1121
+ /**
1122
+ * Writes the ignifx identity into a node's Lite metadata bag, under the single `ignifx` key.
1123
+ *
1124
+ * @remarks
1125
+ * `LiteMetadata` is an open record (`{ gltf?: GltfMetadata; [key: string]: unknown }`), so the tag
1126
+ * coexists with the `gltf.extras` a glTF load writes. The metadata object is created on demand;
1127
+ * nodes ignifx never tags keep `metadata` undefined.
1128
+ *
1129
+ * @param node - The node to tag.
1130
+ * @param tag - The owning entity, and the component that created the node when it is not the
1131
+ * entity's own transform.
1132
+ *
1133
+ * @internal
1134
+ */
1135
+ function tagNode(node, tag) {
1136
+ const metadata = node.metadata ??= {};
1137
+ metadata[METADATA_KEY] = tag;
1138
+ }
1139
+ /**
1140
+ * Reads the ignifx identity back from a node.
1141
+ *
1142
+ * @param node - The node to read; it may be any Lite node, including one ignifx never created.
1143
+ * @returns The tag {@link tagNode} wrote, or `null` when the node carries none.
1144
+ *
1145
+ * @internal
1146
+ */
1147
+ function readNodeTag(node) {
1148
+ const metadata = node.metadata;
1149
+ if (metadata === void 0) return null;
1150
+ const value = metadata[METADATA_KEY];
1151
+ if (typeof value !== "object" || value === null || !("entity" in value)) return null;
1152
+ const entity = value.entity;
1153
+ if (typeof entity !== "number") return null;
1154
+ const component = "component" in value ? value.component : void 0;
1155
+ return typeof component === "number" ? {
1156
+ entity,
1157
+ component
1158
+ } : { entity };
1159
+ }
1160
+ /**
1161
+ * The `children` array of a world-matrix provider, when it has one.
1162
+ *
1163
+ * @remarks
1164
+ * `SceneNode.parent` is typed as the minimal {@link IWorldMatrixProvider}, which declares no
1165
+ * `children`, but every parent ignifx links is a scene node. Lite's own `setParent` solves this the
1166
+ * same way (`lib/scene/set-parent.js`), and the array check keeps a non-node provider — a camera,
1167
+ * say — from being treated as a tree node.
1168
+ *
1169
+ * @param provider - The candidate parent.
1170
+ * @returns The provider's children, or `null` when it is not a tree node.
1171
+ */
1172
+ function childrenOf(provider) {
1173
+ if (provider === null || !("children" in provider)) return null;
1174
+ const children = provider.children;
1175
+ return Array.isArray(children) ? children : null;
1176
+ }
1177
+ /**
1178
+ * The node's local position as a live, writable view.
1179
+ *
1180
+ * @remarks
1181
+ * Zero-copy: the returned object *is* Lite's `ObservableVec3` over the node's TRS, so `.x += 1`,
1182
+ * `.set(x, y, z)`, and `.copyFrom(v)` write straight through and invalidate the subtree's world
1183
+ * matrices (`docs/architecture/02-scene-graph.md` §5). Never hold it past the node's lifetime.
1184
+ *
1185
+ * @param node - The node to view.
1186
+ * @returns The live local position.
1187
+ *
1188
+ * @internal
1189
+ */
1190
+ function localPosition(node) {
1191
+ return node.position;
1192
+ }
1193
+ /**
1194
+ * The node's local rotation as a live, writable view.
1195
+ *
1196
+ * @param node - The node to view.
1197
+ * @returns The live local rotation quaternion.
1198
+ *
1199
+ * @internal
1200
+ */
1201
+ function localRotation(node) {
1202
+ return node.rotationQuaternion;
1203
+ }
1204
+ /**
1205
+ * The node's local scale as a live, writable view.
1206
+ *
1207
+ * @param node - The node to view.
1208
+ * @returns The live local scale.
1209
+ *
1210
+ * @internal
1211
+ */
1212
+ function localScale(node) {
1213
+ return node.scaling;
1214
+ }
1215
+ /**
1216
+ * Renames a node.
1217
+ *
1218
+ * @remarks
1219
+ * Lite never uses the name for lookup, so this is purely for debugging and for the names that show
1220
+ * up in Lite-side tooling; ignifx keeps `Entity.name` as the source of truth and mirrors it here.
1221
+ *
1222
+ * @param node - The node to rename.
1223
+ * @param name - The new name.
1224
+ *
1225
+ * @internal
1226
+ */
1227
+ function setNodeName(node, name) {
1228
+ node.name = name;
1229
+ }
1230
+ /**
1231
+ * The parent a node is currently linked to, when that parent is itself a scene node.
1232
+ *
1233
+ * @param node - The node to read.
1234
+ * @returns The parent node, or `null` when the node is unparented or its parent is a bare
1235
+ * world-matrix provider such as a camera.
1236
+ *
1237
+ * @internal
1238
+ */
1239
+ function parentNode(node) {
1240
+ const parent = node.parent;
1241
+ if (parent === null || !("children" in parent)) return null;
1242
+ return parent;
1243
+ }
1244
+ //#endregion
1245
+ //#region src/lite/gpu/mesh.ts
1246
+ /**
1247
+ * Creates a box template.
1248
+ *
1249
+ * @param engine - The engine that owns the GPU buffers.
1250
+ * @param options - A uniform size, or per-axis dimensions.
1251
+ * @returns The mesh. It belongs to no scene yet.
1252
+ *
1253
+ * @example
1254
+ * ```ts
1255
+ * const template = createBoxMesh(engine, { size: 2 });
1256
+ * const instance = cloneMeshUnderNode(template, entityNode);
1257
+ * addMeshToScene(scene, instance);
1258
+ * ```
1259
+ *
1260
+ * @internal
1261
+ */
1262
+ function createBoxMesh(engine, options) {
1263
+ return createBox(engine, options);
1264
+ }
1265
+ /**
1266
+ * Creates a sphere template.
1267
+ *
1268
+ * @param engine - The engine that owns the GPU buffers.
1269
+ * @param options - Segment count and diameters.
1270
+ * @returns The mesh.
1271
+ *
1272
+ * @internal
1273
+ */
1274
+ function createSphereMesh(engine, options) {
1275
+ return createSphere(engine, options);
1276
+ }
1277
+ /**
1278
+ * Creates a plane template in the XY plane.
1279
+ *
1280
+ * @param engine - The engine that owns the GPU buffers.
1281
+ * @param options - Size, or width and height.
1282
+ * @returns The mesh.
1283
+ *
1284
+ * @internal
1285
+ */
1286
+ function createPlaneMesh(engine, options) {
1287
+ return createPlane(engine, options);
1288
+ }
1289
+ /**
1290
+ * Creates a subdivided ground template in the XZ plane.
1291
+ *
1292
+ * @param engine - The engine that owns the GPU buffers.
1293
+ * @param options - Width, height, subdivisions, and UV scale.
1294
+ * @returns The mesh.
1295
+ *
1296
+ * @internal
1297
+ */
1298
+ function createGroundMesh(engine, options) {
1299
+ return createGround(engine, options);
1300
+ }
1301
+ /**
1302
+ * Creates a cylinder template along the Y axis.
1303
+ *
1304
+ * @param engine - The engine that owns the GPU buffers.
1305
+ * @param options - Height, diameters, and tessellation.
1306
+ * @returns The mesh.
1307
+ *
1308
+ * @internal
1309
+ */
1310
+ function createCylinderMesh(engine, options) {
1311
+ return createCylinder(engine, options);
1312
+ }
1313
+ /**
1314
+ * Creates a capsule template along the Y axis.
1315
+ *
1316
+ * @remarks
1317
+ * `height` is the **total** height including both caps (`index.d.ts` 1523), which is the same
1318
+ * convention `@ignifx/physics`'s capsule collider uses, so a renderer and a collider built from one
1319
+ * pair of numbers line up.
1320
+ *
1321
+ * @param engine - The engine that owns the GPU buffers.
1322
+ * @param options - Height, radius, and tessellation.
1323
+ * @returns The mesh.
1324
+ *
1325
+ * @internal
1326
+ */
1327
+ function createCapsuleMesh(engine, options) {
1328
+ return createCapsule(engine, options);
1329
+ }
1330
+ /**
1331
+ * Creates a torus template in the XZ plane.
1332
+ *
1333
+ * @param engine - The engine that owns the GPU buffers.
1334
+ * @param options - Diameter, thickness, and tessellation.
1335
+ * @returns The mesh.
1336
+ *
1337
+ * @internal
1338
+ */
1339
+ function createTorusMesh(engine, options) {
1340
+ return createTorus(engine, options);
1341
+ }
1342
+ /**
1343
+ * Creates a mesh from raw vertex data.
1344
+ *
1345
+ * @remarks
1346
+ * Lite keeps a reference to the arrays that are handed in — it does not copy them — and uses them
1347
+ * for CPU ray picking and bounds (`lib/mesh/mesh-factories.js`). Callers must not mutate them
1348
+ * afterwards.
1349
+ *
1350
+ * @param engine - The engine that owns the GPU buffers.
1351
+ * @param name - A debug name.
1352
+ * @param positions - Three floats per vertex.
1353
+ * @param normals - Three floats per vertex.
1354
+ * @param indices - Three indices per triangle.
1355
+ * @param uvs - Two floats per vertex, or omitted.
1356
+ * @param uvs2 - Two floats per vertex for the second UV set, or omitted.
1357
+ * @param tangents - Four floats per vertex, or omitted.
1358
+ * @param colors - Four floats per vertex, or omitted.
1359
+ * @returns The mesh.
1360
+ *
1361
+ * @internal
1362
+ */
1363
+ function createMeshFromGeometry(engine, name, positions, normals, indices, uvs, uvs2, tangents, colors) {
1364
+ return createMeshFromData(engine, name, positions, normals, indices, uvs, uvs2, tangents, colors);
1365
+ }
1366
+ /**
1367
+ * Re-uploads part of a mesh's position buffer.
1368
+ *
1369
+ * @remarks
1370
+ * A no-op range is accepted; an out-of-range one, or a mesh whose GPU geometry has co-owners,
1371
+ * throws a Lite error (see the module note). It does **not** refresh the CPU picking geometry or
1372
+ * the bounds.
1373
+ *
1374
+ * @param engine - The engine that owns the buffer.
1375
+ * @param mesh - The mesh to update.
1376
+ * @param positions - Three floats per vertex, read from index 0.
1377
+ * @param vertexOffset - The first destination vertex to overwrite.
1378
+ * @param vertexCount - How many vertices to write.
1379
+ *
1380
+ * @internal
1381
+ */
1382
+ function updateMeshPositions$1(engine, mesh, positions, vertexOffset, vertexCount) {
1383
+ updateMeshPositions(engine, mesh, positions, vertexOffset, vertexCount);
1384
+ }
1385
+ /**
1386
+ * Re-uploads part of a mesh's normal buffer.
1387
+ *
1388
+ * @param engine - The engine that owns the buffer.
1389
+ * @param mesh - The mesh to update.
1390
+ * @param normals - Three floats per vertex.
1391
+ * @param vertexOffset - The first destination vertex to overwrite.
1392
+ * @param vertexCount - How many vertices to write.
1393
+ *
1394
+ * @internal
1395
+ */
1396
+ function updateMeshNormals$1(engine, mesh, normals, vertexOffset, vertexCount) {
1397
+ updateMeshNormals(engine, mesh, normals, vertexOffset, vertexCount);
1398
+ }
1399
+ /**
1400
+ * Re-uploads part of a mesh's UV buffer.
1401
+ *
1402
+ * @remarks
1403
+ * Lite makes it a no-op when the mesh was created without UVs, rather than an error.
1404
+ *
1405
+ * @param engine - The engine that owns the buffer.
1406
+ * @param mesh - The mesh to update.
1407
+ * @param uvs - Two floats per vertex.
1408
+ * @param vertexOffset - The first destination vertex to overwrite.
1409
+ * @param vertexCount - How many vertices to write.
1410
+ *
1411
+ * @internal
1412
+ */
1413
+ function updateMeshUvs$1(engine, mesh, uvs, vertexOffset, vertexCount) {
1414
+ updateMeshUvs(engine, mesh, uvs, vertexOffset, vertexCount);
1415
+ }
1416
+ /**
1417
+ * Re-uploads part of a mesh's vertex-colour buffer.
1418
+ *
1419
+ * @remarks
1420
+ * The colour attribute is `vec4`, and Lite makes the call a no-op when the mesh was created without
1421
+ * colours.
1422
+ *
1423
+ * @param engine - The engine that owns the buffer.
1424
+ * @param mesh - The mesh to update.
1425
+ * @param colors - Four floats per vertex.
1426
+ * @param vertexOffset - The first destination vertex to overwrite.
1427
+ * @param vertexCount - How many vertices to write.
1428
+ *
1429
+ * @internal
1430
+ */
1431
+ function updateMeshColors$1(engine, mesh, colors, vertexOffset, vertexCount) {
1432
+ updateMeshColors(engine, mesh, colors, vertexOffset, vertexCount);
1433
+ }
1434
+ /**
1435
+ * Writes a mesh's object-local bounding box.
1436
+ *
1437
+ * @remarks
1438
+ * `Mesh.boundMin`/`boundMax` are declared consumer-writable, and writing them is the only way to
1439
+ * keep the shadow fit, the thin-instance culler and the Havok shape extents honest after a partial
1440
+ * vertex update — none of the partial updaters recomputes them. The existing arrays are mutated in
1441
+ * place when they are there, so repeated sculpting allocates nothing.
1442
+ *
1443
+ * @param mesh - The mesh to re-bound.
1444
+ * @param minX - The smallest X.
1445
+ * @param minY - The smallest Y.
1446
+ * @param minZ - The smallest Z.
1447
+ * @param maxX - The largest X.
1448
+ * @param maxY - The largest Y.
1449
+ * @param maxZ - The largest Z.
1450
+ *
1451
+ * @internal
1452
+ */
1453
+ function setMeshBounds(mesh, minX, minY, minZ, maxX, maxY, maxZ) {
1454
+ const boundMin = mesh.boundMin;
1455
+ if (boundMin === void 0) mesh.boundMin = [
1456
+ minX,
1457
+ minY,
1458
+ minZ
1459
+ ];
1460
+ else {
1461
+ boundMin[0] = minX;
1462
+ boundMin[1] = minY;
1463
+ boundMin[2] = minZ;
1464
+ }
1465
+ const boundMax = mesh.boundMax;
1466
+ if (boundMax === void 0) mesh.boundMax = [
1467
+ maxX,
1468
+ maxY,
1469
+ maxZ
1470
+ ];
1471
+ else {
1472
+ boundMax[0] = maxX;
1473
+ boundMax[1] = maxY;
1474
+ boundMax[2] = maxZ;
1475
+ }
1476
+ }
1477
+ /**
1478
+ * Gives a cloned mesh bounding-box arrays of its own.
1479
+ *
1480
+ * @remarks
1481
+ * `cloneMeshNode` shallow-spreads the template (`lib/scene/transform-node.js`), so a clone starts
1482
+ * out sharing the template's `boundMin`/`boundMax` arrays and {@link setMeshBounds} — which mutates
1483
+ * in place — would write through to the template and to every other clone. Any caller that re-bounds
1484
+ * one clone alone has to call this first.
1485
+ *
1486
+ * @param mesh - The clone.
1487
+ *
1488
+ * @internal
1489
+ */
1490
+ function detachMeshBounds(mesh) {
1491
+ const boundMin = mesh.boundMin;
1492
+ if (boundMin !== void 0) mesh.boundMin = [
1493
+ boundMin[0],
1494
+ boundMin[1],
1495
+ boundMin[2]
1496
+ ];
1497
+ const boundMax = mesh.boundMax;
1498
+ if (boundMax !== void 0) mesh.boundMax = [
1499
+ boundMax[0],
1500
+ boundMax[1],
1501
+ boundMax[2]
1502
+ ];
1503
+ }
1504
+ /**
1505
+ * Recomputes a mesh's object-local bounding box from a position array and writes it.
1506
+ *
1507
+ * @remarks
1508
+ * The partial vertex updaters leave `boundMin`/`boundMax` alone (see the module note), and every
1509
+ * consumer that fits a shadow cascade, culls a thin instance, or measures a Havok shape reads them.
1510
+ * One linear pass, no allocation. A position array too short to hold one vertex leaves the bounds
1511
+ * as they were.
1512
+ *
1513
+ * @param mesh - The mesh to re-bound.
1514
+ * @param positions - Three floats per vertex.
1515
+ *
1516
+ * @internal
1517
+ */
1518
+ function recomputeMeshBounds(mesh, positions) {
1519
+ if (positions.length < 3) return;
1520
+ let minX = Number.POSITIVE_INFINITY;
1521
+ let minY = Number.POSITIVE_INFINITY;
1522
+ let minZ = Number.POSITIVE_INFINITY;
1523
+ let maxX = Number.NEGATIVE_INFINITY;
1524
+ let maxY = Number.NEGATIVE_INFINITY;
1525
+ let maxZ = Number.NEGATIVE_INFINITY;
1526
+ for (let index = 0; index + 2 < positions.length; index += 3) {
1527
+ const x = positions[index] ?? 0;
1528
+ const y = positions[index + 1] ?? 0;
1529
+ const z = positions[index + 2] ?? 0;
1530
+ minX = x < minX ? x : minX;
1531
+ minY = y < minY ? y : minY;
1532
+ minZ = z < minZ ? z : minZ;
1533
+ maxX = x > maxX ? x : maxX;
1534
+ maxY = y > maxY ? y : maxY;
1535
+ maxZ = z > maxZ ? z : maxZ;
1536
+ }
1537
+ setMeshBounds(mesh, minX, minY, minZ, maxX, maxY, maxZ);
1538
+ }
1539
+ /**
1540
+ * Clones a template — mesh or transform-node subtree — and parents the clone under an entity node.
1541
+ *
1542
+ * @remarks
1543
+ * The clone shares the template's GPU buffers (see the module note). Cloning a mesh whose buffers
1544
+ * were already released throws, which is Lite's way of telling you the template outlived its asset.
1545
+ *
1546
+ * Only the `parent` link is written; the clone is deliberately **not** pushed into the parent's
1547
+ * `children` array, for the same reason cameras and lights are not (`./camera.ts`): ignifx
1548
+ * transform nodes are never added to a Lite scene, so nothing in Lite walks their children, and
1549
+ * `removeFromScene` nulls a removed mesh's `parent` without touching the array it was listed in —
1550
+ * so maintaining it would only create a stale entry to clean up.
1551
+ *
1552
+ * @param template - The mesh or subtree to clone.
1553
+ * @param parent - The entity's transform node, or `null` for world space.
1554
+ * @returns The cloned root. Add it to the scene with {@link addMeshToScene}.
1555
+ *
1556
+ * @internal
1557
+ */
1558
+ function cloneMeshUnderNode(template, parent) {
1559
+ const clone = cloneTransformNode(template);
1560
+ clone.parent = parent;
1561
+ return clone;
1562
+ }
1563
+ /**
1564
+ * Adds a mesh — or a transform-node subtree containing meshes — to a render scene.
1565
+ *
1566
+ * @remarks
1567
+ * `addToScene` recurses into `children` and re-parents each one, so a whole instantiated model goes
1568
+ * in with one call. When the scene is already registered, the mesh joins Lite's runtime
1569
+ * material-swap queue and appears once its material family's renderable has been rebuilt
1570
+ * (`docs/architecture/07-rendering.md` §1.1 and ADR-0014).
1571
+ *
1572
+ * @param scene - The render scene.
1573
+ * @param node - The mesh or subtree root to add.
1574
+ *
1575
+ * @internal
1576
+ */
1577
+ function addMeshToScene(scene, node) {
1578
+ addToScene(scene, node);
1579
+ }
1580
+ /**
1581
+ * Removes a mesh — and everything under it — from a render scene, releasing its GPU buffers when it
1582
+ * has left its last scene.
1583
+ *
1584
+ * @remarks
1585
+ * This is destruction, not hiding: use {@link setMeshSubtreeVisible} to hide.
1586
+ *
1587
+ * @param scene - The render scene.
1588
+ * @param node - The mesh or subtree root to remove.
1589
+ *
1590
+ * @internal
1591
+ */
1592
+ function removeMeshFromScene(scene, node) {
1593
+ removeFromScene(scene, node);
1594
+ }
1595
+ /**
1596
+ * Shows or hides a mesh and everything under it.
1597
+ *
1598
+ * @param node - The subtree root.
1599
+ * @param visible - `true` to show it, `false` to hide it.
1600
+ *
1601
+ * @internal
1602
+ */
1603
+ function setMeshSubtreeVisible(node, visible) {
1604
+ setSubtreeVisible(node, visible);
1605
+ }
1606
+ /**
1607
+ * Assigns a mesh's material.
1608
+ *
1609
+ * @remarks
1610
+ * `Mesh.material` is an accessor once the mesh has joined a scene: writing it queues a material
1611
+ * swap on every scene the mesh belongs to (`lib/scene/mesh-scene-registry.js`,
1612
+ * `installMaterialSetter`). Assigning the material the mesh already has is a no-op.
1613
+ *
1614
+ * @param mesh - The mesh to change.
1615
+ * @param material - The material to draw it with.
1616
+ *
1617
+ * @internal
1618
+ */
1619
+ function setMeshMaterial(mesh, material) {
1620
+ mesh.material = material;
1621
+ }
1622
+ /**
1623
+ * Sets whether a mesh is darkened by shadow maps.
1624
+ *
1625
+ * @param mesh - The mesh to change.
1626
+ * @param receiveShadows - `true` to sample shadow maps on this mesh.
1627
+ *
1628
+ * @internal
1629
+ */
1630
+ function setMeshReceiveShadows(mesh, receiveShadows) {
1631
+ mesh.receiveShadows = receiveShadows;
1632
+ }
1633
+ /**
1634
+ * Sets a mesh's sort key within its phase. Lower values are drawn first.
1635
+ *
1636
+ * @param mesh - The mesh to change.
1637
+ * @param renderOrder - The sort key; it only orders within the opaque or the transparent phase.
1638
+ *
1639
+ * @internal
1640
+ */
1641
+ function setMeshRenderOrder(mesh, renderOrder) {
1642
+ mesh.renderOrder = renderOrder;
1643
+ }
1644
+ /**
1645
+ * Sets whether picking considers a mesh at all.
1646
+ *
1647
+ * @remarks
1648
+ * `pickable === false` removes the mesh from both the GPU picker's candidate list and the CPU ray
1649
+ * test, so it neither occludes nor returns a hit (`index.d.ts` 7214, `lib/picking/ray-pick.js`).
1650
+ *
1651
+ * @param mesh - The mesh to change.
1652
+ * @param pickable - `true` to allow picking.
1653
+ *
1654
+ * @internal
1655
+ */
1656
+ function setMeshPickable(mesh, pickable) {
1657
+ mesh.pickable = pickable;
1658
+ }
1659
+ /**
1660
+ * Gives a mesh the string id Lite's light include/exclude sets match on.
1661
+ *
1662
+ * @param mesh - The mesh to name.
1663
+ * @param id - The id. It should be unique within the scene.
1664
+ *
1665
+ * @internal
1666
+ */
1667
+ function setMeshId(mesh, id) {
1668
+ mesh.id = id;
1669
+ }
1670
+ /**
1671
+ * Replaces the materials of every mesh in a subtree whose current material carries one of the given
1672
+ * names.
1673
+ *
1674
+ * @remarks
1675
+ * `Material.name` is "populated by loaders from the source asset (e.g. the glTF material name) so
1676
+ * callers can look a material up by name" (`index.d.ts`), which is the identifier
1677
+ * `docs/architecture/07-rendering.md` §2.4 means by "by material name". Assigning `Mesh.material`
1678
+ * queues a material swap on every scene the mesh belongs to; assigning the material a mesh already
1679
+ * has is a no-op, so re-running this is cheap.
1680
+ *
1681
+ * @param node - The subtree root.
1682
+ * @param overrides - Source material name to replacement material.
1683
+ * @returns How many meshes were re-materialled.
1684
+ *
1685
+ * @internal
1686
+ */
1687
+ function overrideSubtreeMaterials(node, overrides) {
1688
+ let changed = 0;
1689
+ if ("material" in node) {
1690
+ const mesh = node;
1691
+ const name = mesh.material.name;
1692
+ const replacement = name === void 0 ? void 0 : overrides.get(name);
1693
+ if (replacement !== void 0 && replacement !== mesh.material) {
1694
+ mesh.material = replacement;
1695
+ changed += 1;
1696
+ }
1697
+ }
1698
+ const children = node.children;
1699
+ for (let index = 0; index < children.length; index += 1) {
1700
+ const child = children[index];
1701
+ if (child !== void 0) changed += overrideSubtreeMaterials(child, overrides);
1702
+ }
1703
+ return changed;
1704
+ }
1705
+ /**
1706
+ * Releases a template mesh's GPU buffers.
1707
+ *
1708
+ * @remarks
1709
+ * Lite exports no mesh disposer: a mesh's buffers are freed only when it leaves its last scene
1710
+ * (`lib/scene/scene-remove.js`). A template that was never added to a scene therefore has to be
1711
+ * added and removed to be released, which is exactly what this does. Two consequences the caller
1712
+ * must respect:
1713
+ *
1714
+ * 1. The template must carry no material, or the round trip will build and immediately tear down a
1715
+ * renderable for it. Templates created by the factories above start with none.
1716
+ * 2. Any clone still alive keeps the shared buffers: the reference count only reaches zero when the
1717
+ * last co-owner has gone. Releasing the template while clones are in a scene is safe, but the
1718
+ * template can no longer be cloned afterwards.
1719
+ *
1720
+ * @param scene - Any scene on the template's engine; it is used only as the round trip's vehicle.
1721
+ * @param template - The template to release.
1722
+ *
1723
+ * @internal
1724
+ */
1725
+ function disposeMeshTemplate(scene, template) {
1726
+ addToScene(scene, template);
1727
+ removeFromScene(scene, template);
1728
+ }
1729
+ /**
1730
+ * Collects every mesh in a subtree — the root included — in depth-first order.
1731
+ *
1732
+ * @remarks
1733
+ * A scene node that carries `material` is a mesh: the same structural test
1734
+ * {@link overrideSubtreeMaterials} and Lite's own scene walk use (`index.d.ts` 7156 declares
1735
+ * `material` on `Mesh` and nowhere on `SceneNode`, 10104).
1736
+ *
1737
+ * Call it **once**, when the subtree is instantiated. The clone tree `instantiateContainer` built
1738
+ * never changes shape afterwards, so walking it again every frame would put a recursion on the
1739
+ * render path for an answer that cannot have moved (coding standards §7).
1740
+ *
1741
+ * @param node - The subtree root.
1742
+ * @param out - The list the meshes are appended to; it is not cleared first.
1743
+ *
1744
+ * @internal
1745
+ */
1746
+ function collectSubtreeMeshes(node, out) {
1747
+ if ("material" in node) out.push(node);
1748
+ const children = node.children;
1749
+ for (let index = 0; index < children.length; index += 1) {
1750
+ const child = children[index];
1751
+ if (child !== void 0) collectSubtreeMeshes(child, out);
1752
+ }
1753
+ }
1754
+ //#endregion
1755
+ //#region src/math/vec3.ts
1756
+ /**
1757
+ * A 3-component vector: a position or a direction in metres, or a per-axis scale. ignifx is
1758
+ * left-handed with Y up and +Z forward (ADR-0011), so {@link Vec3.forward} is `(0, 0, 1)` and
1759
+ * {@link Vec3.right} is `(1, 0, 0)`.
1760
+ *
1761
+ * The fields are plain mutable numbers, which is what makes a `Vec3` interchangeable with Babylon
1762
+ * Lite's `{ x, y, z }` vectors and with the live {@link MutableVec3} views a `Transform` exposes.
1763
+ *
1764
+ * Three families of operations, and the names say which is which:
1765
+ *
1766
+ * - instance methods mutate the receiver and return `this` (`a.add(b)` means `a += b`);
1767
+ * - `ToRef` statics write into a final `out` argument, allocate nothing, and are safe when `out`
1768
+ * aliases an input — these are what per-frame code uses (coding standards section 7);
1769
+ * - the remaining statics return a fresh vector and are documented as allocating.
1770
+ *
1771
+ * @example
1772
+ * ```ts
1773
+ * // convenience code
1774
+ * const offset = Vec3.add(position, Vec3.scale(direction, distance));
1775
+ *
1776
+ * // per-frame code: no allocation
1777
+ * Vec3.scaleToRef(direction, distance, scratch);
1778
+ * Vec3.addToRef(position, scratch, position);
1779
+ * ```
1780
+ *
1781
+ * @public
1782
+ */
1783
+ var Vec3 = class Vec3 {
1784
+ /** The X component; positive is right. */
1785
+ x;
1786
+ /** The Y component; positive is up. */
1787
+ y;
1788
+ /** The Z component; positive is forward. */
1789
+ z;
1790
+ /**
1791
+ * Creates a vector.
1792
+ *
1793
+ * @param x - The X component. Defaults to 0.
1794
+ * @param y - The Y component. Defaults to 0.
1795
+ * @param z - The Z component. Defaults to 0.
1796
+ */
1797
+ constructor(x = 0, y = 0, z = 0) {
1798
+ this.x = x;
1799
+ this.y = y;
1800
+ this.z = z;
1801
+ }
1802
+ /**
1803
+ * Assigns every component at once.
1804
+ *
1805
+ * @param x - The new X component.
1806
+ * @param y - The new Y component.
1807
+ * @param z - The new Z component.
1808
+ * @returns This vector.
1809
+ */
1810
+ set(x, y, z) {
1811
+ this.x = x;
1812
+ this.y = y;
1813
+ this.z = z;
1814
+ return this;
1815
+ }
1816
+ /**
1817
+ * Copies every component from another vector.
1818
+ *
1819
+ * @param v - The vector to read.
1820
+ * @returns This vector.
1821
+ */
1822
+ copyFrom(v) {
1823
+ this.x = v.x;
1824
+ this.y = v.y;
1825
+ this.z = v.z;
1826
+ return this;
1827
+ }
1828
+ /**
1829
+ * Copies this vector into a new one.
1830
+ *
1831
+ * @returns A new vector. **Allocates.**
1832
+ */
1833
+ clone() {
1834
+ return new Vec3(this.x, this.y, this.z);
1835
+ }
1836
+ /**
1837
+ * Adds another vector to this one.
1838
+ *
1839
+ * @param v - The vector to add.
1840
+ * @returns This vector.
1841
+ */
1842
+ add(v) {
1843
+ this.x += v.x;
1844
+ this.y += v.y;
1845
+ this.z += v.z;
1846
+ return this;
1847
+ }
1848
+ /**
1849
+ * Adds a scaled vector to this one — the "move by velocity times delta time" step, without a
1850
+ * temporary.
1851
+ *
1852
+ * @param v - The vector to add.
1853
+ * @param scale - The factor to multiply `v` by first.
1854
+ * @returns This vector.
1855
+ *
1856
+ * @example
1857
+ * ```ts
1858
+ * position.addScaled(velocity, time.deltaTime);
1859
+ * ```
1860
+ */
1861
+ addScaled(v, scale) {
1862
+ this.x += v.x * scale;
1863
+ this.y += v.y * scale;
1864
+ this.z += v.z * scale;
1865
+ return this;
1866
+ }
1867
+ /**
1868
+ * Subtracts another vector from this one.
1869
+ *
1870
+ * @param v - The vector to subtract.
1871
+ * @returns This vector.
1872
+ */
1873
+ subtract(v) {
1874
+ this.x -= v.x;
1875
+ this.y -= v.y;
1876
+ this.z -= v.z;
1877
+ return this;
1878
+ }
1879
+ /**
1880
+ * Multiplies this vector by another component by component.
1881
+ *
1882
+ * @param v - The vector to multiply by.
1883
+ * @returns This vector.
1884
+ */
1885
+ multiply(v) {
1886
+ this.x *= v.x;
1887
+ this.y *= v.y;
1888
+ this.z *= v.z;
1889
+ return this;
1890
+ }
1891
+ /**
1892
+ * Multiplies every component by a number.
1893
+ *
1894
+ * @param scale - The factor.
1895
+ * @returns This vector.
1896
+ */
1897
+ scale(scale) {
1898
+ this.x *= scale;
1899
+ this.y *= scale;
1900
+ this.z *= scale;
1901
+ return this;
1902
+ }
1903
+ /**
1904
+ * Flips this vector to point the other way.
1905
+ *
1906
+ * @returns This vector.
1907
+ */
1908
+ negate() {
1909
+ this.x = -this.x;
1910
+ this.y = -this.y;
1911
+ this.z = -this.z;
1912
+ return this;
1913
+ }
1914
+ /**
1915
+ * Scales this vector to unit length. A zero-length vector is left at zero rather than becoming
1916
+ * `NaN`, so callers can normalize an unchecked direction safely.
1917
+ *
1918
+ * @returns This vector.
1919
+ */
1920
+ normalize() {
1921
+ const length = Math.hypot(this.x, this.y, this.z);
1922
+ if (length === 0) return this;
1923
+ return this.scale(1 / length);
1924
+ }
1925
+ /**
1926
+ * Replaces this vector with its cross product with another (`this = this x v`).
1927
+ *
1928
+ * @param v - The right-hand vector.
1929
+ * @returns This vector.
1930
+ */
1931
+ cross(v) {
1932
+ return Vec3.crossToRef(this, v, this);
1933
+ }
1934
+ /**
1935
+ * Moves this vector towards a target by an interpolant.
1936
+ *
1937
+ * @param target - The vector reached at `t === 1`.
1938
+ * @param t - The interpolant; not clamped.
1939
+ * @returns This vector.
1940
+ */
1941
+ lerp(target, t) {
1942
+ return Vec3.lerpToRef(this, target, t, this);
1943
+ }
1944
+ /**
1945
+ * The dot product of this vector with another.
1946
+ *
1947
+ * @param v - The other vector.
1948
+ * @returns The dot product.
1949
+ */
1950
+ dot(v) {
1951
+ return this.x * v.x + this.y * v.y + this.z * v.z;
1952
+ }
1953
+ /**
1954
+ * The length of this vector, in metres.
1955
+ *
1956
+ * @returns The length.
1957
+ */
1958
+ length() {
1959
+ return Math.hypot(this.x, this.y, this.z);
1960
+ }
1961
+ /**
1962
+ * The squared length of this vector. Prefer it over `length()` when comparing distances:
1963
+ * it skips the square root.
1964
+ *
1965
+ * @returns The squared length.
1966
+ */
1967
+ lengthSquared() {
1968
+ return this.x * this.x + this.y * this.y + this.z * this.z;
1969
+ }
1970
+ /**
1971
+ * The distance from this vector to another, in metres.
1972
+ *
1973
+ * @param v - The other position.
1974
+ * @returns The distance.
1975
+ */
1976
+ distance(v) {
1977
+ return Math.hypot(this.x - v.x, this.y - v.y, this.z - v.z);
1978
+ }
1979
+ /**
1980
+ * The squared distance from this vector to another.
1981
+ *
1982
+ * @param v - The other position.
1983
+ * @returns The squared distance.
1984
+ */
1985
+ distanceSquared(v) {
1986
+ return Vec3.distanceSquared(this, v);
1987
+ }
1988
+ /**
1989
+ * Compares this vector with another, component by component, with a tolerance.
1990
+ *
1991
+ * @param v - The vector to compare against.
1992
+ * @param epsilon - The largest per-component difference still considered equal.
1993
+ * @returns `true` when every component matches within `epsilon`.
1994
+ */
1995
+ equalsWithEpsilon(v, epsilon = EPSILON) {
1996
+ return Vec3.equalsWithEpsilon(this, v, epsilon);
1997
+ }
1998
+ /**
1999
+ * Writes this vector into a `Float32Array`, for GPU upload. The output comes first to mirror
2000
+ * Babylon Lite's `ObservableVec3.toArray`, the shape the adapter has to interoperate with.
2001
+ *
2002
+ * @param out - The array to write into.
2003
+ * @param offset - The index of the X component. Defaults to 0.
2004
+ * @returns `out`.
2005
+ */
2006
+ toArray(out, offset = 0) {
2007
+ out[offset] = this.x;
2008
+ out[offset + 1] = this.y;
2009
+ out[offset + 2] = this.z;
2010
+ return out;
2011
+ }
2012
+ /**
2013
+ * The zero vector.
2014
+ *
2015
+ * @returns A new `(0, 0, 0)`. **Allocates**; use {@link VEC3_ZERO} when a read-only value will do.
2016
+ */
2017
+ static zero() {
2018
+ return new Vec3(0, 0, 0);
2019
+ }
2020
+ /**
2021
+ * The vector whose components are all one.
2022
+ *
2023
+ * @returns A new `(1, 1, 1)`. **Allocates.**
2024
+ */
2025
+ static one() {
2026
+ return new Vec3(1, 1, 1);
2027
+ }
2028
+ /**
2029
+ * The world up direction.
2030
+ *
2031
+ * @returns A new `(0, 1, 0)`. **Allocates**; see {@link VEC3_UP}.
2032
+ */
2033
+ static up() {
2034
+ return new Vec3(0, 1, 0);
2035
+ }
2036
+ /**
2037
+ * The world down direction.
2038
+ *
2039
+ * @returns A new `(0, -1, 0)`. **Allocates.**
2040
+ */
2041
+ static down() {
2042
+ return new Vec3(0, -1, 0);
2043
+ }
2044
+ /**
2045
+ * The world right direction.
2046
+ *
2047
+ * @returns A new `(1, 0, 0)`. **Allocates**; see {@link VEC3_RIGHT}.
2048
+ */
2049
+ static right() {
2050
+ return new Vec3(1, 0, 0);
2051
+ }
2052
+ /**
2053
+ * The world left direction.
2054
+ *
2055
+ * @returns A new `(-1, 0, 0)`. **Allocates.**
2056
+ */
2057
+ static left() {
2058
+ return new Vec3(-1, 0, 0);
2059
+ }
2060
+ /**
2061
+ * The world forward direction. ignifx is left-handed, so forward is **+Z** (ADR-0011).
2062
+ *
2063
+ * @returns A new `(0, 0, 1)`. **Allocates**; see {@link VEC3_FORWARD}.
2064
+ */
2065
+ static forward() {
2066
+ return new Vec3(0, 0, 1);
2067
+ }
2068
+ /**
2069
+ * The world backward direction.
2070
+ *
2071
+ * @returns A new `(0, 0, -1)`. **Allocates.**
2072
+ */
2073
+ static backward() {
2074
+ return new Vec3(0, 0, -1);
2075
+ }
2076
+ /**
2077
+ * Copies any vector-shaped value into a `Vec3`.
2078
+ *
2079
+ * @param v - The vector to copy.
2080
+ * @returns A new vector. **Allocates.**
2081
+ *
2082
+ * @example
2083
+ * ```ts
2084
+ * const position = Vec3.from(node.position); // snapshot of a live Lite view
2085
+ * ```
2086
+ */
2087
+ static from(v) {
2088
+ return new Vec3(v.x, v.y, v.z);
2089
+ }
2090
+ /**
2091
+ * Adds two vectors.
2092
+ *
2093
+ * @param a - The first vector.
2094
+ * @param b - The second vector.
2095
+ * @returns A new vector. **Allocates**; use {@link Vec3.addToRef} in per-frame code.
2096
+ */
2097
+ static add(a, b) {
2098
+ return Vec3.addToRef(a, b, new Vec3());
2099
+ }
2100
+ /**
2101
+ * Subtracts one vector from another.
2102
+ *
2103
+ * @param a - The vector to subtract from.
2104
+ * @param b - The vector to subtract.
2105
+ * @returns A new vector holding `a - b`. **Allocates.**
2106
+ */
2107
+ static subtract(a, b) {
2108
+ return Vec3.subtractToRef(a, b, new Vec3());
2109
+ }
2110
+ /**
2111
+ * Multiplies a vector by a number.
2112
+ *
2113
+ * @param v - The vector to scale.
2114
+ * @param scale - The factor.
2115
+ * @returns A new vector. **Allocates.**
2116
+ */
2117
+ static scale(v, scale) {
2118
+ return Vec3.scaleToRef(v, scale, new Vec3());
2119
+ }
2120
+ /**
2121
+ * The cross product of two vectors.
2122
+ *
2123
+ * @param a - The left-hand vector.
2124
+ * @param b - The right-hand vector.
2125
+ * @returns A new vector holding `a x b`. **Allocates.**
2126
+ */
2127
+ static cross(a, b) {
2128
+ return Vec3.crossToRef(a, b, new Vec3());
2129
+ }
2130
+ /**
2131
+ * A unit-length copy of a vector.
2132
+ *
2133
+ * @param v - The vector to normalize.
2134
+ * @returns A new vector. **Allocates.**
2135
+ */
2136
+ static normalize(v) {
2137
+ return Vec3.normalizeToRef(v, new Vec3());
2138
+ }
2139
+ /**
2140
+ * Linearly interpolates between two vectors.
2141
+ *
2142
+ * @param a - The vector returned at `t === 0`.
2143
+ * @param b - The vector returned at `t === 1`.
2144
+ * @param t - The interpolant; not clamped.
2145
+ * @returns A new vector. **Allocates.**
2146
+ */
2147
+ static lerp(a, b, t) {
2148
+ return Vec3.lerpToRef(a, b, t, new Vec3());
2149
+ }
2150
+ /**
2151
+ * Writes `a + b` into `out`.
2152
+ *
2153
+ * @param a - The first vector.
2154
+ * @param b - The second vector.
2155
+ * @param out - The vector to write; may alias `a` or `b`.
2156
+ * @returns `out`.
2157
+ */
2158
+ static addToRef(a, b, out) {
2159
+ out.set(a.x + b.x, a.y + b.y, a.z + b.z);
2160
+ return out;
2161
+ }
2162
+ /**
2163
+ * Writes `a - b` into `out`.
2164
+ *
2165
+ * @param a - The vector to subtract from.
2166
+ * @param b - The vector to subtract.
2167
+ * @param out - The vector to write; may alias `a` or `b`.
2168
+ * @returns `out`.
2169
+ */
2170
+ static subtractToRef(a, b, out) {
2171
+ out.set(a.x - b.x, a.y - b.y, a.z - b.z);
2172
+ return out;
2173
+ }
2174
+ /**
2175
+ * Writes the component-wise product `a * b` into `out`.
2176
+ *
2177
+ * @param a - The first vector.
2178
+ * @param b - The second vector.
2179
+ * @param out - The vector to write; may alias `a` or `b`.
2180
+ * @returns `out`.
2181
+ */
2182
+ static multiplyToRef(a, b, out) {
2183
+ out.set(a.x * b.x, a.y * b.y, a.z * b.z);
2184
+ return out;
2185
+ }
2186
+ /**
2187
+ * Writes `v * scale` into `out`.
2188
+ *
2189
+ * @param v - The vector to scale.
2190
+ * @param scale - The factor.
2191
+ * @param out - The vector to write; may alias `v`.
2192
+ * @returns `out`.
2193
+ */
2194
+ static scaleToRef(v, scale, out) {
2195
+ out.set(v.x * scale, v.y * scale, v.z * scale);
2196
+ return out;
2197
+ }
2198
+ /**
2199
+ * Writes `-v` into `out`.
2200
+ *
2201
+ * @param v - The vector to flip.
2202
+ * @param out - The vector to write; may alias `v`.
2203
+ * @returns `out`.
2204
+ */
2205
+ static negateToRef(v, out) {
2206
+ out.set(-v.x, -v.y, -v.z);
2207
+ return out;
2208
+ }
2209
+ /**
2210
+ * Writes a unit-length copy of `v` into `out`. A zero-length input is written as zero rather than
2211
+ * `NaN`.
2212
+ *
2213
+ * @param v - The vector to normalize.
2214
+ * @param out - The vector to write; may alias `v`.
2215
+ * @returns `out`.
2216
+ */
2217
+ static normalizeToRef(v, out) {
2218
+ const length = Math.hypot(v.x, v.y, v.z);
2219
+ if (length === 0) {
2220
+ out.set(0, 0, 0);
2221
+ return out;
2222
+ }
2223
+ const inv = 1 / length;
2224
+ out.set(v.x * inv, v.y * inv, v.z * inv);
2225
+ return out;
2226
+ }
2227
+ /**
2228
+ * Writes `a x b` into `out`.
2229
+ *
2230
+ * @param a - The left-hand vector.
2231
+ * @param b - The right-hand vector.
2232
+ * @param out - The vector to write; may alias `a` or `b`.
2233
+ * @returns `out`.
2234
+ */
2235
+ static crossToRef(a, b, out) {
2236
+ const ax = a.x;
2237
+ const ay = a.y;
2238
+ const az = a.z;
2239
+ const bx = b.x;
2240
+ const by = b.y;
2241
+ const bz = b.z;
2242
+ out.set(ay * bz - az * by, az * bx - ax * bz, ax * by - ay * bx);
2243
+ return out;
2244
+ }
2245
+ /**
2246
+ * Writes the interpolation of `a` and `b` into `out`.
2247
+ *
2248
+ * @param a - The vector written at `t === 0`.
2249
+ * @param b - The vector written at `t === 1`.
2250
+ * @param t - The interpolant; not clamped.
2251
+ * @param out - The vector to write; may alias `a` or `b`.
2252
+ * @returns `out`.
2253
+ */
2254
+ static lerpToRef(a, b, t, out) {
2255
+ out.set(lerp(a.x, b.x, t), lerp(a.y, b.y, t), lerp(a.z, b.z, t));
2256
+ return out;
2257
+ }
2258
+ /**
2259
+ * Writes the component-wise minimum of two vectors into `out`.
2260
+ *
2261
+ * @param a - The first vector.
2262
+ * @param b - The second vector.
2263
+ * @param out - The vector to write; may alias `a` or `b`.
2264
+ * @returns `out`.
2265
+ */
2266
+ static minToRef(a, b, out) {
2267
+ out.set(Math.min(a.x, b.x), Math.min(a.y, b.y), Math.min(a.z, b.z));
2268
+ return out;
2269
+ }
2270
+ /**
2271
+ * Writes the component-wise maximum of two vectors into `out`.
2272
+ *
2273
+ * @param a - The first vector.
2274
+ * @param b - The second vector.
2275
+ * @param out - The vector to write; may alias `a` or `b`.
2276
+ * @returns `out`.
2277
+ */
2278
+ static maxToRef(a, b, out) {
2279
+ out.set(Math.max(a.x, b.x), Math.max(a.y, b.y), Math.max(a.z, b.z));
2280
+ return out;
2281
+ }
2282
+ /**
2283
+ * Transforms a **position** by a matrix into `out`: the matrix's translation is applied and the
2284
+ * result is divided by w, so a projection matrix gives clip-space coordinates.
2285
+ *
2286
+ * @param v - The position to transform, in metres.
2287
+ * @param m - The transformation, column-major.
2288
+ * @param out - The vector to write; may alias `v`.
2289
+ * @returns `out`.
2290
+ *
2291
+ * @example
2292
+ * ```ts
2293
+ * Vec3.transformCoordinatesToRef(localPoint, node.worldMatrix, worldPoint);
2294
+ * ```
2295
+ */
2296
+ static transformCoordinatesToRef(v, m, out) {
2297
+ return Mat4.transformPointToRef(m, v, out);
2298
+ }
2299
+ /**
2300
+ * Transforms a **direction** by a matrix into `out`, ignoring the matrix's translation.
2301
+ *
2302
+ * @param v - The direction to transform.
2303
+ * @param m - The transformation, column-major.
2304
+ * @param out - The vector to write; may alias `v`.
2305
+ * @returns `out`.
2306
+ */
2307
+ static transformNormalToRef(v, m, out) {
2308
+ return Mat4.transformDirectionToRef(m, v, out);
2309
+ }
2310
+ /**
2311
+ * The dot product of two vectors.
2312
+ *
2313
+ * @param a - The first vector.
2314
+ * @param b - The second vector.
2315
+ * @returns The dot product.
2316
+ */
2317
+ static dot(a, b) {
2318
+ return a.x * b.x + a.y * b.y + a.z * b.z;
2319
+ }
2320
+ /**
2321
+ * The length of a vector, in metres.
2322
+ *
2323
+ * @param v - The vector to measure.
2324
+ * @returns The length.
2325
+ */
2326
+ static length(v) {
2327
+ return Math.hypot(v.x, v.y, v.z);
2328
+ }
2329
+ /**
2330
+ * The squared length of a vector.
2331
+ *
2332
+ * @param v - The vector to measure.
2333
+ * @returns The squared length.
2334
+ */
2335
+ static lengthSquared(v) {
2336
+ return v.x * v.x + v.y * v.y + v.z * v.z;
2337
+ }
2338
+ /**
2339
+ * The distance between two positions, in metres.
2340
+ *
2341
+ * @param a - The first position.
2342
+ * @param b - The second position.
2343
+ * @returns The distance.
2344
+ */
2345
+ static distance(a, b) {
2346
+ return Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z);
2347
+ }
2348
+ /**
2349
+ * The squared distance between two positions. Compare squared distances to avoid a square root.
2350
+ *
2351
+ * @param a - The first position.
2352
+ * @param b - The second position.
2353
+ * @returns The squared distance.
2354
+ */
2355
+ static distanceSquared(a, b) {
2356
+ const dx = a.x - b.x;
2357
+ const dy = a.y - b.y;
2358
+ const dz = a.z - b.z;
2359
+ return dx * dx + dy * dy + dz * dz;
2360
+ }
2361
+ /**
2362
+ * Compares two vectors component by component, with a tolerance.
2363
+ *
2364
+ * @param a - The first vector.
2365
+ * @param b - The second vector.
2366
+ * @param epsilon - The largest per-component difference still considered equal.
2367
+ * @returns `true` when every component matches within `epsilon`.
2368
+ */
2369
+ static equalsWithEpsilon(a, b, epsilon = EPSILON) {
2370
+ return Math.abs(a.x - b.x) <= epsilon && Math.abs(a.y - b.y) <= epsilon && Math.abs(a.z - b.z) <= epsilon;
2371
+ }
2372
+ };
2373
+ /**
2374
+ * The frozen zero vector, `(0, 0, 0)`. Read-only: pass it anywhere a {@link Vec3Like} is wanted, and
2375
+ * call {@link Vec3.zero} when you need a vector you can write to.
2376
+ *
2377
+ * @public
2378
+ */
2379
+ const VEC3_ZERO = Object.freeze({
2380
+ x: 0,
2381
+ y: 0,
2382
+ z: 0
2383
+ });
2384
+ /**
2385
+ * The frozen vector whose components are all one, `(1, 1, 1)` — the identity scale.
2386
+ *
2387
+ * @public
2388
+ */
2389
+ const VEC3_ONE = Object.freeze({
2390
+ x: 1,
2391
+ y: 1,
2392
+ z: 1
2393
+ });
2394
+ /**
2395
+ * The frozen world up direction, `(0, 1, 0)`.
2396
+ *
2397
+ * @public
2398
+ */
2399
+ const VEC3_UP = Object.freeze({
2400
+ x: 0,
2401
+ y: 1,
2402
+ z: 0
2403
+ });
2404
+ /**
2405
+ * The frozen world down direction, `(0, -1, 0)`.
2406
+ *
2407
+ * @public
2408
+ */
2409
+ const VEC3_DOWN = Object.freeze({
2410
+ x: 0,
2411
+ y: -1,
2412
+ z: 0
2413
+ });
2414
+ /**
2415
+ * The frozen world right direction, `(1, 0, 0)`.
2416
+ *
2417
+ * @public
2418
+ */
2419
+ const VEC3_RIGHT = Object.freeze({
2420
+ x: 1,
2421
+ y: 0,
2422
+ z: 0
2423
+ });
2424
+ /**
2425
+ * The frozen world left direction, `(-1, 0, 0)`.
2426
+ *
2427
+ * @public
2428
+ */
2429
+ const VEC3_LEFT = Object.freeze({
2430
+ x: -1,
2431
+ y: 0,
2432
+ z: 0
2433
+ });
2434
+ /**
2435
+ * The frozen world forward direction, `(0, 0, 1)`. ignifx is left-handed, so forward is +Z
2436
+ * (ADR-0011).
2437
+ *
2438
+ * @public
2439
+ */
2440
+ const VEC3_FORWARD = Object.freeze({
2441
+ x: 0,
2442
+ y: 0,
2443
+ z: 1
2444
+ });
2445
+ /**
2446
+ * The frozen world backward direction, `(0, 0, -1)`.
2447
+ *
2448
+ * @public
2449
+ */
2450
+ const VEC3_BACKWARD = Object.freeze({
2451
+ x: 0,
2452
+ y: 0,
2453
+ z: -1
2454
+ });
2455
+ //#endregion
2456
+ export { basisToQuatToRef as $, setMeshReceiveShadows as A, localPosition as B, overrideSubtreeMaterials as C, setMeshId as D, setMeshBounds as E, updateMeshPositions$1 as F, readWorldMatrix as G, localScale as H, updateMeshUvs$1 as I, setNodeSelfVisible as J, reparentKeepingWorld as K, createNode as L, setMeshSubtreeVisible as M, updateMeshColors$1 as N, setMeshMaterial as O, updateMeshNormals$1 as P, Mat4 as Q, disposeNode as R, disposeMeshTemplate as S, removeMeshFromScene as T, parentNode as U, localRotation as V, readNodeTag as W, worldMatrixVersion as X, tagNode as Y, MAT4_IDENTITY as Z, createMeshFromGeometry as _, VEC3_ONE as a, createTorusMesh as b, VEC3_ZERO as c, cloneMeshUnderNode as d, collectSubtreeMeshes as f, createGroundMesh as g, createCylinderMesh as h, VEC3_LEFT as i, setMeshRenderOrder as j, setMeshPickable as k, Vec3 as l, createCapsuleMesh as m, VEC3_DOWN as n, VEC3_RIGHT as o, createBoxMesh as p, setNodeName as q, VEC3_FORWARD as r, VEC3_UP as s, VEC3_BACKWARD as t, addMeshToScene as u, createPlaneMesh as v, recomputeMeshBounds as w, detachMeshBounds as x, createSphereMesh as y, linkParent as z };
2457
+
2458
+ //# sourceMappingURL=vec3-B31o_KF_.js.map