Skip to content

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.md
index 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.jpg
new file mode 100644
index 00000000..bf147df2
Binary files /dev/null and b/assets/showcase/shard-storm.jpg differ
diff --git a/examples/31_shard_storm/README.md b/examples/31_shard_storm/README.md
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.md
index 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 Schema
Common 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.ts
index 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 evaluation
let skinningMatrices: Float32Array | undefined;
const animProgress =
diff --git a/packages/compositions/src/program/schema.ts b/packages/compositions/src/program/schema.ts
index 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> = z
exposure: 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> = z
colorTint: 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 array
let 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 Pipeline
const 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.ts
new file mode 100644
index 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.ts
index 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 size
shadowBias : vec4<f32>, // x = depth bias, y = normal offset (world px), z = darkness 0..1, w = unused
shadowMatrix : 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: vec3
display = 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.ts
index 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.md
index 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 reflections
fog: { color: BG, start: 2000, end: 5000 }, // surfaces fade into the background color
bloom: 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.yaml
index 498e06f9..aceef795 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -476,6 +476,28 @@ importers:
specifier: ^4.1.11
+ 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
+
nodes/node-apply-lut:
dependencies:
'@framefields/core':
diff --git a/specs/3d-shards.md b/specs/3d-shards.md
new file mode 100644
index 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`.
+