@dailies-studio/particles 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dailies-studio/particles",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "First-party GLB particle emitter: a contracted react-three-fiber component whose emission is a pure function of (frame, seed) — seeded PCG32 + closed-form kinematics, never per-tick integration. Dogfoods the contract system's curve/gradient/asset kinds.",
   "type": "module",
   "exports": {
@@ -29,9 +29,9 @@
     "@react-three/drei": "^10.7.7",
     "@react-three/fiber": "^9.6.1",
     "three": "^0.185.1",
-    "@dailies-studio/contract": "0.1.0",
-    "@dailies-studio/engine": "0.1.0",
-    "@dailies-studio/runtime": "0.1.0"
+    "@dailies-studio/contract": "0.2.0",
+    "@dailies-studio/engine": "0.2.0",
+    "@dailies-studio/runtime": "0.2.0"
   },
   "peerDependencies": {
     "react": ">=18.0"

package/src/controls.ts

@@ -39,6 +39,14 @@ export const DEFAULTS = {
   scaleOverLife: DEFAULT_SCALE_OVER_LIFE,
   colorOverLife: DEFAULT_COLOR_OVER_LIFE,
   glbSrc: null as string | null,
+  // The basics-overhaul growth: an emission volume, a burst mode, a sprite.
+  // Every default is the pre-growth behaviour, so "no props" stays the same
+  // animation it always was.
+  emitterShape: "point" as "point" | "box" | "sphere",
+  emitterExtent: 0.5,
+  emitMode: "loop" as "loop" | "burst",
+  burstSeconds: 0.25,
+  spriteSrc: null as string | null,
 } as const;
 
 export const FOIL_BALLOONS_DEFAULTS = {
@@ -143,5 +151,35 @@ export const controls: Contract = defineControls({
   seed: c.number({ default: DEFAULTS.seed, min: 0, max: 99999, step: 1, animatable: false }),
   scaleOverLife: c.curve({ default: DEFAULT_SCALE_OVER_LIFE, label: "Scale over life" }),
   colorOverLife: c.gradient({ default: DEFAULT_COLOR_OVER_LIFE, label: "Color over life" }),
+  // Where particles are born. No "cone" volume on purpose: conical emission is
+  // `spread`'s whole job, and a second cone would be two knobs over one
+  // meaning.
+  emitterShape: c.enum({
+    options: ["point", "box", "sphere"],
+    default: DEFAULTS.emitterShape,
+    label: "Emitter shape",
+  }),
+  emitterExtent: c.number({
+    default: DEFAULTS.emitterExtent,
+    min: 0.01,
+    max: 10,
+    step: 0.01,
+    label: "Emitter extent",
+  }),
+  // "loop" streams forever; "burst" emits only the first window's worth —
+  // closed-form (an index cap, never emitted-so-far state), so scrubbing
+  // backwards through a burst is exact.
+  emitMode: c.enum({ options: ["loop", "burst"], default: DEFAULTS.emitMode, label: "Emit" }),
+  burstSeconds: c.number({
+    default: DEFAULTS.burstSeconds,
+    min: 0.05,
+    max: 5,
+    step: 0.05,
+    unit: "s",
+    label: "Burst window",
+  }),
   glbSrc: c.asset({ assetKind: "glb", default: null, label: "GLB model" }),
+  // A textured quad as the particle — Spline's model. The GLB wins when both
+  // are set (the pre-growth precedence, so no shipped document changes).
+  spriteSrc: c.asset({ assetKind: "image", default: null, label: "Sprite image" }),
 });

package/src/emission.ts

@@ -27,6 +27,22 @@ export interface EmissionConfig {
   spinMaxDegPerSec: number;
   /** The contract seed: same seed = same animation, everywhere, forever. */
   seed: number;
+  /**
+   * The emission VOLUME a particle is born inside (basics overhaul). Absent =
+   * "point", which is every animation shipped before the field existed. There
+   * is deliberately no "cone" volume: conical emission is `spreadDeg`'s whole
+   * job, and a second cone would be two knobs fighting over one meaning.
+   */
+  emitterShape?: "point" | "box" | "sphere";
+  /** The volume's extent, world units: box half-extent per axis, sphere
+   *  radius. Absent = 0.5. Ignored for "point". */
+  emitterExtent?: number;
+  /** "loop" (absent, the default) streams forever; "burst" emits ONLY the
+   *  first `burstSeconds` worth of particles and then nothing, closed-form —
+   *  the range is capped by index, never by state. */
+  emitMode?: "loop" | "burst";
+  /** The burst window, seconds. Absent = 0.25. */
+  burstSeconds?: number;
 }
 
 export type Vec3Tuple = readonly [number, number, number];
@@ -43,6 +59,9 @@ export interface ParticleAttributes {
   spinAxis: Vec3Tuple;
   /** Signed spin rate, radians/sec. */
   spinRate: number;
+  /** Birth position inside the emitter volume, emitter-local. [0,0,0] for a
+   *  "point" emitter — every pre-volume animation, bit-identical. */
+  origin: Vec3Tuple;
 }
 
 const DEG = Math.PI / 180;
@@ -51,6 +70,14 @@ const DEG = Math.PI / 180;
  * Particle i's immutable attributes. Draw order (the wire format):
  *   1. cone cap height  2. cone azimuth  3. speed jitter
  *   4. spin-axis z      5. spin-axis azimuth  6. spin rate
+ *   7. volume u1        8. volume u2          9. volume u3
+ *
+ * Draws 7-9 were APPENDED for the emitter volume (basics overhaul) and are
+ * drawn UNCONDITIONALLY — a "point" emitter discards them — so switching the
+ * shape can never reshuffle another channel, and a future draw 10 sits after
+ * them for every shape. Draws 1-6 are byte-identical to the original wire
+ * format, which is what keeps every animation exported before the volume
+ * existed exact.
  */
 export function particleAttributes(cfg: EmissionConfig, index: number): ParticleAttributes {
   // PCG32 seeding is 64-bit integer math; a fractional or non-finite seed
@@ -81,15 +108,44 @@ export function particleAttributes(cfg: EmissionConfig, index: number): Particle
 
   const spinRate = (rng.next01() * 2 - 1) * cfg.spinMaxDegPerSec * DEG;
 
+  // Draws 7-9: the volume uniforms, drawn for EVERY shape (see the wire-format
+  // note above). Interpretation is per shape and closed-form — no rejection
+  // sampling, whose variable draw count would be its own wire-format break.
+  const u1 = rng.next01();
+  const u2 = rng.next01();
+  const u3 = rng.next01();
+  const extent = Number.isFinite(cfg.emitterExtent) && cfg.emitterExtent! > 0 ? cfg.emitterExtent! : 0.5;
+  let origin: Vec3Tuple = [0, 0, 0];
+  if (cfg.emitterShape === "box") {
+    origin = [(u1 * 2 - 1) * extent, (u2 * 2 - 1) * extent, (u3 * 2 - 1) * extent];
+  } else if (cfg.emitterShape === "sphere") {
+    // Uniform in the ball: direction from (z, phi), radius by cbrt — the
+    // closed-form density-correct draw.
+    const z = u1 * 2 - 1;
+    const phi = u2 * 2 * Math.PI;
+    const r = Math.cbrt(u3) * extent;
+    const ring = Math.sqrt(Math.max(0, 1 - z * z));
+    origin = [ring * Math.cos(phi) * r, z * r, ring * Math.sin(phi) * r];
+  }
+
   return {
     birth: index / cfg.emissionRate,
     direction,
     speed,
     spinAxis,
     spinRate,
+    origin,
   };
 }
 
+/** How many particles a BURST emits: every index whose birth lands inside the
+ *  window. Infinity for the loop mode, so range math can `min` against it. */
+export function burstIndexCap(cfg: EmissionConfig): number {
+  if (cfg.emitMode !== "burst") return Number.POSITIVE_INFINITY;
+  const seconds = Number.isFinite(cfg.burstSeconds) && cfg.burstSeconds! > 0 ? cfg.burstSeconds! : 0.25;
+  return Math.ceil(cfg.emissionRate * seconds);
+}
+
 /**
  * CANDIDATE indices for particles alive at time t — a guaranteed superset of
  * every index whose {@link particleState} gate (birth ≤ t < birth+lifetime)
@@ -104,15 +160,20 @@ export function particleAttributes(cfg: EmissionConfig, index: number): Particle
 export function activeIndexRange(cfg: EmissionConfig, t: number): [number, number] {
   if (!(cfg.emissionRate > 0) || !(cfg.particleLifetime > 0) || !(t >= 0)) return [0, 0];
   // birth = i/rate ≤ t  →  i ≤ t·rate ; t < birth + L  →  i > (t - L)·rate
-  const end = Math.floor(t * cfg.emissionRate) + 2;
+  // A burst caps the candidate INDEX, never the gate: indices past the window
+  // simply never existed, which is what keeps the mode a pure function of the
+  // frame rather than a piece of emitted-so-far state.
+  const end = Math.min(Math.floor(t * cfg.emissionRate) + 2, burstIndexCap(cfg));
   const start = Math.max(0, Math.floor((t - cfg.particleLifetime) * cfg.emissionRate) - 1);
   return start < end ? [start, end] : [0, 0];
 }
 
-/** Capacity an instance buffer needs to hold every concurrently-live particle. */
+/** Capacity an instance buffer needs to hold every concurrently-live particle.
+ *  A burst can never hold more than its own index cap. */
 export function particleCapacity(cfg: EmissionConfig, cap = 4096): number {
   if (!(cfg.emissionRate > 0) || !(cfg.particleLifetime > 0)) return 0;
-  return Math.min(cap, Math.ceil(cfg.emissionRate * cfg.particleLifetime) + 1);
+  const streaming = Math.ceil(cfg.emissionRate * cfg.particleLifetime) + 1;
+  return Math.min(cap, streaming, burstIndexCap(cfg));
 }
 
 export interface ParticleState {
@@ -132,18 +193,28 @@ export function particleState(
   attrs: ParticleAttributes,
   cfg: EmissionConfig,
   t: number,
+  /** Written in place and returned when given: the emitter's per-frame loop
+   *  runs this once per live particle (up to 4096 per frame) and allocated a
+   *  state object and a position tuple for each. Same numbers either way. */
+  out?: ParticleState,
 ): ParticleState | null {
   const age = t - attrs.birth;
   if (!(age >= 0) || age >= cfg.particleLifetime) return null;
   const s = attrs.speed;
   const halfG = -0.5 * cfg.gravity * age * age;
-  return {
-    position: [
-      attrs.direction[0] * s * age,
-      attrs.direction[1] * s * age + halfG,
-      attrs.direction[2] * s * age,
-    ],
-    spinAngle: attrs.spinRate * age,
-    life01: age / cfg.particleLifetime,
-  };
+  const x = attrs.origin[0] + attrs.direction[0] * s * age;
+  const y = attrs.origin[1] + attrs.direction[1] * s * age + halfG;
+  const z = attrs.origin[2] + attrs.direction[2] * s * age;
+  const spinAngle = attrs.spinRate * age;
+  const life01 = age / cfg.particleLifetime;
+  if (out !== undefined) {
+    const position = out.position as [number, number, number];
+    position[0] = x;
+    position[1] = y;
+    position[2] = z;
+    out.spinAngle = spinAngle;
+    out.life01 = life01;
+    return out;
+  }
+  return { position: [x, y, z], spinAngle, life01 };
 }

package/src/emitter.tsx

@@ -7,7 +7,7 @@
 import React, { Suspense, useLayoutEffect, useMemo } from "react";
 import * as THREE from "three";
 import { useThree } from "@react-three/fiber";
-import { useGLTF } from "@react-three/drei";
+import { useGLTF, useTexture } from "@react-three/drei";
 import { compileCurve, compileGradient } from "@dailies-studio/contract";
 import type { CurveValue, GradientValue } from "@dailies-studio/contract";
 import { useStudioClock } from "@dailies-studio/runtime";
@@ -17,7 +17,7 @@ import {
   particleCapacity,
   particleState,
 } from "./emission.js";
-import type { EmissionConfig, ParticleAttributes } from "./emission.js";
+import type { EmissionConfig, ParticleAttributes, ParticleState } from "./emission.js";
 import { DEFAULTS, DEFAULT_COLOR_OVER_LIFE, DEFAULT_SCALE_OVER_LIFE } from "./controls.js";
 
 export interface ParticleEmitterProps {
@@ -33,6 +33,11 @@ export interface ParticleEmitterProps {
   scaleOverLife?: CurveValue;
   colorOverLife?: GradientValue;
   glbSrc?: string | null;
+  emitterShape?: "point" | "box" | "sphere";
+  emitterExtent?: number;
+  emitMode?: "loop" | "burst";
+  burstSeconds?: number;
+  spriteSrc?: string | null;
 }
 
 // Loop temporaries — module scope so the per-frame update allocates nothing.
@@ -41,7 +46,23 @@ const POS = new THREE.Vector3();
 const SCL = new THREE.Vector3();
 const AXIS = new THREE.Vector3();
 const QUAT = new THREE.Quaternion();
-const COLOR = new THREE.Color();
+/** Written in place by `particleState` for every live particle per frame. */
+const STATE: ParticleState = { position: [0, 0, 0], spinAngle: 0, life01: 0 };
+
+// `THREE.Color.set(string)` is a CSS colour parse, and it ran once per live
+// particle per frame (up to 4096). The gradient hands back 8-bit hex strings,
+// so the distinct values are few: one parsed Color per hex, in a table cleared
+// whole when it fills. The returned Color is READ ONLY (`setColorAt` copies).
+const COLOR_BY_HEX = new Map<string, THREE.Color>();
+const COLOR_BY_HEX_LIMIT = 4096;
+function colorForHex(hex: string): THREE.Color {
+  const cached = COLOR_BY_HEX.get(hex);
+  if (cached !== undefined) return cached;
+  const color = new THREE.Color().set(hex);
+  if (COLOR_BY_HEX.size >= COLOR_BY_HEX_LIMIT) COLOR_BY_HEX.clear();
+  COLOR_BY_HEX.set(hex, color);
+  return color;
+}
 
 /** First mesh in a GLTF scene — the emitter's instanced geometry source. */
 export function firstMeshOf(scene: THREE.Object3D): THREE.Mesh | null {
@@ -96,6 +117,8 @@ export function ParticleInstances(props: ParticleInstancesProps): React.ReactEle
       config.speed,
       config.speedJitter,
       config.spinMaxDegPerSec,
+      config.emitterShape,
+      config.emitterExtent,
     ];
     return new Map<number, ParticleAttributes>();
   }, [
@@ -105,6 +128,11 @@ export function ParticleInstances(props: ParticleInstancesProps): React.ReactEle
     config.speed,
     config.speedJitter,
     config.spinMaxDegPerSec,
+    // The volume feeds `origin`, so its two fields re-roll the cache exactly
+    // as the six draw inputs above do. The burst fields deliberately do NOT:
+    // they cap the index range and never touch an attribute.
+    config.emitterShape,
+    config.emitterExtent,
   ]);
 
   const scaleFn = useMemo(() => compileCurve(props.scaleOverLife), [props.scaleOverLife]);
@@ -124,7 +152,7 @@ export function ParticleInstances(props: ParticleInstancesProps): React.ReactEle
         attrs = particleAttributes(config, i);
         attrCache.set(i, attrs);
       }
-      const st = particleState(attrs, config, timeSeconds);
+      const st = particleState(attrs, config, timeSeconds, STATE);
       if (!st) continue;
       const s = Math.max(0, size * scaleFn(st.life01));
       AXIS.set(attrs.spinAxis[0], attrs.spinAxis[1], attrs.spinAxis[2]);
@@ -134,8 +162,7 @@ export function ParticleInstances(props: ParticleInstancesProps): React.ReactEle
       M4.compose(POS, QUAT, SCL);
       mesh.setMatrixAt(n, M4);
       // THREE.Color has no alpha channel — an 8-digit stop keeps its rgb.
-      COLOR.set(colorFn(st.life01).slice(0, 7));
-      mesh.setColorAt(n, COLOR);
+      mesh.setColorAt(n, colorForHex(colorFn(st.life01).slice(0, 7)));
       n++;
     }
     mesh.count = n;
@@ -172,6 +199,34 @@ const DEFAULT_GEOMETRY = new THREE.TetrahedronGeometry(1);
 // Unlit: the gradient IS the look, with or without user lights.
 const DEFAULT_MATERIAL = new THREE.MeshBasicMaterial({ color: 0xffffff });
 
+// The sprite quad, shared: a unit plane every sprite particle instances.
+const SPRITE_GEOMETRY = new THREE.PlaneGeometry(1, 1);
+
+/**
+ * Sprite particles — a textured quad as the particle (Spline's model).
+ *
+ * NOT billboarded, deliberately: a camera-facing quad needs the camera pose at
+ * commit time, which is a second read-order dependency between subtrees this
+ * lane refuses to own. The quad faces +Z, which faces the camera in the rest
+ * framing, and the ordinary spin channel reads as designed on round sprites.
+ * Alpha-blended with depthWrite off, the layer-plane rule, so soft edges never
+ * punch holes in what draws behind them.
+ */
+function SpriteParticles(
+  props: Omit<ParticleInstancesProps, "geometry" | "material"> & { url: string },
+): React.ReactElement | null {
+  const texture = useTexture(props.url);
+  const material = useMemo(() => {
+    // drei caches textures by url; the colour space stamp is idempotent, and
+    // the MATERIAL is ours to make (and dispose) per mount.
+    texture.colorSpace = THREE.SRGBColorSpace;
+    return new THREE.MeshBasicMaterial({ map: texture, transparent: true, depthWrite: false });
+  }, [texture]);
+  useLayoutEffect(() => () => material.dispose(), [material]);
+  const { url: _url, ...rest } = props;
+  return <ParticleInstances {...rest} geometry={SPRITE_GEOMETRY} material={material} />;
+}
+
 /**
  * The contracted emitter. Props mirror ./controls.ts one-to-one; DEFAULTS
  * keeps "no props at all" identical to the contract's defaults.
@@ -190,6 +245,11 @@ export function ParticleEmitter(props: ParticleEmitterProps): React.ReactElement
     scaleOverLife = DEFAULT_SCALE_OVER_LIFE,
     colorOverLife = DEFAULT_COLOR_OVER_LIFE,
     glbSrc = null,
+    emitterShape = DEFAULTS.emitterShape,
+    emitterExtent = DEFAULTS.emitterExtent,
+    emitMode = DEFAULTS.emitMode,
+    burstSeconds = DEFAULTS.burstSeconds,
+    spriteSrc = null,
   } = props;
 
   const clock = useStudioClock();
@@ -205,11 +265,30 @@ export function ParticleEmitter(props: ParticleEmitterProps): React.ReactElement
       gravity,
       spinMaxDegPerSec: spin,
       seed,
+      emitterShape,
+      emitterExtent,
+      emitMode,
+      burstSeconds,
     }),
-    [emissionRate, particleLifetime, spread, speed, speedJitter, gravity, spin, seed],
+    [
+      emissionRate,
+      particleLifetime,
+      spread,
+      speed,
+      speedJitter,
+      gravity,
+      spin,
+      seed,
+      emitterShape,
+      emitterExtent,
+      emitMode,
+      burstSeconds,
+    ],
   );
 
   const shared = { config, size, scaleOverLife, colorOverLife, timeSeconds };
+  // Precedence: the GLB wins over the sprite — the pre-growth rule, so no
+  // shipped document's look moves — and the tetrahedron is the fallback.
   if (glbSrc) {
     return (
       <Suspense fallback={null}>
@@ -217,6 +296,13 @@ export function ParticleEmitter(props: ParticleEmitterProps): React.ReactElement
       </Suspense>
     );
   }
+  if (spriteSrc) {
+    return (
+      <Suspense fallback={null}>
+        <SpriteParticles url={spriteSrc} {...shared} />
+      </Suspense>
+    );
+  }
   return (
     <ParticleInstances {...shared} geometry={DEFAULT_GEOMETRY} material={DEFAULT_MATERIAL} />
   );