@khudiiash/particles-playcanvas 0.2.0

package/dist/index.mjs

@@ -0,0 +1,254 @@
+// src/index.js
+import * as pc from "playcanvas";
+import {
+  ParticleSimulation,
+  PARTICLE_BYTES,
+  resolveEffect,
+  mergeRender
+} from "@khudiiash/particles-core";
+
+// src/render-wgsl.js
+function particleVertexWgsl() {
+  return (
+    /* wgsl */
+    `
+struct Particle {
+    position: vec3f,
+    life: f32,
+    velocity: vec3f,
+    maxLife: f32,
+    size: f32,
+    opacity: f32,
+    pathPhase: f32,
+    pathSpread: f32,
+    color: vec3f,
+    seed: f32,
+};
+
+var<storage, read> particles: array<Particle>;
+
+uniform matrix_viewProjection: mat4x4f;
+uniform matrix_view: mat4x4f;
+uniform uSizeScale: f32;
+
+varying vColor: vec4f;
+varying vUv: vec2f;
+
+const QUAD = array<vec2f, 6>(
+    vec2f(-0.5, -0.5), vec2f(0.5, -0.5), vec2f(0.5, 0.5),
+    vec2f(-0.5, -0.5), vec2f(0.5, 0.5), vec2f(-0.5, 0.5),
+);
+
+struct VertexInput {
+    @builtin(vertex_index) vertexIndex: u32,
+};
+
+struct VertexOutput {
+    @builtin(position) position: vec4f,
+};
+
+@vertex
+fn vertexMain(input: VertexInput) -> VertexOutput {
+    let particleIndex = input.vertexIndex / 6u;
+    let corner = QUAD[input.vertexIndex % 6u];
+    let p = particles[particleIndex];
+
+    let alive = select(0.0, 1.0, p.life > 0.0);
+    let scale = p.size * uniform.uSizeScale * alive;
+
+    let right = vec3f(uniform.matrix_view[0][0], uniform.matrix_view[1][0], uniform.matrix_view[2][0]);
+    let up = vec3f(uniform.matrix_view[0][1], uniform.matrix_view[1][1], uniform.matrix_view[2][1]);
+    let world = p.position + (right * corner.x + up * corner.y) * scale;
+
+    var output: VertexOutput;
+    output.position = uniform.matrix_viewProjection * vec4f(world, 1.0);
+    vColor = vec4f(p.color, p.opacity * alive);
+    vUv = corner;
+    return output;
+}
+`
+  );
+}
+function particleFragmentWgsl() {
+  return (
+    /* wgsl */
+    `
+uniform uAlphaCutoff: f32;
+
+varying vColor: vec4f;
+varying vUv: vec2f;
+
+struct FragmentOutput {
+    @location(0) color: vec4f,
+};
+
+@fragment
+fn fragmentMain() -> FragmentOutput {
+    let d = length(vUv) * 2.0;
+    let soft = clamp(1.0 - d, 0.0, 1.0);
+    let a = vColor.a * soft;
+    if (a < uniform.uAlphaCutoff) { discard; }
+    var output: FragmentOutput;
+    output.color = vec4f(vColor.rgb, a);
+    return output;
+}
+`
+  );
+}
+
+// src/index.js
+var FRAME_DT_CLAMP = 1 / 60;
+var ParticleSystem = class _ParticleSystem {
+  /**
+   * @param {pc.AppBase} app
+   * @param {object} config effect config (raw or resolved)
+   * @param {object} [opts]
+   * @param {pc.Entity} [opts.camera] camera entity (defaults to first scene camera)
+   * @param {pc.Entity} [opts.parent] entity to parent the particle render to
+   */
+  static async create(app, config, opts = {}) {
+    const system = new _ParticleSystem(app, config, opts);
+    await system.init();
+    return system;
+  }
+  constructor(app, config, opts = {}) {
+    this.app = app;
+    this.device = app.graphicsDevice;
+    this.gpu = this.device.wgpu;
+    if (!this.gpu) {
+      throw new Error(
+        "@khudiiash/particles-playcanvas requires a WebGPU graphics device (DEVICETYPE_WEBGPU)"
+      );
+    }
+    this._rawConfig = config;
+    this.camera = opts.camera || null;
+    this.parent = opts.parent || app.root;
+    this.config = null;
+    this.sim = null;
+    this.entity = null;
+    this.storageBuffer = null;
+    this._playing = true;
+    this._disposed = false;
+  }
+  async init() {
+    this.config = resolveEffect(this._rawConfig);
+    this.sim = new ParticleSimulation(this.gpu, this.config);
+    await this.sim.init();
+    this._buildRender();
+    return this;
+  }
+  _buildRender() {
+    const pcLib = pc;
+    const count = this.config.maxParticles;
+    const render = mergeRender(this.config.render);
+    this.storageBuffer = new pcLib.StorageBuffer(
+      this.device,
+      count * PARTICLE_BYTES,
+      pcLib.BUFFERUSAGE_COPY_DST | pcLib.BUFFERUSAGE_STORAGE
+    );
+    const shader = pcLib.ShaderMaterial ? new pcLib.ShaderMaterial({
+      uniqueName: "particles-core",
+      vertexGLSL: void 0,
+      fragmentGLSL: void 0,
+      vertexWGSL: particleVertexWgsl(),
+      fragmentWGSL: particleFragmentWgsl(),
+      attributes: {}
+    }) : new pcLib.Material();
+    shader.cull = pcLib.CULLFACE_NONE;
+    shader.blendType = blendType(pcLib, render.blendMode);
+    shader.depthWrite = !!render.depthWrite;
+    shader.depthTest = true;
+    shader.setParameter("particles", this.storageBuffer);
+    shader.setParameter("uSizeScale", 1);
+    shader.setParameter("uAlphaCutoff", render.alphaCutoff ?? 0.05);
+    shader.update();
+    this.material = shader;
+    const mesh = new pcLib.Mesh(this.device);
+    mesh.vertexBuffer = null;
+    mesh.primitive[0] = {
+      type: pcLib.PRIMITIVE_TRIANGLES,
+      base: 0,
+      count: count * 6,
+      indexed: false
+    };
+    mesh.aabb = new pcLib.BoundingBox(new pcLib.Vec3(), new pcLib.Vec3(1e4, 1e4, 1e4));
+    const node = new pcLib.GraphNode();
+    const instance = new pcLib.MeshInstance(mesh, shader, node);
+    instance.cull = false;
+    this.entity = new pcLib.Entity("particles-core");
+    this.entity.addComponent("render", { meshInstances: [instance] });
+    this.parent.addChild(this.entity);
+    this.meshInstance = instance;
+  }
+  _updateMatrices() {
+    const cam = this.camera || this.app.root.findComponent("camera")?.entity;
+    if (!cam) return;
+    const camComp = cam.camera;
+    if (!camComp) return;
+    const vp = camComp.viewProjectionMatrix || camComp._viewProjMat;
+    const view = camComp.viewMatrix || camComp._viewMat;
+    if (vp) this.material.setParameter("matrix_viewProjection", vp.data);
+    if (view) this.material.setParameter("matrix_view", view.data);
+  }
+  play() {
+    this._playing = true;
+  }
+  pause() {
+    this._playing = false;
+  }
+  reset() {
+    this.sim?.reset();
+  }
+  /** Advance the simulation and mirror the buffer. Call once per frame. */
+  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._copyToStorage();
+    this._updateMatrices();
+  }
+  _copyToStorage() {
+    const dst = this.storageBuffer?.impl?.buffer;
+    if (!dst) return;
+    const enc = this.gpu.createCommandEncoder();
+    enc.copyBufferToBuffer(
+      this.sim.particleBuffer,
+      0,
+      dst,
+      0,
+      this.config.maxParticles * PARTICLE_BYTES
+    );
+    this.gpu.queue.submit([enc.finish()]);
+  }
+  async setConfig(config) {
+    this.config = resolveEffect(config);
+    await this.sim.setConfig(this.config);
+  }
+  dispose() {
+    this._disposed = true;
+    this.entity?.destroy();
+    this.entity = null;
+    this.storageBuffer?.destroy?.();
+    this.storageBuffer = null;
+    this.sim?.dispose(true);
+    this.sim = null;
+  }
+};
+function blendType(pcLib, mode) {
+  switch (mode) {
+    case "additive":
+    case "additiveAlpha":
+    case "screen":
+      return pcLib.BLEND_ADDITIVEALPHA ?? pcLib.BLEND_ADDITIVE;
+    case "multiply":
+      return pcLib.BLEND_MULTIPLICATIVE;
+    case "premultiplied":
+      return pcLib.BLEND_PREMULTIPLIED;
+    default:
+      return pcLib.BLEND_NORMAL;
+  }
+}
+export {
+  PARTICLE_BYTES,
+  ParticleSystem
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@khudiiash/particles-playcanvas",
+	"version": "0.2.0",
+	"description": "PlayCanvas WebGPU runtime player for @khudiiash/particles-core effect configs.",
+	"license": "MIT",
+	"author": "khudiiash",
+	"keywords": [
+		"webgpu",
+		"particles",
+		"playcanvas",
+		"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:playcanvas --external:@khudiiash/particles-core",
+		"prepublishOnly": "npm run build"
+	},
+	"peerDependencies": {
+		"playcanvas": ">=1.65.0"
+	},
+	"dependencies": {
+		"@khudiiash/particles-core": "^0.2.0"
+	},
+	"devDependencies": {
+		"esbuild": "^0.21.5"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/src/index.js

@@ -0,0 +1,204 @@
+/**
+ * @khudiiash/particles-playcanvas
+ *
+ * Plays a `@khudiiash/particles-core` effect config inside a PlayCanvas
+ * application using the WebGPU backend. The simulation runs as a WebGPU compute
+ * pass on PlayCanvas's own `GPUDevice` (`graphicsDevice.wgpu`); particles are
+ * drawn from the shared GPU storage buffer with a PlayCanvas WGSL material — no
+ * CPU readback.
+ *
+ * Requires PlayCanvas Engine v2 with a WebGPU device (DEVICETYPE_WEBGPU).
+ *
+ * Usage:
+ *   import * as pc from 'playcanvas';
+ *   import { ParticleSystem } from '@khudiiash/particles-playcanvas';
+ *   const ps = await ParticleSystem.create(app, effectConfig, { camera });
+ *   app.on('update', (dt) => ps.update(dt));
+ */
+import * as pc from "playcanvas";
+import {
+	ParticleSimulation,
+	PARTICLE_BYTES,
+	resolveEffect,
+	mergeRender,
+} from "@khudiiash/particles-core";
+import { particleVertexWgsl, particleFragmentWgsl } from "./render-wgsl.js";
+
+const FRAME_DT_CLAMP = 1 / 60;
+
+export class ParticleSystem {
+	/**
+	 * @param {pc.AppBase} app
+	 * @param {object} config effect config (raw or resolved)
+	 * @param {object} [opts]
+	 * @param {pc.Entity} [opts.camera] camera entity (defaults to first scene camera)
+	 * @param {pc.Entity} [opts.parent] entity to parent the particle render to
+	 */
+	static async create(app, config, opts = {}) {
+		const system = new ParticleSystem(app, config, opts);
+		await system.init();
+		return system;
+	}
+
+	constructor(app, config, opts = {}) {
+		this.app = app;
+		this.device = app.graphicsDevice;
+		this.gpu = this.device.wgpu;
+		if (!this.gpu) {
+			throw new Error(
+				"@khudiiash/particles-playcanvas requires a WebGPU graphics device (DEVICETYPE_WEBGPU)",
+			);
+		}
+		this._rawConfig = config;
+		this.camera = opts.camera || null;
+		this.parent = opts.parent || app.root;
+		this.config = null;
+		this.sim = null;
+		this.entity = null;
+		this.storageBuffer = null;
+		this._playing = true;
+		this._disposed = false;
+	}
+
+	async init() {
+		this.config = resolveEffect(this._rawConfig);
+		this.sim = new ParticleSimulation(this.gpu, this.config);
+		await this.sim.init();
+		this._buildRender();
+		return this;
+	}
+
+	_buildRender() {
+		const pcLib = pc;
+		const count = this.config.maxParticles;
+		const render = mergeRender(this.config.render);
+
+		// PlayCanvas-managed storage buffer that the material reads from; we copy
+		// the simulation output into it each frame (GPU -> GPU).
+		this.storageBuffer = new pcLib.StorageBuffer(
+			this.device,
+			count * PARTICLE_BYTES,
+			pcLib.BUFFERUSAGE_COPY_DST | pcLib.BUFFERUSAGE_STORAGE,
+		);
+
+		const shader = pcLib.ShaderMaterial
+			? new pcLib.ShaderMaterial({
+					uniqueName: "particles-core",
+					vertexGLSL: undefined,
+					fragmentGLSL: undefined,
+					vertexWGSL: particleVertexWgsl(),
+					fragmentWGSL: particleFragmentWgsl(),
+					attributes: {},
+			  })
+			: new pcLib.Material();
+
+		shader.cull = pcLib.CULLFACE_NONE;
+		shader.blendType = blendType(pcLib, render.blendMode);
+		shader.depthWrite = !!render.depthWrite;
+		shader.depthTest = true;
+		shader.setParameter("particles", this.storageBuffer);
+		shader.setParameter("uSizeScale", 1);
+		shader.setParameter("uAlphaCutoff", render.alphaCutoff ?? 0.05);
+		shader.update();
+		this.material = shader;
+
+		// A vertex-only mesh: 6 verts per particle, no vertex buffers (the shader
+		// reads everything from the storage buffer via vertex_index).
+		const mesh = new pcLib.Mesh(this.device);
+		mesh.vertexBuffer = null;
+		mesh.primitive[0] = {
+			type: pcLib.PRIMITIVE_TRIANGLES,
+			base: 0,
+			count: count * 6,
+			indexed: false,
+		};
+		mesh.aabb = new pcLib.BoundingBox(new pcLib.Vec3(), new pcLib.Vec3(1e4, 1e4, 1e4));
+
+		const node = new pcLib.GraphNode();
+		const instance = new pcLib.MeshInstance(mesh, shader, node);
+		instance.cull = false;
+
+		this.entity = new pcLib.Entity("particles-core");
+		this.entity.addComponent("render", { meshInstances: [instance] });
+		this.parent.addChild(this.entity);
+		this.meshInstance = instance;
+	}
+
+	_updateMatrices() {
+		const cam = this.camera || this.app.root.findComponent("camera")?.entity;
+		if (!cam) return;
+		const camComp = cam.camera;
+		if (!camComp) return;
+		const vp = camComp.viewProjectionMatrix || camComp._viewProjMat;
+		const view = camComp.viewMatrix || camComp._viewMat;
+		if (vp) this.material.setParameter("matrix_viewProjection", vp.data);
+		if (view) this.material.setParameter("matrix_view", view.data);
+	}
+
+	play() {
+		this._playing = true;
+	}
+
+	pause() {
+		this._playing = false;
+	}
+
+	reset() {
+		this.sim?.reset();
+	}
+
+	/** Advance the simulation and mirror the buffer. Call once per frame. */
+	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._copyToStorage();
+		this._updateMatrices();
+	}
+
+	_copyToStorage() {
+		const dst = this.storageBuffer?.impl?.buffer;
+		if (!dst) return;
+		const enc = this.gpu.createCommandEncoder();
+		enc.copyBufferToBuffer(
+			this.sim.particleBuffer,
+			0,
+			dst,
+			0,
+			this.config.maxParticles * PARTICLE_BYTES,
+		);
+		this.gpu.queue.submit([enc.finish()]);
+	}
+
+	async setConfig(config) {
+		this.config = resolveEffect(config);
+		await this.sim.setConfig(this.config);
+	}
+
+	dispose() {
+		this._disposed = true;
+		this.entity?.destroy();
+		this.entity = null;
+		this.storageBuffer?.destroy?.();
+		this.storageBuffer = null;
+		this.sim?.dispose(true);
+		this.sim = null;
+	}
+}
+
+function blendType(pcLib, mode) {
+	switch (mode) {
+		case "additive":
+		case "additiveAlpha":
+		case "screen":
+			return pcLib.BLEND_ADDITIVEALPHA ?? pcLib.BLEND_ADDITIVE;
+		case "multiply":
+			return pcLib.BLEND_MULTIPLICATIVE;
+		case "premultiplied":
+			return pcLib.BLEND_PREMULTIPLIED;
+		default:
+			return pcLib.BLEND_NORMAL;
+	}
+}
+
+export { PARTICLE_BYTES };

package/src/render-wgsl.js

@@ -0,0 +1,90 @@
+/**
+ * Minimal PlayCanvas-dialect WGSL render shader for the PlayCanvas runtime.
+ *
+ * Reads the particle storage buffer (written by the core compute simulation) and
+ * draws each live particle as a camera-facing billboard. Written in PlayCanvas's
+ * WGSL flavour (`uniform`/`varying`/`var<storage>` declarations) so it can be
+ * compiled by `pc.ShaderMaterial` with `SHADERLANGUAGE_WGSL`.
+ */
+export function particleVertexWgsl() {
+	return /* wgsl */ `
+struct Particle {
+    position: vec3f,
+    life: f32,
+    velocity: vec3f,
+    maxLife: f32,
+    size: f32,
+    opacity: f32,
+    pathPhase: f32,
+    pathSpread: f32,
+    color: vec3f,
+    seed: f32,
+};
+
+var<storage, read> particles: array<Particle>;
+
+uniform matrix_viewProjection: mat4x4f;
+uniform matrix_view: mat4x4f;
+uniform uSizeScale: f32;
+
+varying vColor: vec4f;
+varying vUv: vec2f;
+
+const QUAD = array<vec2f, 6>(
+    vec2f(-0.5, -0.5), vec2f(0.5, -0.5), vec2f(0.5, 0.5),
+    vec2f(-0.5, -0.5), vec2f(0.5, 0.5), vec2f(-0.5, 0.5),
+);
+
+struct VertexInput {
+    @builtin(vertex_index) vertexIndex: u32,
+};
+
+struct VertexOutput {
+    @builtin(position) position: vec4f,
+};
+
+@vertex
+fn vertexMain(input: VertexInput) -> VertexOutput {
+    let particleIndex = input.vertexIndex / 6u;
+    let corner = QUAD[input.vertexIndex % 6u];
+    let p = particles[particleIndex];
+
+    let alive = select(0.0, 1.0, p.life > 0.0);
+    let scale = p.size * uniform.uSizeScale * alive;
+
+    let right = vec3f(uniform.matrix_view[0][0], uniform.matrix_view[1][0], uniform.matrix_view[2][0]);
+    let up = vec3f(uniform.matrix_view[0][1], uniform.matrix_view[1][1], uniform.matrix_view[2][1]);
+    let world = p.position + (right * corner.x + up * corner.y) * scale;
+
+    var output: VertexOutput;
+    output.position = uniform.matrix_viewProjection * vec4f(world, 1.0);
+    vColor = vec4f(p.color, p.opacity * alive);
+    vUv = corner;
+    return output;
+}
+`;
+}
+
+export function particleFragmentWgsl() {
+	return /* wgsl */ `
+uniform uAlphaCutoff: f32;
+
+varying vColor: vec4f;
+varying vUv: vec2f;
+
+struct FragmentOutput {
+    @location(0) color: vec4f,
+};
+
+@fragment
+fn fragmentMain() -> FragmentOutput {
+    let d = length(vUv) * 2.0;
+    let soft = clamp(1.0 - d, 0.0, 1.0);
+    let a = vColor.a * soft;
+    if (a < uniform.uAlphaCutoff) { discard; }
+    var output: FragmentOutput;
+    output.color = vec4f(vColor.rgb, a);
+    return output;
+}
+`;
+}