@aethervtt/shard-particles 0.0.1

package/dist/modules.js

@@ -0,0 +1,292 @@
+import {
+  curve,
+  evalCurve,
+  wgslFloat as f,
+  gradient,
+  invalid,
+  rand,
+  scalar,
+  wgslCurve,
+  wgslGradient
+} from "./values.js";
+const vec3 = (v) => `vec3f(${v.map(f).join(", ")})`;
+const MODULES = {
+  gravity: {
+    name: "gravity",
+    description: "Constant acceleration.",
+    params: {
+      acceleration: { kind: "vec3", default: [0, -9.81, 0], description: "m/s\xB2, world axes." }
+    },
+    update: (p) => `vel += ${vec3(p.acceleration)} * dt;`,
+    cpu: (p, s, dt) => {
+      const a = p.acceleration;
+      for (let k = 0; k < 3; k++) s.vel[k] += a[k] * dt;
+    }
+  },
+  drag: {
+    name: "drag",
+    description: "Slows particles exponentially: velocity \xD7 e^(\u2212coefficient \xB7 t).",
+    params: { coefficient: { kind: "number", default: 1, description: "Per second." } },
+    update: (p) => `vel *= exp(${f(-p.coefficient)} * dt);`,
+    cpu: (p, s, dt) => {
+      const k = Math.exp(-p.coefficient * dt);
+      for (let i = 0; i < 3; i++) s.vel[i] *= k;
+    }
+  },
+  "velocity-over-life": {
+    name: "velocity-over-life",
+    description: "An extra velocity, scaled by a curve over life (wind that dies down, a late lift).",
+    params: {
+      velocity: { kind: "vec3", default: [0, 1, 0], description: "m/s." },
+      curve: {
+        kind: "curve",
+        default: [
+          [0, 1],
+          [1, 1]
+        ],
+        description: "Multiplier over life."
+      }
+    },
+    functions: (p, id) => wgslCurve(`${id}_curve`, p.curve),
+    update: (p, id) => `pos += ${vec3(p.velocity)} * ${id}_curve(age / life) * dt;`,
+    cpu: (p, s, dt) => {
+      const m = evalCurve(p.curve, s.age / s.life);
+      const v = p.velocity;
+      for (let k = 0; k < 3; k++) s.pos[k] += v[k] * m * dt;
+    }
+  },
+  "curl-noise": {
+    name: "curl-noise",
+    description: "Swirling, divergence-free turbulence (smoke, exhaust).",
+    params: {
+      strength: { kind: "number", default: 1, description: "m/s\xB2 at full swirl." },
+      frequency: { kind: "number", default: 1, description: "Swirls per meter." },
+      speed: {
+        kind: "number",
+        default: 0.5,
+        description: "How fast the field changes, per second."
+      }
+    },
+    update: (p) => {
+      const s = f(p.strength);
+      const q = f(p.frequency);
+      const w = f(p.speed);
+      return `{
+    let ph = time * ${w};
+    let a = -vec3f(cos(pos.z * ${q} + ph), cos(pos.x * ${q} + ph), cos(pos.y * ${q} + ph));
+    let b = -vec3f(cos((pos.x + pos.y) * ${q} * 1.7 - ph), cos((pos.y + pos.z) * ${q} * 1.7 - ph), cos((pos.z + pos.x) * ${q} * 1.7 - ph)).zxy;
+    vel += (a + 0.5 * b) * ${s} * dt;
+  }`;
+    },
+    cpu: (p, s, dt, time) => {
+      const q = p.frequency;
+      const ph = time * p.speed;
+      const [x, y, z] = [s.pos[0], s.pos[1], s.pos[2]];
+      const a = [-Math.cos(z * q + ph), -Math.cos(x * q + ph), -Math.cos(y * q + ph)];
+      const b0 = [
+        -Math.cos((x + y) * q * 1.7 - ph),
+        -Math.cos((y + z) * q * 1.7 - ph),
+        -Math.cos((z + x) * q * 1.7 - ph)
+      ];
+      const b = [b0[2], b0[0], b0[1]];
+      for (let k = 0; k < 3; k++) s.vel[k] += (a[k] + 0.5 * b[k]) * p.strength * dt;
+    }
+  },
+  attractor: {
+    name: "attractor",
+    description: "Pulls particles toward a point (negative strength pushes away), fading to zero at radius.",
+    params: {
+      position: {
+        kind: "vec3",
+        default: [0, 0, 0],
+        description: "In the effect's space (local to the emitter for local systems)."
+      },
+      strength: { kind: "number", default: 5, description: "m/s\xB2 at the center." },
+      radius: { kind: "number", default: 5, description: "m." }
+    },
+    update: (p) => `{
+    let d = ${vec3(p.position)} - pos;
+    let len = max(length(d), 1e-4);
+    vel += d / len * ${f(p.strength)} * clamp(1.0 - len / ${f(p.radius)}, 0.0, 1.0) * dt;
+  }`,
+    cpu: (p, s, dt) => {
+      const c = p.position;
+      const d = [c[0] - s.pos[0], c[1] - s.pos[1], c[2] - s.pos[2]];
+      const len = Math.max(Math.sqrt(d[0] * d[0] + d[1] * d[1] + d[2] * d[2]), 1e-4);
+      const k = p.strength * Math.min(1, Math.max(0, 1 - len / p.radius)) * dt / len;
+      for (let i = 0; i < 3; i++) s.vel[i] += d[i] * k;
+    }
+  },
+  rotation: {
+    name: "rotation",
+    description: "Spins billboards: a speed per particle, picked from a range.",
+    params: { speed: { kind: "scalar", default: [-90, 90], description: "Degrees per second." } },
+    init: (p) => {
+      const [a, b] = p.speed;
+      return `rot_speed = radians(mix(${f(a)}, ${f(b)}, rand(seed, 20u)));`;
+    },
+    update: () => "rot += rot_speed * dt;",
+    cpuInit: (p, s) => {
+      const [a, b] = p.speed;
+      s.rotSpeed = (a + (b - a) * rand(s.seed, 20)) * Math.PI / 180;
+    },
+    cpu: (_, s, dt) => {
+      s.rot += s.rotSpeed * dt;
+    }
+  },
+  "color-over-life": {
+    name: "color-over-life",
+    description: "Multiplies the color (and alpha) by a gradient over life.",
+    params: { gradient: { kind: "gradient", description: "[[t, color, alpha?], \u2026]." } },
+    functions: (p, id) => wgslGradient(`${id}_gradient`, p.gradient),
+    render: (_, id) => `color *= ${id}_gradient(t);`
+  },
+  "size-over-life": {
+    name: "size-over-life",
+    description: "Multiplies the size by a curve over life.",
+    params: { curve: { kind: "curve", description: "[[t, multiplier], \u2026]." } },
+    functions: (p, id) => wgslCurve(`${id}_curve`, p.curve),
+    render: (_, id) => `size *= ${id}_curve(t);`
+  },
+  collision: {
+    name: "collision",
+    description: "Collides with what the camera sees (its depth buffer): bounce or die. GPU only; off screen, particles pass through. The CPU backend doesn't collide.",
+    params: {
+      mode: {
+        kind: "enum",
+        values: ["bounce", "die"],
+        default: "bounce",
+        description: "What a hit does."
+      },
+      restitution: {
+        kind: "number",
+        default: 0.5,
+        description: "Speed kept along the normal (0..1)."
+      },
+      friction: {
+        kind: "number",
+        default: 0.2,
+        description: "Speed lost along the surface (0..1)."
+      },
+      thickness: {
+        kind: "number",
+        default: 0.5,
+        description: "m: surfaces this far behind the depth buffer still count."
+      }
+    },
+    depth: true,
+    update: (p) => `{
+    let hit = depth_collision(pos, vel, ${f(p.thickness)});
+    if (hit.w > 0.0) {
+      ${p.mode === "die" ? "age = life;" : `let n = hit.xyz;
+      let vn = dot(vel, n);
+      if (vn < 0.0) {
+        let vt = vel - n * vn;
+        vel = vt * ${f(1 - p.friction)} - n * vn * ${f(p.restitution)};
+      }`}
+    }
+  }`
+  }
+};
+function validateModule(json, path, errors) {
+  if (!json || typeof json !== "object" || Array.isArray(json)) {
+    errors.push(invalid(path, 'Expected a module: { "module": "<name>", \u2026parameters }'));
+    return void 0;
+  }
+  const entry = json;
+  const def = MODULES[entry.module];
+  if (!def) {
+    errors.push(
+      invalid(
+        `${path}/module`,
+        `Unknown module ${JSON.stringify(entry.module)}`,
+        `Modules: ${Object.keys(MODULES).join(", ")}.`
+      )
+    );
+    return void 0;
+  }
+  const out = { module: def.name };
+  for (const key of Object.keys(entry)) {
+    if (key !== "module" && !def.params[key]) {
+      errors.push(
+        invalid(
+          `${path}/${key}`,
+          `${def.name} has no parameter "${key}"`,
+          `Parameters: ${Object.keys(def.params).join(", ")}.`
+        )
+      );
+    }
+  }
+  for (const [key, param] of Object.entries(def.params)) {
+    const v = entry[key];
+    const at = `${path}/${key}`;
+    if (v === void 0 && param.default === void 0) {
+      errors.push(invalid(at, `${def.name} needs "${key}"`, param.description));
+      continue;
+    }
+    const value = v ?? param.default;
+    switch (param.kind) {
+      case "number":
+        if (typeof value !== "number" || !Number.isFinite(value))
+          errors.push(invalid(at, "Expected a number"));
+        out[key] = value;
+        break;
+      case "scalar":
+        out[key] = scalar(value, at, errors, 0);
+        break;
+      case "vec3":
+        if (!Array.isArray(value) || value.length !== 3 || !value.every((n) => typeof n === "number")) {
+          errors.push(invalid(at, "Expected [x, y, z]"));
+        }
+        out[key] = value;
+        break;
+      case "curve":
+        out[key] = curve(value, at, errors);
+        break;
+      case "gradient":
+        out[key] = gradient(value, at, errors);
+        break;
+      case "enum":
+        if (!param.values.includes(value)) {
+          errors.push(invalid(at, `Expected one of: ${param.values.join(", ")}`));
+        }
+        out[key] = value;
+        break;
+    }
+  }
+  return out;
+}
+function moduleJsonSchema(def) {
+  const range = { type: "array", items: { type: "number" }, minItems: 2, maxItems: 2 };
+  const forms = {
+    number: { type: "number" },
+    scalar: { anyOf: [{ type: "number" }, range] },
+    vec3: { type: "array", items: { type: "number" }, minItems: 3, maxItems: 3 },
+    curve: { anyOf: [{ type: "number" }, { type: "array", items: range }] },
+    gradient: { type: "array", items: { type: "array" } },
+    enum: {}
+  };
+  const properties = { module: { const: def.name } };
+  for (const [key, p] of Object.entries(def.params)) {
+    properties[key] = {
+      ...p.kind === "enum" ? { enum: p.values } : forms[p.kind],
+      description: p.description,
+      ...p.default !== void 0 ? { default: p.default } : {}
+    };
+  }
+  return {
+    type: "object",
+    description: def.description,
+    properties,
+    required: [
+      "module",
+      ...Object.entries(def.params).filter(([, p]) => p.default === void 0).map(([k]) => k)
+    ],
+    additionalProperties: false
+  };
+}
+export {
+  MODULES,
+  moduleJsonSchema,
+  validateModule
+};

package/dist/plugin.d.ts

@@ -0,0 +1,2 @@
+/** GPU particles (and the CPU backend): simulated after the depth resolve, drawn over HDR. */
+export declare const particlesPlugin: import("@aethervtt/shard-runtime").Plugin;

package/dist/plugin.js

@@ -0,0 +1,39 @@
+import { Last } from "@aethervtt/shard-core";
+import { Graph, RenderDescribers, RenderSet } from "@aethervtt/shard-render";
+import { definePlugin } from "@aethervtt/shard-runtime";
+import { OriginShift } from "@aethervtt/shard-transform";
+import * as componentsModule from "./components.js";
+import * as effectModule from "./effect.js";
+import { ParticleEffects } from "./effect.js";
+import * as previewModule from "./preview.js";
+import * as simModule from "./sim.js";
+import {
+  describeParticles,
+  drawNode,
+  Particles,
+  prepareParticles,
+  shiftParticles,
+  simulateNode
+} from "./sim.js";
+const particlesPlugin = definePlugin({
+  name: "particles",
+  provides: [componentsModule, effectModule, previewModule, simModule],
+  dependencies: ["render/forward"],
+  build(app) {
+    app.world.initResource(ParticleEffects);
+    const store = app.world.initResource(Particles);
+    app.world.observe(OriginShift, ({ data }) => {
+      shiftParticles(store, data.offset[0], data.offset[1], data.offset[2]);
+    });
+    app.addSystems(Last, prepareParticles.inSet(RenderSet.Prepare));
+  },
+  ready(app) {
+    const graph = app.world.resource(Graph);
+    graph.addNode("particles/simulate", simulateNode());
+    graph.addNode("particles", drawNode());
+    app.world.initResource(RenderDescribers).set("particles", (w) => describeParticles(w));
+  }
+});
+export {
+  particlesPlugin
+};

package/dist/preview-render.d.ts

@@ -0,0 +1,4 @@
+import { type PreviewImage } from '@aethervtt/shard-assets';
+import type { World } from '@aethervtt/shard-core';
+/** An effect after one second of seeded, fixed-step simulation, in a private world. */
+export declare function renderEffectPreview(world: World, path: string, width: number, height: number): Promise<PreviewImage>;

package/dist/preview-render.js

@@ -0,0 +1,68 @@
+import { assetServer } from "@aethervtt/shard-assets";
+import {
+  Camera3d,
+  captureView,
+  Exposure,
+  forwardPlugin,
+  Gpu,
+  OffscreenTarget,
+  RenderTargets,
+  renderPlugin
+} from "@aethervtt/shard-render";
+import { App } from "@aethervtt/shard-runtime";
+import { Textures } from "@aethervtt/shard-texture";
+import { lookAt, Transform, TransformPlugin } from "@aethervtt/shard-transform";
+import { ParticleSystem } from "./components.js";
+import { ParticleEffect, ParticleEffects } from "./effect.js";
+async function renderEffectPreview(world, path, width, height) {
+  const server = assetServer(world);
+  const artifact = await server.artifact(path);
+  const effect = ParticleEffect.fromJson(artifact.json, (p) => server.resolve(p));
+  const gpu = world.resource(Gpu);
+  const { particlesPlugin } = await import("./plugin.js");
+  const app = new App().addPlugin(
+    TransformPlugin,
+    renderPlugin({ gpu, windowView: false }),
+    forwardPlugin({ msaa: 1 }),
+    particlesPlugin
+  );
+  await app.init();
+  const w = app.world;
+  const textures = world.resource(Textures);
+  for (const e of effect.emitters) {
+    const guid = e.render.texture?.guid;
+    const t = guid ? textures.byGuid(guid) : void 0;
+    if (guid && t) w.resource(Textures).set(guid, t);
+  }
+  const target = new OffscreenTarget(gpu, { label: "particle-preview", width, height });
+  const targetRef = w.resource(RenderTargets).add(target, "particle-preview");
+  const ref = w.resource(ParticleEffects).add(effect);
+  w.spawn([ParticleSystem, { effect: ref, seed: 1 }], Transform);
+  const reach = Math.max(
+    1,
+    ...effect.emitters.map(
+      (e) => e.bounds || e.shape.radius + e.init.speed[1] * e.init.lifetime[1]
+    )
+  );
+  const eye = [0, reach * 0.6, reach * 2.2];
+  const cam = w.spawn(
+    [Camera3d, { target: targetRef, fovY: 45, clearColor: [0.01, 0.01, 0.02, 1] }],
+    [Exposure, { ev100: 10 }],
+    [Transform, { translation: eye, rotation: lookAt(eye, [0, reach * 0.3, 0]) }]
+  );
+  try {
+    for (let i = 0; i < 60; i++) {
+      app.update(1 / 60);
+      await gpu.pipelines.whenIdle();
+    }
+    const shot = captureView(w, `camera:${cam}`);
+    app.update(1 / 60);
+    const image = await shot;
+    return { width: image.width, height: image.height, data: image.data };
+  } finally {
+    target.destroy();
+  }
+}
+export {
+  renderEffectPreview
+};

package/dist/preview.d.ts

@@ -0,0 +1,2 @@
+/** An effect after one second of seeded, fixed-step simulation, in a private world. */
+export declare const particleEffectPreview: import("@aethervtt/shard-assets").AssetPreview;

package/dist/preview.js

@@ -0,0 +1,11 @@
+import { defineAssetPreview } from "@aethervtt/shard-assets";
+const particleEffectPreview = defineAssetPreview(
+  "ParticleEffect",
+  async (world, path, width, height) => {
+    const { renderEffectPreview } = await import("./preview-render.js");
+    return renderEffectPreview(world, path, width, height);
+  }
+);
+export {
+  particleEffectPreview
+};

package/dist/shaders.d.ts

@@ -0,0 +1,15 @@
+import type { EmitterDef } from './effect.js';
+/** Floats per particle: pos + age, vel + life, size, rot, rot speed, seed, color. */
+export declare const PARTICLE_FLOATS = 16;
+/** Bytes of the simulation uniform (see `Sim` below). */
+export declare const SIM_BYTES = 336;
+/** Bytes of the draw uniform (see `Draw` below). */
+export declare const DRAW_BYTES = 112;
+/** A stable key for an emitter's shaders: its modules and render settings. */
+export declare function emitterKey(def: EmitterDef): string;
+/** The compute module of an emitter: spawn (ring allocation), update (modules inlined), count. */
+export declare function simulationShader(def: EmitterDef): string;
+/** The draw module of an emitter: billboards (or meshes) from the particle buffer. */
+export declare function renderShader(def: EmitterDef): string;
+/** Bitonic sort steps (alpha emitters): keys by view depth, far first; dead slots last. */
+export declare const SORT_SHADER = "\nimport shard::view::view;\n\nstruct Particle {\n  /** position, age */\n  p0: vec4f,\n  /** velocity, lifetime (0: never spawned) */\n  p1: vec4f,\n  /** size, rotation, rotation speed, seed bits */\n  p2: vec4f,\n  /** initial color (linear, alpha) */\n  p3: vec4f,\n}\n\nstruct Step { j: u32, k: u32, n: u32, capacity: u32 }\n\n@group(0) @binding(10) var<storage, read> particles: array<Particle>;\n@group(0) @binding(11) var<storage, read_write> keys: array<f32>;\n@group(0) @binding(12) var<storage, read_write> order: array<u32>;\n@group(0) @binding(13) var<uniform> step: Step;\n@group(0) @binding(14) var<uniform> model: mat4x4f;\n\n@compute @workgroup_size(64)\nfn keys_pass(@builtin(global_invocation_id) gid: vec3u) {\n  let i = gid.x;\n  if (i >= step.n) { return; }\n  order[i] = i;\n  var key = 3.0e38;\n  if (i < step.capacity) {\n    let q = particles[i];\n    if (q.p1.w > 0.0 && q.p0.w < q.p1.w) {\n      let world = (model * vec4f(q.p0.xyz, 1.0)).xyz;\n      key = (view.view * vec4f(world, 1.0)).z;\n    }\n  }\n  keys[i] = key;\n}\n\n@compute @workgroup_size(64)\nfn sort_pass(@builtin(global_invocation_id) gid: vec3u) {\n  let i = gid.x;\n  let l = i ^ step.j;\n  if (i >= step.n || l <= i) { return; }\n  let ascending = (i & step.k) == 0u;\n  let a = keys[i];\n  let b = keys[l];\n  if ((a > b) == ascending) {\n    keys[i] = b;\n    keys[l] = a;\n    let t = order[i];\n    order[i] = order[l];\n    order[l] = t;\n  }\n}";