@khudiiash/particles-three 0.2.0

package/dist/index.mjs

@@ -0,0 +1,186 @@
+// src/index.js
+import * as THREE2 from "three";
+import {
+  ParticleSimulation,
+  PARTICLE_BYTES as PARTICLE_BYTES2,
+  resolveEffect,
+  mergeRender,
+  PARTICLE_STRIDE_FLOATS as PARTICLE_STRIDE_FLOATS2
+} from "@khudiiash/particles-core";
+
+// src/mesh.js
+import * as THREE from "three";
+import { StorageInstancedBufferAttribute } from "three";
+import {
+  Fn,
+  storage,
+  instanceIndex,
+  vec3,
+  vec4,
+  float,
+  uniform,
+  positionLocal
+} from "three/tsl";
+import { SpriteNodeMaterial } from "three/webgpu";
+import { PARTICLE_STRIDE_FLOATS, PARTICLE_BYTES } from "@khudiiash/particles-core";
+var VEC4_PER_PARTICLE = PARTICLE_STRIDE_FLOATS / 4;
+var BLEND = {
+  additive: THREE.AdditiveBlending,
+  additiveAlpha: THREE.AdditiveBlending,
+  normal: THREE.NormalBlending,
+  premultiplied: THREE.CustomBlending,
+  multiply: THREE.MultiplyBlending,
+  screen: THREE.AdditiveBlending
+};
+function buildParticleMesh({ renderer, particleBuffer, maxParticles, render }) {
+  const count = maxParticles;
+  const storageArray = new Float32Array(count * PARTICLE_STRIDE_FLOATS);
+  const storageAttr = new StorageInstancedBufferAttribute(storageArray, 4);
+  storageAttr.setUsage?.(THREE.DynamicDrawUsage);
+  const particles = storage(storageAttr, "vec4", count * VEC4_PER_PARTICLE);
+  const base = instanceIndex.mul(VEC4_PER_PARTICLE);
+  const p0 = particles.element(base);
+  const p2 = particles.element(base.add(2));
+  const p3 = particles.element(base.add(3));
+  const lifeT = p0.w;
+  const sizeAttr = p2.x;
+  const opacityAttr = p2.y;
+  const sizeScale = uniform(1);
+  const material = new SpriteNodeMaterial();
+  material.transparent = true;
+  material.depthWrite = !!render.depthWrite;
+  material.depthTest = true;
+  material.blending = BLEND[render.blendMode] ?? THREE.NormalBlending;
+  material.positionNode = p0.xyz;
+  material.scaleNode = sizeAttr.mul(sizeScale);
+  const alphaCutoff = float(render.alphaCutoff ?? 0.05);
+  material.colorNode = Fn(() => {
+    const uv = positionLocal.xy;
+    const d = uv.length().mul(2);
+    const soft = float(1).sub(d).clamp(0, 1);
+    const a = soft.mul(opacityAttr);
+    return vec4(p3.xyz, a);
+  })();
+  material.scaleNode = sizeAttr.mul(sizeScale).mul(lifeT.greaterThan(0).select(float(1), float(0)));
+  const geometry = new THREE.PlaneGeometry(1, 1);
+  const instanced = new THREE.InstancedBufferGeometry().copy(geometry);
+  instanced.instanceCount = count;
+  const mesh = new THREE.Mesh(instanced, material);
+  mesh.frustumCulled = false;
+  const device = renderer?.backend?.device;
+  mesh.onSimStep = () => {
+    if (!device) return;
+    const dst = renderer.backend.get(storageAttr)?.buffer;
+    if (!dst) return;
+    const enc = device.createCommandEncoder();
+    enc.copyBufferToBuffer(particleBuffer, 0, dst, 0, count * PARTICLE_BYTES);
+    device.queue.submit([enc.finish()]);
+  };
+  mesh.userData.sizeScale = sizeScale;
+  return mesh;
+}
+
+// src/index.js
+var FRAME_DT_CLAMP = 1 / 60;
+var ParticleSystem = class _ParticleSystem {
+  /**
+   * Async factory — preferred entry point.
+   * @param {object} config effect config (raw or resolved)
+   * @param {object} opts
+   * @param {import('three').WebGPURenderer} opts.renderer initialized WebGPU renderer
+   * @param {import('three').Object3D} [opts.scene] object to add the particle mesh to
+   * @param {import('three').Camera} [opts.camera]
+   */
+  static async create(config, opts) {
+    const system = new _ParticleSystem(config, opts);
+    await system.init();
+    return system;
+  }
+  constructor(config, { renderer, scene, camera } = {}) {
+    if (!renderer) throw new Error("ParticleSystem requires a three.js WebGPURenderer");
+    this.renderer = renderer;
+    this.scene = scene || null;
+    this.camera = camera || null;
+    this._rawConfig = config;
+    this.config = null;
+    this.mesh = null;
+    this.sim = null;
+    this._lastTime = 0;
+    this._playing = true;
+    this._disposed = false;
+  }
+  async init() {
+    const device = getDevice(this.renderer);
+    if (!device) {
+      throw new Error(
+        "WebGPU device unavailable \u2014 call `await renderer.init()` before creating the ParticleSystem"
+      );
+    }
+    this.config = resolveEffect(this._rawConfig);
+    this.sim = new ParticleSimulation(device, this.config);
+    await this.sim.init();
+    this.mesh = buildParticleMesh({
+      renderer: this.renderer,
+      particleBuffer: this.sim.particleBuffer,
+      maxParticles: this.config.maxParticles,
+      render: mergeRender(this.config.render)
+    });
+    if (this.scene) this.scene.add(this.mesh);
+    return this;
+  }
+  /** Swap to a new effect config at runtime. */
+  async setConfig(config) {
+    this.config = resolveEffect(config);
+    await this.sim.setConfig(this.config);
+    if (this.mesh) {
+      this.mesh.parent?.remove(this.mesh);
+      this.mesh.geometry.dispose();
+      this.mesh.material.dispose();
+    }
+    this.mesh = buildParticleMesh({
+      renderer: this.renderer,
+      particleBuffer: this.sim.particleBuffer,
+      maxParticles: this.config.maxParticles,
+      render: mergeRender(this.config.render)
+    });
+    if (this.scene) this.scene.add(this.mesh);
+  }
+  play() {
+    this._playing = true;
+  }
+  pause() {
+    this._playing = false;
+  }
+  reset() {
+    this.sim?.reset();
+  }
+  /**
+   * Advance the simulation. Call once per frame before `renderer.render`.
+   * @param {number} [dt] seconds since last update; clamped to 1/60 for stability
+   */
+  update(dt) {
+    if (this._disposed || !this._playing || !this.sim) return;
+    const clamped = Math.min(dt > 0 ? dt : 1 / 60, FRAME_DT_CLAMP);
+    this.sim.step(clamped);
+    this.mesh?.onSimStep?.();
+  }
+  dispose() {
+    this._disposed = true;
+    if (this.mesh) {
+      this.mesh.parent?.remove(this.mesh);
+      this.mesh.geometry.dispose();
+      this.mesh.material.dispose();
+      this.mesh = null;
+    }
+    this.sim?.dispose(true);
+    this.sim = null;
+  }
+};
+function getDevice(renderer) {
+  return renderer?.backend?.device || renderer?.backend?.data?.device || renderer?._device || null;
+}
+export {
+  PARTICLE_BYTES2 as PARTICLE_BYTES,
+  PARTICLE_STRIDE_FLOATS2 as PARTICLE_STRIDE_FLOATS,
+  ParticleSystem
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@khudiiash/particles-three",
+	"version": "0.2.0",
+	"description": "three.js WebGPU runtime player for @khudiiash/particles-core effect configs.",
+	"license": "MIT",
+	"author": "khudiiash",
+	"keywords": [
+		"webgpu",
+		"particles",
+		"three",
+		"threejs",
+		"gpu",
+		"wgsl",
+		"vfx"
+	],
+	"type": "module",
+	"main": "./src/index.js",
+	"module": "./src/index.js",
+	"unpkg": "./dist/index.mjs",
+	"jsdelivr": "./dist/index.mjs",
+	"exports": {
+		".": {
+			"default": "./src/index.js"
+		}
+	},
+	"files": [
+		"src",
+		"dist"
+	],
+	"scripts": {
+		"build": "esbuild src/index.js --bundle --format=esm --outfile=dist/index.mjs --external:three --external:three/* --external:@khudiiash/particles-core",
+		"prepublishOnly": "npm run build"
+	},
+	"peerDependencies": {
+		"three": ">=0.160.0"
+	},
+	"dependencies": {
+		"@khudiiash/particles-core": "^0.2.0"
+	},
+	"devDependencies": {
+		"esbuild": "^0.21.5"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/src/index.js

@@ -0,0 +1,146 @@
+/**
+ * @khudiiash/particles-three
+ *
+ * Plays a `@khudiiash/particles-core` effect config inside a three.js scene
+ * using the WebGPU backend. The simulation runs as a compute pass on the
+ * renderer's own `GPUDevice`, and particles are drawn straight from the GPU
+ * storage buffer — there is no CPU readback.
+ *
+ * Usage:
+ *   import * as THREE from 'three';
+ *   import { WebGPURenderer } from 'three/webgpu';
+ *   import { ParticleSystem } from '@khudiiash/particles-three';
+ *
+ *   const renderer = new WebGPURenderer({ antialias: true });
+ *   await renderer.init();
+ *   const ps = await ParticleSystem.create(effectConfig, { renderer, scene, camera });
+ *   renderer.setAnimationLoop((t) => { ps.update(dt); renderer.render(scene, camera); });
+ */
+import * as THREE from "three";
+import {
+	ParticleSimulation,
+	PARTICLE_BYTES,
+	resolveEffect,
+	mergeRender,
+	PARTICLE_STRIDE_FLOATS,
+} from "@khudiiash/particles-core";
+import { buildParticleMesh } from "./mesh.js";
+
+const FRAME_DT_CLAMP = 1 / 60;
+
+export class ParticleSystem {
+	/**
+	 * Async factory — preferred entry point.
+	 * @param {object} config effect config (raw or resolved)
+	 * @param {object} opts
+	 * @param {import('three').WebGPURenderer} opts.renderer initialized WebGPU renderer
+	 * @param {import('three').Object3D} [opts.scene] object to add the particle mesh to
+	 * @param {import('three').Camera} [opts.camera]
+	 */
+	static async create(config, opts) {
+		const system = new ParticleSystem(config, opts);
+		await system.init();
+		return system;
+	}
+
+	constructor(config, { renderer, scene, camera } = {}) {
+		if (!renderer) throw new Error("ParticleSystem requires a three.js WebGPURenderer");
+		this.renderer = renderer;
+		this.scene = scene || null;
+		this.camera = camera || null;
+		this._rawConfig = config;
+		this.config = null;
+		this.mesh = null;
+		this.sim = null;
+		this._lastTime = 0;
+		this._playing = true;
+		this._disposed = false;
+	}
+
+	async init() {
+		const device = getDevice(this.renderer);
+		if (!device) {
+			throw new Error(
+				"WebGPU device unavailable — call `await renderer.init()` before creating the ParticleSystem",
+			);
+		}
+		this.config = resolveEffect(this._rawConfig);
+		this.sim = new ParticleSimulation(device, this.config);
+		await this.sim.init();
+
+		this.mesh = buildParticleMesh({
+			renderer: this.renderer,
+			particleBuffer: this.sim.particleBuffer,
+			maxParticles: this.config.maxParticles,
+			render: mergeRender(this.config.render),
+		});
+		if (this.scene) this.scene.add(this.mesh);
+		return this;
+	}
+
+	/** Swap to a new effect config at runtime. */
+	async setConfig(config) {
+		this.config = resolveEffect(config);
+		await this.sim.setConfig(this.config);
+		// Rebuild the mesh so it points at the (possibly new) particle buffer.
+		if (this.mesh) {
+			this.mesh.parent?.remove(this.mesh);
+			this.mesh.geometry.dispose();
+			this.mesh.material.dispose();
+		}
+		this.mesh = buildParticleMesh({
+			renderer: this.renderer,
+			particleBuffer: this.sim.particleBuffer,
+			maxParticles: this.config.maxParticles,
+			render: mergeRender(this.config.render),
+		});
+		if (this.scene) this.scene.add(this.mesh);
+	}
+
+	play() {
+		this._playing = true;
+	}
+
+	pause() {
+		this._playing = false;
+	}
+
+	reset() {
+		this.sim?.reset();
+	}
+
+	/**
+	 * Advance the simulation. Call once per frame before `renderer.render`.
+	 * @param {number} [dt] seconds since last update; clamped to 1/60 for stability
+	 */
+	update(dt) {
+		if (this._disposed || !this._playing || !this.sim) return;
+		const clamped = Math.min(dt > 0 ? dt : 1 / 60, FRAME_DT_CLAMP);
+		this.sim.step(clamped);
+		this.mesh?.onSimStep?.();
+	}
+
+	dispose() {
+		this._disposed = true;
+		if (this.mesh) {
+			this.mesh.parent?.remove(this.mesh);
+			this.mesh.geometry.dispose();
+			this.mesh.material.dispose();
+			this.mesh = null;
+		}
+		this.sim?.dispose(true);
+		this.sim = null;
+	}
+}
+
+/** Resolve the underlying GPUDevice from a three WebGPURenderer across versions. */
+function getDevice(renderer) {
+	return (
+		renderer?.backend?.device ||
+		renderer?.backend?.data?.device ||
+		renderer?._device ||
+		null
+	);
+}
+
+export { PARTICLE_BYTES, PARTICLE_STRIDE_FLOATS };

package/src/mesh.js

@@ -0,0 +1,107 @@
+/**
+ * Builds the renderable particle mesh for the three.js WebGPU runtime.
+ *
+ * The mesh reads particle state directly from a GPU storage buffer (the buffer
+ * the core `ParticleSimulation` compute pass writes to) using TSL storage nodes,
+ * so no per-frame CPU readback is required. The mesh is a billboarded instanced
+ * quad — one instance per particle — driven by `SpriteNodeMaterial`.
+ *
+ * Particle struct layout (16 floats / 4 vec4 per particle), see core/layout.js:
+ *   vec4 0: position.xyz, life
+ *   vec4 1: velocity.xyz, maxLife
+ *   vec4 2: size, opacity, pathPhase, pathSpread
+ *   vec4 3: color.rgb, seed
+ */
+import * as THREE from "three";
+import { StorageInstancedBufferAttribute } from "three";
+import {
+	Fn,
+	storage,
+	instanceIndex,
+	vec3,
+	vec4,
+	float,
+	uniform,
+	positionLocal,
+} from "three/tsl";
+import { SpriteNodeMaterial } from "three/webgpu";
+import { PARTICLE_STRIDE_FLOATS, PARTICLE_BYTES } from "@khudiiash/particles-core";
+
+const VEC4_PER_PARTICLE = PARTICLE_STRIDE_FLOATS / 4; // 4
+
+const BLEND = {
+	additive: THREE.AdditiveBlending,
+	additiveAlpha: THREE.AdditiveBlending,
+	normal: THREE.NormalBlending,
+	premultiplied: THREE.CustomBlending,
+	multiply: THREE.MultiplyBlending,
+	screen: THREE.AdditiveBlending,
+};
+
+export function buildParticleMesh({ renderer, particleBuffer, maxParticles, render }) {
+	const count = maxParticles;
+
+	// three-owned storage buffer that the material reads from. We mirror the
+	// simulation buffer into it every frame with a GPU->GPU copy.
+	const storageArray = new Float32Array(count * PARTICLE_STRIDE_FLOATS);
+	const storageAttr = new StorageInstancedBufferAttribute(storageArray, 4);
+	storageAttr.setUsage?.(THREE.DynamicDrawUsage);
+
+	const particles = storage(storageAttr, "vec4", count * VEC4_PER_PARTICLE);
+
+	const base = instanceIndex.mul(VEC4_PER_PARTICLE);
+	const p0 = particles.element(base);
+	const p2 = particles.element(base.add(2));
+	const p3 = particles.element(base.add(3));
+
+	const lifeT = p0.w; // remaining life > 0 means alive (sim writes life)
+	const sizeAttr = p2.x;
+	const opacityAttr = p2.y;
+
+	const sizeScale = uniform(1);
+
+	const material = new SpriteNodeMaterial();
+	material.transparent = true;
+	material.depthWrite = !!render.depthWrite;
+	material.depthTest = true;
+	material.blending = BLEND[render.blendMode] ?? THREE.NormalBlending;
+
+	// Per-instance world position = particle position.
+	material.positionNode = p0.xyz;
+	// Per-instance billboard scale.
+	material.scaleNode = sizeAttr.mul(sizeScale);
+
+	// Soft round sprite alpha from quad-local UV, modulated by particle opacity.
+	const alphaCutoff = float(render.alphaCutoff ?? 0.05);
+	material.colorNode = Fn(() => {
+		const uv = positionLocal.xy; // [-0.5, 0.5]
+		const d = uv.length().mul(2.0);
+		const soft = float(1.0).sub(d).clamp(0.0, 1.0);
+		const a = soft.mul(opacityAttr);
+		return vec4(p3.xyz, a);
+	})();
+
+	// Hide dead particles (life <= 0) by collapsing their scale.
+	material.scaleNode = sizeAttr.mul(sizeScale).mul(lifeT.greaterThan(0.0).select(float(1), float(0)));
+
+	const geometry = new THREE.PlaneGeometry(1, 1);
+	const instanced = new THREE.InstancedBufferGeometry().copy(geometry);
+	instanced.instanceCount = count;
+
+	const mesh = new THREE.Mesh(instanced, material);
+	mesh.frustumCulled = false;
+
+	// Mirror the simulation buffer into the storage attribute each step.
+	const device = renderer?.backend?.device;
+	mesh.onSimStep = () => {
+		if (!device) return;
+		const dst = renderer.backend.get(storageAttr)?.buffer;
+		if (!dst) return; // not allocated until first render
+		const enc = device.createCommandEncoder();
+		enc.copyBufferToBuffer(particleBuffer, 0, dst, 0, count * PARTICLE_BYTES);
+		device.queue.submit([enc.finish()]);
+	};
+
+	mesh.userData.sizeScale = sizeScale;
+	return mesh;
+}