paperlab 0.7.1 → 0.8.1

package/dist/fx.js

@@ -31,11 +31,11 @@ import {
   luminance,
   srgbToLinear,
   timesPaperWhite
-} from "./chunk-GB6BMHC3.js";
+} from "./chunk-S74YZAXE.js";
 import {
   DAMAGE_CHANNELS,
   DAMAGE_LOOK_DEFAULTS
-} from "./chunk-7TLIWPGM.js";
+} from "./chunk-BIFUJCUA.js";
 
 // src/fx/particles.ts
 var particlePresets = {
@@ -47,7 +47,7 @@ var particlePresets = {
    * caught the bug in the version before this one. That version said "the hot
    * end is now ~5.6, well over the bloom threshold" — and 5.6 was an ABSOLUTE
    * luminance, while paper white under `window` is 1.6. So the hottest spark
-   * in the frame was **3.5× paper, under the spec's own 4× floor**, and its
+   * in the frame was **3.5× paper, under the 4× floor**, and its
    * own comment said otherwise. A number that cannot be compared to anything
    * is a number nobody can check.
    *
@@ -67,12 +67,12 @@ var particlePresets = {
     drag: 0.8,
     jitter: 1.5,
     windCatch: 0.8,
-    // 0.3-1 mm of core (§5). A sheet is one world unit across, 210 mm, so
+    // 0.3-1 mm of core. A sheet is one world unit across, 210 mm, so
     // 0.0035 is 0.7 mm. It was 0.005 — a full millimetre wide before the
     // streak stretched it, which is where "wide bars" started.
     size: [35e-4, 12e-4],
     color: [
-      // 6× paper white: inside §4.3's 4–8 band, so it blooms.
+      // 6× paper white: inside the 4–8× band, so it blooms.
       emitHex("#FFC271", 6),
       // 0.7× — UNDER the bloom threshold on purpose, so a dying spark stops
       // glowing rather than merely fading.
@@ -90,7 +90,13 @@ var particlePresets = {
    * simulation, on purpose; see the fx plan.
    */
   smoke: {
-    life: [1.8, 3.5],
+    // Shorter, and smaller below: these are the thread beside the
+    // simulator's smoke, and the simulator's is gone within a second or two
+    // of the last flame. Left to live three and a half seconds and grow to
+    // seven centimetres, the last few of them overlapped into a flat wash
+    // over the hole with nothing left to move them — the one moment of a
+    // burn where the smoke looked wrong.
+    life: [1.4, 2.6],
     speed: [0.05, 0.15],
     direction: [0, 1, 0],
     spread: 0.3,
@@ -98,13 +104,13 @@ var particlePresets = {
     drag: 0.9,
     jitter: 0.3,
     windCatch: 1,
-    size: [0.05, 0.35],
+    size: [0.05, 0.18],
     // #6B6560 grey-brown, linear, and thin — the background stays clear.
     color: [
       [0.147, 0.13, 0.117],
       [0.2, 0.19, 0.18]
     ],
-    alpha: [0.08, 0],
+    alpha: [0.07, 0],
     spin: 0.4,
     blend: "normal",
     shape: "soft",
@@ -116,7 +122,9 @@ var particlePresets = {
    * burn that proves paper was there.
    */
   ash: {
-    life: [2.5, 5],
+    // A second or two: ash that hung in the air for five read as grey
+    // confetti over the hole, dust or stars rather than something falling.
+    life: [1.2, 2.6],
     // Thrown UP by the heat it came off, before it is heavier than the air.
     // It used to leave at almost nothing (0.02–0.1) with a lift of −0.35, so
     // every flake began falling the moment it was born — straight through the
@@ -124,17 +132,21 @@ var particlePresets = {
     speed: [0.14, 0.3],
     direction: [0, 1, 0],
     spread: 0.55,
-    lift: -0.22,
+    // Heavier than the air once the throw is spent: most flakes tumble down,
+    // only the lightest ride the heat up a little first.
+    lift: -0.42,
     drag: 1.6,
     jitter: 1.2,
     windCatch: 1,
-    // 5–10 mm across (§8.3). A sheet is 210 mm, so 0.03 is 6.3 mm. They were
+    // 5–10 mm across. A sheet is 210 mm, so 0.03 is 6.3 mm. They were
     // 3.8 mm and there were far too many of them: a shower of specks rather
     // than a few flakes you would notice.
     size: [0.03, 0.026],
+    // Charred paper, near black: under a bright key the old value read as
+    // pale grey against the black stage, which is the confetti.
     color: [
-      [0.07, 0.065, 0.06],
-      [0.12, 0.115, 0.11]
+      [0.04, 0.037, 0.034],
+      [0.07, 0.066, 0.062]
     ],
     alpha: [0.95, 0],
     spin: 4,
@@ -358,13 +370,14 @@ var ParticlePool = class {
 
 // src/fx/fire.ts
 var fireEmitterDefaults = {
-  embers: 0.35,
-  smoke: 0,
-  ash: 0.12,
+  embers: 0.39,
+  smoke: 0.135,
+  ash: 0.36,
   seed: 7,
   caps: {}
 };
 var PER_UPDATE = 24;
+var CRACKLE_SPARKS = 0.06;
 var FireEmitter = class {
   field;
   pool;
@@ -401,7 +414,10 @@ var FireEmitter = class {
       heat /= front;
       const struggle = 0.35 + 1.6 * Math.max(0, 0.7 - heat) + air * 0.8;
       const oxygen = 1 + air * 1.5;
-      this.emberDebt = Math.min(this.emberDebt + front * o.embers * oxygen * dt, PER_UPDATE);
+      this.emberDebt = Math.min(
+        this.emberDebt + front * o.embers * oxygen * dt + field.lastStats.charred * o.embers * CRACKLE_SPARKS,
+        PER_UPDATE
+      );
       this.smokeDebt = Math.min(this.smokeDebt + front * o.smoke * struggle * dt, PER_UPDATE);
       while (this.emberDebt >= 1) {
         this.emberDebt -= 1;
@@ -533,7 +549,7 @@ void main() {
   // It used to be flat-topped across (smoothstep from 0.35, so the middle
   // seventy per cent of the width was all at full brightness) and to keep a
   // quarter of that brightness all the way to the end of the quad. Both
-  // together drew a wide bar with a squared-off end, which is what the review
+  // together drew a wide bar with a squared-off end, which is what a visual review
   // saw up close. A spark is a point of light smeared by its own motion: it
   // is brightest on its centre line and it runs out.
   float across = abs(vQuad.x);
@@ -653,14 +669,14 @@ void main() {
   float edge = 0.62 + 0.3 * flNoise(vec2(a * 1.6 + vSeed * 31.0, vSeed * 7.0));
   float mask = 1.0 - smoothstep(edge - 0.06, edge, r);
   if (mask <= 0.0) discard;
-  // Char in the middle, pale brittle ash at the edge (\xA78.3) \u2014 in patches
+  // Char in the middle, pale brittle ash at the edge \u2014 in patches
   // along it, not all the way round: a flake is a few pixels across, and a
   // continuous pale rim round a dark middle drew it as a hollow ring.
   float rim = smoothstep(edge - 0.32, edge - 0.04, r);
   float patches = smoothstep(0.45, 0.75, flNoise(vec2(a * 2.2 + vSeed * 17.0, vSeed * 13.0)));
   float grain = flNoise(vQuad * 3.0 + vSeed * 23.0);
   vec3 charC = vec3(0.05, 0.043, 0.038) * (0.7 + 0.6 * grain);
-  // #A49E9D, the spec's own sample of ash (\xA78.3), in linear.
+  // #A49E9D, sampled from the reference ash, in linear.
   vec3 ashC = vec3(0.372, 0.344, 0.340);
   // Pale ash with char under it, not char with a pale rim.
   //
@@ -757,7 +773,7 @@ function FxParticles({ pool }) {
 import { Suspense, lazy } from "react";
 import { jsx as jsx2 } from "react/jsx-runtime";
 var Pass = lazy(
-  () => import("./FxPostPass-M66QMVVC.js").then((m) => ({ default: m.FxPostPass })).catch((error) => {
+  () => import("./FxPostPass-ACFSHY3S.js").then((m) => ({ default: m.FxPostPass })).catch((error) => {
     warnOnce(error);
     return { default: (() => null) };
   })
@@ -767,7 +783,7 @@ function warnOnce(cause) {
   if (warned) return;
   warned = true;
   console.warn(
-    "[paperlab/fx] Rendering without FxPost \u2014 fire will not bloom.\nIt needs two optional peers:\n  npm i @react-three/postprocessing postprocessing\nLeave <FxPost> out to go without it deliberately and silence this.",
+    "[paperlab/fx] Rendering without FxPost, so fire will not bloom.\nIt needs two optional peers:\n  npm i @react-three/postprocessing postprocessing\nLeave <FxPost> out to go without it deliberately and silence this.",
     ...cause === void 0 ? [] : [cause]
   );
 }
@@ -818,7 +834,7 @@ var Afterglow = class {
   }
   /**
    * Advance by `dt`, after the field has stepped. `blow` is the breath on the
-   * sheet, 0..1: it flares what is left (§10.6, "on smoulder: beads flare,
+   * sheet, 0..1: it flares what is left ("on smoulder: beads flare,
    * then fade").
    */
   step(dt, blow = 0) {
@@ -1742,10 +1758,17 @@ void main() {
   float rootMask = smoothstep(mix(0.4, 0.02, uRootReach), mix(0.6, 0.12, uRootReach), fuel) * (1.0 - smoothstep(0.25, 0.6, t));
   fire += uRootColor * rootMask * uRootAmount * uPaperWhite * uGlow * 0.6;
 
-  // Smoke: warm grey-brown (a cool grey over cream reads lavender), lit by
-  // the fire under it.
+  // Smoke: grey-brown, warm (a cool grey over cream reads lavender), and LIT
+  // BY THE FIRE UNDER IT rather than by nothing.
+  //
+  // The base used to be bright enough to read on its own \u2014 beige \u2014 which is
+  // right while flames are lighting it and wrong the moment they stop: the
+  // last of the smoke hung over a black stage as flat beige slabs, the same
+  // colour everywhere, which reads as a filled shape rather than as smoke.
+  // Dim at the base and warm where the fire is: smoke by
+  // the flames looks as it did, smoke after them goes to a dim grey.
   float smokeAlpha = 1.0 - exp(-smoke * uSmokeDensity);
-  vec3 smokeColor = vec3(0.16, 0.13, 0.10) + vec3(0.22, 0.09, 0.02) * smoothstep(0.15, 0.9, t);
+  vec3 smokeColor = vec3(0.075, 0.068, 0.062) + vec3(0.3, 0.14, 0.045) * smoothstep(0.12, 0.9, t);
   float alpha = smokeAlpha + fireAlpha - smokeAlpha * fireAlpha;
   // No square edge: the domain fades out before its borders.
   float edge = smoothstep(0.0, 0.06, vUv.x) * smoothstep(1.0, 0.94, vUv.x) * smoothstep(0.0, 0.03, vUv.y) * smoothstep(1.0, 0.9, vUv.y);
@@ -2131,7 +2154,7 @@ var fireFluidDefaults = {
   smoke: 0.7,
   // Was 5 — a full unit a second, 210 mm/s, of gas pushed sideways out of the
   // rim. Against a buoyancy of 1.7 units/s² that is what rolled the flames
-  // into mushroom caps: the grey spirals over the text that the review called
+  // into mushroom caps: the grey spirals over the text that a visual review called
   // the most synthetic thing in the frame. A flame leaves paper going UP.
   radialImpulse: 0.8,
   // In world units a second now (see `solverUniforms`): 1.4 is ~0.3 m/s, the
@@ -2164,7 +2187,7 @@ var fireFluidDefaults = {
   // reached the text (~150 mm), 1.6 ~100 mm, 2.1 short licks (~60 mm);
   // Hero.png's tallest is ~70 mm.
   cooling: 1.8,
-  // Was 1.4, which made a thick grey column, then 0.5. Noor's direction is
+  // Was 1.4, which made a thick grey column, then 0.5. The direction is
   // light smoke, and with MacCormack advection keeping the smoke's fine
   // structure it needs less of it to read: at 0.5 it veiled the upper sheet.
   smokeProduction: 0.25,
@@ -2544,55 +2567,261 @@ function FxFireFluid({
 import * as THREE6 from "three";
 import { useFrame as useFrame5 } from "@react-three/fiber";
 import { useRef as useRef4 } from "react";
-import { Fragment as Fragment3, jsx as jsx6, jsxs as jsxs2 } from "react/jsx-runtime";
-function FxFireLight({ field, locate, gain = FIRE_LIGHT_GAIN }) {
-  const front = useRef4(null);
-  const through = useRef4(null);
-  const anchors = useRef4([]);
-  useFrame5(({ camera }) => {
-    const a = front.current;
-    const b = through.current;
-    if (!a || !b) return;
-    const n = flameAnchors(field, locate, 32, anchors.current);
-    if (n === 0) {
-      a.intensity = 0;
-      b.intensity = 0;
-      return;
-    }
+
+// src/fx/fireState.ts
+var FLAMES = 32;
+var FIRE_CLUSTERS = 4;
+var CLUSTER_REACH = 25 / 210;
+var FireState = class {
+  constructor(field, locate) {
+    this.field = field;
+    this.locate = locate;
+  }
+  field;
+  locate;
+  /** The flames it was taken over. Only the first {@link count} are current. */
+  anchors = [];
+  count = 0;
+  /** Where the fire is, as a whole: its flames' mean. Zero with none. */
+  x = 0;
+  y = 0;
+  z = 0;
+  /** Its flames' mean height. */
+  height = 0;
+  /** Its flames' mean puff. */
+  flicker = 0;
+  /** Where it is gathered. Only the first {@link clusterCount} are current. */
+  clusters = [];
+  clusterCount = 0;
+  frame = Number.NaN;
+  order = [];
+  root = new Float64Array(FIRE_CLUSTERS * 3);
+  weight = new Float64Array(FIRE_CLUSTERS);
+  /**
+   * Bring it up to date for `frame` — any number that is the same for every
+   * reader in one frame and different in the next; R3F's `clock.elapsedTime`
+   * is the one in hand. Free the second time it is asked in a frame.
+   */
+  update(frame) {
+    if (frame === this.frame) return this;
+    this.frame = frame;
+    const { field, anchors } = this;
+    const n = flameAnchors(field, this.locate, FLAMES, anchors);
+    this.count = n;
     let x = 0;
     let y = 0;
     let z = 0;
     let h = 0;
     let flicker = 0;
     for (let i = 0; i < n; i++) {
-      const f = anchors.current[i];
+      const f = anchors[i];
       x += f.x;
       y += f.y;
       z += f.z;
       h += f.height;
       flicker += flamePuff(f.seed, field.time);
     }
-    x /= n;
-    y /= n;
-    z /= n;
-    h /= n;
-    flicker /= n;
-    const toCamera = new THREE6.Vector3(camera.position.x - x, 0, camera.position.z - z);
-    toCamera.normalize().multiplyScalar(0.035);
-    const lift = h * 0.5;
-    a.position.set(x + toCamera.x, y + lift, z + toCamera.z);
-    b.position.set(x - toCamera.x, y + lift, z - toCamera.z);
-    const level = field.lastStats.front * gain * flicker;
-    a.intensity = level;
-    b.intensity = level * 0.35;
+    if (n > 0) {
+      x /= n;
+      y /= n;
+      z /= n;
+      h /= n;
+      flicker /= n;
+    }
+    this.x = x;
+    this.y = y;
+    this.z = z;
+    this.height = h;
+    this.flicker = flicker;
+    this.gather();
+    return this;
+  }
+  /**
+   * Group the flames into at most {@link FIRE_CLUSTERS} clusters.
+   *
+   * Tallest first, so each cluster is named by its tallest tongue and stands
+   * where that one stands: a flame joins the nearest cluster within
+   * {@link CLUSTER_REACH} of it, or starts one while there is room, or joins
+   * the nearest once there is not. Pure arithmetic over the flames, so the
+   * same burn gathers the same way every time.
+   */
+  gather() {
+    const anchors = this.anchors;
+    const clusters = this.clusters;
+    const order = this.order;
+    const root = this.root;
+    const weight = this.weight;
+    const n = this.count;
+    order.length = 0;
+    for (let i = 0; i < n; i++) order.push(i);
+    order.sort((i, j) => anchors[j].height - anchors[i].height || i - j);
+    let k = 0;
+    for (const i of order) {
+      const f = anchors[i];
+      let best = -1;
+      let near = Number.POSITIVE_INFINITY;
+      for (let c = 0; c < k; c++) {
+        const d = Math.hypot(f.x - root[c * 3], f.y - root[c * 3 + 1], f.z - root[c * 3 + 2]);
+        if (d < near) {
+          near = d;
+          best = c;
+        }
+      }
+      if (best < 0 || near > CLUSTER_REACH && k < FIRE_CLUSTERS) {
+        best = k++;
+        root[best * 3] = f.x;
+        root[best * 3 + 1] = f.y;
+        root[best * 3 + 2] = f.z;
+        weight[best] = 0;
+        let cluster2 = clusters[best];
+        if (!cluster2) {
+          cluster2 = { x: 0, y: 0, z: 0, height: 0, tallest: 0, flicker: 0, heat: 0, count: 0 };
+          clusters[best] = cluster2;
+        }
+        cluster2.x = 0;
+        cluster2.y = 0;
+        cluster2.z = 0;
+        cluster2.height = 0;
+        cluster2.tallest = f.height;
+        cluster2.flicker = 0;
+        cluster2.heat = 0;
+        cluster2.count = 0;
+      }
+      const cluster = clusters[best];
+      const w = f.height;
+      cluster.x += f.x * w;
+      cluster.y += f.y * w;
+      cluster.z += f.z * w;
+      weight[best] = weight[best] + w;
+      cluster.height += f.height;
+      cluster.flicker += flamePuff(f.seed, this.field.time);
+      cluster.heat += f.heat;
+      cluster.count++;
+    }
+    for (let c = 0; c < k; c++) {
+      const cluster = clusters[c];
+      const w = weight[c];
+      if (w > 0) {
+        cluster.x /= w;
+        cluster.y /= w;
+        cluster.z /= w;
+      } else {
+        cluster.x = root[c * 3];
+        cluster.y = root[c * 3 + 1];
+        cluster.z = root[c * 3 + 2];
+      }
+      cluster.height /= cluster.count;
+      cluster.flicker /= cluster.count;
+      cluster.heat /= cluster.count;
+    }
+    this.clusterCount = k;
+  }
+};
+var shared = /* @__PURE__ */ new WeakMap();
+function fireStateOf(field, locate) {
+  let byLocator = shared.get(field);
+  if (!byLocator) {
+    byLocator = /* @__PURE__ */ new WeakMap();
+    shared.set(field, byLocator);
+  }
+  let state = byLocator.get(locate);
+  if (!state) {
+    state = new FireState(field, locate);
+    byLocator.set(locate, state);
+  }
+  return state;
+}
+
+// src/fx/FxFireLight.tsx
+import { Fragment as Fragment3, jsx as jsx6, jsxs as jsxs2 } from "react/jsx-runtime";
+function FxFireLight({ field, locate, gain = FIRE_LIGHT_GAIN, shadows = false }) {
+  const front = useRef4([]);
+  const through = useRef4(null);
+  const spot = useRef4(null);
+  useFrame5(({ camera, clock }) => {
+    const b = through.current;
+    if (!b) return;
+    const fire = fireStateOf(field, locate).update(clock.elapsedTime);
+    const level = field.lastStats.front * gain;
+    let total = 0;
+    let brightest = -1;
+    let most = 0;
+    for (let c = 0; c < fire.clusterCount; c++) {
+      const cluster = fire.clusters[c];
+      const share = cluster.count * cluster.height;
+      total += share;
+      if (share > most) {
+        most = share;
+        brightest = c;
+      }
+    }
+    const s = shadows ? spot.current : null;
+    if (s) s.intensity = 0;
+    for (let i = 0; i < FIRE_CLUSTERS; i++) {
+      const light = front.current[i];
+      if (!light) continue;
+      const cluster = i < fire.clusterCount ? fire.clusters[i] : null;
+      if (!cluster || !(total > 0)) {
+        light.intensity = 0;
+        continue;
+      }
+      toward.set(camera.position.x - cluster.x, 0, camera.position.z - cluster.z).normalize().multiplyScalar(0.035);
+      light.position.set(cluster.x + toward.x, cluster.y + cluster.height * 0.5, cluster.z + toward.z);
+      light.intensity = level * cluster.flicker * (cluster.count * cluster.height / total);
+      light.color.copy(COOLING).lerp(FIRE_COLOR, Math.min(1, Math.max(0, cluster.heat)));
+      if (s && i === brightest) {
+        s.position.copy(light.position);
+        s.target.position.set(cluster.x, cluster.y, cluster.z);
+        s.target.updateMatrixWorld();
+        s.intensity = light.intensity;
+        s.color.copy(light.color);
+        light.intensity = 0;
+      }
+    }
+    if (fire.count === 0) {
+      b.intensity = 0;
+      return;
+    }
+    toward.set(camera.position.x - fire.x, 0, camera.position.z - fire.z).normalize().multiplyScalar(0.035);
+    b.position.set(fire.x - toward.x, fire.y + fire.height * 0.5, fire.z - toward.z);
+    b.intensity = level * fire.flicker * 0.35;
   });
   return /* @__PURE__ */ jsxs2(Fragment3, { children: [
-    /* @__PURE__ */ jsx6("pointLight", { ref: front, color: FIRE_COLOR, intensity: 0, decay: 0.9, distance: 0 }),
+    Array.from({ length: FIRE_CLUSTERS }, (_, i) => /* @__PURE__ */ jsx6(
+      "pointLight",
+      {
+        ref: (light) => {
+          front.current[i] = light;
+        },
+        color: FIRE_COLOR,
+        intensity: 0,
+        decay: 0.9,
+        distance: 0
+      },
+      i
+    )),
+    shadows && /* @__PURE__ */ jsx6(
+      "spotLight",
+      {
+        ref: spot,
+        color: FIRE_COLOR,
+        intensity: 0,
+        decay: 0.9,
+        distance: 0,
+        angle: 1.3,
+        penumbra: 0.8,
+        castShadow: true,
+        "shadow-mapSize": [512, 512],
+        "shadow-bias": -4e-4
+      }
+    ),
     /* @__PURE__ */ jsx6("pointLight", { ref: through, color: FIRE_COLOR, intensity: 0, decay: 0.9, distance: 0 })
   ] });
 }
+var toward = new THREE6.Vector3();
 var FIRE_COLOR = new THREE6.Color("#ffa24c");
-var FIRE_LIGHT_GAIN = 42;
+var COOLING = new THREE6.Color("#ff8a33");
+var FIRE_LIGHT_GAIN = 26;
 
 // src/fx/FxMatchFlame.tsx
 import * as THREE7 from "three";
@@ -2736,7 +2965,7 @@ var FxAudio = class {
   constructor(options) {
     const { quality = "auto", context, volume = 0.8 } = options;
     this.quality = typeof quality === "string" ? fxQualityFor(quality) : quality;
-    if (!context) throw new Error("FxAudio needs a context \u2014 see createAudioContext()");
+    if (!context) throw new Error("FxAudio needs a context. See createAudioContext()");
     this.ctx = context;
     this.master = this.ctx.createGain();
     this.master.gain.value = volume;
@@ -2996,18 +3225,18 @@ var FireSound = class {
   }
   /**
    * A match struck: the scratch of the head across the box, then the hiss of
-   * it flaring as the head burns off (spec §10.2). Two bursts of the shared
+   * it flaring as the head burns off. Two bursts of the shared
    * noise, one bright and short, one breathier and longer.
    */
   strike() {
     this.burst("fire-strike", 0.9, { type: "bandpass", frequency: 3200, q: 1.1 }, 4e-3, 0.07, 0.8);
     this.burst("fire-flare", 0.8, { type: "highpass", frequency: 1800, q: 0.7 }, 0.03, 0.45, 0.45, 0.05);
   }
-  /** Blown out: a soft, low breath of noise (spec §10.6). */
+  /** Blown out: a soft, low breath of noise. */
   puff() {
     this.burst("fire-puff", 0.6, { type: "lowpass", frequency: 520, q: 0.6 }, 0.02, 0.28, 0.55);
   }
-  /** One ember popping in the air — a tiny click on the frame it flashes (spec §8.1). */
+  /** One ember popping in the air — a tiny click on the frame it flashes. */
   pop() {
     const f = 3e3 + this.next() * 3e3;
     this.burst(
@@ -3148,6 +3377,7 @@ export {
   FIELD_SIZE,
   FIRE_GLOW,
   FIRE_HEAT_SCALE,
+  FIRE_LIGHT_GAIN,
   FIRE_SOOT_SCALE,
   FIRE_ZONES,
   FIXED_DT,