lecodes-gl-lite 2.0.0

package/src/core/math3d.ts

@@ -0,0 +1,275 @@
+// Column-major mat4 math for the lite 3D engine. Mirrors creator-gl's transform semantics exactly
+// (transformUtils.cpp): matrices are column-major (m[col*4 + row], filament/GL layout), and the
+// component setters (position/quaternion/euler/scale) rewrite only their part of the local TRS
+// while preserving the rest — that contract is what the SDK's Node accessors are written against.
+// Generalized over ArrayLike (Mat4Like) so it runs directly on OGL Mat4 instances (Array subclasses)
+// without copies. This is the single shared copy — lecodes-headless's g3/ imports it too (the former
+// g3/math3d.ts was merged in here; getEulerYXZDeg/composeTRS came from that copy).
+
+export type Mat4Like = Float32Array | number[]
+
+/** Concrete column-major mat4 — what the allocating helpers (identity/invert/compose/…) return. */
+export type Mat4 = Float32Array
+
+export const identity = (): Float32Array => {
+  const m = new Float32Array(16)
+  m[0] = m[5] = m[10] = m[15] = 1
+  return m
+}
+
+/** out = a · b (column-major). `out` may not alias a or b. Returns `out` (narrowed to its type). */
+export const multiply = <T extends Mat4Like>(out: T, a: Mat4Like, b: Mat4Like): T => {
+  for (let c = 0; c < 4; c++) {
+    const b0 = b[c * 4], b1 = b[c * 4 + 1], b2 = b[c * 4 + 2], b3 = b[c * 4 + 3]
+    out[c * 4] = a[0] * b0 + a[4] * b1 + a[8] * b2 + a[12] * b3
+    out[c * 4 + 1] = a[1] * b0 + a[5] * b1 + a[9] * b2 + a[13] * b3
+    out[c * 4 + 2] = a[2] * b0 + a[6] * b1 + a[10] * b2 + a[14] * b3
+    out[c * 4 + 3] = a[3] * b0 + a[7] * b1 + a[11] * b2 + a[15] * b3
+  }
+  return out
+}
+
+/** Invert an affine TRS matrix (general 3x3 inverse, so non-uniform scale is handled). */
+export const invertTRS = (m: Mat4Like): Float32Array => {
+  const a00 = m[0], a01 = m[1], a02 = m[2]
+  const a10 = m[4], a11 = m[5], a12 = m[6]
+  const a20 = m[8], a21 = m[9], a22 = m[10]
+  const det = a00 * (a11 * a22 - a12 * a21) - a10 * (a01 * a22 - a02 * a21) + a20 * (a01 * a12 - a02 * a11)
+  const id = det === 0 ? 0 : 1 / det
+  const out = new Float32Array(16)
+  out[0] = (a11 * a22 - a12 * a21) * id
+  out[1] = (a02 * a21 - a01 * a22) * id
+  out[2] = (a01 * a12 - a02 * a11) * id
+  out[4] = (a12 * a20 - a10 * a22) * id
+  out[5] = (a00 * a22 - a02 * a20) * id
+  out[6] = (a02 * a10 - a00 * a12) * id
+  out[8] = (a10 * a21 - a11 * a20) * id
+  out[9] = (a01 * a20 - a00 * a21) * id
+  out[10] = (a00 * a11 - a01 * a10) * id
+  const tx = m[12], ty = m[13], tz = m[14]
+  out[12] = -(out[0] * tx + out[4] * ty + out[8] * tz)
+  out[13] = -(out[1] * tx + out[5] * ty + out[9] * tz)
+  out[14] = -(out[2] * tx + out[6] * ty + out[10] * tz)
+  out[15] = 1
+  return out
+}
+
+/** Column norms — the scale a TRS matrix carries (same as creator-gl's getScale). */
+export const getScale = (m: Mat4Like): [number, number, number] => [
+  Math.hypot(m[0], m[1], m[2]),
+  Math.hypot(m[4], m[5], m[6]),
+  Math.hypot(m[8], m[9], m[10]),
+]
+
+/** Rewrite the rotation part from a quaternion, preserving the current scale (setQuaternion). */
+export const setQuaternionOn = (m: Mat4Like, x: number, y: number, z: number, w: number): void => {
+  const [sx, sy, sz] = getScale(m)
+  const len = Math.hypot(x, y, z, w) || 1
+  const nx = x / len, ny = y / len, nz = z / len, nw = w / len
+  const xx = nx * nx, xy = nx * ny, xz = nx * nz, xw = nx * nw
+  const yy = ny * ny, yz = ny * nz, yw = ny * nw
+  const zz = nz * nz, zw = nz * nw
+  m[0] = (1 - 2 * (yy + zz)) * sx
+  m[1] = 2 * (xy + zw) * sx
+  m[2] = 2 * (xz - yw) * sx
+  m[4] = 2 * (xy - zw) * sy
+  m[5] = (1 - 2 * (xx + zz)) * sy
+  m[6] = 2 * (yz + xw) * sy
+  m[8] = 2 * (xz + yw) * sz
+  m[9] = 2 * (yz - xw) * sz
+  m[10] = (1 - 2 * (xx + yy)) * sz
+}
+
+const DEG = Math.PI / 180
+
+/** Rewrite the rotation from euler angles (degrees) in the given order, preserving scale
+ *  (setEulerAngles; orders match transformUtils.cpp — 1 = YXZ is the SDK convention). */
+export const setEulerOn = (m: Mat4Like, xDeg: number, yDeg: number, zDeg: number, order: number): void => {
+  const [scx, scy, scz] = getScale(m)
+  const x = xDeg * DEG, y = yDeg * DEG, z = zDeg * DEG
+  const cx = Math.cos(x), sx = Math.sin(x)
+  const cy = Math.cos(y), sy = Math.sin(y)
+  const cz = Math.cos(z), sz = Math.sin(z)
+  let m11 = 1, m12 = 0, m13 = 0, m21 = 0, m22 = 1, m23 = 0, m31 = 0, m32 = 0, m33 = 1
+  switch (order) {
+    case 0: // XYZ
+      m11 = cy * cz; m12 = -cy * sz; m13 = sy
+      m21 = sx * sy * cz + cx * sz; m22 = -sx * sy * sz + cx * cz; m23 = -sx * cy
+      m31 = -cx * sy * cz + sx * sz; m32 = cx * sy * sz + sx * cz; m33 = cx * cy
+      break
+    case 1: // YXZ
+      m11 = cy * cz + sy * sx * sz; m12 = -cy * sz + sy * sx * cz; m13 = sy * cx
+      m21 = cx * sz; m22 = cx * cz; m23 = -sx
+      m31 = -sy * cz + cy * sx * sz; m32 = sy * sz + cy * sx * cz; m33 = cy * cx
+      break
+    case 2: // ZXY
+      m11 = cy * cz - sy * sx * sz; m12 = -cx * sz; m13 = sy * cz + cy * sx * sz
+      m21 = cy * sz + sy * sx * cz; m22 = cx * cz; m23 = sy * sz - cy * sx * cz
+      m31 = -sy * cx; m32 = sx; m33 = cy * cx
+      break
+    case 3: // ZYX
+      m11 = cy * cz; m12 = sx * sy * cz - cx * sz; m13 = cx * sy * cz + sx * sz
+      m21 = cy * sz; m22 = sx * sy * sz + cx * cz; m23 = cx * sy * sz - sx * cz
+      m31 = -sy; m32 = sx * cy; m33 = cx * cy
+      break
+    case 4: // YZX
+      m11 = cy * cz; m12 = -sz; m13 = sy * cz
+      m21 = sx * sy + cx * cy * sz; m22 = cx * cz; m23 = -cy * sx + cx * sy * sz
+      m31 = -cx * sy + sx * cy * sz; m32 = sx * cz; m33 = cx * cy + sx * sy * sz
+      break
+    case 5: // XZY
+      m11 = cy * cz; m12 = -cy * sz; m13 = sy
+      m21 = cx * sz + sx * sy * cz; m22 = cx * cz - sx * sy * sz; m23 = -sx * cy
+      m31 = sx * sz - cx * sy * cz; m32 = sx * cz + cx * sy * sz; m33 = cx * cy
+      break
+  }
+  m[0] = m11 * scx; m[1] = m21 * scx; m[2] = m31 * scx
+  m[4] = m12 * scy; m[5] = m22 * scy; m[6] = m32 * scy
+  m[8] = m13 * scz; m[9] = m23 * scz; m[10] = m33 * scz
+}
+
+/** Rescale the basis columns to the given absolute scale (setScale). */
+export const setScaleOn = (m: Mat4Like, x: number, y: number, z: number): void => {
+  const [sx, sy, sz] = getScale(m)
+  if (sx === 0 || sy === 0 || sz === 0) {
+    m[0] = x; m[1] = 0; m[2] = 0
+    m[4] = 0; m[5] = y; m[6] = 0
+    m[8] = 0; m[9] = 0; m[10] = z
+    return
+  }
+  const fx = x / sx, fy = y / sy, fz = z / sz
+  m[0] *= fx; m[1] *= fx; m[2] *= fx
+  m[4] *= fy; m[5] *= fy; m[6] *= fy
+  m[8] *= fz; m[9] *= fz; m[10] *= fz
+}
+
+/** Extract YXZ euler angles (degrees) from the rotation part — the SDK's euler convention. */
+export const getEulerYXZDeg = (m: Mat4Like): [number, number, number] => {
+  const [sx, sy, sz] = getScale(m)
+  if (sx === 0 || sy === 0 || sz === 0) return [0, 0, 0]
+  // normalized rotation elements, math notation m_{row,col}; memory is m[col*4 + row]
+  const r11 = m[0] / sx, r21 = m[1] / sx, r31 = m[2] / sx
+  const r12 = m[4] / sy, r22 = m[5] / sy
+  const r13 = m[8] / sz, r23 = m[9] / sz, r33 = m[10] / sz
+  const x = Math.asin(-Math.min(1, Math.max(-1, r23)))
+  let y: number, z: number
+  if (Math.abs(r23) < 0.9999) {
+    y = Math.atan2(r13, r33)
+    z = Math.atan2(r21, r22)
+  } else { // gimbal lock: cx ≈ 0
+    y = Math.atan2(-r31, r11)
+    z = 0
+  }
+  return [x / DEG, y / DEG, z / DEG]
+}
+
+/** Compose a local matrix from glTF TRS (translation, rotation quat, scale): M = T·R·S. */
+export const composeTRS = (
+  t: [number, number, number], r: [number, number, number, number], s: [number, number, number],
+): Float32Array => {
+  const m = identity()
+  setQuaternionOn(m, r[0], r[1], r[2], r[3])
+  setScaleOn(m, s[0], s[1], s[2])
+  m[12] = t[0]; m[13] = t[1]; m[14] = t[2]
+  return m
+}
+
+/** Standard perspective projection (vertical fov in degrees). */
+export const perspective = (fovYDeg: number, aspect: number, near: number, far: number): Float32Array => {
+  const f = 1 / Math.tan((fovYDeg * DEG) / 2)
+  const m = new Float32Array(16)
+  m[0] = f / aspect
+  m[5] = f
+  m[10] = (far + near) / (near - far)
+  m[11] = -1
+  m[14] = (2 * far * near) / (near - far)
+  return m
+}
+
+/** Orthographic projection (for the shadow camera). */
+export const orthographic = (
+  left: number, right: number, bottom: number, top: number, near: number, far: number,
+): Float32Array => {
+  const m = new Float32Array(16)
+  m[0] = 2 / (right - left)
+  m[5] = 2 / (top - bottom)
+  m[10] = -2 / (far - near)
+  m[12] = -(right + left) / (right - left)
+  m[13] = -(top + bottom) / (top - bottom)
+  m[14] = -(far + near) / (far - near)
+  m[15] = 1
+  return m
+}
+
+// ---- ray intersection (port of collider.cpp) --------------------------------------------------
+
+/** Ray vs local-space AABB (center + half extents); returns tmin or -1 (collider.cpp intersectRay). */
+export const intersectRayBox = (
+  center: ArrayLike<number>, extent: ArrayLike<number>,
+  origin: ArrayLike<number>, direction: ArrayLike<number>,
+): number => {
+  let tmin = -Infinity, tmax = Infinity
+  for (let i = 0; i < 3; i++) {
+    if (direction[i] === 0) continue
+    const tx1 = (center[i] - extent[i] - origin[i]) / direction[i]
+    const tx2 = (center[i] + extent[i] - origin[i]) / direction[i]
+    tmin = Math.max(tmin, Math.min(tx1, tx2))
+    tmax = Math.min(tmax, Math.max(tx1, tx2))
+  }
+  if (tmin < 0 || tmax < tmin) return -1
+  return tmin
+}
+
+/** Ray vs local-space sphere; nearest positive t or -1 (collider.cpp intersectRay). */
+export const intersectRaySphere = (
+  center: ArrayLike<number>, radius: number,
+  origin: ArrayLike<number>, direction: ArrayLike<number>,
+): number => {
+  const ocx = origin[0] - center[0], ocy = origin[1] - center[1], ocz = origin[2] - center[2]
+  const a = direction[0] ** 2 + direction[1] ** 2 + direction[2] ** 2
+  const b = 2 * (ocx * direction[0] + ocy * direction[1] + ocz * direction[2])
+  const c = ocx * ocx + ocy * ocy + ocz * ocz - radius * radius
+  const disc = b * b - 4 * a * c
+  if (disc < 0) return -1
+  const sq = Math.sqrt(disc)
+  const t1 = (-b - sq) / (2 * a)
+  const t2 = (-b + sq) / (2 * a)
+  if (t1 > 0 && t2 > 0) return Math.min(t1, t2)
+  if (t1 > 0) return t1
+  if (t2 > 0) return t2
+  return -1
+}
+
+/** Transform a point/direction by an affine matrix (w=1 point, w=0 direction). */
+export const transformPoint = (out: number[], m: Mat4Like, x: number, y: number, z: number, w: number): number[] => {
+  out[0] = m[0] * x + m[4] * y + m[8] * z + m[12] * w
+  out[1] = m[1] * x + m[5] * y + m[9] * z + m[13] * w
+  out[2] = m[2] * x + m[6] * y + m[10] * z + m[14] * w
+  return out
+}
+
+/** A VIEW matrix (world → camera) for a camera at `eye` looking at `target`, Y up (falls back to
+ *  -Z up when looking straight up/down — a top view reads with +Z pointing down the screen). Column-
+ *  major, OpenGL convention — the same frame Filament's Camera::lookAt produces natively. */
+export const lookAtView = (eye: ArrayLike<number>, target: ArrayLike<number>): Float32Array => {
+  let fx = target[0] - eye[0], fy = target[1] - eye[1], fz = target[2] - eye[2]
+  let fl = Math.hypot(fx, fy, fz)
+  if (fl < 1e-9) { fx = 0; fy = 0; fz = -1; fl = 1 }
+  fx /= fl; fy /= fl; fz /= fl
+  let ux = 0, uy = 1, uz = 0
+  if (Math.abs(fy) > 0.999) { ux = 0; uy = 0; uz = -1 }
+  // s = f × up, u = s × f
+  let sx = fy * uz - fz * uy, sy = fz * ux - fx * uz, sz = fx * uy - fy * ux
+  const sl = Math.hypot(sx, sy, sz) || 1
+  sx /= sl; sy /= sl; sz /= sl
+  const uxx = sy * fz - sz * fy, uyy = sz * fx - sx * fz, uzz = sx * fy - sy * fx
+  const out = new Float32Array(16)
+  out[0] = sx; out[4] = sy; out[8] = sz
+  out[1] = uxx; out[5] = uyy; out[9] = uzz
+  out[2] = -fx; out[6] = -fy; out[10] = -fz
+  out[12] = -(sx * eye[0] + sy * eye[1] + sz * eye[2])
+  out[13] = -(uxx * eye[0] + uyy * eye[1] + uzz * eye[2])
+  out[14] = fx * eye[0] + fy * eye[1] + fz * eye[2]
+  out[15] = 1
+  return out
+}

package/src/core/particleBridge.ts

@@ -0,0 +1,154 @@
+// The web hosts' particle runtime: creator-particles' wasm behind the same `_creator` particle /
+// noise method shapes creator-gl exposes natively — ONE simulation for every host. Shared by
+// viewer-lite's WebGL engine (which uploads the streams) and lecodes-headless (headless, which reads
+// the counts); the host only supplies the emitters' world matrices and the camera position.
+//
+// Lazy like the animation and physics systems: the module loads asynchronously
+// (`loadCreatorParticles()`, awaited by createViewerLite / runProject), the real bridge is created on
+// the first particle call, and a host that never loaded it gets the standalone noise as zeros and
+// systems that record but do not simulate.
+//
+// On top of the simulation this layer RECORDS what the SDK configured onto the entity (Ent.particles:
+// the material, the config records decoded back to readable keys, bursts) plus the live `alive` count
+// after each update — the headless JSON snapshot shows the emitter as set up and as running.
+
+import { createParticleBridge, loadCreatorParticles, isCreatorParticlesLoaded, type ParticleHost, type ParticleBridge, type ParticleFrame } from "../vendor/creator-particles/js/index"
+import type { Ent } from "./sceneCore"
+
+export { loadCreatorParticles, isCreatorParticlesLoaded }
+export type { ParticleHost, ParticleBridge, ParticleFrame }
+
+export type ParticleRuntimeHost = ParticleHost & {
+  ent(id: number): Ent
+  /** A system exists now (the renderer prepares its drawable for the material). */
+  created?(entityId: number, materialId: number): void
+  /** This frame's stream for a system (the renderer uploads it). */
+  frame?(entityId: number, frame: ParticleFrame): void
+  destroyed?(entityId: number): void
+}
+
+const noiseFallback = {
+  createNoise: (): number => 0,
+  setNoiseFrequency(): void {},
+  setNoiseOctaves(): void {},
+  setNoiseFractalLunacrity(): void {},
+  setNoiseFractalGain(): void {},
+  getNoise2D: (): number => 0,
+  getNoise3D: (): number => 0,
+}
+
+export const createParticleRuntime = (host: ParticleRuntimeHost) => {
+  let real: ParticleBridge | null = null
+  const get = (): ParticleBridge | null => {
+    if (!real && isCreatorParticlesLoaded()) real = createParticleBridge(host)
+    return real
+  }
+  let nextNoise = 1   // ids for the no-module fallback
+
+  const setParticle = (entityId: number, key: string, value: unknown): void => {
+    const e = host.ent(entityId)
+    if (!e.particles) e.particles = {}
+    if (value === undefined) delete e.particles[key]
+    else e.particles[key] = value
+  }
+
+  const methods = {
+    createParticleSystem(entityId: number, materialInstanceId: number, maxParticles: number): void {
+      host.ent(entityId).particles = { material: materialInstanceId, ...(maxParticles ? { maxParticles } : {}) }
+      const b = get()
+      if (!b) return
+      b.methods.createParticleSystem(entityId, materialInstanceId, maxParticles)
+      host.created?.(entityId, materialInstanceId)
+    },
+    spawnParticles(entityId: number, count: number): void {
+      const p = host.ent(entityId).particles
+      if (p) p.spawned = ((p.spawned as number) ?? 0) + count
+      get()?.methods.spawnParticles(entityId, count)
+    },
+    // Tags mirror CPART_TAG_* in creator-particles.h (via the SDK's gl/Particles.ts writer).
+    setParticleSystemConfig(entityId: number, data: Float32Array): void {
+      const range = (lo: number, hi: number) => (lo === hi ? lo : { min: lo, max: hi })
+      const rgba = (o: number) => [ data[o], data[o + 1], data[o + 2], data[o + 3] ]
+      for (let i = 0; i + 2 <= data.length; i += 2 + data[i + 1]) {
+        const p = i + 2
+        switch (data[i]) {
+          case 1: {  // shape
+            const kind = data[p]
+            if (kind === 0) setParticle(entityId, "shape", { type: "point", at: [ data[p + 1], data[p + 2], data[p + 3] ] })
+            else if (kind === 1) setParticle(entityId, "shape", { type: "box", min: [ data[p + 1], data[p + 2], data[p + 3] ], max: [ data[p + 4], data[p + 5], data[p + 6] ] })
+            else setParticle(entityId, "shape", { type: "circle", center: [ data[p + 1], data[p + 2], data[p + 3] ], radius: data[p + 4] })
+            break
+          }
+          case 2: setParticle(entityId, "lifetime", range(data[p], data[p + 1])); break
+          case 3: setParticle(entityId, "rate", data[p]); break
+          case 4:
+            setParticle(entityId, "velocity", { kind: data[p], value: [ data[p + 1], data[p + 2], data[p + 3] ] })
+            setParticle(entityId, "speed", range(data[p + 4], data[p + 5]))
+            break
+          case 5:
+            setParticle(entityId, "spreadAngle", data[p] ? { min: [ data[p + 1], data[p + 2] ], max: [ data[p + 3], data[p + 4] ] } : undefined)
+            break
+          case 6: setParticle(entityId, "acceleration", [ data[p], data[p + 1], data[p + 2] ]); break
+          case 7: setParticle(entityId, "drag", data[p]); break
+          case 8:
+            setParticle(entityId, "noise", data[p] !== 0 ? { strength: data[p], frequency: data[p + 1], speed: data[p + 2] } : undefined)
+            break
+          case 9: setParticle(entityId, "seed", data[p]); break
+          case 10: {  // param curve: slot, kind, baseLo, baseHi, n, stops…
+            const base = range(data[p + 2], data[p + 3])
+            setParticle(entityId, `param${data[p]}`, data[p + 4] > 0 ? { base, curve: data[p + 4] } : base)
+            break
+          }
+          case 11: {  // color curve: baseLo rgba, baseHi rgba, n, stops…
+            const lo = rgba(p), hi = rgba(p + 4)
+            const base = lo.every((v, k) => v === hi[k]) ? lo : { min: lo, max: hi }
+            setParticle(entityId, "color", data[p + 8] > 0 ? { base, curve: data[p + 8] } : base)
+            break
+          }
+          case 12: setParticle(entityId, "space", data[p] ? "world" : "local"); break
+          case 15: setParticle(entityId, "render", [ "point", "quad", "ribbon", "mesh" ][data[p]] ?? data[p]); break
+        }
+      }
+      get()?.methods.setParticleSystemConfig(entityId, data)
+    },
+    ...noiseFallback,
+  }
+  // The standalone noise goes to the module when it is there (FastNoiseLite), else stays zeros.
+  const noiseMethods = Object.fromEntries(Object.keys(noiseFallback).map((name) => [
+    name,
+    (...args: unknown[]) => {
+      const b = get()
+      if (!b) return name === "createNoise" ? nextNoise++ : (noiseFallback as Record<string, (...a: unknown[]) => unknown>)[name](...args)
+      return (b.methods as unknown as Record<string, (...a: unknown[]) => unknown>)[name](...args)
+    },
+  ]))
+  Object.assign(methods, noiseMethods)
+
+  return {
+    methods,
+    loaded: (): boolean => real !== null,
+    /** After the animators (creator-gl's updateParticles): advance every system, record the live
+     *  count, hand the streams to the renderer. */
+    update(dt: number): void {
+      if (!real) return
+      real.update(dt, (id, frame) => {
+        const p = host.ent(id).particles
+        if (p) p.alive = frame.alive
+        host.frame?.(id, frame)
+      })
+    },
+    /** The node (or an ancestor) was shown / hidden: a hidden system is not simulated. */
+    setVisible(entityId: number, visible: boolean): void { real?.setVisible(entityId, visible) },
+    /** The index pattern for a system's current capacity (the renderer's index buffer). */
+    indexPattern: (entityId: number): Uint32Array => real?.indexPattern(entityId) ?? new Uint32Array(0),
+    /** destroyEntity hook. */
+    onEntityDestroyed(entityId: number): void {
+      if (!real) return
+      if (real.materialOf(entityId) === undefined) return
+      real.destroy(entityId)
+      host.destroyed?.(entityId)
+    },
+  }
+}
+
+export type ParticleRuntime = ReturnType<typeof createParticleRuntime>