@aethervtt/shard-particles 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @aethervtt/shard-particles
+
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/components.d.ts

@@ -0,0 +1,13 @@
+export declare const ParticleSystem: import("@aethervtt/shard-core").ComponentDef<{
+    readonly effect: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"ParticleEffect"> | null, "object">;
+    readonly playing: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly seed: import("@aethervtt/shard-core").FieldType<number, "u32">;
+    readonly timeScale: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly space: import("@aethervtt/shard-core").FieldType<"local" | "world", "u8">;
+    readonly backend: import("@aethervtt/shard-core").FieldType<"cpu" | "gpu", "u8">;
+}>;
+export declare const ParticleEmitterOverrides: import("@aethervtt/shard-core").ComponentDef<{
+    readonly emitter: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly spawnRate: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly spawnScale: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;

package/dist/components.js

@@ -0,0 +1,45 @@
+import { defineComponent, t } from "@aethervtt/shard-core";
+import { Visibility } from "@aethervtt/shard-render";
+import { Transform } from "@aethervtt/shard-transform";
+const ParticleSystem = defineComponent(
+  "particles/ParticleSystem",
+  {
+    effect: t.handle("ParticleEffect", { description: "The effect (*.particles.json) to run." }),
+    playing: t.bool({ default: true, description: "Spawns and simulates. Off: frozen in place." }),
+    seed: t.u32({ description: "Random seed: the same seed replays the same particles." }),
+    timeScale: t.f32({ default: 1, min: 0, description: "Simulation speed." }),
+    space: t.enum(["world", "local"], {
+      description: "world: particles stay where they were emitted (a moving ship leaves its exhaust behind). local: they move with the entity (an engine's glow)."
+    }),
+    backend: t.enum(["gpu", "cpu"], {
+      description: "gpu: compute shaders, for any count. cpu: the same effect simulated in TypeScript, for small counts that gameplay reads."
+    })
+  },
+  {
+    description: "Runs a particle effect at the entity's transform.",
+    requires: [Transform, Visibility]
+  }
+);
+const ParticleEmitterOverrides = defineComponent(
+  "particles/ParticleEmitterOverrides",
+  {
+    emitter: t.string({ description: "Emitter name to change (empty: every emitter)." }),
+    spawnRate: t.f32({
+      default: -1,
+      description: "Particles per second, replacing the effect's rate (negative: the effect's own)."
+    }),
+    spawnScale: t.f32({
+      default: 1,
+      min: 0,
+      description: "Multiplies the spawn rate (thrust \u2192 exhaust)."
+    })
+  },
+  {
+    description: "Gameplay control of a ParticleSystem: its spawn rate, read every frame.",
+    requires: [ParticleSystem]
+  }
+);
+export {
+  ParticleEmitterOverrides,
+  ParticleSystem
+};

package/dist/effect.d.ts

@@ -0,0 +1,85 @@
+import { AssetStore } from '@aethervtt/shard-assets';
+import { type AssetRef, ShardError } from '@aethervtt/shard-core';
+import { type Rgba } from './values.js';
+export declare const SHAPES: readonly ['point', 'sphere', 'cone', 'box'];
+export declare const RENDER_MODES: readonly ['billboard', 'stretched', 'axis', 'mesh'];
+export declare const PARTICLE_BLENDS: readonly ['additive', 'alpha', 'premultiplied'];
+export declare const OFFSCREEN: readonly ['simulate', 'pause', 'reduced'];
+/** One emitter of an effect, validated and with defaults filled in. */
+export interface EmitterDef {
+    name: string;
+    capacity: number;
+    spawn: {
+        rate: number;
+        bursts: {
+            time: number;
+            count: number;
+            interval: number;
+            cycles: number;
+        }[];
+    };
+    shape: {
+        type: (typeof SHAPES)[number];
+        radius: number;
+        angle: number;
+        size: [number, number, number];
+    };
+    init: {
+        lifetime: [number, number];
+        speed: [number, number];
+        size: [number, number];
+        rotation: [number, number];
+        color: [Rgba, Rgba];
+    };
+    update: Record<string, unknown>[];
+    render: {
+        mode: (typeof RENDER_MODES)[number];
+        blend: (typeof PARTICLE_BLENDS)[number];
+        texture: {
+            path?: string;
+            guid?: string;
+        } | null;
+        mesh: {
+            path?: string;
+            guid?: string;
+        } | null;
+        /** Luminance of color 1 (cd/m²). */
+        emissive: number;
+        /** Soft particles: fade over this depth distance (m) at intersections (0: off). */
+        softness: number;
+        /** Stretched mode: length per m/s of speed. */
+        stretch: number;
+        flipbook: {
+            columns: number;
+            rows: number;
+            fps: number;
+        };
+    };
+    offscreen: (typeof OFFSCREEN)[number];
+    /** Authored bounds radius (m) for culling; 0 estimates it from speed and lifetime. */
+    bounds: number;
+}
+/** Validates an effect file; every problem comes back with its JSON pointer. */
+export declare function parseEffect(json: unknown): {
+    emitters: EmitterDef[];
+    errors: ShardError[];
+};
+/** A loaded effect: its emitters, and texture and mesh refs resolved. */
+export declare class ParticleEffect {
+    emitters: EmitterDef[];
+    /** Bumps on hot reload: running systems keep their particles and pick up the new rules. */
+    version: number;
+    constructor(emitters: EmitterDef[]);
+    static fromJson(json: unknown, resolve?: (path: string) => AssetRef | undefined): ParticleEffect;
+    copyFrom(next: ParticleEffect): void;
+}
+export declare class ParticleEffectStore extends AssetStore<ParticleEffect, 'ParticleEffect'> {
+    constructor();
+}
+export declare const ParticleEffects: import("@aethervtt/shard-core").ResourceDef<ParticleEffectStore>;
+export declare const ParticleEffectAssetType: import("@aethervtt/shard-assets").AssetTypeDef<ParticleEffect>;
+/** `*.particles.json`: an effect, validated with pointers into the file. */
+export declare const ParticleEffectImporter: import("@aethervtt/shard-assets").ImporterDef;
+/** The effect file's JSON Schema, from the module registry. */
+export declare function particleEffectJsonSchema(): Record<string, unknown>;
+export declare const particleEffectSchema: () => unknown;

package/dist/effect.js

@@ -0,0 +1,333 @@
+import {
+  AssetStore,
+  defineAssetSchema,
+  defineAssetType,
+  defineImporter
+} from "@aethervtt/shard-assets";
+import {
+  defineResource,
+  defineSchema,
+  ShardError
+} from "@aethervtt/shard-core";
+import { MODULES, moduleJsonSchema, validateModule } from "./modules.js";
+import { color, invalid, scalar } from "./values.js";
+const SHAPES = ["point", "sphere", "cone", "box"];
+const RENDER_MODES = ["billboard", "stretched", "axis", "mesh"];
+const PARTICLE_BLENDS = ["additive", "alpha", "premultiplied"];
+const OFFSCREEN = ["simulate", "pause", "reduced"];
+const num = (v, fallback) => typeof v === "number" && Number.isFinite(v) ? v : fallback;
+function oneOf(values, v, path, errors, fallback) {
+  if (v === void 0) return fallback;
+  if (values.includes(v)) return v;
+  errors.push(invalid(path, `Expected one of: ${values.join(", ")}`));
+  return fallback;
+}
+function object(v, path, errors) {
+  if (v === void 0) return {};
+  if (v && typeof v === "object" && !Array.isArray(v)) return v;
+  errors.push(invalid(path, "Expected an object"));
+  return {};
+}
+function ref(v, path, errors) {
+  if (v === void 0 || v === null) return null;
+  if (v && typeof v === "object" && (typeof v.path === "string" || typeof v.guid === "string")) {
+    return v;
+  }
+  errors.push(invalid(path, 'Expected an asset reference: { "path": "assets/\u2026" }'));
+  return null;
+}
+function emitter(json, path, errors, index) {
+  const e = object(json, path, errors);
+  const spawn = object(e.spawn, `${path}/spawn`, errors);
+  const shape = object(e.shape, `${path}/shape`, errors);
+  const init = object(e.init, `${path}/init`, errors);
+  const render = object(e.render, `${path}/render`, errors);
+  const flip = object(render.flipbook, `${path}/render/flipbook`, errors);
+  const capacity = num(e.capacity, 1e3);
+  if (!Number.isInteger(capacity) || capacity < 1 || capacity > 4194304) {
+    errors.push(invalid(`${path}/capacity`, "Capacity must be a whole number from 1 to 4194304"));
+  }
+  const bursts = Array.isArray(spawn.bursts) ? spawn.bursts : [];
+  const update = Array.isArray(e.update) ? e.update : [];
+  if (e.update !== void 0 && !Array.isArray(e.update))
+    errors.push(invalid(`${path}/update`, "Expected a list of modules"));
+  return {
+    name: typeof e.name === "string" ? e.name : `emitter${index}`,
+    capacity: Math.max(1, Math.floor(capacity)),
+    spawn: {
+      rate: num(spawn.rate, 0),
+      bursts: bursts.map((b, i) => {
+        const o = object(b, `${path}/spawn/bursts/${i}`, errors);
+        return {
+          time: num(o.time, 0),
+          count: num(o.count, 10),
+          interval: num(o.interval, 0),
+          cycles: num(o.cycles, 1)
+        };
+      })
+    },
+    shape: {
+      type: oneOf(SHAPES, shape.type, `${path}/shape/type`, errors, "point"),
+      radius: num(shape.radius, 0),
+      angle: num(shape.angle, 25),
+      size: Array.isArray(shape.size) ? shape.size : [1, 1, 1]
+    },
+    init: {
+      lifetime: scalar(init.lifetime, `${path}/init/lifetime`, errors, 1),
+      speed: scalar(init.speed, `${path}/init/speed`, errors, 1),
+      size: scalar(init.size, `${path}/init/size`, errors, 0.1),
+      rotation: scalar(init.rotation, `${path}/init/rotation`, errors, 0),
+      color: color(init.color, `${path}/init/color`, errors)
+    },
+    update: update.map((m, i) => validateModule(m, `${path}/update/${i}`, errors)).filter((m) => m !== void 0),
+    render: {
+      mode: oneOf(RENDER_MODES, render.mode, `${path}/render/mode`, errors, "billboard"),
+      blend: oneOf(PARTICLE_BLENDS, render.blend, `${path}/render/blend`, errors, "additive"),
+      texture: ref(render.texture, `${path}/render/texture`, errors),
+      mesh: ref(render.mesh, `${path}/render/mesh`, errors),
+      emissive: num(render.emissive, 1e3),
+      softness: num(render.softness, 0),
+      stretch: num(render.stretch, 0.05),
+      flipbook: { columns: num(flip.columns, 1), rows: num(flip.rows, 1), fps: num(flip.fps, 0) }
+    },
+    offscreen: oneOf(OFFSCREEN, e.offscreen, `${path}/offscreen`, errors, "simulate"),
+    bounds: num(e.bounds, 0)
+  };
+}
+function parseEffect(json) {
+  const errors = [];
+  const root = object(json, "", errors);
+  const list = root.emitters;
+  if (!Array.isArray(list) || list.length === 0) {
+    errors.push(
+      invalid(
+        "/emitters",
+        "An effect needs at least one emitter",
+        'Add "emitters": [{ "name": "sparks", \u2026 }].'
+      )
+    );
+    return { emitters: [], errors };
+  }
+  return { emitters: list.map((e, i) => emitter(e, `/emitters/${i}`, errors, i)), errors };
+}
+class ParticleEffect {
+  emitters;
+  /** Bumps on hot reload: running systems keep their particles and pick up the new rules. */
+  version = 0;
+  constructor(emitters) {
+    this.emitters = emitters;
+  }
+  static fromJson(json, resolve) {
+    const { emitters, errors } = parseEffect(json);
+    if (errors.length > 0) {
+      const first = errors[0];
+      throw new ShardError("particles/invalid-effect", first.message, {
+        path: first.path,
+        hint: first.hint,
+        details: errors
+      });
+    }
+    for (const e of emitters) {
+      if (e.render.texture?.path && resolve)
+        e.render.texture = resolve(e.render.texture.path) ?? e.render.texture;
+      if (e.render.mesh?.path && resolve)
+        e.render.mesh = resolve(e.render.mesh.path) ?? e.render.mesh;
+    }
+    return new ParticleEffect(emitters);
+  }
+  copyFrom(next) {
+    this.emitters = next.emitters;
+    this.version++;
+  }
+}
+class ParticleEffectStore extends AssetStore {
+  constructor() {
+    super("ParticleEffect");
+  }
+}
+const ParticleEffects = defineResource("particles/ParticleEffects", {
+  description: "Loaded particle effects by guid.",
+  init: () => new ParticleEffectStore()
+});
+const ParticleEffectAssetType = defineAssetType("ParticleEffect", {
+  store: ParticleEffects,
+  load: (artifact, ctx) => ParticleEffect.fromJson(artifact.json, (p) => ctx.resolve(p)),
+  update: (existing, next) => existing.copyFrom(next)
+});
+const NoSettings = defineSchema(
+  "particles/NoSettings",
+  {},
+  { description: "None: the effect is the file." }
+);
+const ParticleEffectImporter = defineImporter({
+  name: "particles",
+  version: 1,
+  extensions: [".particles.json"],
+  settings: NoSettings,
+  async import(source) {
+    let json;
+    try {
+      json = JSON.parse(source.text());
+    } catch (cause) {
+      throw new ShardError("assets/import-failed", `${source.path} isn't valid JSON`, {
+        path: source.path,
+        cause
+      });
+    }
+    if (json && typeof json === "object" && "$schema" in json) {
+      const { $schema: _, ...rest } = json;
+      json = rest;
+    }
+    const { emitters, errors } = parseEffect(json);
+    if (errors.length > 0) {
+      const first = errors[0];
+      throw new ShardError(
+        "assets/import-failed",
+        `${source.path}: ${first.message}${errors.length > 1 ? ` (+${errors.length - 1} more)` : ""}`,
+        { path: first.path, hint: first.hint, details: errors }
+      );
+    }
+    const dependencies = /* @__PURE__ */ new Set();
+    for (const e of emitters) {
+      if (e.render.texture?.path) dependencies.add(e.render.texture.path);
+      if (e.render.mesh?.path && !e.render.mesh.path.startsWith("procedural:"))
+        dependencies.add(e.render.mesh.path);
+    }
+    return {
+      assets: [
+        {
+          label: "",
+          type: "ParticleEffect",
+          json,
+          ...dependencies.size ? { dependencies: [...dependencies] } : {},
+          info: {
+            emitters: emitters.length,
+            capacity: emitters.reduce((n, e) => n + e.capacity, 0)
+          }
+        }
+      ]
+    };
+  }
+});
+function particleEffectJsonSchema() {
+  const scalar2 = {
+    anyOf: [
+      { type: "number" },
+      { type: "array", items: { type: "number" }, minItems: 2, maxItems: 2 }
+    ],
+    description: "A number, or a [min, max] range picked per particle."
+  };
+  const colorForm = {
+    anyOf: [
+      { type: "string", pattern: "^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" },
+      { type: "array", items: { type: "number" }, minItems: 3, maxItems: 4 },
+      { type: "array", minItems: 2, maxItems: 2 }
+    ],
+    description: '"#rrggbb" (sRGB), [r, g, b, a] (linear), or a range of two colors.'
+  };
+  const ref2 = { type: "object", properties: { path: { type: "string" } }, required: ["path"] };
+  return {
+    $schema: "http://json-schema.org/draft-07/schema#",
+    title: "Particle effect (*.particles.json)",
+    type: "object",
+    properties: {
+      $schema: { type: "string" },
+      emitters: {
+        type: "array",
+        minItems: 1,
+        items: {
+          type: "object",
+          properties: {
+            name: { type: "string" },
+            capacity: { type: "integer", minimum: 1, description: "Most particles alive at once." },
+            spawn: {
+              type: "object",
+              properties: {
+                rate: { type: "number", description: "Particles per second." },
+                bursts: {
+                  type: "array",
+                  items: {
+                    type: "object",
+                    properties: {
+                      time: { type: "number" },
+                      count: { type: "number" },
+                      interval: { type: "number", description: "Seconds between repeats." },
+                      cycles: { type: "number", description: "Repeats (0: forever)." }
+                    }
+                  }
+                }
+              }
+            },
+            shape: {
+              type: "object",
+              properties: {
+                type: { enum: SHAPES },
+                radius: { type: "number" },
+                angle: { type: "number", description: "Cone half-angle, degrees." },
+                size: { type: "array", items: { type: "number" }, minItems: 3, maxItems: 3 }
+              }
+            },
+            init: {
+              type: "object",
+              properties: {
+                lifetime: scalar2,
+                speed: scalar2,
+                size: scalar2,
+                rotation: scalar2,
+                color: colorForm
+              }
+            },
+            update: {
+              type: "array",
+              items: { oneOf: Object.values(MODULES).map(moduleJsonSchema) }
+            },
+            render: {
+              type: "object",
+              properties: {
+                mode: { enum: RENDER_MODES },
+                blend: { enum: PARTICLE_BLENDS },
+                texture: ref2,
+                mesh: ref2,
+                emissive: { type: "number", description: "cd/m\xB2 of color 1." },
+                softness: {
+                  type: "number",
+                  description: "Depth fade distance (m) at intersections."
+                },
+                stretch: { type: "number" },
+                flipbook: {
+                  type: "object",
+                  properties: {
+                    columns: { type: "number" },
+                    rows: { type: "number" },
+                    fps: { type: "number" }
+                  }
+                }
+              }
+            },
+            offscreen: { enum: OFFSCREEN },
+            bounds: { type: "number" }
+          }
+        }
+      }
+    },
+    required: ["emitters"]
+  };
+}
+const particleEffectSchema = defineAssetSchema(
+  "particle-effect.schema.json",
+  particleEffectJsonSchema
+);
+export {
+  OFFSCREEN,
+  PARTICLE_BLENDS,
+  ParticleEffect,
+  ParticleEffectAssetType,
+  ParticleEffectImporter,
+  ParticleEffectStore,
+  ParticleEffects,
+  RENDER_MODES,
+  SHAPES,
+  parseEffect,
+  particleEffectJsonSchema,
+  particleEffectSchema
+};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { ParticleEmitterOverrides, ParticleSystem } from './components.js';
+export { type EmitterDef, OFFSCREEN, PARTICLE_BLENDS, ParticleEffect, ParticleEffectAssetType, ParticleEffectImporter, ParticleEffectStore, ParticleEffects, parseEffect, particleEffectJsonSchema, RENDER_MODES, SHAPES, } from './effect.js';
+export { MODULES, type ModuleDef } from './modules.js';
+export { particlesPlugin } from './plugin.js';
+export { PARTICLE_FLOATS, renderShader, simulationShader } from './shaders.js';
+export { describeParticles, type EmitterState, MAX_SORTED, ParticleStore, Particles, prepareParticles, readParticles, type SystemState, shiftParticles, } from './sim.js';
+export { pcg, rand } from './values.js';

package/dist/index.js

@@ -0,0 +1,56 @@
+import { ParticleEmitterOverrides, ParticleSystem } from "./components.js";
+import {
+  OFFSCREEN,
+  PARTICLE_BLENDS,
+  ParticleEffect,
+  ParticleEffectAssetType,
+  ParticleEffectImporter,
+  ParticleEffectStore,
+  ParticleEffects,
+  parseEffect,
+  particleEffectJsonSchema,
+  RENDER_MODES,
+  SHAPES
+} from "./effect.js";
+import { MODULES } from "./modules.js";
+import { particlesPlugin } from "./plugin.js";
+import { PARTICLE_FLOATS, renderShader, simulationShader } from "./shaders.js";
+import {
+  describeParticles,
+  MAX_SORTED,
+  ParticleStore,
+  Particles,
+  prepareParticles,
+  readParticles,
+  shiftParticles
+} from "./sim.js";
+import { pcg, rand } from "./values.js";
+export {
+  MAX_SORTED,
+  MODULES,
+  OFFSCREEN,
+  PARTICLE_BLENDS,
+  PARTICLE_FLOATS,
+  ParticleEffect,
+  ParticleEffectAssetType,
+  ParticleEffectImporter,
+  ParticleEffectStore,
+  ParticleEffects,
+  ParticleEmitterOverrides,
+  ParticleStore,
+  ParticleSystem,
+  Particles,
+  RENDER_MODES,
+  SHAPES,
+  describeParticles,
+  parseEffect,
+  particleEffectJsonSchema,
+  particlesPlugin,
+  pcg,
+  prepareParticles,
+  rand,
+  readParticles,
+  renderShader,
+  shiftParticles,
+  simulationShader
+};

package/dist/modules.d.ts

@@ -0,0 +1,41 @@
+import type { ShardError } from '@aethervtt/shard-core';
+/** A module parameter: its form, default, and what it means (for the published schema). */
+export interface ParamDef {
+    kind: 'number' | 'scalar' | 'vec3' | 'curve' | 'gradient' | 'enum';
+    default?: unknown;
+    values?: readonly string[];
+    description: string;
+}
+/** A particle's state as the CPU backend holds it (one particle, reused). */
+export interface CpuParticle {
+    pos: Float32Array;
+    vel: Float32Array;
+    age: number;
+    life: number;
+    rot: number;
+    rotSpeed: number;
+    seed: number;
+}
+export interface ModuleDef {
+    name: string;
+    description: string;
+    params: Record<string, ParamDef>;
+    /** WGSL run once at spawn, after the init values (can set rot_speed). */
+    init?(p: Record<string, unknown>): string;
+    /** WGSL run every step for a live particle: pos, vel, age, life, rot, rot_speed, seed, dt. */
+    update?(p: Record<string, unknown>, id: string): string;
+    /** Helper functions the update or render code calls (curves, gradients). */
+    functions?(p: Record<string, unknown>, id: string): string;
+    /** WGSL in the vertex stage: t (life fraction), color, size. */
+    render?(p: Record<string, unknown>, id: string): string;
+    /** The CPU backend's version of `init` and `update`. */
+    cpuInit?(p: Record<string, unknown>, s: CpuParticle): void;
+    cpu?(p: Record<string, unknown>, s: CpuParticle, dt: number, time: number): void;
+    /** Needs the view's depth buffer (collision). */
+    depth?: boolean;
+}
+export declare const MODULES: Record<string, ModuleDef>;
+/** Validates a module entry in place (filling defaults); pushes errors with pointers. */
+export declare function validateModule(json: unknown, path: string, errors: ShardError[]): Record<string, unknown> | undefined;
+/** JSON Schema of a module entry, from its parameter definitions. */
+export declare function moduleJsonSchema(def: ModuleDef): Record<string, unknown>;