@aura3d/rendering 1.3.3 → 1.4.1

package/src/effects/Particle.ts

@@ -1,108 +0,0 @@
-export interface Vector3Like {
-  x: number;
-  y: number;
-  z: number;
-}
-
-export interface ColorLike {
-  r: number;
-  g: number;
-  b: number;
-  a: number;
-}
-
-export interface Particle {
-  id: number;
-  age: number;
-  lifetime: number;
-  position: Vector3Like;
-  previousPosition: Vector3Like;
-  velocity: Vector3Like;
-  acceleration: Vector3Like;
-  color: ColorLike;
-  size: number;
-  rotation: number;
-  angularVelocity: number;
-  alive: boolean;
-  userData: Record<string, unknown>;
-}
-
-export interface ParticleInitialState {
-  id?: number;
-  age?: number;
-  lifetime?: number;
-  position?: Partial<Vector3Like>;
-  velocity?: Partial<Vector3Like>;
-  acceleration?: Partial<Vector3Like>;
-  color?: Partial<ColorLike>;
-  size?: number;
-  rotation?: number;
-  angularVelocity?: number;
-  alive?: boolean;
-  userData?: Record<string, unknown>;
-}
-
-export function createVector3(value: Partial<Vector3Like> = {}): Vector3Like {
-  return {
-    x: value.x ?? 0,
-    y: value.y ?? 0,
-    z: value.z ?? 0,
-  };
-}
-
-export function cloneVector3(value: Vector3Like): Vector3Like {
-  return { x: value.x, y: value.y, z: value.z };
-}
-
-export function addScaledVector3(target: Vector3Like, source: Vector3Like, scale: number): void {
-  target.x += source.x * scale;
-  target.y += source.y * scale;
-  target.z += source.z * scale;
-}
-
-export function setVector3(target: Vector3Like, source: Vector3Like): void {
-  target.x = source.x;
-  target.y = source.y;
-  target.z = source.z;
-}
-
-export function createColor(value: Partial<ColorLike> = {}): ColorLike {
-  return {
-    r: value.r ?? 1,
-    g: value.g ?? 1,
-    b: value.b ?? 1,
-    a: value.a ?? 1,
-  };
-}
-
-export function cloneColor(value: ColorLike): ColorLike {
-  return { r: value.r, g: value.g, b: value.b, a: value.a };
-}
-
-export function createParticle(initial: ParticleInitialState = {}): Particle {
-  if ((initial.lifetime ?? 1) <= 0) {
-    throw new RangeError("Particle lifetime must be greater than zero.");
-  }
-
-  const position = createVector3(initial.position);
-
-  return {
-    id: initial.id ?? 0,
-    age: initial.age ?? 0,
-    lifetime: initial.lifetime ?? 1,
-    position,
-    previousPosition: cloneVector3(position),
-    velocity: createVector3(initial.velocity),
-    acceleration: createVector3(initial.acceleration),
-    color: createColor(initial.color),
-    size: initial.size ?? 1,
-    rotation: initial.rotation ?? 0,
-    angularVelocity: initial.angularVelocity ?? 0,
-    alive: initial.alive ?? true,
-    userData: { ...(initial.userData ?? {}) },
-  };
-}
-
-export function normalizedParticleAge(particle: Particle): number {
-  return particle.lifetime <= 0 ? 1 : Math.min(Math.max(particle.age / particle.lifetime, 0), 1);
-}

package/src/effects/ParticleDiagnostics.ts

@@ -1,224 +0,0 @@
-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

@@ -1,147 +0,0 @@
-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 }
-      ])
-    ]
-  });
-}