lecodes-sdk 2.4.10 → 2.5.0

package/src/gl/Particles.ts

@@ -1,265 +1,38 @@
 // GPU particle system, as a Node. Draws with the default point-sprite material (Material.particles)
 // unless a custom one is passed; properties drive the native emitter.
 //
+// The config vocabulary — the record tags, the curve()/colorCurve() builders, the emitter option
+// types and the record writers — lives in core/particlesConfig.ts, shared with the 2D node
+// (g2/Particles2D.ts): one simulation (creator-particles), one language. This file holds only what is
+// 3D: the material, mesh mode, baked light (`lit`), the Filament render priority, and `Trail`.
 // All emitter/curve config crosses the bridge as ONE Float32Array of [tag, payloadLen, ...payload]
 // records (_creator.setParticleSystemConfig) — the constructor batches every option into a single
-// call, live setters send a one-record buffer. The tag values mirror CPART_TAG_* in
-// creator-particles/include/creator-particles/creator-particles.h (guarded by tests/gl/particles-tags.test.ts).
-//
-// Curves over a particle's lifetime are built with curve()/colorCurve() chains — see the builders
-// below. A builder's whole state is the flat `_data` array (the exact record payload), so the
-// chisel compiler can constant-fold literal chains into the buffer at compile time.
+// call, live setters send a one-record buffer.
 
-import { Color, type ColorInput } from "../core/color"
-import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
+import type { Vec3Like } from "../math/vec"
+import { cx, cy, cz } from "../math/vec"
 import type { Geometry } from "./Geometry"
 import { Material, _sheetColsRows, type ParticlesMaterialOptions } from "./Material"
 import { Node } from "./Node"
+import {
+  TAG_ACCELERATION, TAG_DRAG, TAG_INHERIT_VELOCITY, TAG_LIFETIME, TAG_LIT, TAG_NOISE, TAG_ORDER,
+  TAG_RATE, TAG_RATE_DISTANCE, TAG_RENDER_MODE, TAG_RIBBON_ORIENT, TAG_SEED, TAG_SMOOTH_PATH,
+  TAG_SPACE,
+  curve, lohi, pushAngularVelocity, pushColor, pushGround, pushMesh, pushParam, pushShape,
+  pushVelocity, pushVelocityLife,
+  type ParticleColor, type ParticleGround, type ParticleNoise as Noise, type ParticleShape as Shape,
+  type ParticleValue, type Range, type VelocityOverLife, type VelocityValue,
+} from "../core/particlesConfig"
+
+// What this module exported before the vocabulary moved to core/ — importers keep working.
+export {
+  _particleTags, CurveBuilder, ColorCurveBuilder, curve, colorCurve,
+  type ParticleValue, type ParticleColor, type VelocityOverLife, type ParticleGround,
+} from "../core/particlesConfig"
 
-type Range<T> = T | { min: T, max: T }
-
-// --- config record tags (keep in sync with CPART_TAG_* in creator-particles.h) ------------------
-
-const TAG_SHAPE = 1
-const TAG_LIFETIME = 2
-const TAG_RATE = 3
-const TAG_VELOCITY = 4
-const TAG_VELOCITY_RND = 5
-const TAG_ACCELERATION = 6
-const TAG_DRAG = 7
-const TAG_NOISE = 8
-const TAG_SEED = 9
-const TAG_PARAM_CURVE = 10
-const TAG_COLOR_CURVE = 11
-const TAG_SPACE = 12
-const TAG_INHERIT_VELOCITY = 13
-const TAG_RATE_DISTANCE = 14
-const TAG_RENDER_MODE = 15
-const TAG_MESH_GEOMETRY = 16
-const TAG_ANGULAR_VELOCITY = 17
-const TAG_GROUND = 18
-const TAG_VELOCITY_LIFE = 19
-const TAG_ORDER = 20
-const TAG_SMOOTH_PATH = 21
-const TAG_RIBBON_ORIENT = 22
-const TAG_LIT = 23
 /** `TrailOptions.orient` → the native axis code (0 = the camera-facing default). */
 const RIBBON_AXIS: Record<"camera" | "x" | "y" | "z", number> = { camera: 0, x: 1, y: 2, z: 3 }
 
-/** @internal — exported for the tag-sync test only. */
-export const _particleTags = {
-  SHAPE: TAG_SHAPE, LIFETIME: TAG_LIFETIME, RATE: TAG_RATE, VELOCITY: TAG_VELOCITY,
-  VELOCITY_RND: TAG_VELOCITY_RND, ACCELERATION: TAG_ACCELERATION, DRAG: TAG_DRAG,
-  NOISE: TAG_NOISE, SEED: TAG_SEED, PARAM_CURVE: TAG_PARAM_CURVE, COLOR_CURVE: TAG_COLOR_CURVE,
-  SPACE: TAG_SPACE, INHERIT_VELOCITY: TAG_INHERIT_VELOCITY, RATE_DISTANCE: TAG_RATE_DISTANCE,
-  RENDER_MODE: TAG_RENDER_MODE, MESH_GEOMETRY: TAG_MESH_GEOMETRY,
-  ANGULAR_VELOCITY: TAG_ANGULAR_VELOCITY, GROUND: TAG_GROUND, VELOCITY_LIFE: TAG_VELOCITY_LIFE,
-  ORDER: TAG_ORDER, SMOOTH_PATH: TAG_SMOOTH_PATH, RIBBON_ORIENT: TAG_RIBBON_ORIENT,
-  LIT: TAG_LIT,
-}
-
-// --- curve builders -----------------------------------------------------------------------------
-
-// A value curve reads as a journey over the particle's life:
-//   curve(0.3).from(0).via(0.15, 1).via(0.6, 1).to(0)   // fade in, hold, fade out — or:
-//   curve(0.3).fade(0.15, 0.4)
-// The curve multiplies the base value (or adds to it with mode 'add'); the base and any stop can be
-// a { min, max } range, randomized per particle. With no `.from` the curve starts at the identity
-// (1 for multiply, 0 for add); with no `.to` it holds its last value to end of life.
-//
-// chisel constant-folds a literal chain into its `_data` buffer at compile time and validates it
-// (bad stop order, >8 stops, unparsable color → a build diagnostic): chisel-core/src/curve.rs mirrors
-// these method bodies op-for-op, against a verbatim copy of them in chisel's fixtures/curve-sdk/. Keep
-// the two in step — a change here means a change there (chisel's scripts/curve-exact.mjs compares the
-// fused payload against the real builder, buffer for buffer).
-
-const lohi = (v: Range<number>): [number, number] =>
-  typeof v === "number" ? [ v, v ] : [ v.min, v.max ]
-
-export class CurveBuilder {
-  private _kind: 0 | 1
-  private _lo: number
-  private _hi: number
-  private _stops: number[] = []   // flat (t, lo, hi)
-
-  constructor(base: Range<number>, mode: "multiply" | "add") {
-    this._kind = mode === "add" ? 1 : 0
-    ;[ this._lo, this._hi ] = lohi(base)
-  }
-
-  /** Curve value at birth (t = 0). Must come before any other stop. */
-  from(v: Range<number>): this {
-    if (this._stops.length > 0) throw new Error("curve: .from() must come first")
-    return this.via(0, v)
-  }
-
-  /** Curve value at `t` (0..1 of the particle's life). Stops must be added in ascending t order. */
-  via(t: number, v: Range<number>): this {
-    const [ lo, hi ] = lohi(v)
-    this._stops.push(t, lo, hi)
-    return this
-  }
-
-  /** Curve value at death (t = 1). */
-  to(v: Range<number>): this {
-    return this.via(1, v)
-  }
-
-  /** The classic opacity envelope: rise over the first `fadeIn`, fall over the last `fadeOut`. */
-  fade(fadeIn = 0.15, fadeOut = fadeIn): this {
-    const up = Math.min(Math.max(fadeIn, 0), 1)
-    const down = Math.min(Math.max(fadeOut, 0), 1 - up)
-    if (up > 0) this.via(0, 0).via(up, 1)
-    else this.via(0, 1)
-    if (down > 0) {
-      if (1 - down > up) this.via(1 - down, 1)
-      this.via(1, 0)
-    }
-    return this
-  }
-
-  /** The PARAM_CURVE record payload (sans slot): [kind, baseLo, baseHi, n, (t, lo, hi)×n]. */
-  get _data(): Float32Array {
-    const stops = this._stops
-    const prepend = stops.length > 0 && stops[0] > 0
-    const n = stops.length / 3 + (prepend ? 1 : 0)
-    const out = new Float32Array(4 + n * 3)
-    out[0] = this._kind
-    out[1] = this._lo
-    out[2] = this._hi
-    out[3] = n
-    let o = 4
-    if (prepend) {
-      const identity = this._kind === 1 ? 0 : 1
-      out[o + 1] = identity
-      out[o + 2] = identity
-      o += 3
-    }
-    out.set(stops, o)
-    return out
-  }
-}
-
-export class ColorCurveBuilder {
-  private _lo: [number, number, number, number]
-  private _hi: [number, number, number, number]
-  private _stops: number[] = []   // flat (t, lo rgba, hi rgba)
-
-  constructor(base: Range<ColorInput>) {
-    if (isColorRange(base)) {
-      this._lo = Color.toRgba01(base.min)
-      this._hi = Color.toRgba01(base.max)
-    } else {
-      this._lo = Color.toRgba01(base)
-      this._hi = this._lo
-    }
-  }
-
-  /** Curve color at birth (t = 0). Must come first. The curve multiplies the base color. */
-  from(c: Range<ColorInput>): this {
-    if (this._stops.length > 0) throw new Error("colorCurve: .from() must come first")
-    return this.via(0, c)
-  }
-
-  /** Curve color at `t` (0..1 of the particle's life), in ascending t order. */
-  via(t: number, c: Range<ColorInput>): this {
-    let lo: number[], hi: number[]
-    if (isColorRange(c)) {
-      lo = Color.toRgba01(c.min)
-      hi = Color.toRgba01(c.max)
-    } else {
-      lo = hi = Color.toRgba01(c)
-    }
-    this._stops.push(t, ...lo, ...hi)
-    return this
-  }
-
-  /** Curve color at death (t = 1). */
-  to(c: Range<ColorInput>): this {
-    return this.via(1, c)
-  }
-
-  /** The COLOR_CURVE record payload: [baseLo rgba, baseHi rgba, n, (t, lo rgba, hi rgba)×n]. */
-  get _data(): Float32Array {
-    const stops = this._stops
-    const prepend = stops.length > 0 && stops[0] > 0
-    const n = stops.length / 9 + (prepend ? 1 : 0)
-    const out = new Float32Array(9 + n * 9)
-    out.set(this._lo, 0)
-    out.set(this._hi, 4)
-    out[8] = n
-    let o = 9
-    if (prepend) {
-      for (let i = 1; i < 9; i++) out[o + i] = 1   // identity multiplier: white, t = 0
-      o += 9
-    }
-    out.set(stops, o)
-    return out
-  }
-}
-
-/** A value curve over each particle's lifetime. Default mode `multiply` (the curve scales the
- *  base); `add` offsets it instead. */
-export const curve = (base: Range<number> = 1, mode: "multiply" | "add" = "multiply"): CurveBuilder =>
-  new CurveBuilder(base, mode)
-
-/** A color curve over each particle's lifetime — always multiplies the base color. */
-export const colorCurve = (base: Range<ColorInput> = "#ffffff"): ColorCurveBuilder =>
-  new ColorCurveBuilder(base)
-
-// --- option types -------------------------------------------------------------------------------
-
-export type ParticleValue = Range<number> | CurveBuilder | { _data: Float32Array }
-export type ParticleColor = ColorInput | { min: ColorInput, max: ColorInput } | ColorCurveBuilder | { _data: Float32Array }
-
-type VelocityValue = {
-  speed?: Range<number>
-  /** Cone half-angle in radians — jitter the launch direction uniformly within it. */
-  spread?: number
-  /** Asymmetric jitter: two angles (u, v — the x/y components) in radians. */
-  randomizeAngle?: { min: Vec3Like, max: Vec3Like }
-} & ({ from: Vec3Like } | { to: Vec3Like } | { dir: Vec3Like } | {})
-
-/** Where particles are born, in emitter space. Sphere / hemisphere / cone have an axis of +Y (the
- *  hemisphere is the +Y half, the cone opens along +Y from its base disc at `center`) — aim the
- *  node with `lookAt(target, 'y')`. `thickness` 0 emits from the surface only, 1 (default) from the
- *  whole volume. A sphere or cone also sets the LAUNCH DIRECTION (outward / from the cone's apex)
- *  when `startVelocity` gives a speed but no direction, like Unity's shapes. */
-type Shape =
-  | { type: "point", v: Vec3Like }
-  | { type: "box", min: Vec3Like, max: Vec3Like }
-  | { type: "circle", center: Vec3Like, radius: number }
-  | { type: "sphere", center?: Vec3Like, radius: number, thickness?: number }
-  | { type: "hemisphere", center?: Vec3Like, radius: number, thickness?: number }
-  | { type: "cone", center?: Vec3Like, radius: number, /** half-angle, radians */ angle?: number, /** emit this far up the axis too */ length?: number, thickness?: number }
-/** Extra velocity over each particle's life — evaluated from the curves every frame and ADDED as a
- *  displacement (not accumulated like `acceleration`): `radial` pushes outward along the particle's
- *  birth direction (a burst that decays: `curve(4).to(0)`), `x`/`y`/`z` drift in the simulation
- *  space (rising smoke: `y: curve(2).from(0).to(1)`). Unity's velocityOverLifetime. */
-export type VelocityOverLife = { radial?: ParticleValue, x?: ParticleValue, y?: ParticleValue, z?: ParticleValue }
-type Noise = {
-  strength?: number, frequency?: number, speed?: number,
-  /** How much of the displacement a particle earns with AGE (default 0 = all of it from birth).
-   *  The field is sampled by position, so at 0 every particle born at the same spot is pushed the
-   *  same way and a plume's root wanders off its emitter by up to `strength` metres; at 1 a particle
-   *  is born exactly where the emitter put it and drifts into the field over its life — what you
-   *  want whenever the source is visible (an exhaust pipe, a contact patch, a muzzle). */
-  ramp?: number,
-}
-
-/** Ground plane for bouncing particles (all render modes). `height` is in the simulation space:
- *  world y with `space: 'world'`, emitter-local y otherwise. */
-export type ParticleGround = {
-  /** Plane height (default 0). */
-  height?: number
-  /** Contact radius — particles stop `radius` above the plane (a mesh's half-extent; default 0). */
-  radius?: number
-  /** Fraction of the vertical speed kept on impact, 0..1 (default 0.3). */
-  bounce?: number
-  /** Tangential damping while in contact, per second — like `drag` (default 8). */
-  friction?: number
-}
-
 export type ParticlesOptions = ParticlesMaterialOptions & {
   /** Draw every particle as this mesh — lit, tumbling 3D debris (shell casings, rubble, leaves,
    *  shrapnel) in one draw call. The system switches to the mesh render mode; the default
@@ -350,118 +123,6 @@ export type ParticlesOptions = ParticlesMaterialOptions & {
   seed?: number
 }
 
-// --- record assembly ----------------------------------------------------------------------------
-
-const isColorRange = (v: unknown): v is { min: ColorInput, max: ColorInput } =>
-  typeof v === "object" && v !== null && !Array.isArray(v) && "min" in v
-
-const hasData = (v: unknown): v is { _data: Float32Array } =>
-  typeof v === "object" && v !== null && "_data" in v
-
-const pushParam = (out: number[], slot: number, value: ParticleValue): void => {
-  if (typeof value === "number") {
-    out.push(TAG_PARAM_CURVE, 5, slot, 0, value, value, 0)
-  } else if (hasData(value)) {
-    const d = value._data
-    out.push(TAG_PARAM_CURVE, d.length + 1, slot)
-    for (let i = 0; i < d.length; i++) out.push(d[i])
-  } else {
-    out.push(TAG_PARAM_CURVE, 5, slot, 0, value.min, value.max, 0)
-  }
-}
-
-const pushColor = (out: number[], value: ParticleColor): void => {
-  let d: Float32Array
-  if (hasData(value)) {
-    d = value._data
-  } else if (isColorRange(value)) {
-    d = new ColorCurveBuilder(value)._data
-  } else {
-    d = new ColorCurveBuilder(value as ColorInput)._data
-  }
-  out.push(TAG_COLOR_CURVE, d.length)
-  for (let i = 0; i < d.length; i++) out.push(d[i])
-}
-
-const pushMesh = (out: number[], g: Geometry): void => {
-  const nv = g.vertices.length / 3
-  const ni = g.indices.length
-  out.push(TAG_MESH_GEOMETRY, 2 + nv * 8 + ni, nv, ni)
-  for (let i = 0; i < nv * 3; i++) out.push(g.vertices[i])
-  for (let i = 0; i < nv * 3; i++) out.push(g.normals[i])
-  for (let i = 0; i < nv * 2; i++) out.push(g.uv[i])
-  for (let i = 0; i < ni; i++) out.push(g.indices[i])
-}
-
-const pushAngularVelocity = (out: number[], v: Vec3Like | { min: Vec3Like, max: Vec3Like }): void => {
-  const r = v as { min: Vec3Like, max: Vec3Like }
-  if (typeof r === "object" && r !== null && !Array.isArray(r) && "min" in r && !(v instanceof Float32Array) && !(v instanceof Vec3)) {
-    out.push(TAG_ANGULAR_VELOCITY, 6, cx(r.min), cy(r.min), cz(r.min), cx(r.max), cy(r.max), cz(r.max))
-  } else {
-    const a = v as Vec3Like
-    out.push(TAG_ANGULAR_VELOCITY, 6, cx(a), cy(a), cz(a), cx(a), cy(a), cz(a))
-  }
-}
-
-const pushGround = (out: number[], g: ParticleGround | null): void => {
-  if (g === null) out.push(TAG_GROUND, 5, 0, 0, 0, 0, 0)
-  else out.push(TAG_GROUND, 5, 1, g.height ?? 0, g.radius ?? 0, g.bounce ?? 0.3, g.friction ?? 8)
-}
-
-const pushShape = (out: number[], shape: Shape): void => {
-  if (shape.type === "point") out.push(TAG_SHAPE, 4, 0, cx(shape.v), cy(shape.v), cz(shape.v))
-  else if (shape.type === "box") out.push(TAG_SHAPE, 7, 1, cx(shape.min), cy(shape.min), cz(shape.min), cx(shape.max), cy(shape.max), cz(shape.max))
-  else if (shape.type === "circle") out.push(TAG_SHAPE, 5, 2, cx(shape.center), cy(shape.center), cz(shape.center), shape.radius)
-  else {
-    const c = shape.center ?? [ 0, 0, 0 ]
-    const thickness = shape.thickness ?? 1
-    if (shape.type === "cone") out.push(TAG_SHAPE, 8, 5, cx(c), cy(c), cz(c), shape.radius, shape.angle ?? 0, shape.length ?? 0, thickness)
-    else out.push(TAG_SHAPE, 6, shape.type === "sphere" ? 3 : 4, cx(c), cy(c), cz(c), shape.radius, thickness)
-  }
-}
-
-const pushVelocityLife = (out: number[], v: VelocityOverLife): void => {
-  const axes: Array<[number, ParticleValue | undefined]> = [ [ 0, v.radial ], [ 1, v.x ], [ 2, v.y ], [ 3, v.z ] ]
-  for (const [ axis, value ] of axes) {
-    if (value === undefined) continue
-    if (typeof value === "number") out.push(TAG_VELOCITY_LIFE, 5, axis, 0, value, value, 0)
-    else if (hasData(value)) {
-      const d = value._data
-      out.push(TAG_VELOCITY_LIFE, d.length + 1, axis)
-      for (let i = 0; i < d.length; i++) out.push(d[i])
-    } else out.push(TAG_VELOCITY_LIFE, 5, axis, 0, value.min, value.max, 0)
-  }
-}
-
-const pushVelocity = (out: number[], val: Vec3Like | VelocityValue): void => {
-  if (Array.isArray(val) || val instanceof Float32Array || val instanceof Vec3) {
-    // a plain vector: launch along it, its length is the speed (native derives it)
-    out.push(TAG_VELOCITY, 6, 1, cx(val), cy(val), cz(val), 0, 0)
-    out.push(TAG_VELOCITY_RND, 5, 0, 0, 0, 0, 0)
-    return
-  }
-  const v = val as VelocityValue
-  let mode = 0
-  let p: Vec3Like = [ 0, 0, 0 ]
-  if ("dir" in v) { mode = 1; p = v.dir }
-  else if ("from" in v) { mode = 2; p = v.from }
-  else if ("to" in v) { mode = 3; p = v.to }
-  let lo = 0, hi = 0
-  if (v.speed !== undefined) {
-    if (typeof v.speed === "number") lo = hi = v.speed
-    else { lo = v.speed.min; hi = v.speed.max }
-  }
-  out.push(TAG_VELOCITY, 6, mode, cx(p), cy(p), cz(p), lo, hi)
-  if (v.spread !== undefined) {
-    out.push(TAG_VELOCITY_RND, 5, 1, -v.spread, -v.spread, v.spread, v.spread)
-  } else if (v.randomizeAngle) {
-    const a = v.randomizeAngle
-    out.push(TAG_VELOCITY_RND, 5, 1, cx(a.min), cy(a.min), cx(a.max), cy(a.max))
-  } else {
-    out.push(TAG_VELOCITY_RND, 5, 0, 0, 0, 0, 0)
-  }
-}
-
 // --- the node -----------------------------------------------------------------------------------
 
 export class Particles extends Node {