// 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.
//
// 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 PsTag in
// creator-gl/src/particles.h (guarded by tests/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.

import { Color, type ColorInput } from "../core/color"
import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
import type { Geometry } from "./Geometry"
import { Material, _sheetColsRows, type ParticlesMaterialOptions } from "./Material"
import { Node } from "./Node"

type Range<T> = T | { min: T, max: T }

// --- config record tags (keep in sync with PsTag in creator-gl/src/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

/** @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,
}

// --- 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 }

/** 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
   *  material becomes `Material.lit()` (pass `material` for color/roughness/metallic — the
   *  sprite look options are ignored). `size` scales the mesh (default 1); `rotation`/`opacity`/
   *  `frame` don't apply. See `angularVelocity` and `ground`. */
  mesh?: Geometry
  /** (mesh) Spin, radians per second about the particle's own axes — a vector, or a per-component
   *  `{ min, max }` range randomized at spawn. Particles are born in the emitter's orientation. */
  angularVelocity?: Vec3Like | { min: Vec3Like, max: Vec3Like }
  /** A ground plane the particles bounce on and come to rest on (any render mode); `null`
   *  disables it. */
  ground?: ParticleGround | null
  /** Custom draw material. Unset = the default point-sprite material, configured by the
   *  `ParticlesMaterialOptions` sugar (map/sheet/emissive/blend/soft) — which is ignored
   *  when an explicit material is passed. */
  material?: Material
  /** Particle pool capacity (default 1000). */
  maxParticles?: number
  /** Particles emitted per second. */
  rate?: number
  /** Simulation space. `'local'` (default) — particles ride the node's transform; `'world'` —
   *  each particle stays where it was born as the emitter moves on (trails: drift smoke, mud,
   *  wake). Switching at runtime resets live particles. */
  space?: "local" | "world"
  /** Fraction (usually 0..1) of the emitter's own velocity added to each particle at spawn —
   *  smoke "thrown" off a moving car. Takes effect with `space: 'world'`. */
  inheritVelocity?: number
  /** Particles emitted per world unit the emitter MOVES, on top of `rate`, with spawn points
   *  spread evenly along the path — trail density independent of speed, no per-frame clumps.
   *  Meant for `space: 'world'`. */
  rateOverDistance?: number
  /** Draw order among blended systems at the same depth — higher draws later, i.e. on top (Unity's
   *  sortingOrder). Systems are depth-sorted by their node, so the emitters of one effect tie and
   *  without this the engine picks who covers whom per frame (smoke popping over a fireball).
   *  Default 0; a fireball wants 2, its smoke 1, a smoke trail -1. */
  order?: number
  shape?: Shape
  /** Extra velocity over life (radial burst that decays, axis drift) — see `VelocityOverLife`. */
  velocityOverLife?: VelocityOverLife
  startVelocity?: Vec3Like | VelocityValue
  /** Downward acceleration, world units/s² — positive pulls particles DOWN (sugar for
   *  `acceleration: [0, -g, 0]`). */
  gravity?: number
  /** Constant acceleration vector (gravity, wind, …). Wins over `gravity` when both are set. */
  acceleration?: Vec3Like
  drag?: number
  lifetime?: Range<number>
  color?: ParticleColor
  /** World-unit diameter (alias of custom[0]). Default 1. */
  size?: ParticleValue
  /** Radians (alias of custom[1]). */
  rotation?: ParticleValue
  /** Per-particle opacity 0..1 (alias of custom[2]). Default 1. */
  opacity?: ParticleValue
  /** Flipbook frame index (alias of custom[3]). With `sheet` set and no explicit frame, the
   *  default is one full sheet cycle over each particle's lifetime, starting at `startFrame`. */
  frame?: ParticleValue
  /** Where the default flipbook cycle begins: `'random'` (default — desynchronized loops like
   *  fire/smoke) or a frame index (`0` plays the sheet in order — explosions, one-shot bursts).
   *  Only shapes the default; an explicit `frame` wins. */
  startFrame?: number | "random"
  noise?: Noise | null
  /** Fixed random seed for deterministic tests. */
  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 {
  private _material: Material

  /** Custom curve-param slots (0..3); size/rotation/opacity/frame alias slots 0-3. */
  readonly custom: ParticleValue[]

  constructor(options: ParticlesOptions = {}) {
    super()
    this._material = options.material ?? (options.mesh ? Material.lit() : Material.particles(options))
    _creator.createParticleSystem(this.id, Material.idOf(this._material), options.maxParticles ?? 0)

    const id = this.id
    this.custom = new Proxy([] as ParticleValue[], {
      set(target, prop: string, value: ParticleValue) {
        const i = parseInt(prop)
        if (Number.isNaN(i)) { (target as any)[prop] = value; return true }
        target[i] = value
        const out: number[] = []
        pushParam(out, i, value)
        _creator.setParticleSystemConfig(id, Float32Array.from(out))
        return true
      },
    })

    const out: number[] = []
    if (options.mesh) {
      out.push(TAG_RENDER_MODE, 1, 3)
      pushMesh(out, options.mesh)
    } else if (options.render !== undefined && options.render !== "point") {
      out.push(TAG_RENDER_MODE, 1, options.render === "ribbon" ? 2 : 1)
    }
    if (options.angularVelocity !== undefined) pushAngularVelocity(out, options.angularVelocity)
    if (options.ground !== undefined) pushGround(out, options.ground)
    if (options.space !== undefined) out.push(TAG_SPACE, 1, options.space === "world" ? 1 : 0)
    if (options.inheritVelocity !== undefined) out.push(TAG_INHERIT_VELOCITY, 1, options.inheritVelocity)
    if (options.rateOverDistance !== undefined) out.push(TAG_RATE_DISTANCE, 1, options.rateOverDistance)
    if (options.order !== undefined) out.push(TAG_ORDER, 1, options.order)
    if (options.rate !== undefined) out.push(TAG_RATE, 1, options.rate)
    if (options.shape !== undefined) pushShape(out, options.shape)
    if (options.velocityOverLife !== undefined) pushVelocityLife(out, options.velocityOverLife)
    if (options.startVelocity !== undefined) pushVelocity(out, options.startVelocity)
    if (options.acceleration !== undefined) {
      const a = options.acceleration
      out.push(TAG_ACCELERATION, 3, cx(a), cy(a), cz(a))
    } else if (options.gravity !== undefined) {
      out.push(TAG_ACCELERATION, 3, 0, -options.gravity, 0)
    }
    if (options.drag !== undefined) out.push(TAG_DRAG, 1, options.drag)
    if (options.lifetime !== undefined) {
      const [ lo, hi ] = lohi(options.lifetime)
      out.push(TAG_LIFETIME, 2, lo, hi)
    }
    if (options.color !== undefined) pushColor(out, options.color)
    if (options.size !== undefined) pushParam(out, 0, options.size)
    if (options.rotation !== undefined) pushParam(out, 1, options.rotation)
    if (options.opacity !== undefined) pushParam(out, 2, options.opacity)
    if (options.frame !== undefined) {
      pushParam(out, 3, options.frame)
    } else if (options.material === undefined && !options.mesh) {
      const [ cols, rows ] = _sheetColsRows(options.sheet)
      const frames = cols * rows
      if (frames > 1) {
        const start = options.startFrame ?? "random"
        const base = start === "random" ? { min: 0, max: frames - 1 } : start
        pushParam(out, 3, curve(base, "add").from(0).to(frames))
      }
    }
    if (options.noise !== undefined) {
      const n = options.noise
      out.push(TAG_NOISE, 3, n ? n.strength ?? 1 : 0, n ? n.frequency ?? 1 : 0, n ? n.speed ?? 1 : 0)
    }
    if (options.seed !== undefined) out.push(TAG_SEED, 1, options.seed)

    if (out.length > 0) _creator.setParticleSystemConfig(this.id, Float32Array.from(out))
  }

  /** Emit `count` particles immediately (a burst). */
  spawn(count: number): this { _creator.spawnParticles(this.id, count); return this }

  private _send(out: number[]): void {
    _creator.setParticleSystemConfig(this.id, Float32Array.from(out))
  }

  set rate(val: number) { this._send([ TAG_RATE, 1, val ]) }

  /** `'world'` leaves particles behind where they were born (trails). Switching resets live ones. */
  set space(val: "local" | "world") { this._send([ TAG_SPACE, 1, val === "world" ? 1 : 0 ]) }
  set inheritVelocity(val: number) { this._send([ TAG_INHERIT_VELOCITY, 1, val ]) }
  set rateOverDistance(val: number) { this._send([ TAG_RATE_DISTANCE, 1, val ]) }
  set order(val: number) { this._send([ TAG_ORDER, 1, val ]) }

  set velocityOverLife(v: VelocityOverLife) {
    const out: number[] = []
    pushVelocityLife(out, v)
    this._send(out)
  }

  set shape(shape: Shape) {
    const out: number[] = []
    pushShape(out, shape)
    this._send(out)
  }

  /** (mesh mode) Replace the particle mesh; live particles keep flying as the new shape. */
  set mesh(g: Geometry) {
    const out: number[] = [ TAG_RENDER_MODE, 1, 3 ]
    pushMesh(out, g)
    this._send(out)
  }

  set angularVelocity(v: Vec3Like | { min: Vec3Like, max: Vec3Like }) {
    const out: number[] = []
    pushAngularVelocity(out, v)
    this._send(out)
  }

  set ground(g: ParticleGround | null) {
    const out: number[] = []
    pushGround(out, g)
    this._send(out)
  }

  set startVelocity(val: Vec3Like | VelocityValue) {
    const out: number[] = []
    pushVelocity(out, val)
    this._send(out)
  }

  /** Positive pulls particles down — sugar for `acceleration = [0, -g, 0]`. */
  set gravity(val: number) { this._send([ TAG_ACCELERATION, 3, 0, -val, 0 ]) }
  set acceleration(a: Vec3Like) { this._send([ TAG_ACCELERATION, 3, cx(a), cy(a), cz(a) ]) }
  set drag(val: number) { this._send([ TAG_DRAG, 1, val ]) }
  set seed(val: number) { this._send([ TAG_SEED, 1, val ]) }

  set lifetime(val: Range<number>) {
    const [ lo, hi ] = lohi(val)
    this._send([ TAG_LIFETIME, 2, lo, hi ])
  }

  set size(val: ParticleValue) { this.custom[0] = val }
  set rotation(val: ParticleValue) { this.custom[1] = val }
  set opacity(val: ParticleValue) { this.custom[2] = val }
  set frame(val: ParticleValue) { this.custom[3] = val }

  set color(value: ParticleColor) {
    const out: number[] = []
    pushColor(out, value)
    this._send(out)
  }

  get material(): Material { return this._material }
  set material(material: Material) {
    this._material = material
    _creator.setMaterial(this.id, Material.idOf(material), 0)
  }

  set noise(noise: Noise | null) {
    this._send(noise
      ? [ TAG_NOISE, 3, noise.strength ?? 1, noise.frequency ?? 1, noise.speed ?? 1 ]
      : [ TAG_NOISE, 3, 0, 0, 0 ])
  }
}

// --- ribbon trail -------------------------------------------------------------------------------

/** `Trail` options. The look options (map/sheet/emissive/blend/soft) come from
 *  `ParticlesMaterialOptions`, same as `Particles`. */
export type TrailOptions = Omit<ParticlesMaterialOptions, "render" | "stretch"> & {
  /** Seconds each trail point lives — the trail's length in time. Default 0.5. */
  time?: number
  /** Strip width in world units; a curve tapers it over each point's life (head → tail).
   *  Default 0.1. */
  width?: ParticleValue
  /** Minimum emitter movement (world units) between recorded points. Default 0.05. */
  minDistance?: number
  /** Point capacity (default 128). */
  maxPoints?: number
  color?: ParticleColor
  /** Opacity along the trail. Defaults to fading the tail out (`curve().to(0)`). */
  opacity?: ParticleValue
}

/** A ribbon strip that follows this node through the world — sword swings, skid marks, missile
 *  trails. Attach it to (or under) the moving node and just move; points are laid down per
 *  `minDistance` of movement, live for `time` seconds, and the strip stays glued to the node at
 *  its head. Width/opacity/color accept the same curves as `Particles`, evaluated over each
 *  point's life — i.e. along the trail from head (fresh) to tail (dying). */
export class Trail extends Node {
  private _material: Material
  private _rateDistance: number

  constructor(options: TrailOptions = {}) {
    super()
    this._material = Material.particles({ ...options, render: "ribbon" })
    _creator.createParticleSystem(this.id, Material.idOf(this._material), options.maxPoints ?? 128)

    const time = options.time ?? 0.5
    this._rateDistance = 1 / Math.max(options.minDistance ?? 0.05, 1e-3)
    const out: number[] = [
      TAG_RENDER_MODE, 1, 2,
      TAG_SPACE, 1, 1,          // a trail is only meaningful in world space
      TAG_RATE, 1, 0,           // points come from movement, never from time
      TAG_RATE_DISTANCE, 1, this._rateDistance,
      TAG_LIFETIME, 2, time, time,
    ]
    pushParam(out, 0, options.width ?? 0.1)
    pushParam(out, 2, options.opacity ?? curve().to(0))
    if (options.color !== undefined) pushColor(out, options.color)
    _creator.setParticleSystemConfig(this.id, Float32Array.from(out))
  }

  private _send(out: number[]): void {
    _creator.setParticleSystemConfig(this.id, Float32Array.from(out))
  }

  /** Trail length in seconds — how long each laid-down point lives. */
  set time(val: number) { this._send([ TAG_LIFETIME, 2, val, val ]) }

  set width(val: ParticleValue) {
    const out: number[] = []
    pushParam(out, 0, val)
    this._send(out)
  }

  set opacity(val: ParticleValue) {
    const out: number[] = []
    pushParam(out, 2, val)
    this._send(out)
  }

  set color(value: ParticleColor) {
    const out: number[] = []
    pushColor(out, value)
    this._send(out)
  }

  set minDistance(val: number) {
    this._rateDistance = 1 / Math.max(val, 1e-3)
    this._send([ TAG_RATE_DISTANCE, 1, this._rateDistance ])
  }

  /** Pause/resume laying down points — existing ones still age out, so the trail fades naturally
   *  after e.g. a sword swing ends. */
  set emitting(val: boolean) { this._send([ TAG_RATE_DISTANCE, 1, val ? this._rateDistance : 0 ]) }

  get material(): Material { return this._material }
}
