Code-first video & image, rendered natively on WebGPU.
feat(3d): shard primitives, hardware instancing, swarm simulation, and vision shard dancer (#63)
Okan Aslankan47ea1582aa58
diff --git a/README.md b/README.mdindex ab5e30c8..8e25ced8 100644--- a/README.md+++ b/README.md@@ -70,6 +70,9 @@ Every frame is rendered by framefields directly from TypeScript in [`examples/`]<br><sub><a href="examples/19_framefields_film"><code>19_framefields_film</code></a></sub></td><td width="50%" align="center">+ <a href="https://youtu.be/xSowU7X48J8"><img src="assets/showcase/shard-storm.jpg" alt="Shard storm vision dancer showcase film" width="100%"></a>+ <br><a href="https://youtu.be/xSowU7X48J8"><b>Shard storm</b></a>+ <br><sub><a href="examples/31_shard_storm"><code>31_shard_storm</code></a></sub></td></tr></table>diff --git a/assets/showcase/shard-storm.jpg b/assets/showcase/shard-storm.jpgnew file mode 100644index 00000000..bf147df2Binary files /dev/null and b/assets/showcase/shard-storm.jpg differdiff --git a/examples/31_shard_storm/README.md b/examples/31_shard_storm/README.mdnew file mode 100644index 00000000..7917e44e--- /dev/null+++ b/examples/31_shard_storm/README.md@@ -0,0 +1,23 @@+# Example 31: Shard Storm++Kinetic 3D simulation of a polyhedral shard vortex colliding with a glossy reflective floor plane, exhibiting dynamic Coulomb sliding friction, kinetic heat buildup, secondary spark emission, HDR bloom, and planar reflections.++Demonstrates:+- `Layer3D.shard`: procedural flat-faceted polyhedral rock/crystal geometry generated via Sutherland-Hodgman Fibonacci lattice clipping.+- `Layer3D.swarm`: GPU compute 3D particle simulation with 3D curl noise, 3D vortex fields (`swirl`, `pull`, `axial`), Coulomb ground sliding friction, and kinetic heat accumulation/cooling.+- `Layer.environment(..., { floor })`: planar glossy floor reflection pass with anisotropic roughness blur, Schlick Fresnel grazing angle boost, and distance fade.+- 3D camera trajectory orbiting the vortex and skimming across the reflective floor.++## Run++```bash+# Render video to output/shard-storm.mp4+pnpm render++# Render contact sheet grid+pnpm render grid++# Render specific frames+pnpm render frames 30 90 150+```+diff --git a/examples/31_shard_storm/package.json b/examples/31_shard_storm/package.jsonnew file mode 100644index 00000000..59b31466--- /dev/null+++ b/examples/31_shard_storm/package.json@@ -0,0 +1,22 @@+{+ "name": "@framefields/example-31-shard-storm",+ "version": "2.7.0",+ "private": true,+ "type": "module",+ "scripts": {+ "render": "tsx src/render.ts",+ "render:src": "tsx --tsconfig tsconfig.dev.json --conditions=development src/render.ts",+ "test": "vitest run",+ "typecheck": "tsc --noEmit -p ."+ },+ "dependencies": {+ "framefields": "workspace:*"+ },+ "devDependencies": {+ "@framefields/tsconfig": "workspace:*",+ "@types/node": "^24.1.0",+ "tsx": "^4.20.3",+ "typescript": "^5.8.3",+ "vitest": "^4.1.11"+ }+}diff --git a/examples/31_shard_storm/src/film.test.ts b/examples/31_shard_storm/src/film.test.tsnew file mode 100644index 00000000..3a999dd2--- /dev/null+++ b/examples/31_shard_storm/src/film.test.ts@@ -0,0 +1,21 @@+import { CompositorProgramSchema } from "framefields";+import { describe, expect, it } from "vitest";+import { buildFilm, DURATION } from "./film.js";++describe("shard storm example film", () => {+ it("builds a valid, lint-clean program matching schema", async () => {+ const film = await buildFilm();+ const spec = film.toSpec();+ const result = CompositorProgramSchema.safeParse(spec);+ expect(+ result.success,+ JSON.stringify(result.error?.issues.slice(0, 3)),+ ).toBe(true);++ const lintErrors = film.lint().filter((d) => d.severity === "error");+ expect(lintErrors).toEqual([]);+ expect(Math.round(((film.durationMs ?? 0) / 1000) * film.fps)).toBe(+ DURATION,+ );+ }, 60_000);+});diff --git a/examples/31_shard_storm/src/film.ts b/examples/31_shard_storm/src/film.tsnew file mode 100644index 00000000..077af842--- /dev/null+++ b/examples/31_shard_storm/src/film.ts@@ -0,0 +1,812 @@+import fs from "node:fs";+import {+ CameraAnimation,+ Composition,+ FilmGrain,+ type InstanceTransform3D,+ Layer,+ Layer3D,+ LayerAnimation,+ type PersonTrack,+ type PoseKeypointName,+ Vignette,+} from "framefields";+import {+ BG,+ BLUE,+ BLUE_CORE,+ BLUE_DARK,+ BLUE_DEEP,+ BLUE_GLOW,+ BLUE_ICE,+ BLUE_ROYAL,+ BLUE_SKY,+ DANCER,+ DURATION,+ FLOOR_COLOR,+ FLOOR_Y,+ FPS,+ H,+ W,+} from "./theme.js";++export { DURATION };++interface SimShard {+ x: number;+ y: number;+ z: number;+ vx: number;+ vy: number;+ vz: number;+ rx: number;+ ry: number;+ rz: number;+ wx: number;+ wy: number;+ wz: number;+ baseScale: number;+ colorSeed: number;+ age: number;+ maxAge: number;+}++interface SpawnSite {+ x: number;+ y: number;+ alpha: number;+}++interface KeypointMotion {+ x: number;+ y: number;+ vx: number;+ vy: number;+}++interface FrameKinematics {+ joints: KeypointMotion[];+ axisX: number;+ hipY: number;+ spawns: SpawnSite[];+}++const TRACKED_JOINTS: readonly PoseKeypointName[] = [+ "nose",+ "leftShoulder",+ "rightShoulder",+ "leftElbow",+ "rightElbow",+ "leftWrist",+ "rightWrist",+ "leftHip",+ "rightHip",+ "leftKnee",+ "rightKnee",+ "leftAnkle",+ "rightAnkle",+];++const BODY_PALETTE = [+ BLUE_DARK,+ BLUE_ROYAL,+ BLUE_DEEP,+ BLUE_CORE,+ BLUE,+ BLUE_SKY,+ BLUE_ICE,+] as const;++/** Deterministic [0, 1) hash from integer seed. */+function hash01(n: number): number {+ const x = Math.sin(n * 127.1 + 311.7) * 43758.5453123;+ return x - Math.floor(x);+}++/**+ * 3D Camera motion:+ * Sweeping parallax orbit around the 3D shard dancer with a low grazing angle+ * above the glossy reflective floor plane.+ */+function camera() {+ const half = Math.round(DURATION * 0.5);+ const cameraAnim = CameraAnimation.camera()+ .fromTo("orbitAzimuth", -18, 20, {+ from: 0,+ to: DURATION,+ ease: "sine.inOut",+ })+ .fromTo("orbitElevation", 10, 6, {+ from: 0,+ to: half,+ ease: "power2.out",+ })+ .fromTo("orbitElevation", 6, 11, {+ from: half,+ to: DURATION,+ ease: "power2.inOut",+ })+ .fromTo("orbitRadius", 1660, 1550, {+ from: 0,+ to: half,+ ease: "power2.out",+ })+ .fromTo("orbitRadius", 1550, 1630, {+ from: half,+ to: DURATION,+ ease: "power2.in",+ });++ return Layer.camera({+ id: "main-camera",+ mode: "orbit",+ targetX: 0,+ targetY: -155,+ targetZ: 0,+ lens: {+ focalLength: 50,+ sensorWidth: 36,+ near: 1,+ far: 20000,+ zoom: 1,+ fov: 44,+ },+ animation: cameraAnim,+ });+}++/**+ * Procedural shard variations generated with Fibonacci half-space clipping.+ */+function createShardVariants() {+ return [+ Layer3D.shard({+ radius: 14,+ facets: 12,+ irregularity: 0.35,+ seed: 101,+ color: "#ffffff",+ roughness: 0.24,+ metallic: 0.36,+ }),+ Layer3D.shard({+ radius: 18,+ facets: 16,+ irregularity: 0.46,+ seed: 202,+ color: "#ffffff",+ roughness: 0.22,+ metallic: 0.4,+ }),+ Layer3D.shard({+ radius: 12,+ facets: 10,+ irregularity: 0.3,+ seed: 303,+ color: "#ffffff",+ roughness: 0.28,+ metallic: 0.32,+ }),+ Layer3D.shard({+ radius: 21,+ facets: 18,+ irregularity: 0.5,+ seed: 404,+ color: "#ffffff",+ roughness: 0.25,+ metallic: 0.38,+ }),+ Layer3D.shard({+ radius: 16,+ facets: 14,+ irregularity: 0.4,+ seed: 505,+ color: "#ffffff",+ roughness: 0.26,+ metallic: 0.35,+ }),+ Layer3D.shard({+ radius: 13,+ facets: 12,+ irregularity: 0.42,+ seed: 606,+ color: "#ffffff",+ roughness: 0.28,+ metallic: 0.3,+ }),+ ];+}++const BODY_SHARD_COUNT = 1380;++/**+ * Samples interior silhouette points on `frame` for spawning and respawning shards.+ */+function sampleSilhouetteSpawns(+ person: PersonTrack,+ frame: number,+): SpawnSite[] {+ const sites: SpawnSite[] = [];+ const cols = 42;+ const rows = 38;+ const minX = -390;+ const maxX = 450;+ const minY = -650;+ const maxY = FLOOR_Y - 12;+ const stepX = (maxX - minX) / (cols - 1);+ const stepY = (maxY - minY) / (rows - 1);++ for (let r = 0; r < rows; r++) {+ const y = minY + r * stepY + (hash01(frame * 31 + r) - 0.5) * stepY * 0.6;+ for (let c = 0; c < cols; c++) {+ const x =+ minX + c * stepX + (hash01(frame * 17 + c * 7 + r) - 0.5) * stepX * 0.6;+ const s = person.sample(frame, x, y);+ if (s.alpha >= 0.24) {+ sites.push({ x, y, alpha: s.alpha });+ }+ }+ }+ if (sites.length === 0) {+ const hip = person.point("leftHip", frame);+ sites.push({ x: hip.x, y: hip.y, alpha: 1 });+ }+ return sites;+}++/**+ * Computes tracked pose velocities, spine axis, and interior spawn sites for `frame`.+ */+function computeFrameKinematics(+ person: PersonTrack,+ frame: number,+): FrameKinematics {+ const prev = Math.max(0, frame - 1);+ const joints = TRACKED_JOINTS.map((name) => {+ const now = person.point(name, frame);+ const before = person.point(name, prev);+ return {+ x: now.x,+ y: now.y,+ vx: now.x - before.x,+ vy: now.y - before.y,+ };+ });+ const lHip = person.point("leftHip", frame);+ const rHip = person.point("rightHip", frame);+ const lSho = person.point("leftShoulder", frame);+ const rSho = person.point("rightShoulder", frame);+ const axisX = (lHip.x + rHip.x + lSho.x + rSho.x) * 0.25;+ const hipY = (lHip.y + rHip.y) * 0.5;+ const spawns = sampleSilhouetteSpawns(person, frame);+ return { joints, axisX, hipY, spawns };+}++/**+ * Finds local limb velocity near `(x, y)` weighted by inverse distance to tracked joints.+ */+function sampleLocalVelocity(+ joints: readonly KeypointMotion[],+ x: number,+ y: number,+): { vx: number; vy: number; speed: number } {+ let wx = 0;+ let wy = 0;+ let wSum = 1e-5;+ for (const j of joints) {+ const dx = x - j.x;+ const dy = y - j.y;+ const d2 = dx * dx + dy * dy + 1100;+ const w = 1 / d2;+ wx += j.vx * w;+ wy += j.vy * w;+ wSum += w;+ }+ const vx = wx / wSum;+ const vy = wy / wSum;+ return { vx, vy, speed: Math.hypot(vx, vy) };+}++/**+ * Selects Framefields blue shade and emissive glow from silhouette depth and local motion.+ */+function shadeDancerShard(+ core: number,+ motion: number,+ colorSeed: number,+): { color: string; emissive: string; emissiveIntensity: number } {+ const rim = Math.max(0, 1 - core * 1.45);+ const energy = Math.min(1, rim * 0.45 + motion * 0.72);+ const palettePos = Math.min(+ BODY_PALETTE.length - 1,+ Math.floor(+ Math.min(0.999, core * 0.34 + energy * 0.52 + colorSeed * 0.24) *+ BODY_PALETTE.length,+ ),+ );+ const color = energy > 0.84 ? BLUE_GLOW : (BODY_PALETTE[palettePos] ?? BLUE);+ const emissive = energy > 0.72 ? BLUE_SKY : energy > 0.36 ? BLUE : BLUE_DEEP;+ const emissiveIntensity = 0.07 + energy ** 1.85 * 0.46;+ return { color, emissive, emissiveIntensity };+}++/**+ * Spawns or respawns shard `i` inside the segmented dancer silhouette at `frame`.+ */+function respawnShard(+ i: number,+ frame: number,+ kin: FrameKinematics,+ staggerAge: boolean,+): SimShard {+ const spawns = kin.spawns;+ const pickIdx =+ Math.floor(hash01(i * 73 + frame * 131 + 19) * spawns.length) %+ spawns.length;+ const site = spawns[pickIdx] ?? { x: kin.axisX, y: kin.hipY, alpha: 1 };+ const jitterX = (hash01(i * 19 + frame * 41 + 3) - 0.5) * 14;+ const jitterY = (hash01(i * 23 + frame * 43 + 5) - 0.5) * 14;+ const x = site.x + jitterX;+ const y = Math.min(FLOOR_Y - 10, site.y + jitterY);++ const dome = Math.sqrt(Math.max(0.05, (site.alpha - 0.14) / 0.86));+ const uZ = hash01(i * 29 + frame * 53 + 7) * 2 - 1;+ const z = (uZ >= 0 ? 1 : -1) * Math.abs(uZ) ** 0.65 * dome * 78;++ const vel = sampleLocalVelocity(kin.joints, x, y);+ const maxAge = 34 + Math.floor(hash01(i * 37 + 11) * 44);+ const age = staggerAge ? Math.floor(hash01(i * 41 + 13) * (maxAge - 4)) : 0;++ return {+ x,+ y,+ z,+ vx: vel.vx,+ vy: vel.vy,+ vz: (x - kin.axisX) * 0.08,+ rx: hash01(i * 7 + 11) * 360,+ ry: hash01(i * 7 + 13) * 360,+ rz: hash01(i * 7 + 17) * 360,+ wx: (hash01(i * 11 + 19) - 0.5) * 15,+ wy: 5.5 + hash01(i * 13 + 23) * 9.5,+ wz: (hash01(i * 17 + 29) - 0.5) * 13,+ baseScale: 0.52 + hash01(i * 5 + 31) * 0.48,+ colorSeed: hash01(i * 11 + 37),+ age,+ maxAge,+ };+}++/**+ * Advances a single 3D shard by one frame inside the segmented dancer volume,+ * combining skeletal limb advection, 3D dress vortex rotation, curl turbulence,+ * and silhouette-gradient boundary sliding.+ */+function stepShard(+ shard: SimShard,+ i: number,+ frame: number,+ kin: FrameKinematics,+ person: PersonTrack,+): SimShard {+ shard.age += 1;+ if (shard.age >= shard.maxAge) {+ return respawnShard(i, frame, kin, false);+ }++ const vel = sampleLocalVelocity(kin.joints, shard.x, shard.y);++ // 3D cylindrical vortex around the dancer's spine axis (stronger in spinning skirt)+ const skirtWeight = Math.min(+ 1,+ Math.max(0.35, (shard.y - (kin.hipY - 90)) / 240),+ );+ const omega = 0.075 + skirtWeight * 0.065;+ const dxAxis = shard.x - kin.axisX;+ const orbVx = -shard.z * omega * 1.45;+ const orbVz = dxAxis * omega * 0.72;++ // Helical curl wave so shards weave organically along arms and dress folds+ const phase = shard.colorSeed * Math.PI * 2 + i * 0.13;+ const curlVx = Math.sin(shard.y * 0.028 + frame * 0.22 + phase) * 3.4;+ const curlVy =+ Math.cos(shard.x * 0.028 - frame * 0.19 + phase) * 2.8 -+ (1 - skirtWeight) * 1.6;++ const targetVx = vel.vx * 1.08 + orbVx + curlVx;+ const targetVy = vel.vy * 1.08 + curlVy;+ const targetVz = orbVz + Math.sin(frame * 0.18 + phase) * 2.4;++ shard.vx = shard.vx * 0.42 + targetVx * 0.58;+ shard.vy = shard.vy * 0.42 + targetVy * 0.58;+ shard.vz = shard.vz * 0.45 + targetVz * 0.55;++ shard.x += shard.vx;+ shard.y = Math.min(FLOOR_Y - 8, shard.y + shard.vy);+ shard.z += shard.vz;++ const s = person.sample(frame, shard.x, shard.y);+ if (s.alpha < 0.12) {+ return respawnShard(i, frame, kin, false);+ }++ // Confine and slide shards along the moving silhouette contour+ if (s.alpha < 0.58) {+ const gMag = Math.hypot(s.gx, s.gy);+ if (gMag > 1e-5) {+ const nx = s.gx / gMag;+ const ny = s.gy / gMag;+ const pull = ((0.58 - s.alpha) / 0.58) * 10.5;+ shard.x += nx * pull;+ shard.y = Math.min(FLOOR_Y - 8, shard.y + ny * pull);+ const outDot = shard.vx * nx + shard.vy * ny;+ if (outDot < 0) {+ shard.vx -= outDot * nx * 1.25;+ shard.vy -= outDot * ny * 1.25;+ }+ }+ }++ // Wrap Z smoothly inside the 3D volume shell+ const dome = Math.sqrt(Math.max(0.06, (s.alpha - 0.12) / 0.88));+ const maxZ = dome * 82;+ if (Math.abs(shard.z) > maxZ) {+ shard.z *= 0.82;+ shard.vz = -shard.vz * 0.5;+ }++ // Vigorous 3D tumbling amplified by local shard speed+ const speed = Math.hypot(shard.vx, shard.vy, shard.vz * 0.6);+ const spinBoost = 1 + Math.min(2.2, speed * 0.14);+ shard.rx += shard.wx * spinBoost + shard.vy * 0.65;+ shard.ry += shard.wy * spinBoost + shard.vx * 0.85;+ shard.rz += shard.wz * spinBoost + (shard.vx - shard.vy) * 0.45;++ return shard;+}++/**+ * Converts a simulated shard state at `frame` into a rendered `InstanceTransform3D`.+ */+function shardToInstance(+ shard: SimShard,+ person: PersonTrack,+ frame: number,+): InstanceTransform3D {+ const s = person.sample(frame, shard.x, shard.y);+ const core = Math.min(1, Math.max(0, (s.alpha - 0.12) / 0.84));+ const speed = Math.hypot(shard.vx, shard.vy, shard.vz * 0.5);+ const motion = Math.min(1, speed * 0.085);++ const fadeIn = Math.min(1, (shard.age + 1) / 5);+ const fadeOut = Math.min(1, (shard.maxAge - shard.age) / 6);+ const lifeEnv = fadeIn * fadeOut;+ const edgeScale = 0.6 + 0.46 * core ** 0.35;+ const scale = shard.baseScale * edgeScale * lifeEnv * (1 + motion * 0.24);++ const shaded = shadeDancerShard(core, motion, shard.colorSeed);+ return {+ x: shard.x,+ y: shard.y,+ z: shard.z,+ scale,+ rotation: [shard.rx, shard.ry, shard.rz],+ color: shaded.color,+ emissive: shaded.emissive,+ emissiveIntensity: shaded.emissiveIntensity,+ };+}++/**+ * Pre-simulates the dynamic 3D shard trajectories across all frames of the clip.+ */+function simulateDancerShardTimeline(+ person: PersonTrack,+): InstanceTransform3D[][] {+ const timeline: InstanceTransform3D[][] = [];+ const kin0 = computeFrameKinematics(person, 0);+ const shards: SimShard[] = Array.from({ length: BODY_SHARD_COUNT }, (_, i) =>+ respawnShard(i, 0, kin0, true),+ );++ timeline.push(shards.map((sh) => shardToInstance(sh, person, 0)));++ for (let f = 1; f < DURATION; f++) {+ const kin = computeFrameKinematics(person, f);+ const frameInstances: InstanceTransform3D[] = new Array(BODY_SHARD_COUNT);+ for (let i = 0; i < BODY_SHARD_COUNT; i++) {+ const current = shards[i];+ if (!current) continue;+ const updated = stepShard(current, i, f, kin, person);+ shards[i] = updated;+ frameInstances[i] = shardToInstance(updated, person, f);+ }+ timeline.push(frameInstances);+ }+ return timeline;+}++/**+ * Reconstructs the segmented dancer silhouette as a flowing, swirling 3D volume of+ * faceted Framefields-blue shards (`Layer3D.instances`).+ */+function dancerShardBody(+ person: PersonTrack,+ variants: ReturnType<typeof createShardVariants>,+) {+ const timeline = simulateDancerShardTimeline(person);++ return Layer3D.instances({+ id: "dancer-shard-body",+ mesh: variants,+ count: BODY_SHARD_COUNT,+ material: "lit",+ roughness: 0.28,+ metallic: 0.32,+ specularIntensity: 0.92,+ ambientIntensity: 0.9,+ instanceAt: (i, frame) => {+ const f = Math.max(0, Math.min(DURATION - 1, Math.round(frame)));+ return timeline[f]?.[i];+ },+ });+}++/**+ * GPU-simulated 3D shard swarm shed from the dancer's spinning dress onto the+ * glossy studio floor, kicked and swirled by her tracked limbs.+ */+function sheddingShardSwarm(+ person: PersonTrack,+ variants: ReturnType<typeof createShardVariants>,+) {+ const hipX = (f: number) =>+ (person.point("leftHip", f).x + person.point("rightHip", f).x) * 0.5;++ return Layer3D.swarm({+ id: "dancer-shed-shards",+ max: 560,+ seed: 42,+ prewarm: 2.0,+ substeps: 4,+ mesh: variants,+ emitter: {+ shape: "sphere",+ x: hipX,+ y: FLOOR_Y - 58,+ z: 0,+ radius: 105,+ rate: 240,+ bursts: [+ { frame: 0, count: 140 },+ { frame: 48, count: 90 },+ { frame: 96, count: 90 },+ ],+ },+ lifetime: [1.6, 3.1],+ speed: [60, 190],+ size: [8, 17],+ sizeJitter: 0.42,+ fade: [0.1, 0.3],+ gravity: [0, 820, 0],+ drag: 1.15,+ vortex: {+ axis: [0, 1, 0],+ swirl: 380,+ radius: 220,+ pull: 95,+ },+ attractors: [+ {+ x: (f) => person.point("leftAnkle", f).x,+ y: FLOOR_Y - 14,+ z: 0,+ strength: -480,+ radius: 165,+ },+ {+ x: (f) => person.point("rightAnkle", f).x,+ y: FLOOR_Y - 14,+ z: 0,+ strength: -480,+ radius: 165,+ },+ {+ x: (f) => person.point("leftWrist", f).x,+ y: (f) => person.point("leftWrist", f).y,+ z: 20,+ strength: -380,+ radius: 150,+ },+ {+ x: (f) => person.point("rightWrist", f).x,+ y: (f) => person.point("rightWrist", f).y,+ z: -20,+ strength: -380,+ radius: 150,+ },+ ],+ noise: {+ strength: 140,+ scale: 220,+ speed: 0.6,+ },+ floor: {+ y: FLOOR_Y,+ bounce: 0.2,+ friction: 0.98,+ heatGain: 1.1,+ heatDecay: 0.75,+ },+ angularSpeed: [90, 320],+ color: [BLUE_ROYAL, BLUE_DEEP, BLUE_CORE, BLUE, BLUE_SKY],+ heat: {+ source: "both",+ maxSpeed: 950,+ color: [BLUE_DEEP, BLUE, BLUE_SKY, BLUE_ICE],+ intensity: 0.85,+ curve: 1.85,+ },+ sparks: {+ max: 800,+ rate: 280,+ threshold: 0.48,+ speed: [130, 360],+ lifetime: [0.2, 0.5],+ size: [1.3, 2.5],+ stretch: 0.05,+ color: BLUE_SKY,+ intensity: 1.15,+ },+ material: "lit",+ roughness: 0.3,+ metallic: 0.3,+ specularIntensity: 0.9,+ ambientIntensity: 0.85,+ });+}++/**+ * Picture-in-Picture card in the top-right corner displaying the original dancer video.+ */+function originalVideoPip() {+ const pipW = 440;+ const pipH = 248;+ const margin = 44;++ const cardAnim = LayerAnimation.create().fromTo("y", margin - 14, margin, {+ from: 0,+ to: 16,+ ease: "power3.out",+ });++ return Layer.box({+ id: "original-video-pip",+ position: "absolute",+ x: W - pipW - margin,+ y: margin,+ width: pipW,+ height: pipH,+ borderRadius: 16,+ borderWidth: 2,+ borderColor: "rgba(59, 130, 246, 0.72)",+ background: "#050B1A",+ overflow: "hidden",+ animation: cardAnim,+ children: [+ Layer.video(DANCER, {+ id: "original-dancer-video",+ width: pipW,+ height: pipH,+ fit: "cover",+ muted: false,+ durationFrames: DURATION,+ }),+ ],+ });+}++/**+ * Builds the complete Framefields-blue Vision Shard Dancer composition.+ */+export async function buildFilm(): Promise<Composition> {+ if (!fs.existsSync(DANCER)) {+ throw new Error(+ `Missing ${DANCER}. Generate it with \`pnpm assets\` in examples/19_framefields_film.`,+ );+ }++ const comp = new Composition({+ width: W,+ height: H,+ fps: FPS,+ durationFrames: DURATION,+ backgroundColor: BG,+ });++ const dancer = comp.vision(DANCER);+ await dancer.ready(0, DURATION - 1);+ const person = dancer.person.place({+ x: -912,+ y: -752,+ width: W,+ height: H,+ fit: "cover",+ });++ // 1. Camera+ comp.add(camera());++ // 2. Physically-based environment with glossy planar floor reflection+ comp.add(+ Layer.environment("night", {+ exposure: 0.48,+ rotation: 25,+ bloom: {+ intensity: 0.14,+ threshold: 2.1,+ radius: 4,+ },+ floor: {+ y: FLOOR_Y,+ color: FLOOR_COLOR,+ reflectivity: 0.92,+ roughness: 0.2,+ fadeDistance: 1350,+ opacity: 1.0,+ },+ fog: {+ color: BG,+ start: 1350,+ end: 3100,+ opacity: 0.6,+ },+ }),+ );++ // 3. 3D Lighting rig sculpted for Framefields blue facets+ comp.add([+ // Cool icy key light from top-left-front to carve polyhedron facets+ Layer.light({+ id: "key-light",+ lightType: "directional",+ color: "#e0f2fe",+ intensity: 1.85,+ direction: [0.48, 0.65, 0.58],+ }),+ // Deep Framefields blue fill light from right+ Layer.light({+ id: "fill-light",+ lightType: "directional",+ color: BLUE,+ intensity: 1.35,+ direction: [-0.72, 0.32, 0.62],+ }),+ // Bright sky-blue rim light from behind to outline the 3D shard silhouette+ Layer.light({+ id: "rim-light",+ lightType: "directional",+ color: BLUE_ICE,+ intensity: 1.45,+ direction: [0.1, 0.35, -0.93],+ }),+ ]);++ // 4. Shared faceted shard geometry variants+ const variants = createShardVariants();++ // 5. Segmented dancer reconstructed as a 3D volume of Framefields-blue shards+ comp.add(dancerShardBody(person, variants));++ // 6. Shedding 3D shards & sparks cascading onto the glossy floor around her feet+ comp.add(sheddingShardSwarm(person, variants));++ // 7. Original dancer video in a top-right Picture-in-Picture card (no text)+ comp.add(originalVideoPip());++ // 8. Subtle cinematic grading+ comp.apply(new Vignette({ strength: 32, softness: 0.45 }));+ comp.apply(new FilmGrain({ strength: 3, size: 1.1 }));++ return comp;+}diff --git a/examples/31_shard_storm/src/render.ts b/examples/31_shard_storm/src/render.tsnew file mode 100644index 00000000..607b165c--- /dev/null+++ b/examples/31_shard_storm/src/render.ts@@ -0,0 +1,65 @@+/**+ * pnpm render → output/shard-storm.mp4+ * pnpm render frames 30 90 → output/frames/f0030.png …+ * pnpm render grid → output/grid.png, contact sheet of the whole film+ * pnpm render preview → live player on localhost; add --open for system browser+ */+import fs from "node:fs/promises";+import path from "node:path";+import { HeadlessMediaRenderer, startPreview } from "framefields";+import { buildFilm, DURATION } from "./film.js";+import { OUTPUT } from "./theme.js";++const [mode = "video", ...args] = process.argv.slice(2);++if (mode === "preview") {+ const session = await startPreview(+ { entry: new URL("./film.ts", import.meta.url), export: "buildFilm" },+ { title: "Shard storm", open: args.includes("--open") },+ );+ console.log(`Preview at ${session.url}`);+ await session.closed;+ process.exit(0);+}++const film = await buildFilm();+await fs.mkdir(path.join(OUTPUT, "frames"), { recursive: true });++if (mode === "frames") {+ const renderer = new HeadlessMediaRenderer();+ for (const frame of args.map(Number)) {+ const file = path.join(+ OUTPUT,+ "frames",+ `f${String(frame).padStart(4, "0")}.png`,+ );+ await fs.writeFile(file, await film.renderFrame({ frame, renderer }));+ console.log(file);+ }+} else if (mode === "grid") {+ const frames = Array.from({ length: 16 }, (_, i) =>+ Math.round((i * (DURATION - 1)) / 15),+ );+ const file = path.join(OUTPUT, "grid.png");+ await fs.writeFile(+ file,+ await film.renderFrameGrid({+ frames,+ columns: 4,+ cellWidth: 480,+ showLabels: false,+ }),+ );+ console.log(file);+} else {+ const started = Date.now();+ const result = await film.renderVideo({+ outputPath: path.join(OUTPUT, "shard-storm.mp4"),+ quality: "high",+ });+ await result.cleanup?.().catch(() => {});+ console.log(+ `${result.filePath} (${((Date.now() - started) / 1000).toFixed(1)} s)`,+ );+}+process.exit(0);diff --git a/examples/31_shard_storm/src/theme.ts b/examples/31_shard_storm/src/theme.tsnew file mode 100644index 00000000..9c43e666--- /dev/null+++ b/examples/31_shard_storm/src/theme.ts@@ -0,0 +1,37 @@+import path from "node:path";+import { fileURLToPath } from "node:url";++const HERE = path.dirname(fileURLToPath(import.meta.url));+export const OUTPUT = path.resolve(HERE, "../output");++/** Source dancer clip from example 19. */+export const DANCER = path.resolve(+ HERE,+ "../../19_framefields_film/assets/dancer.mp4",+);++export const W = 1920;+export const H = 1080;+export const FPS = 24;+export const DURATION = 158;++/** 3D scene origin and glossy floor plane (y = 240 aligns with the placed dancer's feet). */+export const CX = W / 2;+export const CY = H / 2;+export const FLOOR_Y = 240;++/** Deep midnight Framefields blue stage & obsidian floor. */+export const BG = "#030712";+export const FLOOR_COLOR = "#040A1A";++/** Framefields blue shard palette (deep navy -> royal -> signature blue -> ice white). */+export const NAVY = "#0B1E4D";+export const BLUE_DARK = "#172554";+export const BLUE_ROYAL = "#1E3A8A";+export const BLUE_DEEP = "#1D4ED8";+export const BLUE_CORE = "#2563EB";+export const BLUE = "#3B82F6";+export const BLUE_SKY = "#60A5FA";+export const BLUE_ICE = "#93C5FD";+export const BLUE_GLOW = "#DBEAFE";+export const WHITE_HOT = "#FFFFFF";diff --git a/examples/31_shard_storm/tsconfig.dev.json b/examples/31_shard_storm/tsconfig.dev.jsonnew file mode 100644index 00000000..c5e4355b--- /dev/null+++ b/examples/31_shard_storm/tsconfig.dev.json@@ -0,0 +1,9 @@+{+ "extends": "./tsconfig.json",+ "include": [+ "src/**/*",+ "../../nodes/**/*",+ "../../packages/**/*",+ "../../node_modules/@framefields/**/*"+ ]+}diff --git a/examples/31_shard_storm/tsconfig.json b/examples/31_shard_storm/tsconfig.jsonnew file mode 100644index 00000000..999801f9--- /dev/null+++ b/examples/31_shard_storm/tsconfig.json@@ -0,0 +1,10 @@+{+ "extends": "@framefields/tsconfig/base.json",+ "compilerOptions": {+ "module": "NodeNext",+ "moduleResolution": "NodeNext",+ "target": "ES2022",+ "noEmit": true+ },+ "include": ["src/**/*"]+}diff --git a/nodes/node-compositor/SKILL.md b/nodes/node-compositor/SKILL.mdindex 62fa7fba..e36910ce 100644--- a/nodes/node-compositor/SKILL.md+++ b/nodes/node-compositor/SKILL.md@@ -60,14 +60,14 @@ This node uses **Variable Inputs**. You can add dynamically named input handles> **`type` vs `kind`:** `type` is an INPUT DataType (`Text`, `Image`, `Video`, `Audio`,> `Caption`, `SVG`, `GIF`, `Lottie` …) and never appears on layout nodes. The layout type of-> a node is its **`kind`**: `flex` | `block` | `box` | `text` | `media` | `shape` | `chart`.+> a node is its **`kind`**: `flex` | `block` | `box` | `text` | `media` | `shape` | `chart` | `model3d` | `camera` | `light`.---### Layout Node SchemaCommon fields (every node):- **`id`** (string, required): Unique node id — also keys the timeline.-- **`kind`** (string, required): `"flex"` | `"block"` | `"box"` | `"text"` | `"media"` | `"shape"`.+- **`kind`** (string, required): `"flex"` | `"block"` | `"box"` | `"text"` | `"media"` | `"shape"` | `"model3d"` | `"camera"` | `"light"`.- **`inputHandleId`** (string, optional): Graph binding — which connected input this node renders (for text/media nodes).> [!WARNING]> Do not place a handle label in `inputHandleId` when updating an existing live Compositor. The renderer may treat the media as unbound and produce a blank layer. Use the actual dynamic input handle ID returned from the live Compositor node.@@ -211,6 +211,10 @@ Each track represents animatable property modifications:- **Transparent meshes:** glTF `BLEND` materials and meshes with reduced layer, material, tint, or vertex alpha draw after opaque items, back to front by the camera-space center of each mesh’s transformed bounds, without writing depth. This is object-level sorting: intersecting meshes, self-overlap, skinned/deformed bounds, translucent flat layers, glass, and transparent shadows have separate limitations.- **Mesh wireframe:** `wireframe: true` on a `model3d` draws triangle edges as one-pixel lines, including triangulation and back edges; it also applies to skinned and audio-deformed meshes and their shadows.- **glTF scenes:** a glTF/GLB `model3d` keeps its node hierarchy, every skin and its animation clips (translation, rotation, scale; linear, step and cubic-spline). Skinned meshes are posed per frame from the clip (`animationName`, `animationTime`/`animationProgress`, `loop`); base-colour textures (with mipmaps), alpha `MASK`/`BLEND` and VRM MToon materials (`material: "toon"`, picked automatically when `material` is unset) render as authored. `center`/`normalizeSize` apply above the scene graph, so skinning stays intact.+- **Procedural Shards (`Layer3D.shard`):** Procedural polyhedron primitive generated by Sutherland-Hodgman convex half-space clipping against Fibonacci lattice normals with PCG jitter. Faceted flat normals, automatic planar UVs, Rapier 3D convex hull collision.+- **Instanced 3D Meshes (`instances3d`):** `kind: "model3d"` with `instances3d` renders hundreds or thousands of mesh instances in 1 GPU draw call (`drawIndexed(indexCount, instanceCount)`). Supports single or multi-mesh variants with round-robin or variant indexing, dynamic per-instance transforms, and per-instance emissive / color modulation. In `framefields`, created with `Layer3D.instances({ count, mesh, instanceAt, bodies, emissiveBySpeed })`.+- **GPU 3D Swarms (`swarm3d`):** `kind: "model3d"` with `swarm3d` runs continuous 3D particle simulation in a WebGPU compute shader with 3D curl noise, 3D vortex fields (`swirl`, `pull`, `axial`), ground plane collisions with Coulomb sliding friction and rotational roll torque, and kinetic heat accumulation/cooling, packing directly into GPU instance buffers.+- **Planar Reflective Floor (`floor` in `environment`):** `kind: "light"` with `lightType: "environment"` and `floor: { y, color, reflectivity, roughness, fadeDistance, opacity }` renders a mirrored-camera reflection pass, subterranean fragment clipping, 2-pass anisotropic roughness blur ($\sigma_y \approx 3.5 \sigma_x$), Schlick Fresnel grazing reflections, and analytical depth unprojection.## Don't Forget- If text rendering required, you must include a font in spec (CLI TOOL only). No emoji font ships with framefields: to draw emoji, provide a color emoji font yourself with `FontManager.registerEmojiFont(path)` (a CBDT/CBLC bitmap font such as Noto Color Emoji).diff --git a/nodes/node-compositor/src/renderers/webgpu-renderer.ts b/nodes/node-compositor/src/renderers/webgpu-renderer.tsindex 0a7f92bf..a5deac3d 100644--- a/nodes/node-compositor/src/renderers/webgpu-renderer.ts+++ b/nodes/node-compositor/src/renderers/webgpu-renderer.ts@@ -67,6 +67,9 @@ import {type ShapeGeometryConfig,SlugFontCache,type SlugGlyphBatch,+ type Swarm3DFrameInput,+ type Swarm3DState,+ type Swarm3DStaticConfig,spansText,srtLoader,Vector3Math,@@ -212,6 +215,7 @@ function getHomographyResources(}const audioTrackLatentCache = new Map<string, AudioLatentTrackCache>();+const swarmStateMap = new WeakMap<object, Swarm3DState>();const deviceRenderer3DCache = new WeakMap<GPUDevice, Map<string, Renderer3D>>();/** One Renderer3D per device, target format and MSAA sample count. */@@ -589,6 +593,53 @@ function effectsReach(effects: unknown[]): number | null {return reach;}+function quatFromEulerAngles(+ rx: number,+ ry: number,+ rz: number,+): [number, number, number, number] {+ const DEG = Math.PI / 180;+ const halfX = (rx * DEG) / 2;+ const halfY = (ry * DEG) / 2;+ const halfZ = (rz * DEG) / 2;+ const cx = Math.cos(halfX);+ const sx = Math.sin(halfX);+ const cy = Math.cos(halfY);+ const sy = Math.sin(halfY);+ const cz = Math.cos(halfZ);+ const sz = Math.sin(halfZ);+ return [+ cz * cy * sx - sz * sy * cx,+ cz * sy * cx + sz * cy * sx,+ sz * cy * cx - cz * sy * sx,+ cz * cy * cx + sz * sy * sx,+ ];+}++function sampleColorRamp(+ ramp: string | string[],+ factor: number,+): [number, number, number] {+ if (!Array.isArray(ramp) || ramp.length === 0) {+ const p = parseColor((ramp as string) || "#ffffff") ?? { r: 1, g: 1, b: 1 };+ return [p.r, p.g, p.b];+ }+ if (ramp.length === 1) {+ const p = parseColor(ramp[0]) ?? { r: 1, g: 1, b: 1 };+ return [p.r, p.g, p.b];+ }+ const t = Math.max(0, Math.min(1, factor)) * (ramp.length - 1);+ const idx = Math.min(Math.floor(t), ramp.length - 2);+ const frac = t - idx;+ const c0 = parseColor(ramp[idx]) ?? { r: 1, g: 1, b: 1 };+ const c1 = parseColor(ramp[idx + 1]) ?? { r: 1, g: 1, b: 1 };+ return [+ c0.r + (c1.r - c0.r) * frac,+ c0.g + (c1.g - c0.g) * frac,+ c0.b + (c1.b - c0.b) * frac,+ ];+}+function expandRect(r: Rect, by: number): Rect {return {x: r.x - by,@@ -1238,6 +1289,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {exposure: target?.exposure ?? lop.exposure,toneMapping: lop.toneMapping,fog: lop.fog,+ floor: lop.floor,...(intensity !== undefined && { intensity }),};sceneBloom =@@ -1401,25 +1453,6 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {}}- const {- pass: pass3d,- cameraBindGroup,- cameraBuffer,- lightsBindGroup,- } = r3d.beginPass(- encoder,- scene3dView,- nativeWidth,- nativeHeight,- camera,- "clear",- { r: 0, g: 0, b: 0, a: 0 },- linearDepthView,- sceneLights,- { environment: sceneEnvironment, shadow },- Boolean(sceneBloom),- );-// Opaque objects establish depth first. Sort blended meshes across the// whole batch by camera-space depth, then draw glass as before.const isGlass = (item: Pending3DItem) =>@@ -1453,6 +1486,108 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {...transparent.map(({ item }) => item),...glass,];++ // Planar floor reflection pass (if environment.floor is active)+ const floorSpec = sceneEnvironment?.floor;+ let blurredReflectionTex: GPUTexture | null = null;+ if (+ floorSpec &&+ typeof floorSpec.y === "number" &&+ camera.eye[1] < floorSpec.y+ ) {+ const reflectedCamera: Camera3DPose = {+ ...camera,+ eye: [camera.eye[0], 2 * floorSpec.y - camera.eye[1], camera.eye[2]],+ target: [+ camera.target[0],+ 2 * floorSpec.y - camera.target[1],+ camera.target[2],+ ],+ up: [camera.up[0], camera.up[1], camera.up[2]],+ };+ const {+ pass: reflPass,+ cameraBindGroup: reflCamBind,+ lightsBindGroup: reflLightsBind,+ reflectionTexture: reflTex,+ } = r3d.beginReflectionPass(+ encoder,+ nativeWidth,+ nativeHeight,+ reflectedCamera,+ sceneLights,+ { environment: sceneEnvironment, shadow: null },+ );+ for (const item of ordered) {+ if (item.kind === "quad") {+ r3d.drawTextureQuad(+ reflPass,+ reflCamBind,+ reflLightsBind,+ item.texture,+ item.opts,+ false,+ );+ } else if (item.kind === "slug") {+ r3d.drawSlugText(+ reflPass,+ reflCamBind,+ reflLightsBind,+ item.batches,+ item.opts,+ item.stackBase,+ false,+ );+ } else if (item.kind === "mesh") {+ r3d.drawMesh3D(+ reflPass,+ reflCamBind,+ reflLightsBind,+ item.meshBuffers ?? item.mesh,+ item.texture,+ item.opts,+ false,+ );+ }+ }+ reflPass.end();+ blurredReflectionTex = r3d.blurReflection(+ encoder,+ reflTex,+ floorSpec.roughness ?? 0.35,+ );+ }++ const {+ pass: pass3d,+ cameraBindGroup,+ cameraBuffer,+ lightsBindGroup,+ } = r3d.beginPass(+ encoder,+ scene3dView,+ nativeWidth,+ nativeHeight,+ camera,+ "clear",+ { r: 0, g: 0, b: 0, a: 0 },+ linearDepthView,+ sceneLights,+ { environment: sceneEnvironment, shadow },+ Boolean(sceneBloom),+ );++ if (floorSpec && blurredReflectionTex) {+ r3d.drawFloor(+ pass3d,+ cameraBindGroup,+ lightsBindGroup,+ blurredReflectionTex,+ floorSpec,+ dofEnabled,+ Boolean(sceneBloom),+ );+ }for (const item of ordered) {if (item.kind === "quad") {r3d.drawTextureQuad(@@ -2012,6 +2147,813 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {const modelOpacity =(target?.opacity ?? lop.opacity ?? 1) * accumulatedOpacity;+ if (lop.instances3d) {+ const instOpt = lop.instances3d as Record<string, any>;+ const rawMeshes = Array.isArray(instOpt.mesh)+ ? instOpt.mesh+ : instOpt.mesh+ ? [instOpt.mesh]+ : lop.modelData+ ? [lop.modelData]+ : lop.primitive3d+ ? [+ getPrimitiveGeometry(+ lop.primitive3d as PrimitiveGeometryOptions,+ ),+ ]+ : [];++ const variants: Model3DData[] = [];+ for (const m of rawMeshes) {+ let vModel: Model3DData | undefined;+ if (typeof m === "object" && m !== null) {+ if ("meshes" in m && Array.isArray((m as any).meshes)) {+ vModel = m as Model3DData;+ } else if (m.modelData && "meshes" in m.modelData) {+ vModel = m.modelData as Model3DData;+ } else if (m.primitive3d) {+ vModel = getPrimitiveGeometry(+ m.primitive3d as PrimitiveGeometryOptions,+ );+ } else if (m.src) {+ try {+ vModel = r3d.loadModel(m.src, m.modelFormat ?? "auto", {+ center: m.center,+ normalizeSize: m.normalizeSize,+ });+ } catch {}+ }+ }+ if (vModel && vModel.meshes && vModel.meshes.length > 0) {+ variants.push(vModel);+ }+ }+ if (variants.length === 0 && model) {+ variants.push(model);+ }+ if (variants.length > 0) {+ const count =+ instOpt.bodies &&+ Array.isArray(instOpt.bodies) &&+ instOpt.bodies.length > 0+ ? instOpt.bodies.length+ : (instOpt.count ??+ (Array.isArray(instOpt.transforms)+ ? instOpt.transforms.length+ : 0));++ if (count > 0) {+ const numVariants = variants.length;+ const bucketCounts = new Uint32Array(numVariants);+ for (let i = 0; i < count; i++) {+ bucketCounts[i % numVariants]++;+ }+ const bucketItems: Float32Array[] = [];+ const bucketBounds: Array<{+ min: [number, number, number];+ max: [number, number, number];+ }> = [];+ for (let k = 0; k < numVariants; k++) {+ bucketItems.push(new Float32Array(bucketCounts[k] * 16));+ bucketBounds.push({+ min: [Infinity, Infinity, Infinity],+ max: [-Infinity, -Infinity, -Infinity],+ });+ }+ const bucketCursors = new Uint32Array(numVariants);++ const frameCtx = {+ frame: shiftedFrame ?? 0,+ fps: fps || 30,+ time: (shiftedFrame ?? 0) / (fps || 30),+ duration: 0,+ durationMs: 0,+ progress: 0,+ deltaTime: 1 / (fps || 30),+ };++ for (let i = 0; i < count; i++) {+ const k = i % numVariants;+ const cursor = bucketCursors[k];+ const bData = bucketItems[k];+ const bBox = bucketBounds[k];+ const off = cursor * 16;++ let ix = 0;+ let iy = 0;+ let iz = 0;+ let iscale = 1.0;+ let iqx = 0;+ let iqy = 0;+ let iqz = 0;+ let iqw = 1.0;+ let icr = 1.0;+ let icg = 1.0;+ let icb = 1.0;+ let ica = 1.0;+ let ier = 0.0;+ let ieg = 0.0;+ let ieb = 0.0;+ let iew = 0.0;++ if (instOpt.bodies && instOpt.bodies[i]) {+ const b = instOpt.bodies[i];+ ix =+ typeof b.x?.get === "function"+ ? Number(b.x.get(frameCtx))+ : Number(b.x ?? 0);+ iy =+ typeof b.y?.get === "function"+ ? Number(b.y.get(frameCtx))+ : Number(b.y ?? 0);+ iz =+ typeof b.z?.get === "function"+ ? Number(b.z.get(frameCtx))+ : Number(b.z ?? 0);+ const rx =+ typeof b.rotateX?.get === "function"+ ? Number(b.rotateX.get(frameCtx))+ : Number(b.rotateX ?? 0);+ const ry =+ typeof b.rotateY?.get === "function"+ ? Number(b.rotateY.get(frameCtx))+ : Number(b.rotateY ?? 0);+ const rz =+ typeof b.rotateZ?.get === "function"+ ? Number(b.rotateZ.get(frameCtx))+ : Number(b.rotateZ ?? 0);+ const q = quatFromEulerAngles(rx, ry, rz);+ iqx = q[0];+ iqy = q[1];+ iqz = q[2];+ iqw = q[3];++ if (instOpt.emissiveBySpeed) {+ const spd =+ typeof b.speed?.get === "function"+ ? Number(b.speed.get(frameCtx))+ : Number(b.speed ?? 0);+ const maxSpd = instOpt.emissiveBySpeed.maxSpeed || 1000;+ const factor = Math.min(1, Math.max(0, spd / maxSpd));+ if (factor > 0.001) {+ const ramp = sampleColorRamp(+ instOpt.emissiveBySpeed.color,+ factor,+ );+ ier = ramp[0];+ ieg = ramp[1];+ ieb = ramp[2];+ iew = factor * (instOpt.emissiveBySpeed.intensity ?? 3.0);+ }+ }+ if (instOpt.emissiveByImpact) {+ const imp =+ typeof b.impact?.get === "function"+ ? Number(b.impact.get(frameCtx))+ : Number(b.impact ?? 0);+ if (imp > 0.01) {+ const impCol = parseColor(+ instOpt.emissiveByImpact.color ?? "#ffffff",+ ) ?? { r: 1, g: 1, b: 1, a: 1 };+ ier = Math.max(ier, impCol.r);+ ieg = Math.max(ieg, impCol.g);+ ieb = Math.max(ieb, impCol.b);+ iew = Math.max(+ iew,+ imp * (instOpt.emissiveByImpact.intensity ?? 4.0),+ );+ }+ }+ } else if (typeof instOpt.instanceAt === "function") {+ const t = instOpt.instanceAt(i, shiftedFrame ?? 0, fps || 30);+ if (!t) continue;+ ix = t.x ?? 0;+ iy = t.y ?? 0;+ iz = t.z ?? 0;+ if (typeof t.scale === "number") iscale = t.scale;+ if (iscale <= 0) continue;+ if (t.rotation) {+ if (t.rotation.length === 4) {+ iqx = t.rotation[0];+ iqy = t.rotation[1];+ iqz = t.rotation[2];+ iqw = t.rotation[3];+ } else {+ const q = quatFromEulerAngles(+ t.rotation[0],+ t.rotation[1],+ t.rotation[2],+ );+ iqx = q[0];+ iqy = q[1];+ iqz = q[2];+ iqw = q[3];+ }+ }+ if (t.color) {+ const p =+ typeof t.color === "string"+ ? parseColor(t.color)+ : {+ r: t.color[0],+ g: t.color[1],+ b: t.color[2],+ a: t.color[3] ?? 1,+ };+ if (p) {+ icr = p.r;+ icg = p.g;+ icb = p.b;+ ica = p.a;+ }+ }+ if (t.emissive) {+ const p =+ typeof t.emissive === "string"+ ? parseColor(t.emissive)+ : {+ r: t.emissive[0],+ g: t.emissive[1],+ b: t.emissive[2],+ };+ if (p) {+ ier = p.r;+ ieg = p.g;+ ieb = p.b;+ }+ iew = t.emissiveIntensity ?? 1.0;+ }+ } else if (+ Array.isArray(instOpt.transforms) &&+ instOpt.transforms[i]+ ) {+ const t = instOpt.transforms[i];+ ix = t.x ?? 0;+ iy = t.y ?? 0;+ iz = t.z ?? 0;+ if (typeof t.scale === "number") iscale = t.scale;+ if (iscale <= 0) continue;+ if (t.rotation) {+ if (t.rotation.length === 4) {+ iqx = t.rotation[0];+ iqy = t.rotation[1];+ iqz = t.rotation[2];+ iqw = t.rotation[3];+ } else {+ const q = quatFromEulerAngles(+ t.rotation[0],+ t.rotation[1],+ t.rotation[2],+ );+ iqx = q[0];+ iqy = q[1];+ iqz = q[2];+ iqw = q[3];+ }+ }+ if (t.color) {+ const p =+ typeof t.color === "string"+ ? parseColor(t.color)+ : {+ r: t.color[0],+ g: t.color[1],+ b: t.color[2],+ a: t.color[3] ?? 1,+ };+ if (p) {+ icr = p.r;+ icg = p.g;+ icb = p.b;+ ica = p.a;+ }+ }+ if (t.emissive) {+ const p =+ typeof t.emissive === "string"+ ? parseColor(t.emissive)+ : {+ r: t.emissive[0],+ g: t.emissive[1],+ b: t.emissive[2],+ };+ if (p) {+ ier = p.r;+ ieg = p.g;+ ieb = p.b;+ }+ iew = t.emissiveIntensity ?? 1.0;+ }+ } else {+ continue;+ }++ bucketCursors[k]++;+ bData[off + 0] = ix;+ bData[off + 1] = iy;+ bData[off + 2] = iz;+ bData[off + 3] = iscale;+ bData[off + 4] = iqx;+ bData[off + 5] = iqy;+ bData[off + 6] = iqz;+ bData[off + 7] = iqw;+ bData[off + 8] = icr;+ bData[off + 9] = icg;+ bData[off + 10] = icb;+ bData[off + 11] = ica;+ bData[off + 12] = ier;+ bData[off + 13] = ieg;+ bData[off + 14] = ieb;+ bData[off + 15] = iew;++ const rad = 50 * iscale;+ bBox.min[0] = Math.min(bBox.min[0], ix - rad);+ bBox.min[1] = Math.min(bBox.min[1], iy - rad);+ bBox.min[2] = Math.min(bBox.min[2], iz - rad);+ bBox.max[0] = Math.max(bBox.max[0], ix + rad);+ bBox.max[1] = Math.max(bBox.max[1], iy + rad);+ bBox.max[2] = Math.max(bBox.max[2], iz + rad);+ }++ for (let k = 0; k < numVariants; k++) {+ const bCount = bucketCursors[k];+ if (bCount === 0) continue;+ const v = variants[k];+ const activeSlice =+ bCount === bucketCounts[k]+ ? bucketItems[k]+ : bucketItems[k].subarray(0, bCount * 16);+ const instanceBuffer = r3d.uploadInstanceData(activeSlice);+ const bounds = Number.isFinite(bucketBounds[k].min[0])+ ? bucketBounds[k]+ : undefined;++ for (const mesh of v.meshes) {+ const mat = mesh.materialName+ ? v.materials[mesh.materialName]+ : undefined;+ const meshOpts: DrawMesh3DOpts = {+ modelMatrix: finalModelMatrix,+ opacity: modelOpacity * (mat?.opacity ?? 1.0),+ colorTint,+ transparent: false,+ twoSided: target?.twoSided ?? lop.twoSided ?? true,+ wireframe: Boolean(target?.wireframe ?? lop.wireframe),+ material:+ target?.material ??+ lop.material ??+ instOpt.material ??+ mat?.shading ??+ "lit",+ roughness:+ target?.roughness ??+ lop.roughness ??+ instOpt.roughness ??+ mat?.roughness,+ specularIntensity:+ target?.specularIntensity ??+ lop.specularIntensity ??+ instOpt.specularIntensity ??+ 0.5,+ ambientIntensity:+ target?.ambientIntensity ??+ lop.ambientIntensity ??+ instOpt.ambientIntensity ??+ 1.0,+ metallic:+ target?.metallic ??+ lop.metallic ??+ instOpt.metallic ??+ mat?.metallic,+ ...surfaceProps(target, lop, mat),+ instanceBuffer,+ instanceCount: bCount,+ bounds,+ };+ pending3DItems.push({+ kind: "mesh",+ mesh,+ texture: mat ? await r3d.materialTexture(mat) : undefined,+ opts: meshOpts,+ });+ }+ }+ return { finalTex: destTex, finalView: destView };+ }+ }+ }++ if (lop.swarm3d) {+ const swarmOpt = lop.swarm3d as Record<string, any>;+ const max = swarmOpt.max ?? 2000;+ const seed = swarmOpt.seed ?? 42;+ const substeps = swarmOpt.substeps ?? 2;+ const prewarm = swarmOpt.prewarm ?? 0;+ const emitter = swarmOpt.emitter ?? {};+ const speed = Array.isArray(swarmOpt.speed)+ ? swarmOpt.speed+ : [swarmOpt.speed ?? 100, swarmOpt.speed ?? 300];+ const direction = swarmOpt.direction ?? [0, -1, 0];+ const spread = ((swarmOpt.spread ?? 45) * Math.PI) / 180;+ const angularSpeed = Array.isArray(swarmOpt.angularSpeed)+ ? swarmOpt.angularSpeed+ : [swarmOpt.angularSpeed ?? 1, swarmOpt.angularSpeed ?? 6];+ const angularDrag = swarmOpt.angularDrag ?? 0.1;+ const lifetime = Array.isArray(swarmOpt.lifetime)+ ? swarmOpt.lifetime+ : [swarmOpt.lifetime ?? 2, swarmOpt.lifetime ?? 4];+ const size = Array.isArray(swarmOpt.size)+ ? swarmOpt.size+ : [swarmOpt.size ?? 18, swarmOpt.size ?? 12];+ const sizeJitter = swarmOpt.sizeJitter ?? 0.25;+ const fade = swarmOpt.fade ?? [0.15, 0.2];++ const colorStops: Array<[number, number, number, number]> = [];+ if (Array.isArray(swarmOpt.color)) {+ for (const c of swarmOpt.color) {+ const p = parseColor(c);+ if (p) colorStops.push([p.r, p.g, p.b, p.a]);+ }+ } else if (typeof swarmOpt.color === "string") {+ const p = parseColor(swarmOpt.color);+ if (p) colorStops.push([p.r, p.g, p.b, p.a]);+ }+ if (colorStops.length === 0) {+ colorStops.push([0.15, 0.14, 0.18, 1.0]);+ }++ const heatOpt = swarmOpt.heat ?? {};+ const heatColorStops: [+ [number, number, number],+ [number, number, number],+ [number, number, number],+ ] = [+ [0.1, 0.05, 0.15],+ [1.0, 0.0, 0.6],+ [1.0, 0.9, 1.0],+ ];+ if (Array.isArray(heatOpt.color) && heatOpt.color.length >= 2) {+ const c0 = parseColor(heatOpt.color[0]) ?? {+ r: 0.1,+ g: 0.05,+ b: 0.15,+ };+ const c1 = parseColor(+ heatOpt.color[Math.floor(heatOpt.color.length / 2)],+ ) ?? { r: 1.0, g: 0.0, b: 0.6 };+ const c2 = parseColor(heatOpt.color[heatOpt.color.length - 1]) ?? {+ r: 1.0,+ g: 0.9,+ b: 1.0,+ };+ heatColorStops[0] = [c0.r, c0.g, c0.b];+ heatColorStops[1] = [c1.r, c1.g, c1.b];+ heatColorStops[2] = [c2.r, c2.g, c2.b];+ }++ const rawVariants = Array.isArray(swarmOpt.meshVariants)+ ? swarmOpt.meshVariants+ : swarmOpt.mesh+ ? [swarmOpt.mesh]+ : [];+ const variants: Model3DData[] = [];+ for (const m of rawVariants) {+ let vModel: Model3DData | undefined;+ if (m && typeof m === "object") {+ if ("meshes" in m && Array.isArray((m as any).meshes)) {+ vModel = m as Model3DData;+ } else if (m.modelData && "meshes" in m.modelData) {+ vModel = m.modelData as Model3DData;+ } else if (m.primitive3d) {+ vModel = getPrimitiveGeometry(+ m.primitive3d as PrimitiveGeometryOptions,+ );+ } else if (m.src) {+ try {+ vModel = r3d.loadModel(m.src, m.modelFormat ?? "auto", {+ center: m.center,+ normalizeSize: m.normalizeSize,+ });+ } catch {}+ }+ }+ if (vModel && vModel.meshes && vModel.meshes.length > 0) {+ variants.push(vModel);+ }+ }+ if (variants.length === 0 && model) {+ variants.push(model);+ }++ let meshRadius = 20;+ const primaryBounds = variants[0]?.bounds;+ if (primaryBounds) {+ const dx = primaryBounds.max[0] - primaryBounds.min[0];+ const dy = primaryBounds.max[1] - primaryBounds.min[1];+ const dz = primaryBounds.max[2] - primaryBounds.min[2];+ const maxExtent = Math.max(dx, dy, dz) * 0.5;+ if (Number.isFinite(maxExtent) && maxExtent > 0.1) {+ meshRadius = maxExtent;+ }+ }++ let sparksConfig: Swarm3DStaticConfig["sparks"] | undefined;+ if (swarmOpt.sparks && typeof swarmOpt.sparks === "object") {+ const sp = swarmOpt.sparks;+ const spSize = Array.isArray(sp.size)+ ? [sp.size[0] ?? 3.2, sp.size[1] ?? 1.2]+ : [sp.size ?? 3.2, (sp.size ?? 3.2) * 0.35];+ const spLife = Array.isArray(sp.lifetime)+ ? [sp.lifetime[0] ?? 0.35, sp.lifetime[1] ?? 0.9]+ : [sp.lifetime ?? 0.35, (sp.lifetime ?? 0.6) * 1.4];+ const spSpeed = Array.isArray(sp.speed)+ ? [sp.speed[0] ?? 60, sp.speed[1] ?? 260]+ : [60, sp.speed ?? 260];+ let spColor: [number, number, number] = [1, 0.9, 1];+ if (Array.isArray(sp.color) && sp.color.length >= 1) {+ const sc = parseColor(+ sp.color[Math.floor(sp.color.length / 2)],+ ) ??+ parseColor(sp.color[0]) ?? { r: 1, g: 0.9, b: 1 };+ spColor = [sc.r, sc.g, sc.b];+ } else if (typeof sp.color === "string") {+ const sc = parseColor(sp.color) ?? { r: 1, g: 0.9, b: 1 };+ spColor = [sc.r, sc.g, sc.b];+ }+ sparksConfig = {+ max: sp.max ?? 2000,+ rate: sp.rate ?? 600,+ threshold: sp.threshold ?? 0.25,+ size: [spSize[0], spSize[1]],+ lifetime: [spLife[0], spLife[1]],+ speed: [spSpeed[0], spSpeed[1]],+ intensity: sp.intensity ?? 9.0,+ color: spColor,+ };+ }++ const staticConfig: Swarm3DStaticConfig = {+ max,+ seed,+ substeps,+ prewarm,+ emitter: {+ shape: emitter.shape ?? "point",+ x: emitter.x ?? 0,+ y: emitter.y ?? 0,+ z: emitter.z ?? 0,+ width: emitter.width ?? 100,+ height: emitter.height ?? 100,+ depth: emitter.depth ?? 100,+ radius: emitter.radius ?? 50,+ },+ speed: [speed[0], speed[1]],+ direction: [direction[0], direction[1], direction[2]],+ spread,+ angularSpeed: [angularSpeed[0], angularSpeed[1]],+ angularDrag,+ lifetime: [lifetime[0], lifetime[1]],+ size: [size[0], size[1]],+ sizeJitter,+ fade: [fade[0], fade[1]],+ colors: colorStops,+ heat: {+ source: heatOpt.source ?? "both",+ maxSpeed: heatOpt.maxSpeed ?? 900,+ curve: heatOpt.curve ?? 1.6,+ intensity: heatOpt.intensity ?? 5.0,+ colors: heatColorStops,+ },+ variants: Math.max(1, variants.length),+ meshRadius,+ sparks: sparksConfig,+ };++ let swarmState = swarmStateMap.get(lop);+ if (!swarmState || swarmState.device !== ctx.device) {+ swarmState = r3d.swarm3dPipeline.createState(staticConfig);+ swarmStateMap.set(lop, swarmState);+ }++ const targetF = shiftedFrame ?? 0;+ const frameSampler = (f: number): Swarm3DFrameInput => {+ const fCtx = {+ frame: f,+ fps: fps || 30,+ time: f / (fps || 30),+ duration: 0,+ durationMs: 0,+ progress: 0,+ deltaTime: 1 / (fps || 30),+ };+ const sample = (d: any, fallback: number) =>+ typeof d === "number"+ ? d+ : typeof d?.get === "function"+ ? Number(d.get(fCtx))+ : typeof d === "function"+ ? Number(d(f))+ : fallback;++ const grav = swarmOpt.gravity;+ let gx = 0;+ let gy = 1200;+ let gz = 0;+ if (Array.isArray(grav)) {+ gx = sample(grav[0], 0);+ gy = sample(grav[1], 1200);+ gz = sample(grav[2], 0);+ } else if (grav !== undefined) {+ gy = sample(grav, 1200);+ }++ const rate = sample(emitter.rate, 150);+ const dragVal = sample(swarmOpt.drag, 0.05);++ let noiseStrength = 0;+ let noiseScale = 200;+ let noiseSpeed = 1.0;+ if (swarmOpt.noise) {+ noiseStrength = sample(swarmOpt.noise.strength, 0);+ noiseScale = swarmOpt.noise.scale ?? 200;+ noiseSpeed = swarmOpt.noise.speed ?? 1.0;+ }++ const attractors: Array<{+ x: number;+ y: number;+ z: number;+ strength: number;+ radius?: number;+ }> = [];+ if (Array.isArray(swarmOpt.attractors)) {+ for (const a of swarmOpt.attractors) {+ attractors.push({+ x: sample(a.x, 0),+ y: sample(a.y, 0),+ z: sample(a.z, 0),+ strength: sample(a.strength, 0),+ radius: a.radius,+ });+ }+ }++ let vortex: Swarm3DFrameInput["vortex"] | undefined;+ if (swarmOpt.vortex) {+ vortex = {+ x: sample(swarmOpt.vortex.x, 0),+ y: sample(swarmOpt.vortex.y, 0),+ z: sample(swarmOpt.vortex.z, 0),+ axis: swarmOpt.vortex.axis ?? [0, -1, 0],+ swirl: sample(swarmOpt.vortex.swirl, 0),+ pull: sample(swarmOpt.vortex.pull, 0),+ axial: sample(swarmOpt.vortex.axial, 0),+ radius: swarmOpt.vortex.radius ?? 800,+ };+ }++ let floor: Swarm3DFrameInput["floor"] | undefined;+ if (swarmOpt.floor) {+ floor = {+ y: swarmOpt.floor.y ?? 500,+ bounce: swarmOpt.floor.bounce ?? 0.3,+ friction: sample(swarmOpt.floor.friction, 1.5),+ heatGain: swarmOpt.floor.heatGain ?? 1.0,+ heatDecay: swarmOpt.floor.heatDecay ?? 0.45,+ };+ }++ let emitterPos: [number, number, number] | undefined;+ if (+ emitter.x !== undefined ||+ emitter.y !== undefined ||+ emitter.z !== undefined+ ) {+ emitterPos = [+ sample(emitter.x, 0),+ sample(emitter.y, 0),+ sample(emitter.z, 0),+ ];+ }++ return {+ rate,+ gravity: [gx, gy, gz],+ drag: dragVal,+ noise: {+ strength: noiseStrength,+ scale: noiseScale,+ speed: noiseSpeed,+ },+ attractors,+ vortex,+ floor,+ emitterPos,+ };+ };++ r3d.swarm3dPipeline.advance(+ swarmState,+ staticConfig,+ targetF,+ fps || 30,+ frameSampler,+ );++ if (variants.length > 0) {+ const sliceCount = swarmState.sliceCount;+ for (let vIdx = 0; vIdx < variants.length; vIdx++) {+ const vModel = variants[vIdx];+ const firstInstance = vIdx * sliceCount;+ for (const mesh of vModel.meshes) {+ const mat = mesh.materialName+ ? vModel.materials[mesh.materialName]+ : undefined;+ const meshOpts: DrawMesh3DOpts = {+ modelMatrix: finalModelMatrix,+ opacity: modelOpacity,+ colorTint,+ transparent: false,+ twoSided: target?.twoSided ?? lop.twoSided ?? true,+ wireframe: Boolean(target?.wireframe ?? lop.wireframe),+ material:+ target?.material ??+ lop.material ??+ swarmOpt.material ??+ mat?.shading ??+ "lit",+ roughness:+ target?.roughness ??+ lop.roughness ??+ swarmOpt.roughness ??+ mat?.roughness ??+ 0.35,+ specularIntensity:+ target?.specularIntensity ??+ lop.specularIntensity ??+ swarmOpt.specularIntensity ??+ 0.5,+ ambientIntensity:+ target?.ambientIntensity ??+ lop.ambientIntensity ??+ swarmOpt.ambientIntensity ??+ 1.0,+ metallic:+ target?.metallic ??+ lop.metallic ??+ swarmOpt.metallic ??+ mat?.metallic ??+ 0.7,+ ...surfaceProps(target, lop, mat),+ instanceBuffer: swarmState.instances,+ instanceCount: sliceCount,+ firstInstance,+ };+ pending3DItems.push({+ kind: "mesh",+ mesh,+ texture: mat ? await r3d.materialTexture(mat) : undefined,+ opts: meshOpts,+ });+ }+ }++ if (sparksConfig && sparksConfig.max > 0) {+ const sparkModel = variants[0];+ const sparkFirst = variants.length * sliceCount;+ for (const mesh of sparkModel.meshes) {+ const mat = mesh.materialName+ ? sparkModel.materials[mesh.materialName]+ : undefined;+ const sparkOpts: DrawMesh3DOpts = {+ modelMatrix: finalModelMatrix,+ opacity: modelOpacity,+ colorTint,+ transparent: false,+ twoSided: true,+ wireframe: false,+ material: "lit",+ roughness: 0.2,+ specularIntensity: 0.8,+ ambientIntensity: 1.0,+ metallic: 0.9,+ ...surfaceProps(target, lop, mat),+ instanceBuffer: swarmState.instances,+ instanceCount: sparksConfig.max,+ firstInstance: sparkFirst,+ };+ pending3DItems.push({+ kind: "mesh",+ mesh,+ texture: mat ? await r3d.materialTexture(mat) : undefined,+ opts: sparkOpts,+ });+ }+ }+ }+ return { finalTex: destTex, finalView: destView };+ }+// Animation evaluationlet skinningMatrices: Float32Array | undefined;const animProgress =diff --git a/packages/compositions/src/program/schema.ts b/packages/compositions/src/program/schema.tsindex 311afc42..66129e3b 100644--- a/packages/compositions/src/program/schema.ts+++ b/packages/compositions/src/program/schema.ts@@ -1314,6 +1314,25 @@ export const BloomConfigSchema = z.strict();export type BloomConfig = z.infer<typeof BloomConfigSchema>;+export const EnvironmentFloorSchema = z+ .object({+ /** World Y coordinate of the floor plane (px, y down). */+ y: z.number(),+ /** Base floor surface color (default "#08070a"). */+ color: ColorSchema.optional(),+ /** Mirror reflectivity at normal incidence / Fresnel scale, 0..1 (default 0.35). */+ reflectivity: z.number().min(0).max(1).optional(),+ /** Surface roughness 0..1: controls anisotropic vertical/horizontal reflection blur (default 0.35). */+ roughness: z.number().min(0).max(1).optional(),+ /** Reflection fade-out distance from the floor plane in world Y px (default 900). */+ fadeDistance: z.number().min(0).optional(),+ /** Optional overall opacity of the floor plane, 0..1 (default 1; 0 draws only additive reflection over background). */+ opacity: z.number().min(0).max(1).optional(),+ })+ .strict();++export type EnvironmentFloor = z.infer<typeof EnvironmentFloorSchema>;+export interface LightNode {id: string;kind: "light";@@ -1349,6 +1368,7 @@ export interface LightNode {exposure?: number;toneMapping?: ToneMapping;fog?: EnvironmentFog;+ floor?: EnvironmentFloor;/** Glow around emissive surfaces and hot highlights: `true` or settings. */bloom?: boolean | BloomConfig;startFrame?: number;@@ -1387,6 +1407,7 @@ export const LightNodeSchema: z.ZodType<LightNode> = zexposure: z.number().min(-16).max(16).optional(),toneMapping: ToneMappingSchema.optional(),fog: EnvironmentFogSchema.optional(),+ floor: EnvironmentFloorSchema.optional(),bloom: z.union([z.boolean(), BloomConfigSchema]).optional(),startFrame: z.number().int().min(0).default(0),durationFrames: z.number().int().min(1).optional(),@@ -1445,8 +1466,12 @@ export interface Model3DNode {animation?: LayerAnimationSpec;audioDeform?: MeshAudioDeformConfig;text3dOptions?: unknown;- /** Layer3D primitive options (roundedBox, sphere, cylinder) the mesh is rebuilt from when modelData is lost. */+ /** Layer3D primitive options (roundedBox, sphere, cylinder, shard) the mesh is rebuilt from when modelData is lost. */primitive3d?: unknown;+ /** Layer3D.instances hardware-instancing options. */+ instances3d?: unknown;+ /** Layer3D.swarm GPU simulation and instancing options. */+ swarm3d?: unknown;}export type LayoutNode =@@ -1769,6 +1794,8 @@ export const Model3DNodeSchema: z.ZodType<Model3DNode> = zcolorTint: ColorSchema.optional(),text3dOptions: z.unknown().optional(),primitive3d: z.unknown().optional(),+ instances3d: z.unknown().optional(),+ swarm3d: z.unknown().optional(),}).strict() as unknown as z.ZodType<Model3DNode>;diff --git a/packages/framefields/src/clip-vision.ts b/packages/framefields/src/clip-vision.tsindex 6cdf28b9..1f42dccd 100644--- a/packages/framefields/src/clip-vision.ts+++ b/packages/framefields/src/clip-vision.ts@@ -391,8 +391,9 @@ export class ClipVision implements ClipSubjectSource {blurredMask(c: number): Float32Array | null {c = Math.max(0, c);if (this.blurred.has(c)) return this.blurred.get(c) ?? null;- const r = this.mustHave(c);- const grid = r.mask ? boxBlur(r.mask, this.cellW, this.cellH, 2) : null;+ this.mustHave(c);+ const mask = bridgedMask(this.results, c, this.smoothing);+ const grid = mask ? boxBlur(mask, this.cellW, this.cellH, 2) : null;this.blurred.set(c, grid);return grid;}@@ -792,29 +793,68 @@ type Segmentation = Awaited<ReturnType<VisionRunner["segment"]>>;* than twice its size (a flowing dress often comes back as "kite").*/function personSilhouette(seg: Segmentation): Uint8Array | undefined {- const people = seg.masks.filter((m) => m.category === "person");- if (people.length === 0) return undefined;- const person = people.reduce((a, b) => (b.area > a.area ? b : a));- const box = seg.detections[person.detectionIndex]?.boundingBox;- const out = new Uint8Array(person.mask);- if (!box) return out;- for (const m of seg.masks) {- if (m === person || m.area > person.area * 2) continue;- const b = seg.detections[m.detectionIndex]?.boundingBox;- if (!b) continue;- const ix = Math.max(- 0,- Math.min(box.originX + box.width, b.originX + b.width) -- Math.max(box.originX, b.originX),- );- const iy = Math.max(- 0,- Math.min(box.originY + box.height, b.originY + b.height) -- Math.max(box.originY, b.originY),- );- if (ix * iy < 0.3 * b.width * b.height) continue;- for (let i = 0; i < out.length; i++)- if (m.mask[i] > out[i]) out[i] = m.mask[i];+ return mergeSubjectMask(seg.masks, {+ classes: ["person"],+ overlap: 0.2,+ maxGrowth: 3.5,+ })?.mask;+}++function maskSum(m: Uint8Array | null | undefined): number {+ if (!m) return 0;+ let s = 0;+ for (let i = 0; i < m.length; i++) s += m[i];+ return s;+}++/**+ * Bridges 1–2 frame segmentation part dropouts (e.g. a fast-spinning skirt+ * missed on a single frame) across the smoothing window.+ */+function bridgedMask(+ results: Map<number, FrameResult>,+ c: number,+ smoothing: number,+): Uint8Array | null {+ const base = results.get(c)?.mask ?? null;+ if (smoothing <= 0) return base;+ const baseSum = maskSum(base);+ let prevFrame = -1;+ let prevMask: Uint8Array | null = null;+ let nextFrame = -1;+ let nextMask: Uint8Array | null = null;+ const threshold = Math.max(1000, baseSum * 1.35);++ for (let d = 1; d <= smoothing + 1; d++) {+ if (prevFrame < 0 && c - d >= 0) {+ const m = results.get(c - d)?.mask ?? null;+ if (maskSum(m) > threshold) {+ prevFrame = c - d;+ prevMask = m;+ }+ }+ if (nextFrame < 0) {+ const m = results.get(c + d)?.mask ?? null;+ if (maskSum(m) > threshold) {+ nextFrame = c + d;+ nextMask = m;+ }+ }+ }+ if (!prevMask && !nextMask) return base;+ const ref = prevMask ?? nextMask;+ if (!ref) return base;+ const out = base ? new Uint8Array(base) : new Uint8Array(ref.length);+ if (prevMask && nextMask && nextFrame > prevFrame) {+ const u = (c - prevFrame) / (nextFrame - prevFrame);+ for (let i = 0; i < out.length; i++) {+ const v = Math.round(prevMask[i] + (nextMask[i] - prevMask[i]) * u);+ if (v > out[i]) out[i] = v;+ }+ } else {+ for (let i = 0; i < out.length; i++) {+ if (ref[i] > out[i]) out[i] = ref[i];+ }}return out;}diff --git a/packages/framefields/src/floor-reflection-render.test.ts b/packages/framefields/src/floor-reflection-render.test.tsnew file mode 100644index 00000000..58e5be6f--- /dev/null+++ b/packages/framefields/src/floor-reflection-render.test.ts@@ -0,0 +1,199 @@+import { Canvas, loadImage } from "skia-canvas";+import { describe, expect, it } from "vitest";+import { Composition, Layer, Layer3D } from "./index.js";++async function decode(png: Buffer) {+ const img = await loadImage(png);+ const canvas = new Canvas(img.width, img.height);+ const ctx = canvas.getContext("2d");+ ctx.drawImage(img, 0, 0);+ const { data } = ctx.getImageData(0, 0, img.width, img.height);+ return {+ at(x: number, y: number) {+ const i = (Math.round(y) * img.width + Math.round(x)) * 4;+ return {+ r: data[i] ?? 0,+ g: data[i + 1] ?? 0,+ b: data[i + 2] ?? 0,+ };+ },+ data,+ };+}++describe("Glossy Floor Reflection (Environment.floor)", () => {+ it("renders planar reflection of glowing 3D shards on the glossy floor with HDR bloom", async () => {+ const comp = new Composition({+ width: 400,+ height: 400,+ fps: 30,+ durationMs: 1000,+ backgroundColor: "#05040a",+ });++ comp.add([+ Layer.camera({+ x: 200,+ y: 80,+ z: -350,+ targetX: 200,+ targetY: 240,+ targetZ: 0,+ }),+ Layer.environment("night", {+ floor: {+ y: 220,+ color: "#08070e",+ reflectivity: 0.7,+ roughness: 0.15,+ fadeDistance: 900,+ opacity: 1.0,+ },+ bloom: { intensity: 1.2, threshold: 0.8 },+ }),+ Layer.directionalLight({+ color: "#ffffff",+ intensity: 1.0,+ x: 100,+ y: 50,+ z: -200,+ targetX: 200,+ targetY: 220,+ targetZ: 0,+ }),+ Layer3D.shard({+ x: 200,+ y: 160,+ z: 0,+ radius: 35,+ color: "#00ffff",+ emissive: "#00ffff",+ emissiveStrength: 4.0,+ }),+ ]);++ const png = await comp.renderFrame(0);+ const { data, at } = await decode(png);++ // 1. Shard itself is visible above the floor line (y ≈ 160)+ const shardSample = at(200, 160);+ expect(shardSample.g + shardSample.b).toBeGreaterThan(100);++ // 2. Floor plane below y = 220 receives the cyan reflection of the shard+ // Look in the reflection region (y ≈ 260 to 300)+ let floorReflectionFound = false;+ for (let y = 240; y < 320; y += 4) {+ const p = at(200, y);+ if (p.b > 25 || p.g > 25) {+ floorReflectionFound = true;+ break;+ }+ }+ expect(floorReflectionFound).toBe(true);++ // 3. Confirm floor reflection contains bloom radiance+ let brightPixels = 0;+ for (let i = 0; i < data.length; i += 4) {+ const b = data[i + 2] ?? 0;+ if (b > 150) brightPixels++;+ }+ expect(brightPixels).toBeGreaterThan(20);+ });++ it("applies anisotropic roughness blur to floor reflections", async () => {+ // Test that higher roughness spreads out reflection pixels vertically+ const compSharp = new Composition({+ width: 300,+ height: 300,+ fps: 30,+ durationMs: 1000,+ backgroundColor: "#05040a",+ });+ compSharp.add([+ Layer.camera({+ x: 150,+ y: 70,+ z: -250,+ targetX: 150,+ targetY: 180,+ targetZ: 0,+ }),+ Layer.environment("night", {+ floor: {+ y: 170,+ reflectivity: 0.8,+ roughness: 0.0,+ },+ }),+ Layer3D.shard({+ x: 150,+ y: 120,+ z: 0,+ radius: 25,+ color: "#ff007f",+ emissive: "#ff007f",+ emissiveStrength: 3.0,+ }),+ ]);++ const compRough = new Composition({+ width: 300,+ height: 300,+ fps: 30,+ durationMs: 1000,+ backgroundColor: "#05040a",+ });+ compRough.add([+ Layer.camera({+ x: 150,+ y: 70,+ z: -250,+ targetX: 150,+ targetY: 180,+ targetZ: 0,+ }),+ Layer.environment("night", {+ floor: {+ y: 170,+ reflectivity: 0.8,+ roughness: 0.5,+ },+ }),+ Layer3D.shard({+ x: 150,+ y: 120,+ z: 0,+ radius: 25,+ color: "#ff007f",+ emissive: "#ff007f",+ emissiveStrength: 3.0,+ }),+ ]);++ const pngSharp = await compSharp.renderFrame(0);+ const pngRough = await compRough.renderFrame(0);++ const { at: atSharp } = await decode(pngSharp);+ const { at: atRough } = await decode(pngRough);++ // Find where magenta reflection appears on the floor below y = 140+ let maxSharpR = 0;+ let maxRoughR = 0;+ for (let y = 140; y < 290; y++) {+ const s = atSharp(150, y);+ const r = atRough(150, y);+ if (s.r > maxSharpR) maxSharpR = s.r;+ if (r.r > maxRoughR) maxRoughR = r.r;+ }+ // Both reflect magenta+ expect(maxSharpR).toBeGreaterThan(50);+ expect(maxRoughR).toBeGreaterThan(50);++ // And rough floor spreads radiance vertically wider+ let roughReflectedCount = 0;+ for (let y = 180; y < 270; y += 2) {+ if (atRough(150, y).r > 5) roughReflectedCount++;+ }+ expect(roughReflectedCount).toBeGreaterThan(10);+ });+});diff --git a/packages/framefields/src/index.ts b/packages/framefields/src/index.tsindex 42d3f8e5..dcdabc63 100644--- a/packages/framefields/src/index.ts+++ b/packages/framefields/src/index.ts@@ -517,6 +517,8 @@ export {type EaseRef,type EnhancedTextNode,EnhancedTextNodeSchema,+ type EnvironmentFloor,+ EnvironmentFloorSchema,type EnvironmentFog,EnvironmentFogSchema,type EnvironmentPreset,@@ -928,6 +930,8 @@ export {type Cylinder3DOptions,type ExtrudedText3DOptions,type Grid3DOptions,+ type Instances3DOptions,+ type InstanceTransform3D,Layer3D,type Plane3DOptions,type Primitive3DNodeOptions,@@ -939,6 +943,7 @@ export {type Text3DOptions,} from "./shapes3d.js";export { type StyleName, Styles } from "./styles.js";+export type { Swarm3DOptions } from "./swarm3d.js";export {type SceneSequenceOptions,type SequenceEntry,@@ -3363,6 +3368,7 @@ export type EnvironmentOptions = Partial<| "exposure"| "toneMapping"| "fog"+ | "floor"| "bloom"| "startFrame"| "durationFrames"diff --git a/packages/framefields/src/instances-3d-render.test.ts b/packages/framefields/src/instances-3d-render.test.tsnew file mode 100644index 00000000..45dc8a2d--- /dev/null+++ b/packages/framefields/src/instances-3d-render.test.ts@@ -0,0 +1,174 @@+import { Canvas, loadImage } from "skia-canvas";+import { describe, expect, it } from "vitest";+import { Composition, Layer, Layer3D, Physics } from "./index.js";++async function decode(png: Buffer) {+ const img = await loadImage(png);+ const canvas = new Canvas(img.width, img.height);+ const ctx = canvas.getContext("2d");+ ctx.drawImage(img, 0, 0);+ const { data } = ctx.getImageData(0, 0, img.width, img.height);+ return {+ at(x: number, y: number) {+ const i = (Math.round(y) * img.width + Math.round(x)) * 4;+ return { r: data[i] ?? 0, g: data[i + 1] ?? 0, b: data[i + 2] ?? 0 };+ },+ data,+ };+}++describe("Layer3D.instances hardware instancing", () => {+ it("renders 100+ instanced procedural shards in a single batch", async () => {+ const comp = new Composition({+ width: 600,+ height: 600,+ fps: 30,+ durationMs: 1000,+ backgroundColor: "#000000",+ });++ comp.add([+ Layer.camera({+ x: 300,+ y: 300,+ z: -600,+ targetX: 300,+ targetY: 300,+ targetZ: 0,+ }),+ Layer.ambientLight("#333333", 0.5),+ Layer.directionalLight({+ color: "#ffffff",+ intensity: 1.5,+ x: 200,+ y: 100,+ z: -500,+ targetX: 300,+ targetY: 300,+ targetZ: 0,+ }),+ ]);++ const shardVariants = [+ Layer3D.shard({ radius: 18, facets: 10, seed: 1, irregularity: 0.3 }),+ Layer3D.shard({ radius: 22, facets: 14, seed: 42, irregularity: 0.5 }),+ Layer3D.shard({ radius: 16, facets: 8, seed: 99, irregularity: 0.2 }),+ ];++ const count = 120;+ comp.add(+ Layer3D.instances({+ mesh: shardVariants,+ count,+ material: "lit",+ roughness: 0.3,+ metallic: 0.8,+ instanceAt(i) {+ const angle = (i / count) * Math.PI * 6;+ const radius = 40 + (i / count) * 180;+ return {+ x: 300 + Math.cos(angle) * radius,+ y: 300 + Math.sin(angle) * radius,+ z: (i - count / 2) * 2,+ scale: 0.8 + (i % 5) * 0.1,+ rotation: [i * 15, i * 27, i * 33],+ color: i % 2 === 0 ? "#00e5ff" : "#ff007f",+ emissive: i % 5 === 0 ? "#ffffff" : undefined,+ emissiveIntensity: i % 5 === 0 ? 3.0 : 0,+ };+ },+ }),+ );++ const png = await comp.renderFrame(0);+ const { data } = await decode(png);++ let nonBlack = 0;+ let hasCyan = 0;+ let hasMagenta = 0;+ for (let i = 0; i < data.length; i += 4) {+ const r = data[i] ?? 0;+ const g = data[i + 1] ?? 0;+ const b = data[i + 2] ?? 0;+ if (r > 20 || g > 20 || b > 20) {+ nonBlack++;+ if (b > 100 && g > 100 && r < 80) hasCyan++;+ if (r > 100 && b > 100 && g < 80) hasMagenta++;+ }+ }++ expect(nonBlack).toBeGreaterThan(1500);+ expect(hasCyan).toBeGreaterThan(100);+ expect(hasMagenta).toBeGreaterThan(100);+ });++ it("renders hardware instances driven by Physics.world3d rigid bodies", async () => {+ const comp = new Composition({+ width: 600,+ height: 600,+ fps: 30,+ durationMs: 1000,+ backgroundColor: "#050508",+ });++ comp.add([+ Layer.camera({+ x: 300,+ y: 200,+ z: -600,+ targetX: 300,+ targetY: 300,+ targetZ: 0,+ }),+ Layer.ambientLight("#ffffff", 0.6),+ ]);++ const physics = await Physics.world3d({+ gravity: 3000,+ fps: 30,+ frames: 30,+ });+ physics.ground({ y: 500 });++ const shardMesh = Layer3D.shard({ radius: 25, facets: 12, seed: 7 });+ const numBodies = 25;+ const bodies = [];+ for (let i = 0; i < numBodies; i++) {+ bodies.push(+ physics.body(shardMesh, {+ x: 200 + (i % 5) * 50,+ y: 100 + Math.floor(i / 5) * 50,+ z: (i % 3) * 30,+ shape: "hull",+ velocity: [(i % 2 === 0 ? 1 : -1) * 100, 0, 0],+ }),+ );+ }+ physics.simulate();++ comp.add(+ Layer3D.instances({+ mesh: shardMesh,+ bodies,+ color: "#ffaa00",+ emissiveBySpeed: {+ color: ["#ffaa00", "#ffffff"],+ maxSpeed: 800,+ intensity: 2.0,+ },+ }),+ );++ const png = await comp.renderFrame(15);+ const { data } = await decode(png);++ let nonBlack = 0;+ for (let i = 0; i < data.length; i += 4) {+ const r = data[i] ?? 0;+ const g = data[i + 1] ?? 0;+ const b = data[i + 2] ?? 0;+ if (r > 30 || g > 30 || b > 30) nonBlack++;+ }+ expect(nonBlack).toBeGreaterThan(1000);+ });+});diff --git a/packages/framefields/src/physics/physics-render.test.ts b/packages/framefields/src/physics/physics-render.test.tsindex 683c4883..62976e6b 100644--- a/packages/framefields/src/physics/physics-render.test.ts+++ b/packages/framefields/src/physics/physics-render.test.ts@@ -167,4 +167,47 @@ describe("physics render", () => {expect(rest.r).toBeGreaterThan(120);expect(rest.g).toBeLessThan(rest.r / 2);});++ it("drops a 3D shard with convex hull collider onto the ground", async () => {+ const c = new Composition({+ width: 800,+ height: 600,+ fps: FPS,+ durationFrames: 60,+ backgroundColor: "#000000",+ });+ c.add([+ Layer.camera({+ x: 400,+ y: 300,+ z: -900,+ targetX: 400,+ targetY: 300,+ targetZ: 0,+ }),+ Layer.ambientLight("#ffffff", 1),+ ]);+ const shard = Layer3D.shard({+ id: "shard",+ radius: 60,+ facets: 12,+ seed: 123,+ x: 400,+ y: -200,+ z: 0,+ color: "#30ff30",+ });+ c.add(shard);+ const world = await Physics.world3d({ fps: FPS, frames: 60 });+ world.ground({ y: 360 });+ world.body(shard, { restitution: 0, angularDamping: 2 });+ world.simulate();++ const start = await frame(c, 0);+ const end = await frame(c, 59);+ expect(getPixel(start, 400, 300).g).toBeLessThan(20);+ const rest = getPixel(end, 400, 300);+ expect(rest.g).toBeGreaterThan(120);+ expect(rest.r).toBeLessThan(rest.g / 2);+ });});diff --git a/packages/framefields/src/physics/world3d.ts b/packages/framefields/src/physics/world3d.tsindex 3db494fb..39a1c289 100644--- a/packages/framefields/src/physics/world3d.ts+++ b/packages/framefields/src/physics/world3d.ts@@ -43,6 +43,18 @@ export interface PhysicsBox3D {}export interface Body3DOptions extends Omit<BodyCommonOptions, "lockRotation"> {+ /** Initial X position override in px. */+ x?: number;+ /** Initial Y position override in px. */+ y?: number;+ /** Initial Z position override in px. */+ z?: number;+ /** Initial Euler X rotation override in degrees. */+ rotateX?: number;+ /** Initial Euler Y rotation override in degrees. */+ rotateY?: number;+ /** Initial Euler Z rotation override in degrees. */+ rotateZ?: number;/*** Never rotates (`true`), or only around some axes: `{ x: true, y: true }`* keeps a card facing the camera while it still spins in the picture plane.@@ -367,11 +379,15 @@ export class PhysicsWorld3D extends WorldCore<Vec3, Quat, PhysicsBody3D> {const isLayer = typeof (target as unknown as LayerLike).kind === "string";const layer = isLayer ? (target as unknown as LayerLike) : undefined;const t = target as unknown as LayerLike;- const position: Vec3 = [num(t.x, 0), num(t.y, 0), num(t.z, 0)];+ const position: Vec3 = [+ num(options.x ?? t.x, 0),+ num(options.y ?? t.y, 0),+ num(options.z ?? t.z, 0),+ ];const rotation: Vec3 = [- num(t.rotateX, 0),- num(t.rotateY, 0),- num(t.rotateZ, 0),+ num(options.rotateX ?? t.rotateX, 0),+ num(options.rotateY ?? t.rotateY, 0),+ num(options.rotateZ ?? t.rotateZ, 0),];const ppm = this.pixelsPerMeter;const type = options.type ?? "dynamic";diff --git a/packages/framefields/src/primitives-3d-render.test.ts b/packages/framefields/src/primitives-3d-render.test.tsindex 470fa89b..33e08d09 100644--- a/packages/framefields/src/primitives-3d-render.test.ts+++ b/packages/framefields/src/primitives-3d-render.test.ts@@ -189,6 +189,39 @@ describe("Layer3D mesh primitives", () => {expect(center.g).toBeGreaterThan(150);expect(center.r).toBeLessThan(center.g / 2);});++ it("renders a faceted 3D shard with specular highlight", async () => {+ const comp = stage();+ comp.add(+ Layer.directionalLight({+ color: "#ffffff",+ intensity: 1.5,+ x: 300,+ y: 0,+ z: -500,+ targetX: 400,+ targetY: 300,+ targetZ: 0,+ }),+ );+ comp.add(+ Layer3D.shard({+ radius: 120,+ facets: 14,+ seed: 7,+ irregularity: 0.4,+ x: 400,+ y: 300,+ color: "#ff0077",+ material: "lit",+ }),+ );+ const decoded = await decode(await comp.renderFrame({ frame: 0 }));+ const pixel = decoded.at(400, 300);+ // Shard is brightly lit and drawn with #ff0077 base color+ expect(pixel.r).toBeGreaterThan(100);+ expect(pixel.b).toBeGreaterThan(30);+ });});describe("text reveal by count", () => {diff --git a/packages/framefields/src/shapes3d.ts b/packages/framefields/src/shapes3d.tsindex a64677d2..d13d542d 100644--- a/packages/framefields/src/shapes3d.ts+++ b/packages/framefields/src/shapes3d.ts@@ -11,11 +11,14 @@ import {type Model3DData,type PrimitiveGeometryOptions,type RoundedBoxGeometryOptions,+ type ShardGeometryOptions,SlugFontCache,type SphereGeometryOptions,} from "@framefields/webgpu-renderers";import { autoId } from "./ids.js";import { type AnimatableNode, Layer } from "./index.js";+import type { PhysicsBody3D } from "./physics/world3d.js";+import { createSwarm3D, type Swarm3DOptions } from "./swarm3d.js";/** Physically based surface options every 3D builder accepts. */export interface Surface3DOptions {@@ -303,6 +306,64 @@ export type Sphere3DOptions = Primitive3DNodeOptions &Omit<SphereGeometryOptions, "type" | "color" | "material">;export type Cylinder3DOptions = Primitive3DNodeOptions &Omit<CylinderGeometryOptions, "type" | "color" | "material">;+export type Shard3DOptions = Primitive3DNodeOptions &+ Omit<ShardGeometryOptions, "type" | "color" | "material">;++export interface InstanceTransform3D {+ x: number;+ y: number;+ z: number;+ /** Euler degrees [rx, ry, rz] or unit quaternion [qx, qy, qz, qw]. */+ rotation?: [number, number, number] | [number, number, number, number];+ scale?: number;+ color?: string | [number, number, number, number];+ emissive?: string | [number, number, number];+ emissiveIntensity?: number;+}++export interface Instances3DOptions extends Surface3DOptions {+ id?: string;+ /** One mesh node/primitive, or an array of mesh variants distributed across instances. */+ mesh: AnimatableNode<Model3DNode> | Array<AnimatableNode<Model3DNode>>;+ /** Count of instances when driven by `instanceAt` or `bodies`. */+ count?: number;+ /** Bind directly to Physics.world3d rigid bodies. */+ bodies?: readonly PhysicsBody3D[];+ /** Per-frame callback `(index, frame, fps) => InstanceTransform3D`. */+ instanceAt?: (+ index: number,+ frame: number,+ fps: number,+ ) => InstanceTransform3D | undefined;+ /** Pre-computed array of instance transforms. */+ transforms?: InstanceTransform3D[];+ /** Optional speed/impact-to-emissive mapping when bound to `bodies`. */+ emissiveBySpeed?: {+ color: string | string[];+ maxSpeed: number;+ intensity?: number;+ };+ emissiveByImpact?: { color: string; intensity?: number };+ x?: number;+ y?: number;+ z?: number;+ rotateX?: number;+ rotateY?: number;+ rotateZ?: number;+ scale?: number;+ color?: string;+ colorTint?: string;+ opacity?: number;+ twoSided?: boolean;+ wireframe?: boolean;+ material?: MaterialType;+ roughness?: number;+ metallic?: number;+ specularIntensity?: number;+ ambientIntensity?: number;+ startFrame?: number;+ durationFrames?: number;+}/** Mesh shading the geometry can bake in; layer materials (glass, …) apply on the node. */function meshShading(@@ -953,6 +1014,79 @@ export const Layer3D = {);},+ /**+ * A procedural faceted convex polyhedron / rock shard: carved from half-space planes.+ * Convex hull collider in Physics.world3d is derived automatically.+ */+ shard(options: Shard3DOptions = {}): AnimatableNode<Model3DNode> {+ return primitiveNode(+ "shard",+ {+ type: "shard",+ radius: options.radius,+ size: options.size,+ facets: options.facets,+ seed: options.seed,+ irregularity: options.irregularity,+ },+ options,+ );+ },++ /**+ * Single-draw-call hardware-instanced 3D mesh batch node.+ * Renders hundreds or thousands of 3D meshes in 1 draw call per mesh variant,+ * driven by Physics.world3d rigid bodies, procedural callbacks, or transform arrays.+ */+ instances(options: Instances3DOptions): AnimatableNode<Model3DNode> {+ const primaryMesh = Array.isArray(options.mesh)+ ? options.mesh[0]+ : options.mesh;+ const node: Model3DNode = {+ id: options.id ?? autoId("instances3d"),+ kind: "model3d",+ x: options.x ?? 0,+ y: options.y ?? 0,+ z: options.z ?? 0,+ rotateX: options.rotateX ?? 0,+ rotateY: options.rotateY ?? 0,+ rotateZ: options.rotateZ ?? 0,+ scale: options.scale ?? 1,+ color: options.color,+ colorTint: options.colorTint,+ opacity: options.opacity ?? 1,+ twoSided: options.twoSided ?? true,+ wireframe: options.wireframe ?? false,+ material: options.material ?? "lit",+ roughness: options.roughness,+ metallic: options.metallic,+ specularIntensity: options.specularIntensity,+ ambientIntensity: options.ambientIntensity,+ startFrame: options.startFrame,+ durationFrames: options.durationFrames,+ instances3d: { ...options },+ ...materialProps(options),+ };+ if (primaryMesh) {+ const m = primaryMesh as unknown as Record<string, unknown>;+ if (m.modelData) node.modelData = m.modelData;+ if (m.primitive3d) node.primitive3d = m.primitive3d;+ if (m.src) node.src = m.src as string;+ }+ return Layer.model(+ node as unknown as Partial<Model3DNode>,+ ) as unknown as AnimatableNode<Model3DNode>;+ },++ /**+ * GPU-simulated 3D particle swarm and shard system.+ * Simulates thousands of 3D mesh particles natively inside WebGPU with 3D curl noise,+ * attractors, vortex fields, floor collisions, and speed/friction-driven HDR bloom emission.+ */+ swarm(options: Swarm3DOptions = {}): AnimatableNode<Model3DNode> {+ return createSwarm3D(options);+ },+/*** Creates a 3D model node rendered natively with WebGPU mesh shaders.*/diff --git a/packages/framefields/src/swarm-3d-render.test.ts b/packages/framefields/src/swarm-3d-render.test.tsnew file mode 100644index 00000000..862de954--- /dev/null+++ b/packages/framefields/src/swarm-3d-render.test.ts@@ -0,0 +1,155 @@+import { Canvas, loadImage } from "skia-canvas";+import { describe, expect, it } from "vitest";+import { Composition, Layer, Layer3D } from "./index.js";++async function decode(png: Buffer) {+ const img = await loadImage(png);+ const canvas = new Canvas(img.width, img.height);+ const ctx = canvas.getContext("2d");+ ctx.drawImage(img, 0, 0);+ const { data } = ctx.getImageData(0, 0, img.width, img.height);+ return {+ at(x: number, y: number) {+ const i = (Math.round(y) * img.width + Math.round(x)) * 4;+ return {+ r: data[i] ?? 0,+ g: data[i + 1] ?? 0,+ b: data[i + 2] ?? 0,+ };+ },+ data,+ };+}++describe("Layer3D.swarm GPU compute simulation", () => {+ it("simulates 3D shard swarm with vortex, floor friction and kinetic HDR heat", async () => {+ const comp = new Composition({+ width: 600,+ height: 600,+ fps: 30,+ durationMs: 1500,+ backgroundColor: "#050408",+ });++ comp.add([+ Layer.camera({+ x: 300,+ y: 200,+ z: -600,+ targetX: 300,+ targetY: 350,+ targetZ: 0,+ }),+ Layer.environment({+ color: "#0a0810",+ bloom: { intensity: 1.5, threshold: 0.8 },+ }),+ Layer.ambientLight("#332244", 0.5),+ Layer.directionalLight({+ color: "#ffffff",+ intensity: 1.2,+ x: 100,+ y: 50,+ z: -400,+ targetX: 300,+ targetY: 350,+ targetZ: 0,+ }),+ ]);++ comp.add(+ Layer3D.swarm({+ max: 800,+ mesh: "shard",+ seed: 1234,+ substeps: 2,+ size: [20, 14],+ emitter: {+ shape: "ring",+ x: 300,+ y: 200,+ z: 0,+ radius: 120,+ rate: 350,+ },+ speed: [150, 400],+ direction: [0, 1, 0],+ spread: 60,+ gravity: [0, 900, 0],+ drag: 0.04,+ noise: {+ strength: 350,+ scale: 180,+ speed: 1.5,+ },+ vortex: {+ x: 300,+ y: 350,+ z: 0,+ axis: [0, -1, 0],+ swirl: 1200,+ pull: 400,+ axial: 200,+ radius: 600,+ },+ floor: {+ y: 520,+ bounce: 0.25,+ friction: 2.0,+ heatGain: 1.5,+ heatDecay: 0.4,+ },+ color: ["#2a2035", "#3a1545"],+ roughness: 0.25,+ metallic: 0.85,+ heat: {+ source: "both",+ maxSpeed: 800,+ curve: 1.5,+ intensity: 6.0,+ color: ["#200530", "#ff007f", "#ffffff"],+ },+ }),+ );++ // Render frame 20 (particles swirling and hitting the floor)+ const png20 = await comp.renderFrame({ frame: 20 });+ const { data: d20 } = await decode(png20);++ let nonBlack20 = 0;+ let hasGlowingHotPixels = 0;+ for (let i = 0; i < d20.length; i += 4) {+ const r = d20[i] ?? 0;+ const g = d20[i + 1] ?? 0;+ const b = d20[i + 2] ?? 0;+ if (r > 20 || g > 20 || b > 20) {+ nonBlack20++;+ // High intensity hot emissive/bloom pixels+ if (r > 180 && b > 140) {+ hasGlowingHotPixels++;+ }+ }+ }++ expect(nonBlack20).toBeGreaterThan(1200);+ expect(hasGlowingHotPixels).toBeGreaterThan(50);++ // Deterministic scrubbing check: render frame 30, then scrub back to frame 20+ await comp.renderFrame({ frame: 30 });+ const png20Scrubbed = await comp.renderFrame({ frame: 20 });+ const { data: d20Scrubbed } = await decode(png20Scrubbed);++ let diffPixels = 0;+ for (let i = 0; i < d20.length; i += 4) {+ const dr = Math.abs((d20[i] ?? 0) - (d20Scrubbed[i] ?? 0));+ const dg = Math.abs((d20[i + 1] ?? 0) - (d20Scrubbed[i + 1] ?? 0));+ const db = Math.abs((d20[i + 2] ?? 0) - (d20Scrubbed[i + 2] ?? 0));+ if (dr > 1 || dg > 1 || db > 1) {+ diffPixels++;+ }+ }++ // Snapshot restore must be bit-identical or within floating point epsilon+ expect(diffPixels).toBeLessThan(10);+ });+});diff --git a/packages/framefields/src/swarm3d.ts b/packages/framefields/src/swarm3d.tsnew file mode 100644index 00000000..b602e27b--- /dev/null+++ b/packages/framefields/src/swarm3d.ts@@ -0,0 +1,221 @@+/**+ * @file packages/framefields/src/swarm3d.ts+ * GPU-Simulated 3D Particle Swarm & Faceted Shards (`Layer3D.swarm`).+ */++import type {+ MaterialType,+ Model3DNode,+} from "@framefields/compositions/program";+import { autoId } from "./ids.js";+import { type AnimatableNode, Layer } from "./index.js";+import type { PhysicsDriver } from "./physics/core.js";+import { Layer3D, type Surface3DOptions } from "./shapes3d.js";++export interface Swarm3DOptions extends Surface3DOptions {+ id?: string;+ startFrame?: number;+ durationFrames?: number;+ /** Maximum 3D mesh particles alive at once (default 2000, up to 100000). */+ max?: number;+ seed?: number;+ /**+ * Geometry drawn per particle:+ * - `"shard"` (default: 8 procedural shard variants)+ * - `{ type: "shard", variants?: number, facets?: number, irregularity?: number, bevel?: number }`+ * - `"sphere" | "roundedBox" | "cylinder"`+ * - `AnimatableNode<Model3DNode> | Array<AnimatableNode<Model3DNode>>`+ */+ mesh?:+ | "shard"+ | "sphere"+ | "roundedBox"+ | "cylinder"+ | {+ type: "shard";+ variants?: number;+ facets?: number;+ irregularity?: number;+ bevel?: number;+ }+ | AnimatableNode<Model3DNode>+ | Array<AnimatableNode<Model3DNode>>;+ /** Particle radius/scale in px at birth -> death (default [18, 12]). */+ size?: number | [number, number];+ sizeJitter?: number;+ fade?: [number, number];+ emitter?: {+ shape?: "point" | "box" | "sphere" | "shell" | "ring" | "disc";+ x?: PhysicsDriver;+ y?: PhysicsDriver;+ z?: PhysicsDriver;+ width?: number;+ height?: number;+ depth?: number;+ radius?: number;+ rate?: PhysicsDriver;+ bursts?: Array<{ frame: number; count: number }>;+ };+ lifetime?: number | [number, number];+ speed?: number | [number, number];+ direction?: [number, number, number];+ spread?: number;+ angularSpeed?: number | [number, number];+ angularDrag?: PhysicsDriver;+ gravity?: PhysicsDriver | [PhysicsDriver, PhysicsDriver, PhysicsDriver];+ drag?: PhysicsDriver;+ noise?: {+ strength?: PhysicsDriver;+ scale?: number;+ speed?: number;+ };+ attractors?: Array<{+ x: PhysicsDriver;+ y: PhysicsDriver;+ z: PhysicsDriver;+ strength: PhysicsDriver;+ radius?: number;+ }>;+ vortex?: {+ x?: PhysicsDriver;+ y?: PhysicsDriver;+ z?: PhysicsDriver;+ axis?: [number, number, number];+ /** Tangential swirl acceleration (px/s²). */+ swirl?: PhysicsDriver;+ /** Radial pull toward the vortex center/axis (px/s²). */+ pull?: PhysicsDriver;+ /** Axial acceleration along `axis` (px/s²). */+ axial?: PhysicsDriver;+ radius?: number;+ };+ floor?: {+ y: number;+ bounce?: number;+ /** Sliding friction damping (0 = ice, 3 = rough stone). Default 1.5. */+ friction?: PhysicsDriver;+ /** How strongly floor scraping & sharp acceleration build up `heat`. Default 1.0. */+ heatGain?: number;+ /** Seconds for friction/acceleration heat to cool down. Default 0.45. */+ heatDecay?: number;+ };+ /** Base surface color (default "#232026"). */+ color?: string | string[];+ roughness?: number;+ metallic?: number;+ material?: MaterialType;+ shininess?: number;+ specularIntensity?: number;+ ambientIntensity?: number;+ /** Dynamic HDR emission driven by particle speed and/or friction heat. */+ heat?: {+ /** Source driver: `"friction"` | `"speed"` | `"both"` (default `"both"`). */+ source?: "friction" | "speed" | "both";+ /** Speed (px/s) that reaches full heat=1 when source includes speed (default 900). */+ maxSpeed?: number;+ /** Emissive color ramp from cool (0) to hot (1). */+ color: string | string[];+ /** Peak HDR emissiveIntensity at heat = 1 (feeds bloom when > 2.5). Default 5.0. */+ intensity?: PhysicsDriver;+ /** Power curve shaping the heat ramp (default 1.6). */+ curve?: number;+ };+ /** Optional secondary fine sparks spawned from hot/scraping shards in 3D. */+ sparks?: {+ max?: number;+ rate?: number;+ threshold?: number;+ size?: number | [number, number];+ lifetime?: number | [number, number];+ speed?: number | [number, number];+ stretch?: number;+ color?: string | string[];+ intensity?: number;+ };+ substeps?: number;+ prewarm?: number;+}++export function createSwarm3D(+ options: Swarm3DOptions,+): AnimatableNode<Model3DNode> {+ let meshVariants: Array<AnimatableNode<Model3DNode>>;++ if (Array.isArray(options.mesh)) {+ meshVariants = options.mesh;+ } else if (+ options.mesh &&+ typeof options.mesh === "object" &&+ "kind" in options.mesh+ ) {+ meshVariants = [options.mesh as AnimatableNode<Model3DNode>];+ } else if (+ options.mesh &&+ typeof options.mesh === "object" &&+ options.mesh.type === "shard"+ ) {+ const numVariants = Math.max(1, options.mesh.variants ?? 8);+ meshVariants = [];+ for (let i = 0; i < numVariants; i++) {+ meshVariants.push(+ Layer3D.shard({+ radius: 20,+ facets: options.mesh.facets ?? 12 + (i % 6),+ seed: (options.seed ?? 1) * 31 + i * 17,+ irregularity: options.mesh.irregularity ?? 0.35,+ }),+ );+ }+ } else if (options.mesh === "sphere") {+ meshVariants = [Layer3D.sphere({ radius: 20 })];+ } else if (options.mesh === "roundedBox") {+ meshVariants = [Layer3D.roundedBox({ size: [30, 30, 30] })];+ } else if (options.mesh === "cylinder") {+ meshVariants = [Layer3D.cylinder({ radius: 15, height: 35 })];+ } else {+ // Default: 8 procedural shard variants+ const numVariants = 8;+ meshVariants = [];+ for (let i = 0; i < numVariants; i++) {+ meshVariants.push(+ Layer3D.shard({+ radius: 20,+ facets: 10 + (i % 8) * 2,+ seed: (options.seed ?? 42) + i * 13,+ irregularity: 0.35 + (i % 3) * 0.1,+ }),+ );+ }+ }++ const node: Model3DNode = {+ id: options.id ?? autoId("swarm3d"),+ kind: "model3d",+ x: 0,+ y: 0,+ z: 0,+ opacity: 1,+ twoSided: true,+ material: options.material ?? "lit",+ roughness: options.roughness ?? 0.35,+ metallic: options.metallic ?? 0.7,+ specularIntensity: options.specularIntensity ?? 0.5,+ ambientIntensity: options.ambientIntensity ?? 1.0,+ startFrame: options.startFrame,+ durationFrames: options.durationFrames,+ swarm3d: {+ ...options,+ meshVariants,+ },+ };++ const primary = meshVariants[0] as unknown as Record<string, unknown>;+ if (primary) {+ if (primary.modelData) node.modelData = primary.modelData;+ if (primary.primitive3d) node.primitive3d = primary.primitive3d;+ }++ return Layer.model(+ node as unknown as Partial<Model3DNode>,+ ) as unknown as AnimatableNode<Model3DNode>;+}diff --git a/packages/webgpu-renderers/src/math3d/environment3d.ts b/packages/webgpu-renderers/src/math3d/environment3d.tsindex 60d6f346..b37ab8d5 100644--- a/packages/webgpu-renderers/src/math3d/environment3d.ts+++ b/packages/webgpu-renderers/src/math3d/environment3d.ts@@ -31,6 +31,21 @@ export interface Environment3DFog {opacity?: number;}+export interface Environment3DFloor {+ /** World Y coordinate of the floor plane (px, y down). */+ y: number;+ /** Base floor surface color (default "#08070a"). */+ color?: string;+ /** Mirror reflectivity at normal incidence / Fresnel scale, 0..1 (default 0.35). */+ reflectivity?: number;+ /** Surface roughness 0..1: controls anisotropic vertical/horizontal reflection blur (default 0.35). */+ roughness?: number;+ /** Reflection fade-out distance from the floor plane in world Y px (default 900). */+ fadeDistance?: number;+ /** Optional overall opacity of the floor plane, 0..1 (default 1; 0 draws only the additive reflection over background). */+ opacity?: number;+}+export interface Environment3DOptions {preset?: EnvironmentPreset;/** Overrides the preset's sky (above), horizon and ground colors. */@@ -48,6 +63,7 @@ export interface Environment3DOptions {/** Default "neutral". */toneMapping?: ToneMapping;fog?: Environment3DFog;+ floor?: Environment3DFloor;}interface PresetDef {@@ -102,7 +118,7 @@ const TONE_MAPPING_CODE: Record<ToneMapping, number> = {neutral: 3,};-function linearRgb(color: string): [number, number, number] {+export function linearRgb(color: string): [number, number, number] {const c = parseCssColor(color) ?? [0, 0, 0, 1];const lin = (v: number) =>v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;@@ -123,6 +139,14 @@ export interface ResolvedEnvironment {end: number;opacity: number;};+ floor?: {+ y: number;+ color: [number, number, number];+ reflectivity: number;+ roughness: number;+ fadeDistance: number;+ opacity: number;+ };}/** Linear radiance and shader codes for an environment. */@@ -152,6 +176,19 @@ export function resolveEnvironment(opacity: Math.max(0, Math.min(1, opts.fog.opacity ?? 1)),}: undefined,+ floor: opts.floor+ ? {+ y: opts.floor.y,+ color: linearRgb(opts.floor.color ?? "#08070a"),+ reflectivity: Math.max(+ 0,+ Math.min(1, opts.floor.reflectivity ?? 0.35),+ ),+ roughness: Math.max(0, Math.min(1, opts.floor.roughness ?? 0.35)),+ fadeDistance: Math.max(0, opts.floor.fadeDistance ?? 900),+ opacity: Math.max(0, Math.min(1, opts.floor.opacity ?? 1.0)),+ }+ : undefined,};}diff --git a/packages/webgpu-renderers/src/math3d/light3d.ts b/packages/webgpu-renderers/src/math3d/light3d.tsindex 8833051c..afcc2dcb 100644--- a/packages/webgpu-renderers/src/math3d/light3d.ts+++ b/packages/webgpu-renderers/src/math3d/light3d.ts@@ -61,9 +61,9 @@ export interface GPULightData {export const MAX_LIGHTS = 8;/*** 16 (ambient) + 16 (params) + 8 * 64 (lights), then the physical-shading- * block appended after them: 8 vec4 (128) + shadow matrix (64).+ * block appended after them: 8 vec4 (128) + shadow matrix (64) + floorParams (16).*/-export const LIGHT_UNIFORM_SIZE_BYTES = 544 + 128 + 64;+export const LIGHT_UNIFORM_SIZE_BYTES = 544 + 128 + 64 + 32;export interface LightsUniformData {ambientColor: [number, number, number, number];@@ -251,9 +251,16 @@ export const Light3D = {lights: Light3DOptions[],environment?: Environment3DOptions | null,shadow?: ShadowUniformInfo | null,+ isReflectionPass = false,): Float32Array {const buffer = new Float32Array(LIGHT_UNIFORM_SIZE_BYTES / 4);- Light3D.packPhysicalBlock(buffer, lights ?? [], environment, shadow);+ Light3D.packPhysicalBlock(+ buffer,+ lights ?? [],+ environment,+ shadow,+ isReflectionPass,+ );if ((!lights || lights.length === 0) && !environment) {// No lights: params.y = 0.0 indicates unlit mode@@ -352,6 +359,7 @@ export const Light3D = {lights: Light3DOptions[],environment?: Environment3DOptions | null,shadow?: ShadowUniformInfo | null,+ isReflectionPass = false,): void {const base = 8 + MAX_LIGHTS * 16; // first float after the lights arraylet ambR = 0;@@ -398,5 +406,17 @@ export const Light3D = {for (let i = 0; i < 16; i++)buffer[base + 32 + i] = shadow.matrix[i] ?? 0;}++ if (environment?.floor) {+ buffer[base + 48] = environment.floor.y;+ buffer[base + 49] = environment.floor.fadeDistance ?? 900;+ buffer[base + 50] = isReflectionPass ? 1.0 : 0.0;+ buffer[base + 51] = 0.0;+ } else {+ buffer[base + 48] = 0.0;+ buffer[base + 49] = 0.0;+ buffer[base + 50] = 0.0;+ buffer[base + 51] = 0.0;+ }},};diff --git a/packages/webgpu-renderers/src/renderer3d/floor-reflection-pipeline.ts b/packages/webgpu-renderers/src/renderer3d/floor-reflection-pipeline.tsnew file mode 100644index 00000000..3fd3a5a3--- /dev/null+++ b/packages/webgpu-renderers/src/renderer3d/floor-reflection-pipeline.ts@@ -0,0 +1,526 @@+/**+ * Glossy reflective floor plane and anisotropic roughness blur pipeline.+ *+ * Implements planar reflection on a horizontal floor plane (y = floor.y):+ * 1. Anisotropic separable 2-pass roughness blur where vertical radius is+ * stretched 3.5x relative to horizontal radius (sigma_y ≈ 3.5 * sigma_x * roughness).+ * 2. Floor plane drawing via analytical ray-plane intersection and frag_depth write+ * with Schlick Fresnel grazing angle boost, base floor color, GGX image-based+ * lighting, and output to color, linear depth, and HDR bloom targets.+ */++import { type Environment3DFloor, linearRgb } from "../math3d/environment3d.js";+import { BufferPool } from "../renderer2d/buffer-pool.js";+import { lighting3dWgsl, lightsBindingsWgsl } from "../shaders/lighting3d.js";+import {+ BloomPipelineVariants,+ createBasePipelines,+ type PipelineVariantBase,+} from "./pipeline-variants.js";++const blurWgsl = /* wgsl */ `+struct BlurUniforms {+ texelStep : vec2<f32>,+ radius : f32,+ _pad : f32,+};++@group(0) @binding(0) var<uniform> u : BlurUniforms;+@group(0) @binding(1) var samp : sampler;+@group(0) @binding(2) var src : texture_2d<f32>;++struct VsOut {+ @builtin(position) pos : vec4<f32>,+ @location(0) uv : vec2<f32>,+};++@vertex+fn vs(@builtin(vertex_index) i : u32) -> VsOut {+ let p = vec2<f32>(f32((i << 1u) & 2u), f32(i & 2u));+ var o : VsOut;+ o.pos = vec4<f32>(p * 2.0 - 1.0, 0.0, 1.0);+ o.uv = vec2<f32>(p.x, 1.0 - p.y);+ return o;+}++@fragment+fn fs(in : VsOut) -> @location(0) vec4<f32> {+ if (u.radius <= 0.01) {+ return textureSampleLevel(src, samp, in.uv, 0.0);+ }+ var col = vec4<f32>(0.0);+ var totalW = 0.0;+ let sigma = max(0.5, u.radius * 0.45);+ let inv2Sigma2 = 0.5 / (sigma * sigma);+ for (var k = -8; k <= 8; k = k + 1) {+ let fk = f32(k);+ let offsetFrac = fk * 0.125 * u.radius;+ let w = exp(-(offsetFrac * offsetFrac) * inv2Sigma2);+ let sampleUV = clamp(in.uv + u.texelStep * offsetFrac, vec2<f32>(0.001), vec2<f32>(0.999));+ col += textureSampleLevel(src, samp, sampleUV, 0.0) * w;+ totalW += w;+ }+ return col / max(totalW, 0.0001);+}+`;++const floorWgsl = /* wgsl */ `+${lighting3dWgsl}++struct FloorUniforms {+ params0 : vec4<f32>, // x = floorY, y = reflectivity, z = roughness, w = fadeDistance+ params1 : vec4<f32>, // x = opacity, y = unused, z = unused, w = unused+ baseColor : vec4<f32>, // rgb = base linear color, a = 1.0+};++@group(0) @binding(0) var<uniform> cam : CameraUniforms;+@group(1) @binding(0) var<uniform> floorU : FloorUniforms;+@group(2) @binding(0) var reflectionTexture : texture_2d<f32>;+@group(2) @binding(1) var reflectionSampler : sampler;+${lightsBindingsWgsl}++struct VsOut {+ @builtin(position) pos : vec4<f32>,+ @location(0) uv : vec2<f32>,+};++@vertex+fn vs_floor(@builtin(vertex_index) vid : u32) -> VsOut {+ let p = vec2<f32>(f32((vid << 1u) & 2u), f32(vid & 2u));+ var o : VsOut;+ o.pos = vec4<f32>(p * 2.0 - 1.0, 0.0, 1.0);+ o.uv = vec2<f32>(p.x, 1.0 - p.y);+ return o;+}++struct FloorShaded {+ display : vec3<f32>,+ hdr : vec3<f32>,+ depth : f32,+ linearDepth : f32,+ alpha : f32,+};++fn shadeFloor(in: VsOut) -> FloorShaded {+ var out: FloorShaded;++ let ndcX = in.uv.x * 2.0 - 1.0;+ let ndcY = 1.0 - 2.0 * in.uv.y;++ let pNear = cam.invViewProjMatrix * vec4<f32>(ndcX, ndcY, 0.0, 1.0);+ let pFar = cam.invViewProjMatrix * vec4<f32>(ndcX, ndcY, 1.0, 1.0);++ let p0 = pNear.xyz / pNear.w;+ let p1 = pFar.xyz / pFar.w;++ let D = normalize(p1 - p0);+ let O = p0;++ let floorY = floorU.params0.x;+ let diffY = floorY - O.y;+ if (diffY * D.y <= 0.0001) {+ discard;+ }++ let t = diffY / D.y;+ let worldP = O + t * D;++ let clip = cam.viewProjMatrix * vec4<f32>(worldP, 1.0);+ let depth = clip.z / clip.w;+ if (depth < 0.0 || depth > 1.0) {+ discard;+ }++ out.depth = depth;+ out.linearDepth = dot(worldP - cam.cameraPos.xyz, cam.cameraDir.xyz);++ let N = vec3<f32>(0.0, -1.0, 0.0);+ let toCam = cam.cameraPos.xyz - worldP;+ let dist = length(toCam);+ let V = toCam / max(dist, 0.0001);+ let NdotV = max(0.0, dot(N, V));++ let F0 = floorU.params0.y;+ let fresnel = F0 + (1.0 - F0) * pow(1.0 - NdotV, 5.0);++ let fadeDist = max(floorU.params0.w, 1.0);+ let distFade = clamp(1.0 - dist / (fadeDist * 2.2), 0.0, 1.0);+ let horizonFade = smoothstep(0.015, 0.14, NdotV);+ let smoothFade = distFade * distFade * (3.0 - 2.0 * distFade) * horizonFade;++ let reflUV = vec2<f32>(in.uv.x, 1.0 - in.uv.y);+ let reflSample = textureSample(reflectionTexture, reflectionSampler, reflUV);+ let reflRgb = reflSample.rgb;++ let baseColor = floorU.baseColor.rgb;+ let opacity = floorU.params1.x;++ let baseSrgb = linearToSrgb(baseColor);+ let reflWeight = fresnel * floorU.params0.y * smoothFade;+ let reflSrgb = reflRgb * reflWeight;++ var displaySrgb = select(+ clamp(baseSrgb + reflSrgb, vec3<f32>(0.0), vec3<f32>(1.0)),+ reflSrgb,+ opacity <= 0.001,+ );++ let reflLin = pow(max(reflRgb, vec3<f32>(0.0)), vec3<f32>(2.2));+ let reflLum = max(reflLin.r, max(reflLin.g, reflLin.b));+ var hdr = reflLin * max(0.0, reflLum - 0.25) * 3.0 * reflWeight;++ if (lights.fog.w > 0.5) {+ let f = smoothstep(lights.fogRange.x, max(lights.fogRange.y, lights.fogRange.x + 1.0), dist) * lights.fogRange.z;+ displaySrgb = mix(displaySrgb, linearToSrgb(lights.fog.rgb), f);+ hdr = hdr * (1.0 - f);+ }++ let a = select(opacity * smoothFade, clamp(reflSample.a * reflWeight, 0.0, 1.0), opacity <= 0.001);+ out.display = displaySrgb;+ out.hdr = hdr;+ out.alpha = a;+ return out;+}++struct FsOutputSingle {+ @location(0) color : vec4<f32>,+ @builtin(frag_depth) depth : f32,+};++struct FsOutputMrt {+ @location(0) color : vec4<f32>,+ @location(1) linearDepth : vec4<f32>,+ @builtin(frag_depth) depth : f32,+};++struct FsOutputSingleBloom {+ @location(0) color : vec4<f32>,+ @location(1) hdr : vec4<f32>,+ @builtin(frag_depth) depth : f32,+};++struct FsOutputMrtBloom {+ @location(0) color : vec4<f32>,+ @location(1) linearDepth : vec4<f32>,+ @location(2) hdr : vec4<f32>,+ @builtin(frag_depth) depth : f32,+};++@fragment+fn fs_single(in: VsOut) -> FsOutputSingle {+ var out: FsOutputSingle;+ let s = shadeFloor(in);+ out.color = vec4<f32>(s.display * s.alpha, s.alpha);+ out.depth = s.depth;+ return out;+}++@fragment+fn fs_mrt(in: VsOut) -> FsOutputMrt {+ var out: FsOutputMrt;+ let s = shadeFloor(in);+ out.color = vec4<f32>(s.display * s.alpha, s.alpha);+ out.linearDepth = vec4<f32>(s.linearDepth, 0.0, 0.0, 1.0);+ out.depth = s.depth;+ return out;+}++@fragment+fn fs_single_bloom(in: VsOut) -> FsOutputSingleBloom {+ var out: FsOutputSingleBloom;+ let s = shadeFloor(in);+ out.color = vec4<f32>(s.display * s.alpha, s.alpha);+ out.hdr = vec4<f32>(s.hdr * s.alpha, 1.0);+ out.depth = s.depth;+ return out;+}++@fragment+fn fs_mrt_bloom(in: VsOut) -> FsOutputMrtBloom {+ var out: FsOutputMrtBloom;+ let s = shadeFloor(in);+ out.color = vec4<f32>(s.display * s.alpha, s.alpha);+ out.linearDepth = vec4<f32>(s.linearDepth, 0.0, 0.0, 1.0);+ out.hdr = vec4<f32>(s.hdr * s.alpha, 1.0);+ out.depth = s.depth;+ return out;+}+`;++export class FloorReflectionPipeline {+ private blurPipeline: GPURenderPipeline;+ private blurBindGroupLayout: GPUBindGroupLayout;+ private blurSampler: GPUSampler;+ private blurPool: BufferPool;++ private floorLayout: GPUBindGroupLayout;+ private reflectionLayout: GPUBindGroupLayout;+ private floorSampler: GPUSampler;+ private floorPool: BufferPool;++ private pipelineSingle: GPURenderPipeline;+ private pipelineMrt: GPURenderPipeline;+ private bloomVariants: BloomPipelineVariants;++ constructor(+ private device: GPUDevice,+ format: GPUTextureFormat,+ sampleCount: number,+ cameraLayout: GPUBindGroupLayout,+ lightsLayout: GPUBindGroupLayout,+ depthFormat: GPUTextureFormat = "depth24plus",+ ) {+ const blurModule = device.createShaderModule({+ label: "FloorBlurShader",+ code: blurWgsl,+ });+ this.blurBindGroupLayout = device.createBindGroupLayout({+ label: "FloorBlurBindGroupLayout",+ entries: [+ {+ binding: 0,+ visibility: GPUShaderStage.FRAGMENT,+ buffer: { type: "uniform" },+ },+ {+ binding: 1,+ visibility: GPUShaderStage.FRAGMENT,+ sampler: { type: "filtering" },+ },+ {+ binding: 2,+ visibility: GPUShaderStage.FRAGMENT,+ texture: { sampleType: "float" },+ },+ ],+ });+ this.blurPipeline = device.createRenderPipeline({+ label: "FloorBlurPipeline",+ layout: device.createPipelineLayout({+ bindGroupLayouts: [this.blurBindGroupLayout],+ }),+ vertex: { module: blurModule, entryPoint: "vs" },+ fragment: {+ module: blurModule,+ entryPoint: "fs",+ targets: [{ format }],+ },+ primitive: { topology: "triangle-list" },+ });+ this.blurSampler = device.createSampler({+ label: "FloorBlurSampler",+ magFilter: "linear",+ minFilter: "linear",+ addressModeU: "clamp-to-edge",+ addressModeV: "clamp-to-edge",+ });+ this.blurPool = new BufferPool(+ 16,+ GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,+ );++ this.floorLayout = device.createBindGroupLayout({+ label: "FloorUniformLayout",+ entries: [+ {+ binding: 0,+ visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,+ buffer: { type: "uniform" },+ },+ ],+ });+ this.reflectionLayout = device.createBindGroupLayout({+ label: "FloorReflectionLayout",+ entries: [+ {+ binding: 0,+ visibility: GPUShaderStage.FRAGMENT,+ texture: { sampleType: "float" },+ },+ {+ binding: 1,+ visibility: GPUShaderStage.FRAGMENT,+ sampler: { type: "filtering" },+ },+ ],+ });+ this.floorSampler = device.createSampler({+ label: "FloorReflectionSampler",+ magFilter: "linear",+ minFilter: "linear",+ addressModeU: "clamp-to-edge",+ addressModeV: "clamp-to-edge",+ });+ this.floorPool = new BufferPool(+ 64,+ GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,+ );++ const floorModule = device.createShaderModule({+ label: "FloorPlaneShader",+ code: floorWgsl,+ });+ const pipelineLayout = device.createPipelineLayout({+ label: "FloorPlanePipelineLayout",+ bindGroupLayouts: [+ cameraLayout,+ this.floorLayout,+ this.reflectionLayout,+ lightsLayout,+ ],+ });++ const base: PipelineVariantBase = {+ label: "FloorPlanePipeline",+ layout: pipelineLayout,+ vertex: {+ module: floorModule,+ entryPoint: "vs_floor",+ },+ module: floorModule,+ format,+ depthStencil: {+ format: depthFormat,+ depthWriteEnabled: true,+ depthCompare: "less-equal",+ },+ primitive: { topology: "triangle-list", cullMode: "none" },+ multisample: { count: sampleCount },+ };++ const { single, mrt } = createBasePipelines(device, base);+ this.pipelineSingle = single;+ this.pipelineMrt = mrt;+ this.bloomVariants = new BloomPipelineVariants(device, base);+ }++ applyBlur(+ encoder: GPUCommandEncoder,+ src: GPUTexture,+ temp: GPUTexture,+ dst: GPUTexture,+ width: number,+ height: number,+ roughness: number,+ ): void {+ const sigmaX = roughness * 24.0;+ const sigmaY = roughness * 130.0;++ // Pass 1: Horizontal blur (src -> temp)+ {+ const uData = new Float32Array([1.0 / width, 0.0, sigmaX, 0.0]);+ const uBuf = this.blurPool.getBuffer(this.device, uData);+ const bg = this.device.createBindGroup({+ layout: this.blurBindGroupLayout,+ entries: [+ { binding: 0, resource: { buffer: uBuf } },+ { binding: 1, resource: this.blurSampler },+ { binding: 2, resource: src.createView() },+ ],+ });+ const pass = encoder.beginRenderPass({+ colorAttachments: [+ {+ view: temp.createView(),+ loadOp: "clear",+ storeOp: "store",+ clearValue: { r: 0, g: 0, b: 0, a: 0 },+ },+ ],+ });+ pass.setPipeline(this.blurPipeline);+ pass.setBindGroup(0, bg);+ pass.draw(3);+ pass.end();+ }++ // Pass 2: Vertical blur (temp -> dst)+ {+ const uData = new Float32Array([0.0, 1.0 / height, sigmaY, 0.0]);+ const uBuf = this.blurPool.getBuffer(this.device, uData);+ const bg = this.device.createBindGroup({+ layout: this.blurBindGroupLayout,+ entries: [+ { binding: 0, resource: { buffer: uBuf } },+ { binding: 1, resource: this.blurSampler },+ { binding: 2, resource: temp.createView() },+ ],+ });+ const pass = encoder.beginRenderPass({+ colorAttachments: [+ {+ view: dst.createView(),+ loadOp: "clear",+ storeOp: "store",+ clearValue: { r: 0, g: 0, b: 0, a: 0 },+ },+ ],+ });+ pass.setPipeline(this.blurPipeline);+ pass.setBindGroup(0, bg);+ pass.draw(3);+ pass.end();+ }+ }++ draw(+ pass: GPURenderPassEncoder,+ cameraBindGroup: GPUBindGroup,+ lightsBindGroup: GPUBindGroup,+ reflectionTexture: GPUTexture,+ floor: Environment3DFloor,+ useMrt = false,+ useBloom = false,+ ): void {+ const linColor = linearRgb(floor.color ?? "#08070a");+ const floorData = new Float32Array([+ floor.y,+ floor.reflectivity ?? 0.35,+ floor.roughness ?? 0.35,+ floor.fadeDistance ?? 900,+ floor.opacity ?? 1.0,+ 0.0,+ 0.0,+ 0.0,+ linColor[0],+ linColor[1],+ linColor[2],+ 1.0,+ 0.0,+ 0.0,+ 0.0,+ 0.0,+ ]);+ const floorBuf = this.floorPool.getBuffer(this.device, floorData);+ const floorBindGroup = this.device.createBindGroup({+ layout: this.floorLayout,+ entries: [{ binding: 0, resource: { buffer: floorBuf } }],+ });++ const reflBindGroup = this.device.createBindGroup({+ layout: this.reflectionLayout,+ entries: [+ { binding: 0, resource: reflectionTexture.createView() },+ { binding: 1, resource: this.floorSampler },+ ],+ });++ pass.setPipeline(+ useBloom+ ? this.bloomVariants.get(useMrt)+ : useMrt+ ? this.pipelineMrt+ : this.pipelineSingle,+ );+ pass.setBindGroup(0, cameraBindGroup);+ pass.setBindGroup(1, floorBindGroup);+ pass.setBindGroup(2, reflBindGroup);+ pass.setBindGroup(3, lightsBindGroup);+ pass.draw(3);+ }++ destroy(): void {+ this.blurPool.destroy();+ this.floorPool.destroy();+ }+}diff --git a/packages/webgpu-renderers/src/renderer3d/index.ts b/packages/webgpu-renderers/src/renderer3d/index.tsindex d61f52cf..041d021c 100644--- a/packages/webgpu-renderers/src/renderer3d/index.ts+++ b/packages/webgpu-renderers/src/renderer3d/index.ts@@ -1,6 +1,8 @@export * from "./audio-mesh-deform-pipeline.js";export * from "./bloom-pipeline.js";+export * from "./floor-reflection-pipeline.js";export * from "./glass-pipeline.js";+export * from "./matte3d.js";export * from "./mesh3d-pipeline.js";export * from "./motion-blur-pipeline.js";export * from "./primitive-geometry.js";@@ -11,5 +13,5 @@ export * from "./shadow-frustum.js";export * from "./shadow-pipeline.js";export * from "./ssao-pipeline.js";export * from "./surface-params.js";+export * from "./swarm3d-pipeline.js";export * from "./text-extruder.js";-export * from "./matte3d.js";diff --git a/packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.ts b/packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.tsindex 2f9d57c2..8d3af72c 100644--- a/packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.ts+++ b/packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.ts@@ -51,6 +51,10 @@ export interface MeshUniformData extends SurfaceParams {transparent?: boolean;isSkinned?: boolean;skinningMatrices?: Float32Array; // 128 * 16 floats+ /** Hardware-instanced draw path. */+ isInstanced?: boolean;+ /** Storage buffer containing `array<InstanceData>` (64 bytes per instance). */+ instanceBuffer?: GPUBuffer;material?: "lit" | "unlit" | "toon";/** Screen-space track matte: the mesh shows where this texture's alpha does. */matte?: GPUTexture;@@ -116,6 +120,7 @@ export class Mesh3DPipeline {/** (0.5, 0.5, 1): an unperturbed tangent-space normal. */private flatNormalTexture: GPUTexture;private defaultSkinningBuffer: GPUBuffer;+ private defaultInstanceBuffer: GPUBuffer;/** White vertex colors for meshes without any, grown to the largest mesh. */private whiteColorBuffer: GPUBuffer | null = null;private whiteColorCapacity = 0;@@ -178,6 +183,11 @@ export class Mesh3DPipeline {},matteLayoutEntry(2),matteLayoutEntry(3),+ {+ binding: 4,+ visibility: GPUShaderStage.VERTEX,+ buffer: { type: "read-only-storage" },+ },],});@@ -345,6 +355,34 @@ export class Mesh3DPipeline {idMatrices,);this.defaultSkinningBuffer.unmap();++ // Default 1-element dummy instance buffer (posScale=[0,0,0,1], quat=[0,0,0,1], color=[1,1,1,1], emissive=[0,0,0,0])+ this.defaultInstanceBuffer = device.createBuffer({+ label: "Mesh3DDefaultInstanceBuffer",+ size: 64,+ usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,+ mappedAtCreation: true,+ });+ const defInst = new Float32Array(+ this.defaultInstanceBuffer.getMappedRange(),+ );+ defInst[0] = 0;+ defInst[1] = 0;+ defInst[2] = 0;+ defInst[3] = 1;+ defInst[4] = 0;+ defInst[5] = 0;+ defInst[6] = 0;+ defInst[7] = 1;+ defInst[8] = 1;+ defInst[9] = 1;+ defInst[10] = 1;+ defInst[11] = 1;+ defInst[12] = 0;+ defInst[13] = 0;+ defInst[14] = 0;+ defInst[15] = 0;+ this.defaultInstanceBuffer.unmap();}resetPools(): void {@@ -363,7 +401,7 @@ export class Mesh3DPipeline {this.modelData[36] = data.opacity ?? 1.0;this.modelData[37] = data.twoSided ? 1.0 : 0.0;this.modelData[38] = data.isSkinned ? 1.0 : 0.0;- this.modelData[39] = 0;+ this.modelData[39] = data.isInstanced || data.instanceBuffer ? 1.0 : 0.0;const shininess =data.roughness !== undefined@@ -425,6 +463,12 @@ export class Mesh3DPipeline {(data.glass && data.backdrop?.createView()) ||fullCoverageView(this.device),},+ {+ binding: 4,+ resource: {+ buffer: data.instanceBuffer ?? this.defaultInstanceBuffer,+ },+ },],});}@@ -439,6 +483,8 @@ export class Mesh3DPipeline {data: MeshUniformData,useMrt = false,useBloom = false,+ instanceCount = 1,+ firstInstance = 0,): void {const modelBindGroup = this.packModel(data);const white = this.defaultWhiteTexture;@@ -493,9 +539,19 @@ export class Mesh3DPipeline {wireframe ? meshBuffers.wireIndexBuffer! : meshBuffers.indexBuffer,meshBuffers.indexFormat,);- pass.drawIndexed(- wireframe ? meshBuffers.wireIndexCount! : meshBuffers.indexCount,- );+ if (instanceCount > 1 || data.isInstanced) {+ pass.drawIndexed(+ wireframe ? meshBuffers.wireIndexCount! : meshBuffers.indexCount,+ instanceCount,+ 0,+ 0,+ firstInstance,+ );+ } else {+ pass.drawIndexed(+ wireframe ? meshBuffers.wireIndexCount! : meshBuffers.indexCount,+ );+ }}/** Draws the mesh into a shadow map (`lightCameraBindGroup` holds the light's view-projection). */@@ -504,6 +560,8 @@ export class Mesh3DPipeline {lightCameraBindGroup: GPUBindGroup,meshBuffers: GPUMeshBuffers,data: MeshUniformData,+ instanceCount = 1,+ firstInstance = 0,): void {const wireframe = data.wireframe === true;if (wireframe && !meshBuffers.wireIndexBuffer) {@@ -518,9 +576,19 @@ export class Mesh3DPipeline {wireframe ? meshBuffers.wireIndexBuffer! : meshBuffers.indexBuffer,meshBuffers.indexFormat,);- pass.drawIndexed(- wireframe ? meshBuffers.wireIndexCount! : meshBuffers.indexCount,- );+ if (instanceCount > 1 || data.isInstanced) {+ pass.drawIndexed(+ wireframe ? meshBuffers.wireIndexCount! : meshBuffers.indexCount,+ instanceCount,+ 0,+ 0,+ firstInstance,+ );+ } else {+ pass.drawIndexed(+ wireframe ? meshBuffers.wireIndexCount! : meshBuffers.indexCount,+ );+ }}private colorsFor(meshBuffers: GPUMeshBuffers): GPUBuffer {@@ -552,5 +620,6 @@ export class Mesh3DPipeline {this.defaultWhiteTexture.destroy();this.flatNormalTexture.destroy();this.defaultSkinningBuffer.destroy();+ this.defaultInstanceBuffer.destroy();}}diff --git a/packages/webgpu-renderers/src/renderer3d/primitive-geometry.test.ts b/packages/webgpu-renderers/src/renderer3d/primitive-geometry.test.tsindex e4f9cfb1..f0408ca0 100644--- a/packages/webgpu-renderers/src/renderer3d/primitive-geometry.test.ts+++ b/packages/webgpu-renderers/src/renderer3d/primitive-geometry.test.ts@@ -143,4 +143,40 @@ describe("3D primitive geometry", () => {expect(getPrimitiveGeometry({ ...opts })).toBe(a);expect(getPrimitiveGeometry({ ...opts, width: 66 })).not.toBe(a);});++ it("builds a convex shard wound outward on all facets", () => {+ const shard = generatePrimitiveGeometry({+ type: "shard",+ radius: 40,+ facets: 16,+ seed: 42,+ irregularity: 0.4,+ });+ expect(shard.bounds.center[0]).toBeCloseTo(0, 1);+ expect(shard.bounds.center[1]).toBeCloseTo(0, 1);+ expect(shard.bounds.center[2]).toBeCloseTo(0, 1);+ expect(shard.bounds.boundingSphereRadius).toBeGreaterThan(15);+ expect(shard.bounds.boundingSphereRadius).toBeLessThanOrEqual(+ Math.hypot(40, 40, 40) + 1,+ );+ expectOutwardSolid(shard);++ // Equal shard specs share cached geometry+ const cached = getPrimitiveGeometry({+ type: "shard",+ radius: 40,+ facets: 16,+ seed: 42,+ irregularity: 0.4,+ });+ expect(+ getPrimitiveGeometry({+ type: "shard",+ radius: 40,+ facets: 16,+ seed: 42,+ irregularity: 0.4,+ }),+ ).toBe(cached);+ });});diff --git a/packages/webgpu-renderers/src/renderer3d/primitive-geometry.ts b/packages/webgpu-renderers/src/renderer3d/primitive-geometry.tsindex 1dde6e3e..8d5a95ab 100644--- a/packages/webgpu-renderers/src/renderer3d/primitive-geometry.ts+++ b/packages/webgpu-renderers/src/renderer3d/primitive-geometry.ts@@ -52,10 +52,25 @@ export interface CylinderGeometryOptions extends PrimitiveSurface {openEnded?: boolean;}+export interface ShardGeometryOptions extends PrimitiveSurface {+ type: "shard";+ /** Approximate bounding radius (or half-extent if size is not set). Default 50. */+ radius?: number;+ /** Optional non-uniform half-extents [hx, hy, hz]; overrides radius per axis. */+ size?: [number, number, number];+ /** Number of clipping half-space planes carving the polyhedron (4..48). Default 14. */+ facets?: number;+ /** Deterministic PRNG seed for plane normals and depths. Default 1. */+ seed?: number;+ /** How unevenly planes cut toward the center, 0..0.85 (0 = regular polyhedron, 0.5 = jagged). Default 0.35. */+ irregularity?: number;+}+export type PrimitiveGeometryOptions =| RoundedBoxGeometryOptions| SphereGeometryOptions- | CylinderGeometryOptions;+ | CylinderGeometryOptions+ | ShardGeometryOptions;class MeshBuilder {positions: number[] = [];@@ -281,6 +296,274 @@ function cylinder(o: CylinderGeometryOptions, mb: MeshBuilder): void {}}+function shard(o: ShardGeometryOptions, mb: MeshBuilder): void {+ const r = o.radius ?? 50;+ const hx = (o.size ? o.size[0] : r) || 50;+ const hy = (o.size ? o.size[1] : r) || 50;+ const hz = (o.size ? o.size[2] : r) || 50;+ const maxR = Math.max(hx, hy, hz);+ const facets = Math.max(4, Math.min(64, Math.round(o.facets ?? 14)));+ const seed = Math.round(o.seed ?? 1) >>> 0;+ const irregularity = Math.max(0, Math.min(0.85, o.irregularity ?? 0.35));++ // Simple PCG random generator+ let state = BigInt(seed) * 6364136223846793005n + 1442695040888963407n;+ const rnd = (): number => {+ state = state * 6364136223846793005n + 1442695040888963407n;+ const xorshifted = Number(((state >> 18n) ^ state) >> 27n) >>> 0;+ const rot = Number(state >> 59n) >>> 0;+ const res = (xorshifted >>> rot) | (xorshifted << ((32 - rot) & 31));+ return (res >>> 0) / 4294967296;+ };++ type V3 = [number, number, number];+ type Polygon = V3[];++ const sub3 = (a: V3, b: V3): V3 => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];+ const dot3 = (a: V3, b: V3): number =>+ a[0] * b[0] + a[1] * b[1] + a[2] * b[2];+ const cross3 = (a: V3, b: V3): V3 => [+ a[1] * b[2] - a[2] * b[1],+ a[2] * b[0] - a[0] * b[2],+ a[0] * b[1] - a[1] * b[0],+ ];++ // Start with bounding box of size [2*hx, 2*hy, 2*hz] as 6 rectangular faces+ // Each face is an array of CCW vertices facing outward+ let faces: Polygon[] = [+ [+ [-hx, -hy, -hz],+ [hx, -hy, -hz],+ [hx, hy, -hz],+ [-hx, hy, -hz],+ ], // front (-z)+ [+ [hx, -hy, hz],+ [-hx, -hy, hz],+ [-hx, hy, hz],+ [hx, hy, hz],+ ], // back (+z)+ [+ [-hx, -hy, hz],+ [-hx, -hy, -hz],+ [-hx, hy, -hz],+ [-hx, hy, hz],+ ], // left (-x)+ [+ [hx, -hy, -hz],+ [hx, -hy, hz],+ [hx, hy, hz],+ [hx, hy, -hz],+ ], // right (+x)+ [+ [-hx, -hy, hz],+ [hx, -hy, hz],+ [hx, -hy, -hz],+ [-hx, -hy, -hz],+ ], // top (-y)+ [+ [-hx, hy, -hz],+ [hx, hy, -hz],+ [hx, hy, hz],+ [-hx, hy, hz],+ ], // bottom (+y)+ ];++ // Clip against `facets` random half-spaces: n · x <= d+ // Using Fibonacci sphere distribution + jitter+ const phi = (1 + Math.sqrt(5)) / 2;+ for (let i = 0; i < facets; i++) {+ const theta = (2 * Math.PI * i) / phi + (rnd() - 0.5) * 0.4;+ const zNorm = 1 - (2 * (i + 0.5)) / facets;+ const radiusAtZ = Math.sqrt(Math.max(0, 1 - zNorm * zNorm));+ let n: V3 = [+ Math.cos(theta) * radiusAtZ,+ Math.sin(theta) * radiusAtZ,+ zNorm,+ ];+ // Jitter normal slightly+ n[0] += (rnd() - 0.5) * 0.2;+ n[1] += (rnd() - 0.5) * 0.2;+ n[2] += (rnd() - 0.5) * 0.2;+ const len = Math.hypot(n[0], n[1], n[2]);+ if (len < 1e-6) continue;+ n = [n[0] / len, n[1] / len, n[2] / len];++ // Scale distance according to bounding box dimensions+ const supportR = Math.hypot(n[0] * hx, n[1] * hy, n[2] * hz);+ const d = supportR * (1 - irregularity * (0.2 + 0.8 * rnd()));++ // Sutherland-Hodgman 3D convex clipping+ const nextFaces: Polygon[] = [];+ const capVertices: V3[] = [];++ for (const face of faces) {+ const clipped: V3[] = [];+ const numV = face.length;+ for (let j = 0; j < numV; j++) {+ const p1 = face[j]!;+ const p2 = face[(j + 1) % numV]!;+ const dist1 = dot3(n, p1) - d;+ const dist2 = dot3(n, p2) - d;++ if (dist1 <= 1e-5) {+ clipped.push(p1);+ }+ if (+ (dist1 > 1e-5 && dist2 < -1e-5) ||+ (dist1 < -1e-5 && dist2 > 1e-5)+ ) {+ const t = dist1 / (dist1 - dist2);+ const intersection: V3 = [+ p1[0] + (p2[0] - p1[0]) * t,+ p1[1] + (p2[1] - p1[1]) * t,+ p1[2] + (p2[2] - p1[2]) * t,+ ];+ clipped.push(intersection);+ capVertices.push(intersection);+ }+ }+ if (clipped.length >= 3) {+ nextFaces.push(clipped);+ }+ }++ if (capVertices.length >= 3) {+ // Cluster / deduplicate vertices close to each other+ const uniqueCap: V3[] = [];+ for (const pt of capVertices) {+ let duplicate = false;+ for (const u of uniqueCap) {+ if (Math.hypot(pt[0] - u[0], pt[1] - u[1], pt[2] - u[2]) < 1e-3) {+ duplicate = true;+ break;+ }+ }+ if (!duplicate) uniqueCap.push(pt);+ }++ if (uniqueCap.length >= 3) {+ // Compute center of cap+ let cx = 0;+ let cy = 0;+ let cz = 0;+ for (const u of uniqueCap) {+ cx += u[0];+ cy += u[1];+ cz += u[2];+ }+ const c: V3 = [+ cx / uniqueCap.length,+ cy / uniqueCap.length,+ cz / uniqueCap.length,+ ];++ // Tangent vectors on cutting plane+ const up: V3 = Math.abs(n[1]) < 0.9 ? [0, 1, 0] : [1, 0, 0];+ const tangentX = normalize(cross3(up, n)) as V3;+ const tangentY = cross3(n, tangentX);++ // Sort vertices CCW with respect to outward normal n+ uniqueCap.sort((vA, vB) => {+ const aA = Math.atan2(+ dot3(sub3(vA, c), tangentY),+ dot3(sub3(vA, c), tangentX),+ );+ const aB = Math.atan2(+ dot3(sub3(vB, c), tangentY),+ dot3(sub3(vB, c), tangentX),+ );+ return aA - aB;+ });++ nextFaces.push(uniqueCap);+ }+ }++ if (nextFaces.length >= 4) {+ faces = nextFaces;+ }+ }++ // Compute bounding box center+ let minX = Number.POSITIVE_INFINITY;+ let minY = Number.POSITIVE_INFINITY;+ let minZ = Number.POSITIVE_INFINITY;+ let maxX = Number.NEGATIVE_INFINITY;+ let maxY = Number.NEGATIVE_INFINITY;+ let maxZ = Number.NEGATIVE_INFINITY;+ for (const face of faces) {+ for (const pt of face) {+ if (pt[0] < minX) minX = pt[0];+ if (pt[0] > maxX) maxX = pt[0];+ if (pt[1] < minY) minY = pt[1];+ if (pt[1] > maxY) maxY = pt[1];+ if (pt[2] < minZ) minZ = pt[2];+ if (pt[2] > maxZ) maxZ = pt[2];+ }+ }+ const center: V3 = [(minX + maxX) / 2, (minY + maxY) / 2, (minZ + maxZ) / 2];++ // Center faces on origin+ for (const face of faces) {+ for (let j = 0; j < face.length; j++) {+ const pt = face[j]!;+ face[j] = [pt[0] - center[0], pt[1] - center[1], pt[2] - center[2]];+ }+ }++ // Triangulate each face into MeshBuilder with flat-shaded face normals+ for (const face of faces) {+ if (face.length < 3) continue;++ // Compute true face normal+ let fn: V3 = [0, 0, 0];+ for (let j = 0; j < face.length; j++) {+ const curr = face[j]!;+ const next = face[(j + 1) % face.length]!;+ fn[0] += (curr[1] - next[1]) * (curr[2] + next[2]);+ fn[1] += (curr[2] - next[2]) * (curr[0] + next[0]);+ fn[2] += (curr[0] - next[0]) * (curr[1] + next[1]);+ }+ const fnLen = Math.hypot(fn[0], fn[1], fn[2]);+ if (fnLen < 1e-6) continue;+ fn = [fn[0] / fnLen, fn[1] / fnLen, fn[2] / fnLen];++ // Check winding with respect to center (origin)+ const faceCenter: V3 = [+ face.reduce((s, p) => s + p[0], 0) / face.length,+ face.reduce((s, p) => s + p[1], 0) / face.length,+ face.reduce((s, p) => s + p[2], 0) / face.length,+ ];+ if (dot3(fn, faceCenter) < 0) {+ // Flip winding if normal pointed inward+ face.reverse();+ fn = [-fn[0], -fn[1], -fn[2]];+ }++ // Local face UV basis+ const up: V3 = Math.abs(fn[1]) < 0.9 ? [0, 1, 0] : [1, 0, 0];+ const tx = normalize(cross3(up, fn)) as V3;+ const ty = cross3(fn, tx);++ // Project face vertices to [0, 1] UVs+ const uvs: [number, number][] = face.map((pt) => [+ 0.5 + dot3(pt, tx) / (2 * maxR),+ 0.5 + dot3(pt, ty) / (2 * maxR),+ ]);++ const baseIdx = mb.positions.length / 3;+ for (let j = 0; j < face.length; j++) {+ mb.vertex(face[j]!, fn, uvs[j]!);+ }++ // Fan triangulation+ for (let j = 1; j < face.length - 1; j++) {+ mb.indices.push(baseIdx, baseIdx + j, baseIdx + j + 1);+ }+ }+}+/** Builds a procedural solid as a single-mesh Model3DData. */export function generatePrimitiveGeometry(options: PrimitiveGeometryOptions,@@ -289,6 +572,7 @@ export function generatePrimitiveGeometry(if (options.type === "roundedBox") roundedBox(options, mb);else if (options.type === "sphere") sphere(options, mb);else if (options.type === "cylinder") cylinder(options, mb);+ else if (options.type === "shard") shard(options, mb);else {throw new Error(`Unknown 3D primitive: ${(options as { type?: string }).type}`,diff --git a/packages/webgpu-renderers/src/renderer3d/renderer3d.ts b/packages/webgpu-renderers/src/renderer3d/renderer3d.tsindex 0fb8ae79..dd8bbd21 100644--- a/packages/webgpu-renderers/src/renderer3d/renderer3d.ts+++ b/packages/webgpu-renderers/src/renderer3d/renderer3d.ts@@ -23,6 +23,7 @@ import type {Model3DData,} from "../loaders/types.js";import type {+ Environment3DFloor,Environment3DOptions,ShadowUniformInfo,} from "../math3d/environment3d.js";@@ -44,6 +45,7 @@ import { dofBokehWgsl } from "../shaders/dof-bokeh.js";import type { SlugGlyphBatch } from "../slug/slug-pipeline.js";import { AudioMeshDeformPipeline } from "./audio-mesh-deform-pipeline.js";import { type BloomOptions, BloomPipeline } from "./bloom-pipeline.js";+import { FloorReflectionPipeline } from "./floor-reflection-pipeline.js";import {type GPUMeshBuffers,Mesh3DPipeline,@@ -58,6 +60,7 @@ import {} from "./shadow-frustum.js";import { Slug3DPipeline } from "./slug3d-pipeline.js";import type { SurfaceParams } from "./surface-params.js";+import { Swarm3DPipeline } from "./swarm3d-pipeline.js";const ADDRESS_MODES: Record<"repeat" | "clamp" | "mirror", GPUAddressMode> = {repeat: "repeat",@@ -196,6 +199,14 @@ export interface DrawMesh3DOpts extends SurfaceParams {timeMs?: number;sampleRate?: number;};+ /** Hardware instancing: number of instances to draw in a single draw call. */+ instanceCount?: number;+ /** Starting instance index in `instanceBuffer` (default 0). */+ firstInstance?: number;+ /** Storage buffer holding `InstanceData` structs (64 bytes per instance). */+ instanceBuffer?: GPUBuffer;+ /** Optional overall bounding box (e.g. for instanced clusters or swarms) for shadow frustum fitting. */+ bounds?: Aabb;}/** Scene-wide world settings for a 3D pass. */@@ -232,14 +243,22 @@ export class Renderer3D {public slug3dPipeline: Slug3DPipeline;public mesh3dPipeline: Mesh3DPipeline;public audioMeshDeformPipeline: AudioMeshDeformPipeline;+ public swarm3dPipeline: Swarm3DPipeline;+ public floorReflectionPipeline: FloorReflectionPipeline;private dofPipeline: GPURenderPipeline;private dofBindGroupLayout: GPUBindGroupLayout;private cameraPool: BufferPool;private lightsPool: BufferPool;+ private instancePool: BufferPool;private cameraUniformBindGroupCache = new UniformBindGroupCache();private samplerCache = new SamplerCache();private depthTexture: GPUTexture | null = null;private linearDepthTexture: GPUTexture | null = null;+ private reflectionColorTexture: GPUTexture | null = null;+ private reflectionMsaaColorTexture: GPUTexture | null = null;+ private reflectionDepthTexture: GPUTexture | null = null;+ private reflectionTempTexture: GPUTexture | null = null;+ private reflectionBlurredTexture: GPUTexture | null = null;// Multisampled targets the pass draws into; they resolve into the caller's views.private msaaColorTexture: GPUTexture | null = null;private msaaLinearDepthTexture: GPUTexture | null = null;@@ -301,6 +320,15 @@ export class Renderer3D {sampleCount,);this.audioMeshDeformPipeline = new AudioMeshDeformPipeline(device);+ this.swarm3dPipeline = new Swarm3DPipeline(device);+ this.floorReflectionPipeline = new FloorReflectionPipeline(+ device,+ format,+ sampleCount,+ this.quad3dPipeline.cameraLayout,+ this.quad3dPipeline.lightsLayout,+ "depth24plus",+ );this.cameraPool = new BufferPool(320,@@ -312,6 +340,11 @@ export class Renderer3D {GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,);+ this.instancePool = new BufferPool(+ 65536,+ GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,+ );+// Initialize DoF Bokeh Pipelineconst dofModule = device.createShaderModule({label: "dof-bokeh.wgsl",@@ -373,6 +406,7 @@ export class Renderer3D {this.lastCameraPose = null;this.lastCameraBuffer = null;this.lightsPool.reset();+ this.instancePool.reset();this.quad3dPipeline.resetPools();this.slug3dPipeline.resetPools();this.mesh3dPipeline.resetPools();@@ -458,6 +492,99 @@ export class Renderer3D {return this.linearDepthTexture;}+ getOrCreateReflectionTexture(width: number, height: number): GPUTexture {+ if (+ !this.reflectionColorTexture ||+ this.reflectionColorTexture.width !== width ||+ this.reflectionColorTexture.height !== height+ ) {+ this.reflectionColorTexture?.destroy();+ this.reflectionColorTexture = this.device.createTexture({+ label: "Renderer3DReflectionColor",+ size: { width, height },+ format: this.format,+ usage:+ GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,+ });+ }+ return this.reflectionColorTexture;+ }++ getOrCreateReflectionMsaaTexture(width: number, height: number): GPUTexture {+ if (+ !this.reflectionMsaaColorTexture ||+ this.reflectionMsaaColorTexture.width !== width ||+ this.reflectionMsaaColorTexture.height !== height+ ) {+ this.reflectionMsaaColorTexture?.destroy();+ this.reflectionMsaaColorTexture = this.device.createTexture({+ label: "Renderer3DReflectionMsaaColor",+ size: { width, height },+ format: this.format,+ sampleCount: this.sampleCount,+ usage: GPUTextureUsage.RENDER_ATTACHMENT,+ });+ }+ return this.reflectionMsaaColorTexture;+ }++ getOrCreateReflectionDepthTexture(width: number, height: number): GPUTexture {+ if (+ !this.reflectionDepthTexture ||+ this.reflectionDepthTexture.width !== width ||+ this.reflectionDepthTexture.height !== height+ ) {+ this.reflectionDepthTexture?.destroy();+ this.reflectionDepthTexture = this.device.createTexture({+ label: "Renderer3DReflectionDepth",+ size: { width, height },+ format: "depth24plus",+ sampleCount: this.sampleCount,+ usage: GPUTextureUsage.RENDER_ATTACHMENT,+ });+ }+ return this.reflectionDepthTexture;+ }++ getOrCreateReflectionTempTexture(width: number, height: number): GPUTexture {+ if (+ !this.reflectionTempTexture ||+ this.reflectionTempTexture.width !== width ||+ this.reflectionTempTexture.height !== height+ ) {+ this.reflectionTempTexture?.destroy();+ this.reflectionTempTexture = this.device.createTexture({+ label: "Renderer3DReflectionTemp",+ size: { width, height },+ format: this.format,+ usage:+ GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,+ });+ }+ return this.reflectionTempTexture;+ }++ getOrCreateReflectionBlurredTexture(+ width: number,+ height: number,+ ): GPUTexture {+ if (+ !this.reflectionBlurredTexture ||+ this.reflectionBlurredTexture.width !== width ||+ this.reflectionBlurredTexture.height !== height+ ) {+ this.reflectionBlurredTexture?.destroy();+ this.reflectionBlurredTexture = this.device.createTexture({+ label: "Renderer3DReflectionBlurred",+ size: { width, height },+ format: this.format,+ usage:+ GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,+ });+ }+ return this.reflectionBlurredTexture;+ }+packCameraUniforms(camera: Camera3DPose,surfaceWidth: number,@@ -614,6 +741,7 @@ export class Renderer3D {/** World bounds of a mesh or quad draw, for fitting shadow frusta. */worldBounds(item: ShadowCaster3D): Aabb {if (item.kind === "mesh") {+ if (item.opts.bounds) return item.opts.bounds;return transformAabb(this.meshAabb(item.mesh),this.meshModelMatrix(item.opts),@@ -714,7 +842,14 @@ export class Renderer3D {wireframe: c.opts.wireframe,isSkinned: c.opts.isSkinned,skinningMatrices: c.opts.skinningMatrices,+ isInstanced: Boolean(+ c.opts.instanceBuffer ||+ (c.opts.instanceCount && c.opts.instanceCount > 1),+ ),+ instanceBuffer: c.opts.instanceBuffer,},+ c.opts.instanceCount ?? 1,+ c.opts.firstInstance ?? 0,);} else {const m = this.quadModelMatrix(c.opts);@@ -881,6 +1016,128 @@ export class Renderer3D {return { pass, cameraBindGroup, cameraBuffer, lightsBindGroup };}+ beginReflectionPass(+ encoder: GPUCommandEncoder,+ surfaceWidth: number,+ surfaceHeight: number,+ camera: Camera3DPose,+ lights?: Light3DOptions[],+ world?: Scene3DWorld,+ ): {+ pass: GPURenderPassEncoder;+ cameraBindGroup: GPUBindGroup;+ lightsBindGroup: GPUBindGroup;+ reflectionTexture: GPUTexture;+ } {+ this.passWritesHdr = false;+ const reflWidth = Math.max(1, Math.floor(surfaceWidth / 2));+ const reflHeight = Math.max(1, Math.floor(surfaceHeight / 2));+ const colorTex = this.getOrCreateReflectionTexture(reflWidth, reflHeight);+ const depthTex = this.getOrCreateReflectionDepthTexture(+ reflWidth,+ reflHeight,+ );++ const cameraBuffer = this.packCameraUniforms(camera, reflWidth, reflHeight);+ const cameraBindGroup = this.createCameraBindGroup(cameraBuffer);++ const lightsData = Light3D.packLightsUniforms(+ lights ?? [],+ world?.environment,+ world?.shadow,+ true,+ );+ const lightsBuffer = this.lightsPool.getBuffer(this.device, lightsData);+ const lightsBindGroup = this.createLightsBindGroup(+ lightsBuffer,+ Boolean(world?.shadow),+ );++ const msaa = this.sampleCount > 1;+ const msaaTex = msaa+ ? this.getOrCreateReflectionMsaaTexture(reflWidth, reflHeight)+ : null;++ const colorAttachments: GPURenderPassColorAttachment[] = [+ msaaTex+ ? {+ view: msaaTex.createView(),+ resolveTarget: colorTex.createView(),+ loadOp: "clear",+ storeOp: "discard",+ clearValue: { r: 0, g: 0, b: 0, a: 0 },+ }+ : {+ view: colorTex.createView(),+ loadOp: "clear",+ storeOp: "store",+ clearValue: { r: 0, g: 0, b: 0, a: 0 },+ },+ ];++ const pass = encoder.beginRenderPass({+ colorAttachments,+ depthStencilAttachment: {+ view: depthTex.createView(),+ depthClearValue: 1.0,+ depthLoadOp: "clear",+ depthStoreOp: msaa ? "discard" : "store",+ },+ });++ return {+ pass,+ cameraBindGroup,+ lightsBindGroup,+ reflectionTexture: colorTex,+ };+ }++ blurReflection(+ encoder: GPUCommandEncoder,+ reflectionTexture: GPUTexture,+ roughness: number,+ ): GPUTexture {+ if (roughness <= 0.001) {+ return reflectionTexture;+ }+ const width = reflectionTexture.width;+ const height = reflectionTexture.height;+ const tempTex = this.getOrCreateReflectionTempTexture(width, height);+ const blurredTex = this.getOrCreateReflectionBlurredTexture(width, height);++ this.floorReflectionPipeline.applyBlur(+ encoder,+ reflectionTexture,+ tempTex,+ blurredTex,+ width,+ height,+ roughness,+ );+ return blurredTex;+ }++ drawFloor(+ pass: GPURenderPassEncoder,+ cameraBindGroup: GPUBindGroup,+ lightsBindGroup: GPUBindGroup,+ reflectionTexture: GPUTexture,+ floor: Environment3DFloor,+ useMrt = false,+ useBloom = false,+ ): void {+ this.floorReflectionPipeline.draw(+ pass,+ cameraBindGroup,+ lightsBindGroup,+ reflectionTexture,+ floor,+ useMrt,+ useBloom,+ );+ }+/*** A layer's unit quad ([-0.5, 0.5] square) in world space:* T(pos) * Rz * Ry * Rx * S(w * sx, h * sy, sz) * T(0.5 - ax, 0.5 - ay, 0).@@ -1364,9 +1621,15 @@ export class Renderer3D {emissiveIntensity: opts.emissiveIntensity,matte: opts.matte,maps: opts.maps,+ isInstanced: Boolean(+ opts.instanceBuffer || (opts.instanceCount && opts.instanceCount > 1),+ ),+ instanceBuffer: opts.instanceBuffer,},useMrt,this.passWritesHdr,+ opts.instanceCount ?? 1,+ opts.firstInstance ?? 0,);}@@ -1561,6 +1824,38 @@ export class Renderer3D {pass.end();}+ /** Uploads raw `InstanceData` float buffer to a GPU storage buffer from the instance pool. */+ uploadInstanceData(data: Float32Array): GPUBuffer {+ return this.instancePool.getBuffer(this.device, data);+ }++ /** Draws instanced 3D meshes in a single hardware-instanced draw call. */+ drawMesh3DInstanced(+ pass: GPURenderPassEncoder,+ cameraBindGroup: GPUBindGroup,+ lightsBindGroup: GPUBindGroup,+ meshOrBuffers: Mesh3DData | GPUMeshBuffers,+ instanceBuffer: GPUBuffer,+ instanceCount: number,+ texture: GPUTexture | undefined = undefined,+ opts: DrawMesh3DOpts = {},+ useMrt = false,+ ): void {+ this.drawMesh3D(+ pass,+ cameraBindGroup,+ lightsBindGroup,+ meshOrBuffers,+ texture,+ {+ ...opts,+ instanceBuffer,+ instanceCount,+ },+ useMrt,+ );+ }+destroy(): void {this.bloomPipeline?.destroy();this.depthTexture?.destroy();@@ -1574,8 +1869,15 @@ export class Renderer3D {this.quad3dPipeline.destroy();this.slug3dPipeline.destroy();this.mesh3dPipeline.destroy();+ this.floorReflectionPipeline.destroy();+ this.reflectionColorTexture?.destroy();+ this.reflectionMsaaColorTexture?.destroy();+ this.reflectionDepthTexture?.destroy();+ this.reflectionTempTexture?.destroy();+ this.reflectionBlurredTexture?.destroy();this.cameraPool.destroy();this.lightsPool.destroy();+ this.instancePool.destroy();this.cameraUniformBindGroupCache.destroy();}}diff --git a/packages/webgpu-renderers/src/renderer3d/swarm3d-pipeline.ts b/packages/webgpu-renderers/src/renderer3d/swarm3d-pipeline.tsnew file mode 100644index 00000000..3916dda2--- /dev/null+++ b/packages/webgpu-renderers/src/renderer3d/swarm3d-pipeline.ts@@ -0,0 +1,1073 @@+/**+ * @file packages/webgpu-renderers/src/renderer3d/swarm3d-pipeline.ts+ * GPU Compute Simulation & Instancing Pipeline for 3D Particle Swarms, Faceted Shards & Secondary Sparks.+ * Supports 3D curl noise, 3D attractors, centripetally-confined 3D vortex/cyclone fields,+ * floor collision with Coulomb sliding friction, angular tumble, kinetic/friction HDR heat emission,+ * multi-variant mesh slice packing, and GPU-coupled secondary spark emission.+ */++export const SWARM_PARTICLE_BYTES = 80; // 5 x vec4<f32>+export const SWARM_INSTANCE_BYTES = 64; // 4 x vec4<f32>+export const SWARM_PARAM_VEC4S = 32;+export const SWARM_MAX_ATTRACTORS = 5;+export const SWARM_SNAPSHOT_EVERY = 24;+export const SWARM_MAX_SNAPSHOTS = 64;+export const SWARM_WORKGROUP = 64;++export const SWARM_SIM_WGSL = /* wgsl */ `+struct SwarmParticle3D {+ pos : vec3<f32>, // world-space position (px, y down)+ age : f32, // seconds alive+ vel : vec3<f32>, // world-space velocity (px/s)+ life : f32, // total lifetime (seconds; <= 0 means dead)+ quat : vec4<f32>, // unit orientation quaternion+ angVel : vec3<f32>, // angular velocity (rad/s)+ heat : f32, // smoothed kinetic/friction heat [0..1+]+ scale : f32, // size multiplier (for sparks: radius in px)+ variant : u32, // mesh variant index+ seed : u32, // per-particle deterministic random id+ contact : f32, // floor contact factor [0..1]+};++struct InstanceData {+ posScale : vec4<f32>, // xyz = translation, w = mesh scale+ quat : vec4<f32>, // xyzw = orientation quaternion+ color : vec4<f32>, // rgba = color multiplier+ emissive : vec4<f32>, // rgb = sRGB emissive color, w = emissiveIntensity+};++struct Params { v : array<vec4<f32>, ${SWARM_PARAM_VEC4S}> };++@group(0) @binding(0) var<uniform> P : Params;+@group(0) @binding(1) var<storage, read_write> particles : array<SwarmParticle3D>;+@group(0) @binding(2) var<storage, read_write> instances : array<InstanceData>;++fn pcg(v : u32) -> u32 {+ let state = v * 747796405u + 2891336453u;+ let word = ((state >> ((state >> 28u) + 4u)) ^ state) * 277803737u;+ return (word >> 22u) ^ word;+}++fn rnd(idx : u32, channel : u32, seed : u32) -> f32 {+ return f32(pcg(idx * 16u + channel + pcg(seed))) / 4294967295.0;+}++fn hash3(p : vec3<f32>) -> f32 {+ let q = fract(p * vec3<f32>(0.1031, 0.1030, 0.0973));+ let r = q + dot(q, q.yzx + 33.33);+ return fract((r.x + r.y) * r.z);+}++fn vnoise3(p : vec3<f32>) -> f32 {+ let i = floor(p);+ let f = fract(p);+ let u = f * f * (3.0 - 2.0 * f);+ let n000 = hash3(i);+ let n100 = hash3(i + vec3<f32>(1.0, 0.0, 0.0));+ let n010 = hash3(i + vec3<f32>(0.0, 1.0, 0.0));+ let n110 = hash3(i + vec3<f32>(1.0, 1.0, 0.0));+ let n001 = hash3(i + vec3<f32>(0.0, 0.0, 1.0));+ let n101 = hash3(i + vec3<f32>(1.0, 0.0, 1.0));+ let n011 = hash3(i + vec3<f32>(0.0, 1.0, 1.0));+ let n111 = hash3(i + vec3<f32>(1.0, 1.0, 1.0));+ return mix(+ mix(mix(n000, n100, u.x), mix(n010, n110, u.x), u.y),+ mix(mix(n001, n101, u.x), mix(n011, n111, u.x), u.y),+ u.z+ );+}++fn fbm3(p : vec3<f32>) -> f32 {+ return vnoise3(p) * 0.6 + vnoise3(p * 2.02 + 13.5) * 0.3 + vnoise3(p * 4.05 + 31.7) * 0.1;+}++fn curl3(p : vec3<f32>) -> vec3<f32> {+ let e = 0.02;+ let dx = vec3<f32>(e, 0.0, 0.0);+ let dy = vec3<f32>(0.0, e, 0.0);+ let dz = vec3<f32>(0.0, 0.0, e);++ let p0 = p;+ let p1 = p + vec3<f32>(31.4, 15.9, 26.5);+ let p2 = p + vec3<f32>(65.3, 58.9, 79.3);++ let dAy_dz = (fbm3(p1 + dz) - fbm3(p1 - dz)) / (2.0 * e);+ let dAz_dy = (fbm3(p2 + dy) - fbm3(p2 - dy)) / (2.0 * e);++ let dAz_dx = (fbm3(p2 + dx) - fbm3(p2 - dx)) / (2.0 * e);+ let dAx_dz = (fbm3(p0 + dz) - fbm3(p0 - dz)) / (2.0 * e);++ let dAx_dy = (fbm3(p0 + dy) - fbm3(p0 - dy)) / (2.0 * e);+ let dAy_dx = (fbm3(p1 + dx) - fbm3(p1 - dx)) / (2.0 * e);++ return vec3<f32>(dAz_dy - dAy_dz, dAx_dz - dAz_dx, dAy_dx - dAx_dy);+}++fn quatMul(a: vec4<f32>, b: vec4<f32>) -> vec4<f32> {+ return vec4<f32>(+ a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,+ a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,+ a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w,+ a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z,+ );+}++fn spawn3D(i : u32, idx : u32, birthFrac : f32) {+ let baseSeed = u32(P.v[1].y);+ let timeSalt = u32(max(0.0, P.v[0].y + 100.0) * 997.0);+ let seed = baseSeed + timeSalt;+ let shape = u32(P.v[4].x); // 0=point, 1=box, 2=sphere, 3=shell, 4=ring, 5=disc+ let ex = P.v[4].y; let ey = P.v[4].z; let ez = P.v[4].w;+ let ew = P.v[5].x; let eh = P.v[5].y; let ed = P.v[5].z; let er = P.v[5].w;++ let r0 = rnd(idx, 0u, seed);+ let r1 = rnd(idx, 1u, seed);+ let r2 = rnd(idx, 2u, seed);++ var pos = vec3<f32>(ex, ey, ez);+ if (shape == 1u) {+ pos = vec3<f32>(ex + (r0 - 0.5) * ew, ey + (r1 - 0.5) * eh, ez + (r2 - 0.5) * ed);+ } else if (shape == 2u) {+ let phi = r0 * 6.2831853;+ let cosTheta = (r1 * 2.0) - 1.0;+ let sinTheta = sqrt(max(0.0, 1.0 - cosTheta * cosTheta));+ let rad = er * pow(r2, 0.33333);+ pos = vec3<f32>(ex + cos(phi) * sinTheta * rad, ey + sin(phi) * sinTheta * rad, ez + cosTheta * rad);+ } else if (shape == 3u) {+ let phi = r0 * 6.2831853;+ let cosTheta = (r1 * 2.0) - 1.0;+ let sinTheta = sqrt(max(0.0, 1.0 - cosTheta * cosTheta));+ pos = vec3<f32>(ex + cos(phi) * sinTheta * er, ey + sin(phi) * sinTheta * er, ez + cosTheta * er);+ } else if (shape == 4u || shape == 5u) {+ let phi = r0 * 6.2831853;+ let ringJitter = 1.0 + (r1 - 0.5) * 0.35;+ let rad = select(er * ringJitter, er * sqrt(r1), shape == 5u);+ pos = vec3<f32>(ex + cos(phi) * rad, ey + (r2 - 0.5) * eh, ez + sin(phi) * rad);+ }++ let dir = P.v[6].xyz;+ let spread = P.v[6].w;+ let speedMin = P.v[7].x;+ let speedMax = P.v[7].y;+ let spd = mix(speedMin, speedMax, rnd(idx, 3u, seed));++ var vDir = normalize(dir);+ if (length(dir) < 0.001) {+ vDir = vec3<f32>(0.0, -1.0, 0.0);+ }+ if (spread > 0.001) {+ let theta = (rnd(idx, 4u, seed) - 0.5) * spread;+ let phi = rnd(idx, 5u, seed) * 6.2831853;+ var tangent = cross(vDir, vec3<f32>(0.0, 1.0, 0.0));+ if (length(tangent) < 0.01) {+ tangent = cross(vDir, vec3<f32>(1.0, 0.0, 0.0));+ }+ tangent = normalize(tangent);+ let bitangent = cross(vDir, tangent);+ vDir = normalize(vDir + (tangent * cos(phi) + bitangent * sin(phi)) * tan(theta));+ }++ // If vortex is active, give newly spawned shards an initial orbital velocity component+ var initVel = vDir * spd;+ let vortexSwirl = P.v[14].w;+ if (abs(vortexSwirl) > 0.001) {+ let vCenter = P.v[14].xyz;+ let vAxis = normalize(P.v[15].xyz);+ let r = pos - vCenter;+ let rPerp = r - vAxis * dot(r, vAxis);+ if (length(rPerp) > 1.0) {+ let orbTangent = normalize(cross(vAxis, rPerp));+ initVel += orbTangent * (spd * 0.85 * sign(vortexSwirl));+ }+ }++ let lifeMin = P.v[7].z;+ let lifeMax = P.v[7].w;+ let life = mix(lifeMin, lifeMax, rnd(idx, 6u, seed));++ let angSpeed = mix(P.v[8].x, P.v[8].y, rnd(idx, 7u, seed));+ let angAxis = normalize(vec3<f32>(+ rnd(idx, 8u, seed) - 0.5,+ rnd(idx, 9u, seed) - 0.5,+ rnd(idx, 10u, seed) - 0.5,+ ));++ let qAngle = rnd(idx, 11u, seed) * 6.2831853;+ let qAxis = normalize(vec3<f32>(+ rnd(idx, 12u, seed) - 0.5,+ rnd(idx, 13u, seed) - 0.5,+ rnd(idx, 14u, seed) - 0.5,+ ));+ let initQuat = vec4<f32>(qAxis * sin(qAngle * 0.5), cos(qAngle * 0.5));++ let sizeJitter = P.v[16].w;+ let pScale = max(0.25, 1.0 + (rnd(idx, 15u, seed) - 0.5) * sizeJitter * 2.0);++ var p: SwarmParticle3D;+ p.pos = pos;+ p.age = birthFrac * P.v[0].x;+ p.vel = initVel;+ p.life = life;+ p.quat = initQuat;+ p.angVel = angAxis * angSpeed;+ p.heat = 0.0;+ p.scale = pScale;+ p.variant = idx % max(1u, u32(P.v[8].z));+ p.seed = pcg(idx + seed);+ p.contact = 0.0;++ particles[i] = p;+}++fn spawnSpark3D(i : u32, sparkIdx : u32, maxParticles : u32, birthFrac : f32) {+ let baseSeed = u32(P.v[1].y);+ let timeSalt = u32(max(0.0, P.v[0].y + 100.0) * 1319.0);+ let seed = baseSeed ^ timeSalt;++ // Search up to 6 candidate shards to find a hot or scraping parent shard+ var parentIdx = pcg(sparkIdx * 7u + seed) % maxParticles;+ var parent = particles[parentIdx];+ let threshold = P.v[29].x;+ for (var attempt = 1u; attempt < 6u; attempt = attempt + 1u) {+ if (parent.life > 0.0 && (parent.heat >= threshold || parent.contact > 0.5)) {+ break;+ }+ let candIdx = pcg(sparkIdx * 13u + attempt * 37u + seed) % maxParticles;+ let cand = particles[candIdx];+ if (cand.life > 0.0 && (cand.heat > parent.heat || parent.life <= 0.0)) {+ parent = cand;+ parentIdx = candIdx;+ }+ }++ if (parent.life <= 0.0) {+ return;+ }++ let r0 = rnd(sparkIdx, 0u, seed) - 0.5;+ let r1 = rnd(sparkIdx, 1u, seed) - 0.5;+ let r2 = rnd(sparkIdx, 2u, seed) - 0.5;+ let scatterDir = normalize(vec3<f32>(r0, r1 - 0.25, r2));+ let sparkSpd = mix(P.v[29].w, P.v[30].w, rnd(sparkIdx, 3u, seed));++ var p: SwarmParticle3D;+ p.pos = parent.pos + scatterDir * 8.0;+ p.age = birthFrac * P.v[0].x;+ p.vel = parent.vel * 0.6 + scatterDir * sparkSpd;+ p.life = mix(P.v[30].x, P.v[30].y, rnd(sparkIdx, 4u, seed));+ p.quat = parent.quat;+ p.angVel = vec3<f32>(r0, r1, r2) * 18.0;+ p.heat = max(0.75, parent.heat * 1.25);+ p.scale = mix(P.v[29].y, P.v[29].z, rnd(sparkIdx, 5u, seed));+ p.variant = 0u;+ p.seed = pcg(sparkIdx + seed);+ p.contact = 0.0;++ particles[i] = p;+}++@compute @workgroup_size(${SWARM_WORKGROUP})+fn stepSimulation(@builtin(global_invocation_id) id : vec3<u32>) {+ let idx = id.x;+ let maxParticles = u32(P.v[1].x);+ let sparkMax = u32(P.v[1].w);+ let totalSlots = maxParticles + sparkMax;+ if (idx >= totalSlots) { return; }++ let isSpark = idx >= maxParticles;++ if (!isSpark) {+ let emitStart = u32(P.v[0].z);+ let emitCount = u32(P.v[0].w);+ if (emitCount > 0u) {+ let end = emitStart + emitCount;+ var spawned = false;+ if (end <= maxParticles) {+ if (idx >= emitStart && idx < end) {+ let birthFrac = f32(idx - emitStart) / f32(emitCount);+ spawn3D(idx, idx, birthFrac);+ spawned = true;+ }+ } else {+ if (idx >= emitStart || idx < (end % maxParticles)) {+ let slot = select(idx - emitStart, idx + (maxParticles - emitStart), idx < emitStart);+ let birthFrac = f32(slot) / f32(emitCount);+ spawn3D(idx, idx, birthFrac);+ spawned = true;+ }+ }+ if (spawned) { return; }+ }+ } else if (sparkMax > 0u) {+ let sparkIdx = idx - maxParticles;+ let sEmitStart = u32(P.v[2].w);+ let sEmitCount = u32(P.v[16].z);+ if (sEmitCount > 0u) {+ let end = sEmitStart + sEmitCount;+ var spawned = false;+ if (end <= sparkMax) {+ if (sparkIdx >= sEmitStart && sparkIdx < end) {+ let birthFrac = f32(sparkIdx - sEmitStart) / f32(sEmitCount);+ spawnSpark3D(idx, sparkIdx, maxParticles, birthFrac);+ spawned = true;+ }+ } else {+ if (sparkIdx >= sEmitStart || sparkIdx < (end % sparkMax)) {+ let slot = select(sparkIdx - sEmitStart, sparkIdx + (sparkMax - sEmitStart), sparkIdx < sEmitStart);+ let birthFrac = f32(slot) / f32(sEmitCount);+ spawnSpark3D(idx, sparkIdx, maxParticles, birthFrac);+ spawned = true;+ }+ }+ if (spawned) { return; }+ }+ }++ var p = particles[idx];+ if (p.life <= 0.0) { return; }++ let dt = P.v[0].x;+ p.age += dt;+ if (p.age >= p.life) {+ p.life = 0.0;+ particles[idx] = p;+ return;+ }++ var acc = P.v[2].xyz * select(1.0, 0.55, isSpark);++ // Linear Drag+ let drag = P.v[3].x * select(1.0, 2.2, isSpark);+ acc -= p.vel * drag;++ // 3D Curl Noise+ let noiseStrength = P.v[3].y * select(1.0, 1.35, isSpark);+ if (noiseStrength > 0.001) {+ let noiseScale = max(P.v[3].z, 1.0);+ let noiseSpeed = P.v[3].w;+ let time = P.v[0].y;+ let noisePos = (p.pos / noiseScale) + vec3<f32>(0.0, time * noiseSpeed, 0.0);+ let curl = curl3(noisePos);+ acc += curl * noiseStrength;+ }++ // Attractors (up to 5)+ let numAttractors = min(5u, u32(P.v[8].w));+ for (var a = 0u; a < numAttractors; a = a + 1u) {+ let attr = P.v[9u + a];+ let toAttr = attr.xyz - p.pos;+ let dist = length(toAttr);+ let maxRadius = attr.w;+ if (dist > 0.1 && (maxRadius <= 0.0 || dist < maxRadius)) {+ var strength = 0.0;+ if (a == 0u) { strength = P.v[17].x; }+ else if (a == 1u) { strength = P.v[17].y; }+ else if (a == 2u) { strength = P.v[17].z; }+ else if (a == 3u) { strength = P.v[17].w; }+ else { strength = P.v[21].w; }+ let factor = select(1.0, 1.0 - dist / maxRadius, maxRadius > 0.0);+ acc += (toAttr / dist) * (strength * factor);+ }+ }++ // 3D Vortex / Cyclone Field with Hollow Eye & Orbital Belt Equilibrium+ let vortexSwirl = P.v[14].w;+ if (abs(vortexSwirl) > 0.001 || abs(P.v[15].w) > 0.001) {+ let vCenter = P.v[14].xyz;+ let vAxis = normalize(P.v[15].xyz);+ let vPull = P.v[15].w;+ let vAxial = P.v[16].x;+ let vRadius = P.v[16].y;++ let r = p.pos - vCenter;+ let h = dot(r, vAxis);+ let rPerp = r - (vAxis * h);+ let dPerp = length(rPerp);++ if (dPerp > 0.1 && (vRadius <= 0.0 || dPerp < vRadius * 1.35)) {+ let effRadius = select(650.0, vRadius, vRadius > 0.0);+ let eyeRadius = max(effRadius * 0.24, 145.0);+ let bandWidth = max(effRadius * 0.54, 240.0);+ let bandRadius = eyeRadius + rnd(idx, 13u, p.seed) * bandWidth;++ let falloff = clamp(1.0 - (dPerp / (effRadius * 1.25)), 0.18, 1.0);+ let tangent = normalize(cross(vAxis, rPerp));+ let radialInward = -rPerp / dPerp;+ let vTan = dot(p.vel, tangent);+ let vRadOut = dot(p.vel, -radialInward);++ // Target tangential speed for this orbital band so shards don't accelerate to infinity+ let targetVTan = vortexSwirl * (0.55 + 0.45 * falloff);+ let swirlAcc = (targetVTan - vTan) * 2.2;++ // Centripetal balance outside the hollow eye + spring toward each shard's orbital band+ let eyeMask = smoothstep(eyeRadius * 0.55, eyeRadius * 1.15, dPerp);+ let centripetal = ((vTan * vTan) / max(dPerp, 80.0)) * eyeMask * 0.92;+ let bandPull = ((dPerp - bandRadius) / bandWidth) * vPull * 2.4;+ let eyeRepel = select(0.0, -vPull * 3.8 * (1.0 - dPerp / eyeRadius), dPerp < eyeRadius);+ let radialAcc = centripetal + bandPull + eyeRepel - vRadOut * 2.1;++ acc += tangent * swirlAcc + radialInward * radialAcc + vAxis * (vAxial * falloff);+ }+ }++ // Integrate velocity+ p.vel += acc * dt;++ // Floor Collision with Coulomb Sliding Friction & Angular Roll+ p.contact = 0.0;+ if (P.v[18].w > 0.5) {+ let floorY = P.v[18].x;+ let bounce = P.v[18].y;+ let friction = P.v[18].z;+ let progress = clamp(p.age / max(p.life, 0.001), 0.0, 1.0);+ let shardRadius = select(mix(P.v[19].x, P.v[19].y, progress) * p.scale, p.scale, isSpark);++ if (p.pos.y + shardRadius >= floorY) {+ let impactSpeed = max(0.0, p.vel.y);+ p.pos.y = floorY - shardRadius;+ p.contact = 1.0;++ if (p.vel.y > 0.0) {+ p.vel.y = -p.vel.y * select(bounce, min(0.55, bounce + 0.2), isSpark);+ }++ let vSlide = length(vec2<f32>(p.vel.x, p.vel.z));+ let fDamp = exp(-friction * dt * 0.85);+ p.vel.x *= fDamp;+ p.vel.z *= fDamp;++ let normal = vec3<f32>(0.0, -1.0, 0.0);+ let vTan = vec3<f32>(p.vel.x, 0.0, p.vel.z);+ let rollTorque = cross(normal, vTan) / max(shardRadius, 1.0);+ p.angVel += rollTorque * clamp(friction * dt * 2.5, 0.0, 1.0);++ let heatGain = P.v[25].x;+ let thermal = pow(rnd(idx, 14u, p.seed), 2.4);+ let slideHeat = max(0.0, vSlide - 180.0) * friction * dt * 0.0032;+ let impactHeat = smoothstep(30.0, 260.0, impactSpeed) * 0.45;+ p.heat = min(1.35, p.heat + (slideHeat + impactHeat) * heatGain * (0.15 + 1.35 * thermal));+ }+ }++ // Integrate position+ p.pos += p.vel * dt;++ // Angular drag & Quaternion integration+ let angDrag = P.v[25].y;+ p.angVel *= exp(-angDrag * dt);+ let omega = p.angVel;+ let dq = quatMul(vec4<f32>(omega * (0.5 * dt), 0.0), p.quat);+ p.quat = normalize(p.quat + dq);++ // Heat cooldown exponential decay+ let heatDecay = max(P.v[25].z, 0.05);+ p.heat *= exp(-dt / heatDecay);++ particles[idx] = p;+}++@compute @workgroup_size(${SWARM_WORKGROUP})+fn packInstances(@builtin(global_invocation_id) id : vec3<u32>) {+ let idx = id.x;+ let maxParticles = u32(P.v[1].x);+ let sparkMax = u32(P.v[1].w);+ let totalSlots = maxParticles + sparkMax;+ if (idx >= totalSlots) { return; }++ let isSpark = idx >= maxParticles;+ let numVariants = max(1u, u32(P.v[8].z));+ let sliceCount = max(1u, u32(P.v[20].y));+ let meshRadius = max(0.001, P.v[20].x);++ var outIdx = idx;+ if (!isSpark) {+ let vIdx = idx % numVariants;+ let localIdx = idx / numVariants;+ outIdx = vIdx * sliceCount + localIdx;+ } else {+ let sparkIdx = idx - maxParticles;+ outIdx = (numVariants * sliceCount) + sparkIdx;+ }++ let p = particles[idx];+ var out: InstanceData;++ if (p.life <= 0.0 || p.age >= p.life) {+ out.posScale = vec4<f32>(0.0, 0.0, 0.0, 0.0);+ out.quat = vec4<f32>(0.0, 0.0, 0.0, 1.0);+ out.color = vec4<f32>(0.0);+ out.emissive = vec4<f32>(0.0);+ instances[outIdx] = out;+ return;+ }++ let progress = p.age / p.life;+ let fadeIn = smoothstep(0.0, max(0.001, P.v[19].z), progress);+ let fadeOut = 1.0 - smoothstep(max(0.0, 1.0 - P.v[19].w), 1.0, progress);++ if (isSpark) {+ let sparkRadius = max(0.0, p.scale * fadeIn * fadeOut);+ out.posScale = vec4<f32>(p.pos, sparkRadius / meshRadius);+ out.quat = p.quat;+ let sparkCol = mix(P.v[28].rgb, P.v[31].rgb, smoothstep(0.0, 0.55, progress));+ out.color = vec4<f32>(sparkCol, 1.0);+ out.emissive = vec4<f32>(sparkCol, P.v[30].z * fadeOut);+ instances[outIdx] = out;+ return;+ }++ let lifeRadius = mix(P.v[19].x, P.v[19].y, progress) * fadeIn * fadeOut;+ let worldRadius = max(0.0, p.scale * lifeRadius);++ out.posScale = vec4<f32>(p.pos, worldRadius / meshRadius);+ out.quat = p.quat;++ // Base color palette interpolation+ let numColors = u32(P.v[21].x);+ var baseCol = P.v[22];+ if (numColors > 1u) {+ let colorT = progress * f32(numColors - 1u);+ let cIdx = min(u32(floor(colorT)), numColors - 2u);+ let cFrac = colorT - f32(cIdx);+ baseCol = mix(P.v[22u + cIdx], P.v[23u + cIdx], cFrac);+ }++ // Dynamic emissive from friction heat and/or speed, modulated per-shard for natural rock/glow contrast+ let heatSource = u32(P.v[20].z); // 0=both, 1=friction, 2=speed+ let maxSpd = max(P.v[20].w, 1.0);+ let thermal = pow(rnd(idx, 14u, p.seed), 2.2);+ let speedFactor = smoothstep(0.62, 1.0, length(p.vel) / maxSpd) * thermal;+ var heatVal = p.heat;+ if (heatSource == 0u) {+ heatVal = max(p.heat, speedFactor);+ } else if (heatSource == 2u) {+ heatVal = speedFactor;+ }++ let heatCurve = P.v[21].y;+ let curvedHeat = pow(clamp(heatVal, 0.0, 1.0), select(1.0, heatCurve, heatCurve > 0.0));+ let heatRamp = mix(+ P.v[26].rgb,+ mix(P.v[27].rgb, P.v[28].rgb, smoothstep(0.55, 0.95, curvedHeat)),+ smoothstep(0.08, 0.55, curvedHeat),+ );+ let heatIntensity = curvedHeat * P.v[21].z * smoothstep(0.08, 0.65, curvedHeat);++ // Blend base albedo color toward the hot color only for significantly heated shards+ out.color = vec4<f32>(mix(baseCol.rgb, heatRamp, smoothstep(0.12, 0.75, curvedHeat)), baseCol.a);++ if (heatIntensity > 0.01) {+ out.emissive = vec4<f32>(heatRamp, heatIntensity);+ } else {+ out.emissive = vec4<f32>(0.0);+ }++ instances[outIdx] = out;+}+`;++export interface Swarm3DStaticConfig {+ max: number;+ seed: number;+ substeps: number;+ prewarm: number;+ meshRadius?: number;+ emitter: {+ shape: "point" | "box" | "sphere" | "shell" | "ring" | "disc";+ x: number;+ y: number;+ z: number;+ width: number;+ height: number;+ depth: number;+ radius: number;+ };+ speed: [number, number];+ direction: [number, number, number];+ spread: number;+ angularSpeed: [number, number];+ angularDrag: number;+ lifetime: [number, number];+ size: [number, number];+ sizeJitter: number;+ fade: [number, number];+ colors: Array<[number, number, number, number]>;+ heat: {+ source: "both" | "friction" | "speed";+ maxSpeed: number;+ curve: number;+ intensity: number;+ colors: [+ [number, number, number],+ [number, number, number],+ [number, number, number],+ ];+ };+ sparks?: {+ max: number;+ rate: number;+ threshold: number;+ size: [number, number];+ lifetime: [number, number];+ speed: [number, number];+ intensity: number;+ color: [number, number, number];+ };+ variants: number;+}++export interface Swarm3DFrameInput {+ rate: number;+ gravity: [number, number, number];+ drag: number;+ noise: { strength: number; scale: number; speed: number };+ attractors: Array<{+ x: number;+ y: number;+ z: number;+ strength: number;+ radius?: number;+ }>;+ vortex?: {+ x: number;+ y: number;+ z: number;+ axis: [number, number, number];+ swirl: number;+ pull: number;+ axial: number;+ radius: number;+ };+ floor?: {+ y: number;+ bounce: number;+ friction: number;+ heatGain: number;+ heatDecay: number;+ };+ emitterPos?: [number, number, number];+}++export interface Swarm3DState {+ device: GPUDevice;+ particles: GPUBuffer;+ instances: GPUBuffer;+ ubo: GPUBuffer;+ frame: number;+ emitted: number;+ carry: number;+ sparkEmitted: number;+ sparkCarry: number;+ sliceCount: number;+ totalParticleSlots: number;+ totalInstanceSlots: number;+ snapshots: Map<+ number,+ {+ buffer: GPUBuffer;+ emitted: number;+ carry: number;+ sparkEmitted: number;+ sparkCarry: number;+ }+ >;+}++export class Swarm3DPipeline {+ private device: GPUDevice;+ private simPipeline: GPUComputePipeline;+ private packPipeline: GPUComputePipeline;+ private bindGroupLayout: GPUBindGroupLayout;++ constructor(device: GPUDevice) {+ this.device = device;+ const module = device.createShaderModule({+ label: "swarm3d.wgsl",+ code: SWARM_SIM_WGSL,+ });++ this.bindGroupLayout = device.createBindGroupLayout({+ label: "Swarm3DBindGroupLayout",+ entries: [+ {+ binding: 0,+ visibility: GPUShaderStage.COMPUTE,+ buffer: { type: "uniform" },+ },+ {+ binding: 1,+ visibility: GPUShaderStage.COMPUTE,+ buffer: { type: "storage" },+ },+ {+ binding: 2,+ visibility: GPUShaderStage.COMPUTE,+ buffer: { type: "storage" },+ },+ ],+ });++ const pipelineLayout = device.createPipelineLayout({+ bindGroupLayouts: [this.bindGroupLayout],+ });++ this.simPipeline = device.createComputePipeline({+ label: "Swarm3DSimPipeline",+ layout: pipelineLayout,+ compute: { module, entryPoint: "stepSimulation" },+ });++ this.packPipeline = device.createComputePipeline({+ label: "Swarm3DPackPipeline",+ layout: pipelineLayout,+ compute: { module, entryPoint: "packInstances" },+ });+ }++ createState(config: Swarm3DStaticConfig): Swarm3DState {+ const numVariants = Math.max(1, config.variants);+ const sliceCount = Math.ceil(config.max / numVariants);+ const sparkMax = config.sparks?.max ?? 0;+ const totalParticleSlots = config.max + sparkMax;+ const totalInstanceSlots = sliceCount * numVariants + sparkMax;++ const size = totalParticleSlots * SWARM_PARTICLE_BYTES;+ const instSize = totalInstanceSlots * SWARM_INSTANCE_BYTES;+ return {+ device: this.device,+ particles: this.device.createBuffer({+ label: "Swarm3DParticles",+ size,+ usage:+ GPUBufferUsage.STORAGE |+ GPUBufferUsage.COPY_SRC |+ GPUBufferUsage.COPY_DST,+ }),+ instances: this.device.createBuffer({+ label: "Swarm3DInstances",+ size: instSize,+ usage:+ GPUBufferUsage.STORAGE |+ GPUBufferUsage.COPY_SRC |+ GPUBufferUsage.COPY_DST,+ }),+ ubo: this.device.createBuffer({+ label: "Swarm3DUbo",+ size: SWARM_PARAM_VEC4S * 16,+ usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,+ }),+ frame: -999999,+ emitted: 0,+ carry: 0,+ sparkEmitted: 0,+ sparkCarry: 0,+ sliceCount,+ totalParticleSlots,+ totalInstanceSlots,+ snapshots: new Map(),+ };+ }++ packParams(+ s: Swarm3DStaticConfig,+ f: Swarm3DFrameInput,+ out: Float32Array,+ sim: {+ dt: number;+ time: number;+ emitStart: number;+ emitCount: number;+ sparkEmitStart: number;+ sparkEmitCount: number;+ frameDt: number;+ sliceCount: number;+ },+ ): void {+ out.fill(0);+ const v = (i: number, a: number, b: number, c: number, d: number) =>+ out.set([a, b, c, d], i * 4);++ const sparkMax = s.sparks?.max ?? 0;+ v(0, sim.dt, sim.time, sim.emitStart, sim.emitCount);+ v(1, s.max, s.seed, sim.frameDt, sparkMax);+ v(2, f.gravity[0], f.gravity[1], f.gravity[2], sim.sparkEmitStart);+ v(3, f.drag, f.noise.strength, f.noise.scale, f.noise.speed);++ const shapeId =+ s.emitter.shape === "box"+ ? 1+ : s.emitter.shape === "sphere"+ ? 2+ : s.emitter.shape === "shell"+ ? 3+ : s.emitter.shape === "ring"+ ? 4+ : s.emitter.shape === "disc"+ ? 5+ : 0;++ const ex = f.emitterPos ? f.emitterPos[0] : s.emitter.x;+ const ey = f.emitterPos ? f.emitterPos[1] : s.emitter.y;+ const ez = f.emitterPos ? f.emitterPos[2] : s.emitter.z;++ v(4, shapeId, ex, ey, ez);+ v(5, s.emitter.width, s.emitter.height, s.emitter.depth, s.emitter.radius);+ v(6, s.direction[0], s.direction[1], s.direction[2], s.spread);+ v(7, s.speed[0], s.speed[1], s.lifetime[0], s.lifetime[1]);++ const attractors = f.attractors.slice(0, SWARM_MAX_ATTRACTORS);+ v(8, s.angularSpeed[0], s.angularSpeed[1], s.variants, attractors.length);++ const attrStrengths = [0, 0, 0, 0, 0];+ for (let i = 0; i < attractors.length; i++) {+ const a = attractors[i];+ if (!a) continue;+ v(9 + i, a.x, a.y, a.z, a.radius ?? 0);+ attrStrengths[i] = a.strength;+ }+ v(+ 17,+ attrStrengths[0],+ attrStrengths[1],+ attrStrengths[2],+ attrStrengths[3],+ );++ if (f.vortex) {+ v(14, f.vortex.x, f.vortex.y, f.vortex.z, f.vortex.swirl);+ v(+ 15,+ f.vortex.axis[0],+ f.vortex.axis[1],+ f.vortex.axis[2],+ f.vortex.pull,+ );+ v(16, f.vortex.axial, f.vortex.radius, sim.sparkEmitCount, s.sizeJitter);+ } else {+ v(16, 0, 0, sim.sparkEmitCount, s.sizeJitter);+ }++ if (f.floor) {+ v(18, f.floor.y, f.floor.bounce, f.floor.friction, 1.0);+ } else {+ v(18, 0, 0, 0, 0);+ }++ v(19, s.size[0], s.size[1], s.fade[0], s.fade[1]);++ const heatSource =+ s.heat.source === "friction" ? 1 : s.heat.source === "speed" ? 2 : 0;+ v(20, s.meshRadius ?? 20, sim.sliceCount, heatSource, s.heat.maxSpeed);++ const colors = s.colors.slice(0, 3);+ v(21, colors.length, s.heat.curve, s.heat.intensity, attrStrengths[4]);+ for (let i = 0; i < colors.length; i++) {+ const c = colors[i];+ if (c) v(22 + i, c[0], c[1], c[2], c[3]);+ }++ v(+ 25,+ f.floor?.heatGain ?? 1.0,+ s.angularDrag,+ f.floor?.heatDecay ?? 0.45,+ 0,+ );+ v(26, s.heat.colors[0][0], s.heat.colors[0][1], s.heat.colors[0][2], 1);+ v(27, s.heat.colors[1][0], s.heat.colors[1][1], s.heat.colors[1][2], 1);+ v(28, s.heat.colors[2][0], s.heat.colors[2][1], s.heat.colors[2][2], 1);++ if (s.sparks) {+ v(+ 29,+ s.sparks.threshold,+ s.sparks.size[0],+ s.sparks.size[1],+ s.sparks.speed[0],+ );+ v(+ 30,+ s.sparks.lifetime[0],+ s.sparks.lifetime[1],+ s.sparks.intensity,+ s.sparks.speed[1],+ );+ v(31, s.sparks.color[0], s.sparks.color[1], s.sparks.color[2], 1.0);+ }+ }++ advance(+ state: Swarm3DState,+ config: Swarm3DStaticConfig,+ targetFrame: number,+ fps: number,+ frameSampler: (frame: number) => Swarm3DFrameInput,+ ): void {+ const { device } = state;+ const prewarmFrames = Math.max(0, Math.round((config.prewarm ?? 0) * fps));++ if (targetFrame < state.frame || state.frame < -prewarmFrames - 1) {+ let best = -999999;+ for (const k of state.snapshots.keys()) {+ if (k <= targetFrame && k > best) best = k;+ }+ const encoder = device.createCommandEncoder({+ label: "swarm3d_restore",+ });+ if (best >= 0) {+ const snap = state.snapshots.get(best);+ if (snap) {+ encoder.copyBufferToBuffer(+ snap.buffer,+ 0,+ state.particles,+ 0,+ state.totalParticleSlots * SWARM_PARTICLE_BYTES,+ );+ state.emitted = snap.emitted;+ state.carry = snap.carry;+ state.sparkEmitted = snap.sparkEmitted;+ state.sparkCarry = snap.sparkCarry;+ state.frame = best;+ }+ } else {+ encoder.clearBuffer(state.particles);+ encoder.clearBuffer(state.instances);+ state.emitted = 0;+ state.carry = 0;+ state.sparkEmitted = 0;+ state.sparkCarry = 0;+ state.frame = -1 - prewarmFrames;+ }+ device.queue.submit([encoder.finish()]);+ }++ const params = new Float32Array(SWARM_PARAM_VEC4S * 4);+ const substeps = Math.max(1, Math.round(config.substeps));+ const frameDt = 1 / fps;+ const dt = frameDt / substeps;++ const bindGroup = device.createBindGroup({+ layout: this.bindGroupLayout,+ entries: [+ { binding: 0, resource: { buffer: state.ubo } },+ { binding: 1, resource: { buffer: state.particles } },+ { binding: 2, resource: { buffer: state.instances } },+ ],+ });++ const workgroups = Math.ceil(state.totalParticleSlots / SWARM_WORKGROUP);+ const sparkMax = config.sparks?.max ?? 0;+ const sparkRate = config.sparks?.rate ?? 0;++ for (let f = state.frame + 1; f <= targetFrame; f++) {+ const input = frameSampler(Math.max(0, f));+ const targetEmits = input.rate * frameDt + state.carry;+ const totalEmits = Math.floor(targetEmits);+ state.carry = targetEmits - totalEmits;+ const perSubstep = Math.floor(totalEmits / substeps);+ let remainder = totalEmits % substeps;++ const targetSparkEmits =+ sparkMax > 0 ? sparkRate * frameDt + state.sparkCarry : 0;+ const totalSparkEmits = Math.floor(targetSparkEmits);+ state.sparkCarry = targetSparkEmits - totalSparkEmits;+ const sparkPerSubstep = Math.floor(totalSparkEmits / substeps);+ let sparkRemainder = totalSparkEmits % substeps;++ for (let s = 0; s < substeps; s++) {+ const count = perSubstep + (remainder > 0 ? 1 : 0);+ if (remainder > 0) remainder--;++ const emitStart = state.emitted % config.max;+ state.emitted += count;++ const sCount = sparkPerSubstep + (sparkRemainder > 0 ? 1 : 0);+ if (sparkRemainder > 0) sparkRemainder--;++ const sEmitStart = sparkMax > 0 ? state.sparkEmitted % sparkMax : 0;+ state.sparkEmitted += sCount;++ this.packParams(config, input, params, {+ dt,+ time: f * frameDt + s * dt,+ emitStart,+ emitCount: count,+ sparkEmitStart: sEmitStart,+ sparkEmitCount: sCount,+ frameDt,+ sliceCount: state.sliceCount,+ });++ device.queue.writeBuffer(state.ubo, 0, params);++ const encoder = device.createCommandEncoder({+ label: `swarm3d_step_${f}_${s}`,+ });+ const pass = encoder.beginComputePass();+ pass.setPipeline(this.simPipeline);+ pass.setBindGroup(0, bindGroup);+ pass.dispatchWorkgroups(workgroups);+ pass.end();+ device.queue.submit([encoder.finish()]);+ }++ state.frame = f;++ if (+ f >= 0 &&+ f % SWARM_SNAPSHOT_EVERY === 0 &&+ state.snapshots.size < SWARM_MAX_SNAPSHOTS+ ) {+ let snap = state.snapshots.get(f);+ if (!snap) {+ snap = {+ buffer: device.createBuffer({+ label: `swarm3d_snap_${f}`,+ size: state.totalParticleSlots * SWARM_PARTICLE_BYTES,+ usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,+ }),+ emitted: state.emitted,+ carry: state.carry,+ sparkEmitted: state.sparkEmitted,+ sparkCarry: state.sparkCarry,+ };+ state.snapshots.set(f, snap);+ }+ const snapEncoder = device.createCommandEncoder({+ label: `swarm3d_snap_save_${f}`,+ });+ snapEncoder.copyBufferToBuffer(+ state.particles,+ 0,+ snap.buffer,+ 0,+ state.totalParticleSlots * SWARM_PARTICLE_BYTES,+ );+ device.queue.submit([snapEncoder.finish()]);+ }+ }++ // Final pack instances compute pass for the rendered frame+ const packEncoder = device.createCommandEncoder({+ label: "swarm3d_pack_instances",+ });+ const packPass = packEncoder.beginComputePass();+ packPass.setPipeline(this.packPipeline);+ packPass.setBindGroup(0, bindGroup);+ packPass.dispatchWorkgroups(workgroups);+ packPass.end();+ device.queue.submit([packEncoder.finish()]);+ }++ destroyState(state: Swarm3DState): void {+ state.particles.destroy();+ state.instances.destroy();+ state.ubo.destroy();+ for (const snap of state.snapshots.values()) {+ snap.buffer.destroy();+ }+ state.snapshots.clear();+ }+}diff --git a/packages/webgpu-renderers/src/shaders/lighting3d.ts b/packages/webgpu-renderers/src/shaders/lighting3d.tsindex 9d440d3d..c6fc47b5 100644--- a/packages/webgpu-renderers/src/shaders/lighting3d.ts+++ b/packages/webgpu-renderers/src/shaders/lighting3d.ts@@ -44,6 +44,7 @@ struct LightsUniforms {shadowParams : vec4<f32>, // x = enabled, y = shadowed light index, z = softness (texels), w = map sizeshadowBias : vec4<f32>, // x = depth bias, y = normal offset (world px), z = darkness 0..1, w = unusedshadowMatrix : mat4x4<f32>,+ floorParams : vec4<f32>, // x = floorY, y = fadeDistance, z = isReflectionPass, w = unused};const PI = 3.14159265359;@@ -414,6 +415,17 @@ fn shadeSurfaceFull(worldPos: vec3<f32>, worldNormal: vec3<f32>, baseColor: vec3display = mix(display, lights.fog.rgb, f);hdr = hdr * (1.0 - f);}+ if (lights.floorParams.z > 0.5) {+ if (worldPos.y > lights.floorParams.x + 0.1) {+ discard;+ }+ if (lights.floorParams.y > 0.0) {+ let deltaY = max(0.0, lights.floorParams.x - worldPos.y);+ let fade = exp(-deltaY / lights.floorParams.y);+ display = display * fade;+ hdr = hdr * fade;+ }+ }out.display = linearToSrgb(display);out.hdr = hdr;return out;diff --git a/packages/webgpu-renderers/src/shaders/mesh3d.ts b/packages/webgpu-renderers/src/shaders/mesh3d.tsindex 5b63a458..f36a3b53 100644--- a/packages/webgpu-renderers/src/shaders/mesh3d.ts+++ b/packages/webgpu-renderers/src/shaders/mesh3d.ts@@ -17,7 +17,7 @@ struct ModelUniforms {modelMatrix : mat4x4<f32>,normalMatrix : mat4x4<f32>,colorTint : vec4<f32>,- params : vec4<f32>, // x = opacity, y = twoSided (1.0 = yes), z = isSkinned (1.0 = yes), w = reserved+ params : vec4<f32>, // x = opacity, y = twoSided (1.0 = yes), z = isSkinned (1.0 = yes), w = isInstanced (1.0 = yes)materialParams : vec4<f32>, // x = shininess, y = specularIntensity, z = ambientIntensity, w = materialMode (0=unlit, 1=lit, 2=toon)shade : vec4<f32>, // rgb = toon shadow-side color multiplier, a = alpha cutoff (0 = none)pbr : vec4<f32>, // x = roughness (<0 = default), y = metallic@@ -29,10 +29,18 @@ struct SkinningUniforms {jointMatrices : array<mat4x4<f32>, 128>,};+struct InstanceData {+ posScale : vec4<f32>, // xyz = translation, w = scale+ quat : vec4<f32>, // xyzw = unit rotation quaternion+ color : vec4<f32>, // rgba = color multiplier+ emissive : vec4<f32>, // rgb = sRGB emissive color, w = emissiveIntensity+};+@group(0) @binding(0) var<uniform> cam : CameraUniforms;@group(1) @binding(0) var<uniform> model : ModelUniforms;@group(1) @binding(1) var<uniform> skinning : SkinningUniforms;${matte3dWgsl(1, 2)}@group(1) @binding(3) var backdropTex : texture_2d<f32>;+@group(1) @binding(4) var<storage, read> instances : array<InstanceData>;@group(2) @binding(0) var texSampler : sampler;@group(2) @binding(1) var mainTex : texture_2d<f32>;@group(2) @binding(2) var normalTex : texture_2d<f32>;@@ -57,10 +65,19 @@ struct VertexOutput {@location(2) worldNormal : vec3<f32>,@location(3) linearDepth : f32,@location(4) color : vec4<f32>,+ @location(5) emissive : vec4<f32>,};+fn rotateVecByQuat(v: vec3<f32>, q: vec4<f32>) -> vec3<f32> {+ let t = 2.0 * cross(q.xyz, v);+ return v + q.w * t + cross(q.xyz, t);+}+@vertex-fn vs_main(in: VertexInput) -> VertexOutput {+fn vs_main(+ in: VertexInput,+ @builtin(instance_index) instanceIndex: u32,+) -> VertexOutput {var out: VertexOutput;var localPos = in.position;@@ -93,6 +110,23 @@ fn vs_main(in: VertexInput) -> VertexOutput {}}+ // Hardware instancing: transform local vertex by instance transform+ // Static read prevents Tint from dropping the storage buffer binding+ let dummyInst = instances[0].posScale.x;+ var instColor = vec4<f32>(1.0);+ var instEmissive = vec4<f32>(0.0);++ if (model.params.w > 0.5) {+ let inst = instances[instanceIndex];+ let scaledPos = localPos * inst.posScale.w;+ localPos = rotateVecByQuat(scaledPos, inst.quat) + inst.posScale.xyz;+ localNorm = rotateVecByQuat(localNorm, inst.quat);+ instColor = inst.color;+ instEmissive = inst.emissive;+ } else {+ localPos.x += dummyInst * 0.0;+ }+let worldPos4 = model.modelMatrix * vec4<f32>(localPos, 1.0);out.worldPos = worldPos4.xyz;@@ -101,7 +135,8 @@ fn vs_main(in: VertexInput) -> VertexOutput {out.clipPos = cam.viewProjMatrix * worldPos4;out.uv = in.uv;- out.color = in.color;+ out.color = in.color * instColor;+ out.emissive = instEmissive;out.linearDepth = dot(worldPos4.xyz - cam.cameraPos.xyz, cam.cameraDir.xyz);return out;@@ -258,6 +293,9 @@ fn shadeMesh(in: VertexOutput, isFront: bool) -> MeshFragment {if (lights.params.y >= 0.5) {toon = toonLighting(in, baseRgb);}+ if (model.params.w > 0.5 && (in.emissive.w > 0.0 || dot(in.emissive.rgb, in.emissive.rgb) > 0.0)) {+ toon += in.emissive.rgb * in.emissive.w;+ }out.color = vec4<f32>(toon * alpha, alpha);out.hdr = vec4<f32>(srgbToLinear(toon) * alpha, alpha);return out;@@ -289,6 +327,9 @@ fn shadeMesh(in: VertexOutput, isFront: bool) -> MeshFragment {// Linear multiply in display space is close enough for an 8-bit map.emissive = vec4<f32>(emissive.rgb * emissiveSample, emissive.w);}+ if (model.params.w > 0.5 && (in.emissive.w > 0.0 || dot(in.emissive.rgb, in.emissive.rgb) > 0.0)) {+ emissive = in.emissive;+ }let shaded = shadeSurfaceFull(in.worldPos, N, baseRgb, material, pbr, emissive);out.color = vec4<f32>(shaded.display * alpha, alpha);out.hdr = vec4<f32>(shaded.hdr * alpha, alpha);diff --git a/plugins/framefields/skills/framefields-compose/SKILL.md b/plugins/framefields/skills/framefields-compose/SKILL.mdindex d26f739d..f88c5a62 100644--- a/plugins/framefields/skills/framefields-compose/SKILL.md+++ b/plugins/framefields/skills/framefields-compose/SKILL.md@@ -104,7 +104,9 @@ All `Layer.*` builders return `AnimatableNode<T>` instances with chainable `.ani| `Layer.environment(preset, options)` | `"light"` | The 3D scene's world: studio image-based light, exposure, tone mapping, fog, bloom. **Adding one switches the scene to physically based shading.** See *3D Look* below. || `Layer.sequence(entries, options)` | `"box"` | Scenes back to back with `Transition`s between them; returns a box whose `totalFrames` is the length. See *Scenes & Transitions*. || `Layer.model(options)` | `"model3d"` | 3D mesh loader (`.gltf`, `.glb`, `.obj`, `.fbx`, `.stl`, `.ply`). Supports skinning and audio deformation compute shaders. |-| `Layer3D.roundedBox / sphere / cylinder(options)` | `"model3d"` | Procedural solid meshes, centered on `x`/`y`/`z` (y is down, so "top" is -y). `roundedBox`: `width`, `height`, `depth`, `radius`, `segments`, `taper` (top face scale, <1 for a keycap). `sphere`: `radius`. `cylinder`: `radius` or `radiusTop`/`radiusBottom`, `height`, `openEnded`. `color` is baked in; `tint` multiplies it and animates as the `color` prop. Surface: `roughness`, `metallic`, `emissive`, `emissiveIntensity`, `castShadow`. `wireframe: true` draws the mesh triangle edges as one-pixel lines, including triangulation and back edges. Equal shapes share one GPU buffer, so hundreds of copies are cheap. |+| `Layer3D.roundedBox / sphere / cylinder / shard(options)` | `"model3d"` | Procedural solid meshes, centered on `x`/`y`/`z` (y is down, so "top" is -y). `roundedBox`: `width`, `height`, `depth`, `radius`, `segments`, `taper`. `sphere`: `radius`. `cylinder`: `radius` or `radiusTop`/`radiusBottom`, `height`. `shard`: procedural flat-faceted polyhedron rock/crystal clipped against Fibonacci lattice normals (`radius`, `cuts`, `irregularity`, seed); builds automatic UVs and Rapier 3D hull collider. Surface: `color`, `tint`, `roughness`, `metallic`, `emissive`, `emissiveIntensity`, `castShadow`, `wireframe`. Shared GPU buffers cache identical shapes. |+| `Layer3D.instances(options)` | `"model3d"` | Hardware-instanced single or multi-variant mesh rendering in 1 GPU draw call. Options: `count`, `mesh` / `meshes` (array of Layer3D primitives or meshes), `instanceAt(index, frame): { position, rotation, scale, color, emissive }`, or bind directly to Rapier `Physics.world3d` bodies via `bodies: Body3D[]` with `emissiveBySpeed` and `colorRamp`. |+| `Layer3D.swarm(options)` | `"model3d"` | Continuous 3D GPU particle swarm with compute-driven physics, 3D curl turbulence, vortex/cyclone field (`swirl`, `pull`, `axial`), ground plane collisions with Coulomb sliding friction and rotational roll torque, kinetic heat accumulation/cooling, and zero-copy packing directly into GPU instance buffers. |---@@ -430,6 +432,7 @@ comp.add([rotation: 30, // turn the reflectionsfog: { color: BG, start: 2000, end: 5000 }, // surfaces fade into the background colorbloom: true, // or { intensity: 0.3, threshold: 1.6, radius: 6 }+ floor: { y: 200, color: "#111115", reflectivity: 0.8, roughness: 0.25, fadeDistance: 800 }, // glossy floor reflection}),Layer.directionalLight({ x: 400, y: -1200, z: -600, targetX: 960, targetY: 540, castShadow: true }),]);@@ -445,6 +448,7 @@ Layer3D.cylinder({ ..., color: "#111", emissive: "#4da3ff", emissiveIntensity: 3- **Fog** fades to `fog.color` exactly, so set it to the composition background for a seamless horizon.- **Models:** glTF materials bring base color, normal, metallic-roughness, occlusion and emissive maps; OBJ (`map_Kd`, `norm` in the `.mtl`) and FBX bring diffuse and normal maps, looked up next to the model. Textures must be PNG, JPEG, WebP, GIF, TIFF or AVIF: TGA, PSD, DDS and KTX2 are skipped with a warning (convert them). Draco / meshopt-compressed glTF files fail to load: re-export without mesh compression. Vertex colors (VOX, PLY, OFF, glTF `COLOR_0`) multiply the base color.- **Model orientation:** the world is y-down, so a y-up model (most glTF, OBJ and FBX files) needs `rotateX: 180` to stand upright.+- **Planar reflective floor:** `floor: { y, color, reflectivity, roughness, fadeDistance, opacity }` renders an exact mirrored-camera reflection pass with subterranean fragment clipping, 2-pass anisotropic roughness blur ($\sigma_y \approx 3.5 \sigma_x$ along the reflection axis), Schlick Fresnel grazing angle boost, linear distance fade, and HDR radiance bloom output.- `emissive` / `emissiveIntensity` / `exposure` animate like any prop (`.keys("emissiveIntensity", …)`).- **Transparent 3D meshes:** glTF `BLEND` materials and meshes with reduced opacity draw after opaque scene items, sorted back to front by each mesh's bounds center without writing depth. This is an object-level approximation: intersecting or self-overlapping meshes cannot always sort correctly; translucent flat layers and glass use separate rendering paths.- **Glass:** `material: "glass" | "acrylic" | "frosted"` on any Layer3D primitive, extruded text (`Layer3D.extrudedText`) or model refracts whatever is behind it on screen — the video, 2D layers, particles — with a rainbow fringe (`dispersion`, default 0.04), bend strength `thickness` (px, default 80) and `ior` (1.5). `color` tints the glass (deeper toward the edges); `frosted` blurs by `roughness`. Glass needs no environment: it draws its own studio reflections, and against a dark grade it reads best — skip `Lighting.*` rigs for glass-only scenes (their environment washes glass out). Glass shows only 2D content and opaque 3D drawn before it, not other glass.@@ -490,7 +494,7 @@ stage.animate(LayerAnimation.create().signal("y", world.impact, { multiplier: 14- Live worlds bind signals only (no `bakeKeyframes()`); `await world.advanceTo(frame)` steps one without rendering (e.g. to read `collisions`).- **Particles:** for clouds, dust, sparks, fluids and flow fields use `Layer.particles` (GPU, below), not hundreds of physics bodies. Keep physics bodies for a few dozen things that must collide and stack (cards, letters, products).- **Keyframes instead of signals:** `world.bakeKeyframes({ tolerance: 0.25 })` in place of `simulate()` writes plain, simplified linear keyframes (editable, plain JSON).-- **3D:** `Physics.world3d` takes `Layer3D.roundedBox / sphere / cylinder` and models (convex hull of the mesh); same options with 3-vectors, `world.hinge(a, b, at, axis)`, `world.walls({ width, height, depth })`.+- **3D:** `Physics.world3d` takes `Layer3D.roundedBox / sphere / cylinder / shard` and models (convex hull of the mesh); same options with 3-vectors, `world.hinge(a, b, at, axis)`, `world.walls({ width, height, depth })`. Use `Layer3D.instances({ count: bodies.length, mesh: Layer3D.shard({ radius: 24 }), bodies, emissiveBySpeed: { speedThreshold: 200, maxSpeed: 1200, color: "#ff5511", intensity: 4 } })` to render hundreds of physics bodies in a single GPU draw call.- **Timing:** signals are on the composition clock. In a scene that starts at frame `S`, pass `startFrame: S` to the world. Before it and after `frames` the signals hold their first/last value. Add every body, joint and force before `simulate()` (or before reading any signal): the world then locks.- **Feel:** gravity 2400 px/s² reads snappy on a 1080p canvas; `pixelsPerMeter` (100) scales how heavy things feel. Raise `substeps` (4) for tall stacks or thin, fast bodies.- Install note: physics uses the optional dependency `@dimforge/rapier2d-deterministic-compat` / `rapier3d-deterministic-compat` (installed by default with framefields).@@ -522,6 +526,7 @@ comp.add(Layer.particles({- `emitter.x` / `emitter.y`, `rate`, `gravity`, `drag`, `noise.strength`, attractor positions/strengths and `push` strengths take a number, a signal (audio, physics `impact`) or `(frame) => value`, read every frame: bursts on the beat, wind gusts, an attractor following a tracked hand (`person.point("rightWrist", f)`). `emitter.bursts: [{ frame, count }]` adds one-off explosions.- Recipes: **light painting** an additive `"soft"` point emitter whose `x`/`y` follow a tracked wrist (`(f) => person.point("rightWrist", f).x`), lifetime ~1 s, small speed, births spread along the hand's path so fast moves stay continuous; **sparks/fountain** `shape: "spark"`, `blend: "add"`, gravity, `floor`; **smoke/ink** `shape: "soft"`, low opacity, `noise`, sizes growing; **snow/dust** `rect` emitter above the frame, small gravity, `noise`, `bounds: "wrap"`; **swirl** `ring` emitter + attractor + `colorBySpeed`; **fluid around a dancer** `push: { person }` + `drag` 2 + gentle noise, and a vision cutout of the clip above the particle layer.- The system steps as frames render and snapshots itself every 24 frames, so scrubbing back restores instead of replaying from the start; the same GPU gives the same frames.+- For 3D debris, tumbling rocks, and glowing sparks interacting with a floor plane and 3D vortex forces, use `Layer3D.swarm` to simulate and render polyhedral shards directly on the GPU.---diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 498e06f9..aceef795 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -476,6 +476,28 @@ importers:specifier: ^4.1.11version: 4.1.11(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected](@noble/[email protected])([email protected]))([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected])([email protected]))+ examples/31_shard_storm:+ dependencies:+ framefields:+ specifier: workspace:*+ version: link:../../packages/framefields+ devDependencies:+ '@framefields/tsconfig':+ specifier: workspace:*+ version: link:../../packages/tsconfig+ '@types/node':+ specifier: ^24.1.0+ version: 24.10.14+ tsx:+ specifier: ^4.20.3+ version: 4.21.0+ typescript:+ specifier: ^5.8.3+ version: 5.9.3+ vitest:+ specifier: ^4.1.11+ version: 4.1.11(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected](@noble/[email protected])([email protected]))([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected])([email protected]))+nodes/node-apply-lut:dependencies:'@framefields/core':diff --git a/specs/3d-shards.md b/specs/3d-shards.mdnew file mode 100644index 00000000..358dec95--- /dev/null+++ b/specs/3d-shards.md@@ -0,0 +1,443 @@+# Spec: 3D Shards, Instanced 3D Mesh Swarm & Floor Reflections++## Goal++Extend Framefields' 3D engine with general-purpose primitives and GPU pipelines forfaceted polyhedral geometry (`Layer3D.shard`), high-count 3D mesh/particle simulations (`Layer3D.swarm`), instanced 3D rigid-body rendering (`Layer3D.instances`), and glossy ground reflections (`floor` on `Layer.environment`).++All additions are first-class, reusable engine primitives that compose with existing `Camera3D`, `Light3D`, `Layer.environment` (GGX PBR + IBL + HDR bloom + fog + shadows), `Physics.world3d` (Rapier), `Signal`, `comp.vision`, and `CompositorProgramSchema`.++---++## Architectural Pillars++1. **`Layer3D.shard(options)`** — Procedural flat-faceted convex polyhedron primitive in `primitive-geometry.ts` and `Layer3D`.+2. **`Layer3D.instances(options)`** — Single-draw-call hardware-instanced 3D mesh batch node (`Model3DNode` / `Renderer3D`) for rendering hundreds or thousands of 3D meshes driven by `Physics.world3d` or procedural callbacks without layout-tree overhead.+3. **`Layer3D.swarm(options)`** — GPU compute-simulated 3D particle & mesh-shard system rendered natively inside `Renderer3D` (participating in 3D camera projection, depth buffer, GGX PBR lighting, shadow receiving, and HDR bloom) with 3D forces (curl noise, attractors, vortex/swirl, floor friction, and `comp.vision` silhouette push) and dynamic kinetic shading (`emissiveBySpeed`, `emissiveByContact`, secondary spark emission).+4. **`Environment.floor` (Planar Glossy Floor Reflection)** — Scene-wide ground plane reflection in `Renderer3D` / `Layer.environment` with anisotropic roughness blur and Fresnel falloff.++---++## 1. Procedural Faceted Polyhedron Primitive: `Layer3D.shard`++### Motivation+`primitive-geometry.ts` currently provides smooth primitives (`roundedBox`, `sphere`, `cylinder`). Authors need a general-purpose faceted geometric primitive for crystals, low-poly debris, fractured glass, asteroids, Voronoi-like shards, and abstract faceted motion graphics.++### Geometry Algorithm (`packages/webgpu-renderers/src/renderer3d/primitive-geometry.ts`)+Add `ShardGeometryOptions` (`type: "shard"`) to `PrimitiveGeometryOptions`:++```ts+export interface ShardGeometryOptions extends PrimitiveSurface {+ type: "shard";+ /** Approximate bounding radius (or half-extents when aspect/scale is used). Default 50. */+ radius?: number;+ /** Optional non-uniform half-extents [hx, hy, hz]; overrides `radius` per axis. */+ size?: [number, number, number];+ /** Number of clipping half-space planes that carve the convex polyhedron (6..48). Default 14. */+ facets?: number;+ /** Deterministic PRNG seed for plane normals and depths. Default 1. */+ seed?: number;+ /** How unevenly planes cut toward the center, 0..0.85 (0 = regular polyhedron, 0.5 = jagged shard). Default 0.35. */+ irregularity?: number;+ /** Bevel / chamfer fraction along edges, 0..0.3 (0 = razor-sharp flat facets). Default 0. */+ bevel?: number;+}+```++#### Construction (Deterministic Convex Half-Space Clipping)+1. Start from a bounding cube of half-extents `[hx, hy, hz]` (derived from `size ? [size[0]/2, size[1]/2, size[2]/2] : [radius, radius, radius]`).+2. Generate `facets` quasi-uniformly distributed unit normals $\hat{n}_k$ on the sphere using a seeded Fibonacci lattice perturbed by PCG hash jitter (`seed`, `irregularity`).+3. For each plane $k$, choose signed distance $d_k = r_k \cdot (1 - \text{irregularity} \cdot \text{rnd}(k, \text{seed}))$ where $r_k$ is the support radius along $\hat{n}_k$.+4. Iteratively clip the convex polygon soup against each half-space $\hat{n}_k \cdot \mathbf{x} \le d_k$ (Sutherland–Hodgman 3D convex polyhedron clipping):+ - Clip each existing polygon face against the plane.+ - Collect the intersection loop vertices on the clipping plane, sort them counter-clockwise around $\hat{n}_k$, and add the new cap polygon face.+5. **Recenter & Normalize**:+ - Compute the centroid of the resulting polyhedron and shift all vertices so the mesh origin is `[0, 0, 0]`. Rescale so the bounding box matches the requested `radius` / `size`.+6. **Flat-Faceted Normal & UV Generation**:+ - Emit separate vertices per face (no normal averaging across sharp edges) so every facet has a crisp, flat geometric normal $\hat{n}_{\text{face}}$ that catches specular and environment highlights cleanly.+ - Compute planar tangent-space UVs `[u, v]` per face in `[0, 1]`.+7. **Caching & Rapier Integration**:+ - Cached via `getPrimitiveGeometry(options)` by JSON key (identical `(radius, facets, seed, irregularity)` share one `GPUMeshBuffers` allocation).+ - In `Physics.world3d` (`packages/framefields/src/physics/world3d.ts`), `colliderShape3D` automatically falls through to `hull()` (`meshPoints(t.modelData)`), giving every `Layer3D.shard` an exact Rapier 3D `convexHull` collider out of the box.++### Public SDK (`packages/framefields/src/shapes3d.ts`)+```ts+export type Shard3DOptions = Primitive3DNodeOptions &+ Omit<ShardGeometryOptions, "type" | "color" | "material">;++Layer3D.shard(options: Shard3DOptions): AnimatableNode<Model3DNode>+```+Supports all `Primitive3DNodeOptions` (`material: "lit" | "unlit" | "toon" | "glass" | "acrylic" | "frosted" | "metallic"`, `roughness`, `metallic`, `emissive`, `emissiveIntensity`, `castShadow`, `wireframe`, `tint`).++---++## 2. Hardware-Instanced 3D Meshes: `Layer3D.instances`++### Motivation+Currently, rendering $N$ 3D meshes requires $N$ `Model3DNode` items in `layout`, $N$ model matrices computed on the CPU and uploaded to $N$ uniform buffers from `BufferPool`, and $N$ separate `pass.drawIndexed` calls. For $N \ge 200$ (e.g., a `Physics.world3d` simulation of 500 shards or an architectural grid of 1,000 elements), layout/schema/draw-call overhead dominates.++### Renderer3D Instancing (`packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.ts`)+Extend `Mesh3DPipeline` with an instanced draw path:++#### Instance Storage Buffer Layout (`64 bytes` = `4 × vec4<f32>` per instance)+```wgsl+struct InstanceData {+ posScale : vec4<f32>, // xyz = world position, w = uniform scale (or pack non-uniform scale)+ quat : vec4<f32>, // xyzw = unit rotation quaternion+ color : vec4<f32>, // rgba = per-instance linear/sRGB color multiplier+ emissive : vec4<f32>, // rgb = per-instance emissive color, w = emissiveIntensity + variant bits+};+```+- Bound as `@group(1) @binding(4) var<storage, read> instances : array<InstanceData>;` (with a 1-element dummy buffer bound when `useInstancing == 0`, honoring the WGSL rule that every declared binding is statically used in `vs_main`).+- In `vs_main`: when `model.params.w > 0.5` (instanced mode), transform `localPos` and `localNorm` by `instances[instanceIndex].quat` and `instances[instanceIndex].posScale` before applying `model.modelMatrix`, and pass `instances[instanceIndex].color` and `instances[instanceIndex].emissive` to the fragment shader via `VertexOutput`.+- Works seamlessly with:+ - Shadow map pass (`pipelineShadow` also reads `instances[instanceIndex]` so all instances cast shadows in a single instanced draw call).+ - MSAA, Depth of Field (`linearDepth` MRT), and HDR Bloom (`hdr` MRT).+ - Multi-variant meshes: if `variants: Model3DData[]` (e.g. 8 seeded `Layer3D.shard` meshes) are supplied, instances are bucketed by `variantIndex = i % variants.length`, issuing at most `variants.length` instanced draw calls (`drawIndexed(indexCount, instanceCount)`).++### Public SDK (`Layer3D.instances`)+```ts+export interface InstanceTransform3D {+ x: number;+ y: number;+ z: number;+ /** Euler degrees [rx, ry, rz] or unit quaternion [qx, qy, qz, qw]. */+ rotation?: [number, number, number] | [number, number, number, number];+ scale?: number | [number, number, number];+ color?: string | [number, number, number, number];+ emissive?: string | [number, number, number];+ emissiveIntensity?: number;+}++export interface Instances3DOptions extends Surface3DOptions {+ id?: string;+ /** One mesh node/primitive, or an array of mesh variants distributed across instances. */+ mesh: AnimatableNode<Model3DNode> | Array<AnimatableNode<Model3DNode>>;+ /** Count of instances when driven by `instanceAt` or `bodies`. */+ count?: number;+ /** Bind directly to Physics.world3d rigid bodies. */+ bodies?: readonly PhysicsBody3D[];+ /** Per-frame callback `(index, frame, fps) => InstanceTransform3D` (or Float32Array batch). */+ instanceAt?: (index: number, frame: number, fps: number) => InstanceTransform3D;+ /** Optional speed/impact-to-emissive mapping when bound to `bodies`. */+ emissiveBySpeed?: { color: string | string[]; maxSpeed: number; intensity?: number };+ emissiveByImpact?: { color: string; intensity?: number };+ material?: MaterialType;+ roughness?: number;+ metallic?: number;+ specularIntensity?: number;+ startFrame?: number;+ durationFrames?: number;+}+```++---++## 3. GPU 3D Swarm & Shard Simulation: `Layer3D.swarm`++### Motivation+`Layer.particles` (`nodes/node-particles`) is a 2D screen-space particle system (`pos: vec2<f32>`). It does not know about `Camera3D`, 3D depth occlusion, 3D lighting, or 3D mesh orientations.+To simulate thousands of 3D shards and secondary sparks with real-time 3D forces, floor friction, angular tumbling, and velocity/contact-driven HDR emission inside the 3D scene pass, we introduce `Layer3D.swarm` (backed by `Swarm3DPipeline` in `packages/webgpu-renderers/src/renderer3d/swarm3d-pipeline.ts`).++### GPU State & Compute Simulation (`Swarm3DPipeline`)++#### Particle State Struct (`64 bytes` per 3D particle in `GPUBuffer`)+```wgsl+struct SwarmParticle3D {+ pos : vec3<f32>, // world-space position (px, y down)+ age : f32, // seconds alive+ vel : vec3<f32>, // world-space velocity (px/s)+ life : f32, // total lifetime (seconds; <= 0 means dead)+ quat : vec4<f32>, // unit orientation quaternion+ angVel : vec3<f32>, // angular velocity (rad/s)+ heat : f32, // smoothed kinetic/friction heat [0..1+]+ scale : f32, // size multiplier (with jitter)+ variant : u32, // mesh variant index (0..N-1) or spark flag (0xFFFFFFFFu)+ seed : u32, // per-particle deterministic random id+ contact : f32, // floor/surface contact factor [0..1] this step+};+```++#### Deterministic Stepping & Scrubbing Snapshots+Follows the proven architecture of `nodes/node-particles`:+- Steps forward on the GPU with `substeps` per frame (default `2`) and optional `prewarm` seconds before `startFrame`.+- Saves GPU buffer snapshots every `24` frames (`SNAPSHOT_EVERY = 24`, up to `64` snapshots) so scrubbing backward in preview or non-sequential frame rendering restores the nearest snapshot and replays at most 23 frames.++#### 3D Forces & Collision Solver in `SIM_3D_WGSL`+1. **Emitters (`emitter`)**:+ - Shapes in 3D: `"point"`, `"box"`, `"sphere"`, `"shell"`, `"ring"`, `"disc"`, `"cone"`.+ - Position `[x, y, z]` and `rate` accept `PhysicsDriver` (number, `Signal`, or `(frame) => number`) for moving 3D emitters and beat bursts.+2. **3D Curl Noise (`noise`)**:+ - True 3D divergence-free curl of a 3D FBM vector potential $\nabla \times \mathbf{\Psi}(\mathbf{p} / \text{scale} + \mathbf{v}_{\text{time}} t)$ for organic 3D turbulence.+3. **3D Attractors & Vortex / Swirl Fields (`attractors`, `vortex`)**:+ - Point/sphere attractors & repellers in 3D: `{ x, y, z, strength, radius }` (up to 8, drivers supported).+ - **3D Vortex / Orbit (`vortex`)**: `{ x, y, z, axis: [ax, ay, az], swirl, pull, axial, radius, falloff }`:+ - Tangential acceleration around `axis` (`swirl` px/s²), radial inward/outward pull toward the axis or center (`pull` px/s²), and axial lift (`axial` px/s²). This drives cohesive 3D cyclones, orbital streams, and sweeping swarms without hand-keyed paths.+4. **Floor Collision, Sliding Friction & Angular Tumble (`floor`)**:+ - Plane at `y = floor.y` (or arbitrary normal `[nx, ny, nz]`).+ - When `p.pos.y + radius > floor.y`:+ - Project out of floor; reflect normal velocity with `bounce` (restitution).+ - Apply Coulomb/exponential tangential **sliding friction**: $\mathbf{v}_{\parallel} \leftarrow \mathbf{v}_{\parallel} \cdot \exp(-\mu_{\text{friction}} \cdot \Delta t)$.+ - **Friction-induced torque**: sliding along the floor induces angular velocity $\boldsymbol{\omega} \leftarrow \boldsymbol{\omega} + (\hat{n} \times \mathbf{v}_{\parallel}) / r$, making shards physically roll and tumble when scraping the ground.+ - **Friction heat accumulation**: `p.heat` increases proportionally to $|\Delta \mathbf{v}_{\text{friction}}|$ and floor contact speed, and decays exponentially over `heatDecay` seconds (`p.heat *= exp(-dt / heatDecay)`).+5. **Performer 3D Silhouette Push (`push`)**:+ - Reuses `PersonTrack.silhouetteGrid(frame)` from `comp.vision`, pushing 3D particles within a configurable depth slab `zRange: [zMin, zMax]` away from the performer's 2D silhouette gradient and imparting `heat` on impact.+6. **Quaternion Integration**:+ - Updates `p.quat = normalize(p.quat + 0.5 * dt * quatMul(vec4(p.angVel, 0.0), p.quat))` with `angularDrag`.++#### Dual-Mode Rendering in `Renderer3D` (Shards + Secondary Sparks)+A `Layer3D.swarm` can render:+1. **3D Mesh Shards**: Instanced draw of `mesh` variants (default: 8 seeded `Layer3D.shard` geometries) using `Mesh3DPipeline`'s instanced path.+ - Base material uses scene lighting & `Layer.environment` PBR (`color`, `roughness`, `metallic`).+ - **Dynamic Emissive Modulation**: Each shard's emissive radiance is computed in the shader from:+ - `emissiveBySpeed`: ramps emissive color & HDR intensity by `length(p.vel) / maxSpeed`.+ - `emissiveByHeat`: ramps emissive color & HDR intensity by `p.heat` (floor friction + high-acceleration turns + vision push).+ - Color ramp supports multi-stop gradients (e.g. `["#1a161b", "#a8006b", "#ff1aff", "#ffffff"]` with `emissiveIntensity: 6`), feeding directly into `Renderer3D`'s HDR bloom attachment (`hdrTexture`).+2. **Secondary Friction / Trail Sparks (`sparks`)**:+ - Optional companion buffer (or partitioned tail of the particle buffer) spawned where parent shards have high `heat` or `contact > 0` (or high speed).+ - Rendered in the same 3D pass as camera-facing 3D capsules/streaks stretched along `cam.viewProjMatrix * vel`, depth-tested against the shards and writing into both display color and HDR bloom.++### Public SDK (`packages/framefields/src/swarm3d.ts`)+```ts+export interface Swarm3DOptions extends Surface3DOptions {+ id?: string;+ startFrame?: number;+ durationFrames?: number;+ /** Maximum 3D mesh particles alive at once (default 2000, up to 100000). */+ max?: number;+ seed?: number;+ /**+ * Geometry drawn per particle:+ * - `"shard"` (default: 8 procedural shard variants)+ * - `{ type: "shard", variants?: number, facets?: number, irregularity?: number }`+ * - `"sphere" | "roundedBox" | "cylinder"`+ * - `AnimatableNode<Model3DNode> | Array<AnimatableNode<Model3DNode>>`+ */+ mesh?:+ | "shard"+ | "sphere"+ | "roundedBox"+ | "cylinder"+ | { type: "shard"; variants?: number; facets?: number; irregularity?: number; bevel?: number }+ | AnimatableNode<Model3DNode>+ | Array<AnimatableNode<Model3DNode>>;+ /** Particle radius/scale in px at birth -> death (default [18, 12]). */+ size?: number | [number, number];+ sizeJitter?: number;+ fade?: [number, number];+ emitter?: {+ shape?: "point" | "box" | "sphere" | "shell" | "ring" | "disc";+ x?: PhysicsDriver;+ y?: PhysicsDriver;+ z?: PhysicsDriver;+ width?: number;+ height?: number;+ depth?: number;+ radius?: number;+ rate?: PhysicsDriver;+ bursts?: Array<{ frame: number; count: number }>;+ };+ lifetime?: number | [number, number];+ speed?: number | [number, number];+ direction?: [number, number, number];+ spread?: number;+ angularSpeed?: number | [number, number];+ angularDrag?: PhysicsDriver;+ gravity?: PhysicsDriver | [PhysicsDriver, PhysicsDriver, PhysicsDriver];+ drag?: PhysicsDriver;+ noise?: {+ strength?: PhysicsDriver;+ scale?: number;+ speed?: number;+ };+ attractors?: Array<{+ x: PhysicsDriver;+ y: PhysicsDriver;+ z: PhysicsDriver;+ strength: PhysicsDriver;+ radius?: number;+ }>;+ vortex?: {+ x?: PhysicsDriver;+ y?: PhysicsDriver;+ z?: PhysicsDriver;+ axis?: [number, number, number];+ /** Tangential swirl acceleration (px/s²). */+ swirl?: PhysicsDriver;+ /** Radial pull toward the vortex center/axis (px/s²). */+ pull?: PhysicsDriver;+ /** Axial acceleration along `axis` (px/s²). */+ axial?: PhysicsDriver;+ radius?: number;+ };+ push?: {+ person: PersonTrack;+ strength?: PhysicsDriver;+ sweep?: PhysicsDriver;+ zRange?: [number, number];+ };+ floor?: {+ y: number;+ bounce?: number;+ /** Sliding friction damping (0 = ice, 3 = rough stone). Default 1.5. */+ friction?: PhysicsDriver;+ /** How strongly floor scraping & sharp acceleration build up `heat`. Default 1.0. */+ heatGain?: number;+ /** Seconds for friction/acceleration heat to cool down. Default 0.45. */+ heatDecay?: number;+ };+ /** Base surface color (default "#232026"). */+ color?: string | string[];+ roughness?: number;+ metallic?: number;+ /** Dynamic HDR emission driven by particle speed and/or friction heat. */+ heat?: {+ /** Source driver: `"friction"` | `"speed"` | `"both"` (default `"both"`). */+ source?: "friction" | "speed" | "both";+ /** Speed (px/s) that reaches full heat=1 when source includes speed (default 900). */+ maxSpeed?: number;+ /** Emissive color ramp from cool (0) to hot (1). */+ color: string | string[];+ /** Peak HDR emissiveIntensity at heat = 1 (feeds bloom when > 2.5). Default 5.0. */+ intensity?: PhysicsDriver;+ /** Power curve shaping the heat ramp (default 1.6). */+ curve?: number;+ };+ /** Optional secondary fine sparks spawned from hot/scraping shards in 3D. */+ sparks?: {+ max?: number;+ rate?: number;+ /** Minimum shard heat [0..1] required to shed sparks (default 0.25). */+ threshold?: number;+ size?: number | [number, number];+ lifetime?: number | [number, number];+ speed?: number | [number, number];+ stretch?: number;+ color?: string | string[];+ intensity?: number;+ };+ substeps?: number;+ prewarm?: number;+}+```++---++## 4. Glossy Reflective Floor in `Renderer3D` (`Environment.floor`)++### Motivation+In 3D motion graphics and VFX shots (product stages, glowing shards on dark polished stone/acrylic, neon typography over wet ground), a glossy floor that reflects the 3D scene above it—especially bright HDR emissives—grounds the entire shot in 3D space.++### Design (`packages/webgpu-renderers/src/math3d/environment3d.ts` & `Renderer3D`)+Extend `Environment3DOptions` and `LightNode` (`lightType: "environment"`) with an optional `floor` configuration:++```ts+export interface Environment3DFloor {+ /** World Y coordinate of the floor plane (px, y down). */+ y: number;+ /** Base floor surface color (default "#08070a"). */+ color?: string;+ /** Mirror reflectivity at normal incidence / Fresnel scale, 0..1 (default 0.35). */+ reflectivity?: number;+ /** Surface roughness 0..1: controls anisotropic vertical/horizontal reflection blur (default 0.35). */+ roughness?: number;+ /** Reflection fade-out distance from the floor plane in world Y px (default 900). */+ fadeDistance?: number;+ /** Optional overall opacity of the floor plane, 0..1 (default 1; 0 draws only the additive reflection over background). */+ opacity?: number;+}+```++### Rendering Technique (Planar Reflection + Anisotropic Roughness Blur)+Why planar reflection instead of screen-space reflection (SSR)?+- In `Renderer3D`, the scene geometry (`pending3DItems`: meshes, quads, slugs, and `swarm` instances) is already collected in `flush3DPass`.+- SSR fails whenever an object near the floor occludes what is behind it or when camera pitch changes, and requires G-buffer normals.+- **Planar Reflection Pass** in `Renderer3D`:+ 1. Construct the reflected `Camera3D` pose by mirroring `camera.eye` and `camera.target` across the horizontal plane $y = y_{\text{floor}}$ (and flipping the Y scale / winding or clipping vertices with $y > y_{\text{floor}}$ via a clip distance check in the shader).+ 2. Render the reflected 3D items at **half resolution** (`width / 2`, `height / 2`) into a pooled temporary reflection texture (`rgba16float` when bloom/HDR is active, so HDR emissive shards reflect at full HDR radiance before tone mapping).+ 3. Apply a **separable 2-pass roughness blur** (`FloorReflectionPipeline`) where vertical blur radius is stretched relative to horizontal blur ($\sigma_y \approx 3.5 \cdot \sigma_x \cdot \text{roughness}$), matching the physical elongated reflection lobes of a grazing-angle rough floor.+ 4. Composite the floor plane in the 3D pass (or immediately before bloom) with Fresnel grazing boost and vertical distance attenuation $\exp(-\Delta y / \text{fadeDistance})$, writing into both display and `hdr` targets so hot reflections also bloom naturally.++---++## 5. Schema, Compiler & Lint Integration++To satisfy `CompositorProgramSchema` (`.strict()`) and all engine invariants:++1. **`packages/compositions/src/program/schema.ts`**:+ - Add `EnvironmentFloorSchema` to `LightNodeSchema` (`floor?: EnvironmentFloor`).+ - Extend `Model3DNodeSchema` with `instances3d?: unknown` and `swarm3d?: unknown` (similar to `primitive3d` and `text3dOptions`) so `comp.toSpec()` serializes and validates cleanly.+ - Add `"shard"` to `PrimitiveGeometryOptions` validation/types.+2. **`packages/compositions/src/program/lint.ts`**:+ - Warn if `Layer3D.swarm` uses `heat.intensity > 2.5` without an active `Layer.environment({ bloom: true })` when bloom is expected, or if `floor.y` is outside the camera frustum.+3. **`nodes/node-compositor/SKILL.md` & `plugins/framefields/skills/framefields-compose/SKILL.md`**:+ - Document `Layer3D.shard`, `Layer3D.instances`, `Layer3D.swarm`, and `Layer.environment(..., { floor })`.+ - Keep `packages/compositions/src/program/skillmd-check.test.ts` green.++---++## 6. Implementation Plan & Phases++### Phase 1: `Layer3D.shard` Procedural Geometry & Physics Collider+- **Files**:+ - `packages/webgpu-renderers/src/renderer3d/primitive-geometry.ts`+ - `packages/framefields/src/shapes3d.ts`+ - `packages/framefields/src/physics/world3d.ts`+- **Deliverables**:+ - Deterministic 3D half-space convex polyhedron clipper (`shard(o, mb)`).+ - Flat-faceted normals, UVs, centered bounds, and `getPrimitiveGeometry` caching.+ - `Layer3D.shard(options)` builder exported on `Layer3D`.+ - Unit & visual tests in `packages/webgpu-renderers/src/renderer3d/primitive-geometry.test.ts` verifying watertight convex geometry, outward normals, deterministic seed output, and Rapier `Physics.world3d` hull collision.++### Phase 2: Hardware-Instanced 3D Meshes (`Mesh3DPipeline` + `Layer3D.instances`)+- **Files**:+ - `packages/webgpu-renderers/src/shaders/mesh3d.ts`+ - `packages/webgpu-renderers/src/renderer3d/mesh3d-pipeline.ts`+ - `packages/webgpu-renderers/src/renderer3d/shadow-pipeline.ts`+ - `packages/webgpu-renderers/src/renderer3d/renderer3d.ts`+ - `packages/compositions/src/program/schema.ts`+ - `nodes/node-compositor/src/renderers/webgpu-renderer.ts`+ - `packages/framefields/src/shapes3d.ts`+- **Deliverables**:+ - Storage buffer `@group(1) @binding(4)` for per-instance `(posScale, quat, color, emissive)` in `mesh3d.wgsl` and shadow depth shader.+ - `r3d.drawMesh3DInstanced(...)` supporting multi-variant mesh buckets in 1 draw call per variant.+ - `Layer3D.instances({ mesh, count, bodies, instanceAt, emissiveBySpeed })`.+ - Unit & GPU render tests verifying 1,000 instanced shards with per-instance color/emissive and shadow casting.++### Phase 3: GPU 3D Swarm & Secondary Sparks (`Swarm3DPipeline` + `Layer3D.swarm`)+- **Files**:+ - `packages/webgpu-renderers/src/renderer3d/swarm3d-pipeline.ts` (new)+ - `packages/webgpu-renderers/src/renderer3d/renderer3d.ts`+ - `packages/compositions/src/program/schema.ts`+ - `nodes/node-compositor/src/renderers/webgpu-renderer.ts`+ - `packages/framefields/src/swarm3d.ts` (new)+ - `packages/framefields/src/index.ts`+- **Deliverables**:+ - WGSL 3D compute simulator (`SIM_3D_WGSL`): 3D emitters, 3D curl noise, 3D attractors, 3D vortex (`swirl`, `pull`, `axial`), floor plane collision with Coulomb sliding friction, friction-induced angular torque, heat accumulation/decay, and `comp.vision` silhouette push.+ - Snapshot ring (`SNAPSHOT_EVERY = 24`) for deterministic scrubbing.+ - Instanced 3D shard rendering with `heat` colour/emissive ramp into `Renderer3D`'s PBR + HDR bloom pass.+ - Secondary 3D spark emission and velocity-stretched 3D capsule rendering in the same pass.+ - Headless GPU tests verifying deterministic stepping, snapshot restore, floor friction heat buildup, and HDR bloom output.++### Phase 4: Glossy Floor Reflection (`Environment.floor`)+- **Files**:+ - `packages/webgpu-renderers/src/math3d/environment3d.ts`+ - `packages/webgpu-renderers/src/renderer3d/floor-reflection-pipeline.ts` (new)+ - `packages/webgpu-renderers/src/renderer3d/renderer3d.ts`+ - `packages/compositions/src/program/schema.ts`+ - `nodes/node-compositor/src/renderers/webgpu-renderer.ts`+- **Deliverables**:+ - Half-res mirrored-camera planar reflection pass in `Renderer3D` (clipped above `floor.y`).+ - Anisotropic vertical/horizontal roughness blur and Fresnel-weighted floor composite writing to both display and HDR bloom buffers.+ - GPU render tests verifying reflections of emissive 3D shards and bloom integration.++### Phase 5: Docs, Skills & End-to-End Verification+- **Files**:+ - `nodes/node-compositor/SKILL.md`+ - `plugins/framefields/skills/framefields-compose/SKILL.md`+- **Verification Ladder**:+ 1. `tsc --noEmit -p .` across all modified packages.+ 2. `CompositorProgramSchema.parse(comp.toSpec())` validation tests.+ 3. Vitest unit and headless WebGPU tests (`pnpm --filter @framefields/webgpu-renderers test`, `pnpm --filter framefields test`).+ 4. `renderFrame` & `renderFrameGrid` visual verification with pixel probes confirming shard facets, vortex motion, friction-driven HDR magenta/white emission, secondary sparks, and anisotropic floor reflections.+ 5. `pnpm exec biome check --write` and `pnpm run check:plugins`.+