@aura3d/rendering 1.0.6

package/src/effects/ParticleDiagnostics.ts

@@ -0,0 +1,224 @@
+import type { GPUParticleBackendCapabilities } from "./GPUParticleBackend.js";
+
+export interface ParticleBatchDiagnosticsInput {
+  readonly name: string;
+  readonly particleCount: number;
+  readonly drawCalls?: number;
+  readonly staticBytesPerParticle?: number;
+  readonly dynamicBytesPerParticle?: number;
+}
+
+export interface ParticleBatchDiagnosticsOptions {
+  readonly updateMode: "static-geometry" | "cpu-dynamic" | "gpu-compute";
+  readonly backend?: GPUParticleBackendCapabilities;
+  readonly targetFrameMs?: number;
+}
+
+export interface ParticleBatchDiagnostics {
+  readonly batches: readonly ParticleBatchDiagnosticsInput[];
+  readonly totalParticles: number;
+  readonly totalDrawCalls: number;
+  readonly staticGeometryBytes: number;
+  readonly dynamicUploadBytes: number;
+  readonly updateMode: ParticleBatchDiagnosticsOptions["updateMode"];
+  readonly gpuBackend: GPUParticleBackendCapabilities;
+  readonly warnings: readonly string[];
+}
+
+export interface ParticleLayerBudgetInput {
+  readonly name: string;
+  readonly weight: number;
+}
+
+export interface ParticleDensityTier<TMode extends string = string> {
+  readonly threshold: number;
+  readonly label: string;
+  readonly mode: TMode;
+}
+
+export interface LayeredParticleBudgetOptions<TMode extends string = string> {
+  readonly requestedParticles: number;
+  readonly defaultParticles?: number;
+  readonly minParticles: number;
+  readonly maxParticles: number;
+  readonly layers: readonly ParticleLayerBudgetInput[];
+  readonly densityTiers: readonly ParticleDensityTier<TMode>[];
+  readonly nativeGpuComputeDispatches?: number;
+}
+
+export interface ParticleLayerBudget {
+  readonly name: string;
+  readonly weight: number;
+  readonly particleCount: number;
+}
+
+export interface LayeredParticleBudgetPlan<TMode extends string = string> {
+  readonly requestedParticles: number;
+  readonly effectiveParticles: number;
+  readonly densityTier: string;
+  readonly mode: TMode;
+  readonly layers: readonly ParticleLayerBudget[];
+  readonly nativeGpuComputeDispatches: number;
+}
+
+const POSITION_ONLY_BYTES = 3 * Float32Array.BYTES_PER_ELEMENT;
+const SPRITE_UPLOAD_BYTES = (3 + 4 + 1 + 1) * Float32Array.BYTES_PER_ELEMENT;
+
+export function createParticleBatchDiagnostics(
+  batches: readonly ParticleBatchDiagnosticsInput[],
+  options: ParticleBatchDiagnosticsOptions
+): ParticleBatchDiagnostics {
+  let totalParticles = 0;
+  let totalDrawCalls = 0;
+  let staticGeometryBytes = 0;
+  let dynamicUploadBytes = 0;
+
+  for (const batch of batches) {
+    validateParticleBatch(batch);
+    totalParticles += batch.particleCount;
+    totalDrawCalls += batch.drawCalls ?? 1;
+    staticGeometryBytes += batch.particleCount * (batch.staticBytesPerParticle ?? POSITION_ONLY_BYTES);
+    dynamicUploadBytes += batch.particleCount * (batch.dynamicBytesPerParticle ?? SPRITE_UPLOAD_BYTES);
+  }
+
+  const gpuBackend = options.backend ?? {
+    supported: false,
+    backend: "none",
+    reason: "No GPU particle backend capability report was supplied."
+  };
+  const warnings = createParticleWarnings(totalParticles, dynamicUploadBytes, options, gpuBackend);
+
+  return {
+    batches,
+    totalParticles,
+    totalDrawCalls,
+    staticGeometryBytes,
+    dynamicUploadBytes,
+    updateMode: options.updateMode,
+    gpuBackend,
+    warnings
+  };
+}
+
+export function summarizeParticleBatchDiagnostics(diagnostics: ParticleBatchDiagnostics): readonly string[] {
+  const gpu = diagnostics.gpuBackend.supported
+    ? `${diagnostics.gpuBackend.backend}${diagnostics.gpuBackend.adapterName ? `:${diagnostics.gpuBackend.adapterName}` : ""}`
+    : `${diagnostics.gpuBackend.backend}:unsupported`;
+  return [
+    `${diagnostics.totalParticles.toLocaleString("en-US")} particles across ${diagnostics.batches.length} A3D point batches`,
+    `${diagnostics.totalDrawCalls} particle draw batches, ${formatBytes(diagnostics.staticGeometryBytes)} static point data`,
+    `${formatBytes(diagnostics.dynamicUploadBytes)} estimated CPU sprite upload if updated as dynamic particles`,
+    `particle update path: ${diagnostics.updateMode}; accelerator backend: ${gpu}`,
+    ...diagnostics.warnings
+  ];
+}
+
+export function createLayeredParticleBudgetPlan<TMode extends string>(
+  options: LayeredParticleBudgetOptions<TMode>
+): LayeredParticleBudgetPlan<TMode> {
+  validateLayeredBudgetOptions(options);
+  const requestedParticles = Number.isFinite(options.requestedParticles)
+    ? Math.round(options.requestedParticles)
+    : Math.round(options.defaultParticles ?? options.minParticles);
+  const effectiveParticles = Math.min(options.maxParticles, Math.max(options.minParticles, requestedParticles));
+  const layers: ParticleLayerBudget[] = [];
+  let assigned = 0;
+  for (let index = 0; index < options.layers.length; index += 1) {
+    const layer = options.layers[index]!;
+    const isLast = index === options.layers.length - 1;
+    const particleCount = isLast
+      ? Math.max(0, effectiveParticles - assigned)
+      : Math.ceil(effectiveParticles * layer.weight);
+    assigned += particleCount;
+    layers.push({
+      name: layer.name,
+      weight: layer.weight,
+      particleCount
+    });
+  }
+  const densityTier = [...options.densityTiers]
+    .sort((a, b) => b.threshold - a.threshold)
+    .find((tier) => effectiveParticles >= tier.threshold) ?? options.densityTiers[options.densityTiers.length - 1]!;
+
+  return {
+    requestedParticles,
+    effectiveParticles,
+    densityTier: densityTier.label,
+    mode: densityTier.mode,
+    layers,
+    nativeGpuComputeDispatches: Math.max(0, Math.round(options.nativeGpuComputeDispatches ?? 0))
+  };
+}
+
+function validateParticleBatch(batch: ParticleBatchDiagnosticsInput): void {
+  if (!Number.isInteger(batch.particleCount) || batch.particleCount < 0) {
+    throw new RangeError("Particle batch particleCount must be a non-negative integer.");
+  }
+  if (batch.drawCalls !== undefined && (!Number.isInteger(batch.drawCalls) || batch.drawCalls < 0)) {
+    throw new RangeError("Particle batch drawCalls must be a non-negative integer.");
+  }
+  if (batch.staticBytesPerParticle !== undefined && (!Number.isFinite(batch.staticBytesPerParticle) || batch.staticBytesPerParticle < 0)) {
+    throw new RangeError("Particle batch staticBytesPerParticle must be finite and non-negative.");
+  }
+  if (batch.dynamicBytesPerParticle !== undefined && (!Number.isFinite(batch.dynamicBytesPerParticle) || batch.dynamicBytesPerParticle < 0)) {
+    throw new RangeError("Particle batch dynamicBytesPerParticle must be finite and non-negative.");
+  }
+}
+
+function validateLayeredBudgetOptions<TMode extends string>(options: LayeredParticleBudgetOptions<TMode>): void {
+  if (!Number.isFinite(options.minParticles) || !Number.isInteger(options.minParticles) || options.minParticles < 0) {
+    throw new RangeError("Layered particle budget minParticles must be a non-negative integer.");
+  }
+  if (options.defaultParticles !== undefined && (!Number.isFinite(options.defaultParticles) || !Number.isInteger(options.defaultParticles))) {
+    throw new RangeError("Layered particle budget defaultParticles must be an integer when supplied.");
+  }
+  if (!Number.isFinite(options.maxParticles) || !Number.isInteger(options.maxParticles) || options.maxParticles < options.minParticles) {
+    throw new RangeError("Layered particle budget maxParticles must be an integer greater than or equal to minParticles.");
+  }
+  if (options.layers.length === 0) {
+    throw new RangeError("Layered particle budget requires at least one layer.");
+  }
+  for (const layer of options.layers) {
+    if (!layer.name.trim()) throw new RangeError("Layered particle budget layer names must be non-empty.");
+    if (!Number.isFinite(layer.weight) || layer.weight < 0 || layer.weight > 1) {
+      throw new RangeError("Layered particle budget layer weights must be finite values from 0 to 1.");
+    }
+  }
+  if (options.densityTiers.length === 0) {
+    throw new RangeError("Layered particle budget requires at least one density tier.");
+  }
+  for (const tier of options.densityTiers) {
+    if (!Number.isFinite(tier.threshold) || !Number.isInteger(tier.threshold) || tier.threshold < 0) {
+      throw new RangeError("Layered particle budget density tier thresholds must be non-negative integers.");
+    }
+    if (!tier.label.trim()) throw new RangeError("Layered particle budget density tier labels must be non-empty.");
+  }
+}
+
+function createParticleWarnings(
+  totalParticles: number,
+  dynamicUploadBytes: number,
+  options: ParticleBatchDiagnosticsOptions,
+  backend: GPUParticleBackendCapabilities
+): readonly string[] {
+  const warnings: string[] = [];
+  if (options.updateMode !== "gpu-compute") {
+    warnings.push("CPU/static particle update path; positions are generated on CPU and animated by render-item transforms");
+  }
+  if (!backend.supported) {
+    warnings.push(backend.reason ?? "GPU particle backend is unavailable in this runtime");
+  }
+  if (totalParticles >= 50000 && options.updateMode !== "gpu-compute") {
+    warnings.push("50k CPU-generated particles is a dense visualization tier, not a native compute-particle stress proof");
+  }
+  if (options.targetFrameMs !== undefined && dynamicUploadBytes / Math.max(1, options.targetFrameMs) > 750_000) {
+    warnings.push("dynamic CPU particle upload estimate is high for the target frame budget");
+  }
+  return warnings;
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KiB`;
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MiB`;
+}

package/src/effects/ParticleEffectPresets.ts

@@ -0,0 +1,147 @@
+import { CollisionModule } from "./CollisionModule.js";
+import { ColorModule } from "./ColorModule.js";
+import { ForceModule } from "./ForceModule.js";
+import { ParticleEmitter } from "./ParticleEmitter.js";
+import { ParticleSystem } from "./ParticleSystem.js";
+import { SizeModule } from "./SizeModule.js";
+
+export type ParticleEffectPresetName = "fire" | "fountain" | "collision-burst" | "spark-shower";
+
+export interface ParticleEffectPresetOptions {
+  readonly seed?: number;
+  readonly maxParticles?: number;
+}
+
+export function createParticleEffectPreset(
+  name: ParticleEffectPresetName,
+  options: ParticleEffectPresetOptions = {}
+): ParticleSystem {
+  if (name === "fire") return createFirePreset(options);
+  if (name === "fountain") return createFountainPreset(options);
+  if (name === "collision-burst") return createCollisionBurstPreset(options);
+  if (name === "spark-shower") return createSparkShowerPreset(options);
+  const exhaustive: never = name;
+  throw new Error(`Unsupported particle effect preset: ${exhaustive}`);
+}
+
+function createSparkShowerPreset(options: ParticleEffectPresetOptions): ParticleSystem {
+  return new ParticleSystem({
+    maxParticles: options.maxParticles ?? 160,
+    emitters: [
+      new ParticleEmitter({
+        seed: options.seed ?? 404,
+        emissionRate: 0,
+        bursts: [{ time: 0, count: 48 }],
+        lifetime: { min: 0.55, max: 1.1 },
+        speed: { min: 0.55, max: 1.15 },
+        shape: { type: "cone", origin: { x: 0, y: 0.12, z: 0 }, radius: 0.22, length: 0.36, angle: Math.PI / 7, emitFromVolume: true },
+        initial: { size: 0.055, color: { r: 1, g: 0.78, b: 0.25, a: 1 } }
+      })
+    ],
+    modules: [
+      new ForceModule({ x: 0.16, y: -1.4, z: 0 }),
+      new ColorModule([
+        { time: 0, color: { r: 1, g: 0.92, b: 0.42, a: 1 } },
+        { time: 0.55, color: { r: 1, g: 0.35, b: 0.1, a: 0.8 } },
+        { time: 1, color: { r: 0.35, g: 0.08, b: 0.04, a: 0.08 } }
+      ]),
+      new SizeModule([
+        { time: 0, size: 0.035 },
+        { time: 0.22, size: 0.075 },
+        { time: 1, size: 0.012 }
+      ]),
+      new CollisionModule({ normal: { x: 0, y: 1, z: 0 }, constant: 0, restitution: 0.18 })
+    ]
+  });
+}
+
+function createFirePreset(options: ParticleEffectPresetOptions): ParticleSystem {
+  return new ParticleSystem({
+    maxParticles: options.maxParticles ?? 260,
+    emitters: [
+      new ParticleEmitter({
+        seed: options.seed ?? 101,
+        emissionRate: 180,
+        lifetime: { min: 0.85, max: 1.25 },
+        speed: { min: 0.3, max: 0.75 },
+        shape: { type: "cone", origin: { x: 0, y: 0.05, z: 0 }, radius: 0.28, length: 0.16, angle: Math.PI / 6, emitFromVolume: true },
+        initial: { size: 0.13 }
+      })
+    ],
+    modules: [
+      new ForceModule({ x: 0.02, y: 0.82, z: 0 }),
+      new ColorModule([
+        { time: 0, color: { r: 1, g: 0.92, b: 0.28, a: 1 } },
+        { time: 0.38, color: { r: 1, g: 0.38, b: 0.08, a: 0.88 } },
+        { time: 0.76, color: { r: 0.72, g: 0.12, b: 0.04, a: 0.36 } },
+        { time: 1, color: { r: 0.12, g: 0.1, b: 0.1, a: 0.08 } }
+      ]),
+      new SizeModule([
+        { time: 0, size: 0.05 },
+        { time: 0.28, size: 0.18 },
+        { time: 0.72, size: 0.13 },
+        { time: 1, size: 0.035 }
+      ])
+    ]
+  });
+}
+
+function createFountainPreset(options: ParticleEffectPresetOptions): ParticleSystem {
+  return new ParticleSystem({
+    maxParticles: options.maxParticles ?? 220,
+    emitters: [
+      new ParticleEmitter({
+        seed: options.seed ?? 202,
+        emissionRate: 155,
+        lifetime: { min: 1.0, max: 1.4 },
+        speed: { min: 0.72, max: 1.15 },
+        shape: { type: "cone", origin: { x: 0, y: 0.08, z: 0 }, radius: 0.12, length: 0.12, angle: Math.PI / 5, emitFromVolume: true },
+        initial: { size: 0.075 }
+      })
+    ],
+    modules: [
+      new ForceModule({ x: 0, y: -0.78, z: 0 }),
+      new ColorModule([
+        { time: 0, color: { r: 0.55, g: 0.9, b: 1, a: 0.95 } },
+        { time: 0.58, color: { r: 0.18, g: 0.62, b: 1, a: 0.72 } },
+        { time: 1, color: { r: 0.1, g: 0.26, b: 1, a: 0.2 } }
+      ]),
+      new SizeModule([
+        { time: 0, size: 0.045 },
+        { time: 0.38, size: 0.09 },
+        { time: 1, size: 0.028 }
+      ])
+    ]
+  });
+}
+
+function createCollisionBurstPreset(options: ParticleEffectPresetOptions): ParticleSystem {
+  return new ParticleSystem({
+    maxParticles: options.maxParticles ?? 96,
+    emitters: [
+      new ParticleEmitter({
+        seed: options.seed ?? 303,
+        emissionRate: 0,
+        bursts: [{ time: 0, count: 42 }],
+        lifetime: { min: 0.9, max: 1.6 },
+        speed: { min: 0.35, max: 0.95 },
+        shape: { type: "sphere", center: { x: 0, y: 0.56, z: 0 }, radius: 0.24 },
+        initial: { size: 0.1, color: { r: 0.45, g: 1, b: 0.58, a: 1 } }
+      })
+    ],
+    modules: [
+      new ForceModule({ x: 0, y: -2.2, z: 0 }),
+      new CollisionModule({ normal: { x: 0, y: 1, z: 0 }, constant: 0, restitution: 0.32 }),
+      new ColorModule([
+        { time: 0, color: { r: 0.7, g: 1, b: 0.62, a: 1 } },
+        { time: 0.5, color: { r: 0.22, g: 1, b: 0.7, a: 0.72 } },
+        { time: 1, color: { r: 0.08, g: 0.45, b: 0.22, a: 0.16 } }
+      ]),
+      new SizeModule([
+        { time: 0, size: 0.055 },
+        { time: 0.2, size: 0.12 },
+        { time: 1, size: 0.025 }
+      ])
+    ]
+  });
+}

package/src/effects/ParticleEmitter.ts

@@ -0,0 +1,326 @@
+import { createParticle, type Particle, type ParticleInitialState, type Vector3Like } from "./Particle.js";
+
+export interface ParticleBurst {
+  time: number;
+  count: number;
+  interval?: number;
+  cycles?: number;
+}
+
+export type ParticleEmitterShape =
+  | { type: "point"; position?: Partial<Vector3Like> }
+  | { type: "box"; center?: Partial<Vector3Like>; size: Partial<Vector3Like> }
+  | { type: "sphere"; center?: Partial<Vector3Like>; radius: number; shell?: boolean }
+  | { type: "circle"; center?: Partial<Vector3Like>; radius: number; arc?: number; filled?: boolean }
+  | { type: "cone"; origin?: Partial<Vector3Like>; radius: number; length: number; angle?: number; emitFromVolume?: boolean };
+
+export interface ParticleEmitterOptions {
+  seed?: number;
+  emissionRate?: number;
+  maxParticles?: number;
+  duration?: number;
+  looping?: boolean;
+  lifetime?: number | { min: number; max: number };
+  speed?: number | { min: number; max: number };
+  shape?: ParticleEmitterShape;
+  bursts?: readonly ParticleBurst[];
+  initial?: Omit<ParticleInitialState, "id" | "age" | "lifetime" | "position" | "velocity">;
+}
+
+export interface EmissionResult {
+  particles: Particle[];
+  requested: number;
+  emitted: number;
+}
+
+function seededRandom(seed: number): () => number {
+  let state = seed >>> 0;
+
+  return () => {
+    state += 0x6d2b79f5;
+    let mixed = state;
+    mixed = Math.imul(mixed ^ (mixed >>> 15), mixed | 1);
+    mixed ^= mixed + Math.imul(mixed ^ (mixed >>> 7), mixed | 61);
+    return ((mixed ^ (mixed >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function validateRange(name: string, value: number | { min: number; max: number }): void {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value < 0) {
+      throw new RangeError(`${name} must be a finite non-negative number.`);
+    }
+    return;
+  }
+
+  if (!Number.isFinite(value.min) || !Number.isFinite(value.max) || value.min < 0 || value.max < value.min) {
+    throw new RangeError(`${name} range must be finite and ordered.`);
+  }
+}
+
+function sampleRange(value: number | { min: number; max: number }, random: () => number): number {
+  return typeof value === "number" ? value : value.min + (value.max - value.min) * random();
+}
+
+function vector(value: Partial<Vector3Like> = {}): Vector3Like {
+  return { x: value.x ?? 0, y: value.y ?? 0, z: value.z ?? 0 };
+}
+
+function randomUnitVector(random: () => number): Vector3Like {
+  const z = random() * 2 - 1;
+  const angle = random() * Math.PI * 2;
+  const radius = Math.sqrt(Math.max(0, 1 - z * z));
+
+  return {
+    x: Math.cos(angle) * radius,
+    y: Math.sin(angle) * radius,
+    z,
+  };
+}
+
+function sampleShape(shape: ParticleEmitterShape, random: () => number): { readonly position: Vector3Like; readonly direction?: Vector3Like } {
+  if (shape.type === "point") {
+    return { position: vector(shape.position) };
+  }
+
+  if (shape.type === "box") {
+    const center = vector(shape.center);
+    return {
+      position: {
+        x: center.x + (random() - 0.5) * (shape.size.x ?? 0),
+        y: center.y + (random() - 0.5) * (shape.size.y ?? 0),
+        z: center.z + (random() - 0.5) * (shape.size.z ?? 0),
+      }
+    };
+  }
+
+  if (shape.type === "circle") {
+    const center = vector(shape.center);
+    const arc = shape.arc ?? Math.PI * 2;
+    const angle = random() * arc;
+    const radius = shape.radius * (shape.filled ? Math.sqrt(random()) : 1);
+    return {
+      position: {
+        x: center.x + Math.cos(angle) * radius,
+        y: center.y,
+        z: center.z + Math.sin(angle) * radius,
+      },
+      direction: { x: Math.cos(angle), y: 0, z: Math.sin(angle) }
+    };
+  }
+
+  if (shape.type === "cone") {
+    const origin = vector(shape.origin);
+    const axial = shape.length * (shape.emitFromVolume ? random() : 1);
+    const radiusAtAxial = shape.radius * (shape.emitFromVolume ? axial / shape.length : 1);
+    const angle = random() * Math.PI * 2;
+    const radial = radiusAtAxial * (shape.emitFromVolume ? Math.sqrt(random()) : 1);
+    const direction = sampleConeDirection(shape, random);
+    return {
+      position: {
+        x: origin.x + Math.cos(angle) * radial,
+        y: origin.y + axial,
+        z: origin.z + Math.sin(angle) * radial,
+      },
+      direction
+    };
+  }
+
+  const center = vector(shape.center);
+  const direction = randomUnitVector(random);
+  const radius = shape.radius * (shape.shell ? 1 : Math.cbrt(random()));
+
+  return {
+    position: {
+      x: center.x + direction.x * radius,
+      y: center.y + direction.y * radius,
+      z: center.z + direction.z * radius,
+    },
+    direction
+  };
+}
+
+function sampleConeDirection(shape: Extract<ParticleEmitterShape, { type: "cone" }>, random: () => number): Vector3Like {
+  const maxAngle = shape.angle ?? Math.atan2(shape.radius, shape.length);
+  const theta = random() * Math.PI * 2;
+  const spread = Math.tan(maxAngle) * Math.sqrt(random());
+  return normalize({
+    x: Math.cos(theta) * spread,
+    y: 1,
+    z: Math.sin(theta) * spread
+  });
+}
+
+function normalize(value: Vector3Like): Vector3Like {
+  const length = Math.hypot(value.x, value.y, value.z) || 1;
+  return { x: value.x / length, y: value.y / length, z: value.z / length };
+}
+
+function validateShape(shape: ParticleEmitterShape): void {
+  if (shape.type === "sphere" && (!Number.isFinite(shape.radius) || shape.radius < 0)) {
+    throw new RangeError("Particle sphere radius must be a finite non-negative number.");
+  }
+  if (shape.type === "circle") {
+    if (!Number.isFinite(shape.radius) || shape.radius < 0) throw new RangeError("Particle circle radius must be a finite non-negative number.");
+    if (shape.arc !== undefined && (!Number.isFinite(shape.arc) || shape.arc <= 0 || shape.arc > Math.PI * 2)) {
+      throw new RangeError("Particle circle arc must be in the range (0, 2pi].");
+    }
+  }
+  if (shape.type === "cone") {
+    if (!Number.isFinite(shape.radius) || shape.radius < 0) throw new RangeError("Particle cone radius must be a finite non-negative number.");
+    if (!Number.isFinite(shape.length) || shape.length <= 0) throw new RangeError("Particle cone length must be a finite positive number.");
+    if (shape.angle !== undefined && (!Number.isFinite(shape.angle) || shape.angle <= 0 || shape.angle >= Math.PI / 2)) {
+      throw new RangeError("Particle cone angle must be in the range (0, pi/2).");
+    }
+  }
+}
+
+export class ParticleEmitter {
+  readonly random: () => number;
+  readonly maxParticles: number;
+  readonly bursts: readonly ParticleBurst[];
+
+  emissionRate: number;
+  duration: number;
+  looping: boolean;
+  lifetime: number | { min: number; max: number };
+  speed: number | { min: number; max: number };
+  shape: ParticleEmitterShape;
+  initial: Omit<ParticleInitialState, "id" | "age" | "lifetime" | "position" | "velocity">;
+  elapsedTime = 0;
+  paused = false;
+
+  private emissionCarry = 0;
+  private nextParticleId = 1;
+  private burstExecutions: number[];
+
+  constructor(options: ParticleEmitterOptions = {}) {
+    this.random = seededRandom(options.seed ?? 1);
+    this.emissionRate = options.emissionRate ?? 10;
+    this.maxParticles = options.maxParticles ?? Number.POSITIVE_INFINITY;
+    this.duration = options.duration ?? Number.POSITIVE_INFINITY;
+    this.looping = options.looping ?? false;
+    this.lifetime = options.lifetime ?? 1;
+    this.speed = options.speed ?? 0;
+    this.shape = options.shape ?? { type: "point" };
+    this.bursts = options.bursts ?? [];
+    this.initial = options.initial ?? {};
+    this.burstExecutions = this.bursts.map(() => 0);
+    validateShape(this.shape);
+
+    if (!Number.isFinite(this.emissionRate) || this.emissionRate < 0) {
+      throw new RangeError("Particle emissionRate must be a finite non-negative number.");
+    }
+    if (!Number.isFinite(this.duration) && this.duration !== Number.POSITIVE_INFINITY) {
+      throw new RangeError("Particle duration must be finite or positive infinity.");
+    }
+    if (this.duration <= 0) {
+      throw new RangeError("Particle duration must be greater than zero.");
+    }
+
+    validateRange("Particle lifetime", this.lifetime);
+    validateRange("Particle speed", this.speed);
+  }
+
+  reset(): void {
+    this.elapsedTime = 0;
+    this.emissionCarry = 0;
+    this.nextParticleId = 1;
+    this.burstExecutions = this.bursts.map(() => 0);
+    this.paused = false;
+  }
+
+  emit(deltaTime: number, capacity = Number.POSITIVE_INFINITY): EmissionResult {
+    if (!Number.isFinite(deltaTime) || deltaTime < 0) {
+      throw new RangeError("ParticleEmitter.emit deltaTime must be a finite non-negative number.");
+    }
+
+    if (this.paused || capacity <= 0) {
+      return { particles: [], requested: 0, emitted: 0 };
+    }
+
+    const previousTime = this.elapsedTime;
+    this.elapsedTime = this.advanceTime(deltaTime);
+    const requested = this.countContinuous(deltaTime, previousTime) + this.countBursts(previousTime, this.elapsedTime);
+    const capped = Math.max(0, Math.min(requested, capacity, this.maxParticles));
+    const particles: Particle[] = [];
+
+    for (let index = 0; index < capped; index += 1) {
+      particles.push(this.createParticle());
+    }
+
+    return { particles, requested, emitted: particles.length };
+  }
+
+  createParticle(): Particle {
+    const emitted = sampleShape(this.shape, this.random);
+    const position = emitted.position;
+    const direction = emitted.direction ?? randomUnitVector(this.random);
+    const speed = sampleRange(this.speed, this.random);
+
+    return createParticle({
+      ...this.initial,
+      id: this.nextParticleId++,
+      age: 0,
+      lifetime: sampleRange(this.lifetime, this.random),
+      position,
+      velocity: {
+        x: direction.x * speed,
+        y: direction.y * speed,
+        z: direction.z * speed,
+      },
+    });
+  }
+
+  private advanceTime(deltaTime: number): number {
+    if (!Number.isFinite(this.duration)) {
+      return this.elapsedTime + deltaTime;
+    }
+
+    const next = this.elapsedTime + deltaTime;
+    return this.looping ? next % this.duration : Math.min(next, this.duration);
+  }
+
+  private countContinuous(deltaTime: number, previousTime: number): number {
+    if (previousTime >= this.duration && !this.looping) {
+      return 0;
+    }
+
+    const activeDelta = Number.isFinite(this.duration) && !this.looping ? Math.min(deltaTime, this.duration - previousTime) : deltaTime;
+    this.emissionCarry += this.emissionRate * Math.max(0, activeDelta);
+    const count = Math.floor(this.emissionCarry);
+    this.emissionCarry -= count;
+    return count;
+  }
+
+  private countBursts(previousTime: number, currentTime: number): number {
+    let count = 0;
+
+    for (let index = 0; index < this.bursts.length; index += 1) {
+      const burst = this.bursts[index];
+      if (burst.count < 0 || burst.time < 0) {
+        throw new RangeError("Particle burst time and count must be non-negative.");
+      }
+
+      const cycles = burst.cycles ?? 1;
+      const interval = burst.interval ?? 0;
+      let executions = this.burstExecutions[index] ?? 0;
+
+      while (executions < cycles) {
+        const triggerTime = burst.time + interval * executions;
+        const crossed = (triggerTime === 0 && previousTime === 0) || (triggerTime > previousTime && triggerTime <= currentTime);
+
+        if (!crossed) {
+          break;
+        }
+
+        count += burst.count;
+        executions += 1;
+      }
+
+      this.burstExecutions[index] = executions;
+    }
+
+    return count;
+  }
+}