hz-particles 1.0.14 → 1.2.0

package/dist-lib/hz-particles.d.ts

@@ -12,7 +12,8 @@ export interface ParticleSystemConfig {
   lifetime?: number;
   emissionRate?: number;
   emissionDuration?: number;
-  emissionShape?: 'cube' | 'sphere' | 'square' | 'circle' | 'cylinder' | 'point';
+  emissionDurationInfinite?: boolean;
+  emissionShape?: 'cube' | 'sphere' | 'square' | 'circle' | 'cylinder' | 'plain' | 'cone' | 'torus' | 'line' | 'hemisphere' | 'disc' | 'annulus' | 'capsule' | 'arc' | 'spiral' | 'frustum' | 'cubeSurface' | 'sphereSurface' | 'boxFrame' | 'polygon' | 'rectangle' | 'point';
   particleSize?: number;
   particleSpeed?: number;
   particleColor?: [number, number, number];
@@ -24,6 +25,7 @@ export interface ParticleSystemConfig {
   randomColors?: number[][];
   textureEnabled?: boolean;
   textureType?: 'image' | 'glb';
+  textureImageData?: string;
   glbModelEnabled?: boolean;
   glbFileName?: string | null;
   glbAnimated?: boolean;
@@ -33,7 +35,9 @@ export interface ParticleSystemConfig {
   useGlbTexture?: boolean;
   glbHasTexture?: boolean;
   particleShape?: 'square' | 'circle' | 'triangle' | 'diamond' | 'star' | 'hexagon' | 'ring' | 'heart' | 'cross' | 'spark' | 'leaf' | 'capsule' | 'crescent' | 'line' | 'curved-line';
-  particleShapeRotation?: number;
+  particleShapeRotationX?: number;
+  particleShapeRotationY?: number;
+  particleShapeRotationZ?: number;
   pulseEnabled?: boolean;
   pulseAmplitude?: number;
   pulseFrequency?: number;
@@ -47,19 +51,18 @@ export interface ParticleSystemConfig {
   attractorEnabled?: boolean;
   attractorStrength?: number;
   attractorPosition?: [number, number, number];
-  shapeRotationX?: number;
-  shapeRotationY?: number;
-  shapeRotationZ?: number;
-  shapeTranslationX?: number;
-  shapeTranslationY?: number;
-  shapeTranslationZ?: number;
+  emissionRotationX?: number;
+  emissionRotationY?: number;
+  emissionRotationZ?: number;
+  emissionPositionX?: number;
+  emissionPositionY?: number;
+  emissionPositionZ?: number;
   overrideXVelocity?: boolean;
   overrideYVelocity?: boolean;
   overrideZVelocity?: boolean;
   xVelocity?: number;
   yVelocity?: number;
   zVelocity?: number;
-  cubeLength?: number;
   outerLength?: number;
   innerLength?: number;
   outerRadius?: number;
@@ -68,6 +71,8 @@ export interface ParticleSystemConfig {
   squareInnerSize?: number;
   circleOuterRadius?: number;
   circleInnerRadius?: number;
+  rectangleWidth?: number;
+  rectangleHeight?: number;
   circleVelocityDirection?: string;
   cylinderOuterRadius?: number;
   cylinderInnerRadius?: number;
@@ -81,6 +86,12 @@ export interface ParticleSystemConfig {
   aspectRatio?: number;
   velocityStretchEnabled?: boolean;
   velocityStretchFactor?: number;
+  blendMode?: 'normal' | 'additive';
+  noiseDistortEnabled?: boolean;
+  noiseTilingX?: number;
+  noiseTilingY?: number;
+  noiseSpeed?: number;
+  noiseAmplitude?: number;
   randomSize?: boolean;
   minSize?: number;
   maxSize?: number;
@@ -97,6 +108,7 @@ export interface ParticleSystemConfig {
   emissionTrailMinDistance?: number;
   emissionTrailMaxPoints?: number;
   emissionTrailSegments?: number;
+  emissionTrailMode?: 'ribbon' | 'particles';
   emissionTrailShape?: 'straight' | 'zigzag' | 'sine' | 'spiral';
   emissionTrailShapeAmplitude?: number;
   emissionTrailShapeFrequency?: number;
@@ -106,7 +118,9 @@ export interface ParticleSystemConfig {
   followSystemId?: number | null;
   hidden?: boolean;
   oneOnlyMode?: boolean;
+  script?: string;
   glbModelData?: string;
+  displayUnit?: 'm' | 'cm';
   onAppearanceChange?: ((config: ParticleSystemConfig) => void) | null;
   onColorChange?: ((config: ParticleSystemConfig) => void) | null;
   onSizeChange?: ((config: ParticleSystemConfig) => void) | null;
@@ -186,6 +200,8 @@ export interface BindGroupLayouts {
 
 export interface RenderPipelines {
   particlePipeline: GPURenderPipeline;
+  particleAdditivePipeline: GPURenderPipeline;
+  particleDepthWritePipeline: GPURenderPipeline;
   blurPipeline: GPURenderPipeline;
   compositePipeline: GPURenderPipeline;
   directRenderPipeline: GPURenderPipeline;
@@ -243,6 +259,8 @@ export class ParticleSystem {
   activeParticles: number;
   emitting: boolean;
   currentEmissionTime: number;
+  /** true after destroy() — GPU buffers are gone, all mutating methods become no-ops. */
+  destroyed: boolean;
   particleData: Float32Array;
   particleVelocities: Float32Array;
   instanceBuffer: GPUBuffer;
@@ -290,6 +308,7 @@ export class ParticleSystem {
     outParticleData: Float32Array,
     outVelocities: Float32Array
   ): Promise<PhysicsReadbackResult>;
+  setScript(source: string | null): void;
   destroy(): void;
   respawnParticle(oldIndex: number, newIndex: number): void;
   updateBuffers(): void;
@@ -307,6 +326,9 @@ export class ParticleSystemManager {
   activeSystemIndex: number;
   systemCounter: number;
   onSystemCreated: ((systemId: number, config: ParticleSystemConfig) => void) | null;
+  /** false while replaceSystems()/addSystems() rebuild GPU resources — hosts
+   *  driving their own render loop must skip frames while !ready. */
+  ready: boolean;
 
   createParticleSystem(config?: ParticleSystemConfig): number;
   getSystemById(id: number): SystemEntry | null;
@@ -320,7 +342,8 @@ export class ParticleSystemManager {
   getSystemsList(): SystemInfo[];
   duplicateActiveSystem(): number;
   replaceSystems(sceneData: SceneData): Promise<boolean>;
-  addSystems(sceneData: SceneData, positionOffset?: [number, number, number]): Promise<boolean>;
+  /** Returns the ids of the systems it created (race-proof handle), or false on error. */
+  addSystems(sceneData: SceneData, positionOffset?: [number, number, number]): Promise<number[] | false>;
 }
 
 export class ParticleEmitter {
@@ -387,6 +410,13 @@ export class ParticlePhysics {
     instanceBuffer: GPUBuffer,
     velocityBuffer: GPUBuffer
   ): Promise<PhysicsReadbackResult>;
+  readbackForScript(
+    activeParticles: number,
+    outParticleData: Float32Array,
+    outVelocities: Float32Array,
+    instanceBuffer: GPUBuffer,
+    velocityBuffer: GPUBuffer
+  ): Promise<PhysicsReadbackResult>;
   destroy(): void;
   setDamping(dampingValue: number): void;
   setGravity(gravityValue: number): void;
@@ -483,6 +513,23 @@ export class Objects3DManager {
   ): void;
 }
 
+export class ParticleScript {
+  constructor(source: string, config: ParticleSystemConfig, maxParticles: number);
+  compile(source: string): void;
+  execute(
+    deltaTime: number,
+    time: number,
+    frame: number,
+    totalFrames: number,
+    particleData: Float32Array,
+    velocityData: Float32Array,
+    count: number
+  ): boolean;
+  snapshotConfig(config: ParticleSystemConfig): void;
+  restoreConfig(config: ParticleSystemConfig): void;
+  destroy(): void;
+}
+
 // ─── WebGPU Utilities ────────────────────────────────────────────────────────
 
 export function initWebGPU(canvas: HTMLCanvasElement): Promise<WebGPUContext>;
@@ -572,6 +619,127 @@ export function saveScene(particleSystemManager: ParticleSystemManager): void;
 
 export function loadScene(event: Event): Promise<SceneData>;
 
+/** THE single source of truth for the serializable (non-binary) fields of a system config.
+ *  saveScene, the exported standalone code, and editor undo snapshots all build their
+ *  per-system object from this so the field set can never drift. Binary assets
+ *  (textureImageData / glbModelData) are added by the caller. */
+export function serializeSystemConfig(config: ParticleSystemConfig): Record<string, unknown>;
+
 // ─── Preset Fetching ─────────────────────────────────────────────────────────
 
 export function fetchPreset(url: string): Promise<SceneData>;
+
+// ─── .hzfx — self-contained binary effect package ────────────────────────────
+
+export interface PackHZFXOptions {
+  /** Transcode embedded textures to WebP (browser only — needs OffscreenCanvas). */
+  textureFormat?: 'keep' | 'webp';
+  /** WebP quality 0..1 (default 0.85). */
+  quality?: number;
+}
+
+/** Pack a SceneData into a self-contained .hzfx binary package (config + assets). */
+export function packHZFX(sceneData: SceneData, opts?: PackHZFXOptions): Promise<ArrayBuffer>;
+
+/** Unpack a .hzfx package back into a SceneData the engine consumes. */
+export function unpackHZFX(arrayBuffer: ArrayBuffer): SceneData;
+
+/** True if the buffer starts with the HZFX magic. */
+export function isHZFX(arrayBuffer: ArrayBuffer): boolean;
+
+// ─── Engine-faithful FX overlay/inline renderer ──────────────────────────────
+
+export interface HzFxEmitter {
+  preset: SceneData;
+  position?: [number, number, number];
+}
+
+export interface HzFxOverlayOptions {
+  /** Inline mode only — return the host scene's depth texture (or a
+   *  depth-only view) each frame to occlude particles behind host geometry. */
+  getSceneDepth?: () => GPUTexture | { view: GPUTextureView; multisampled?: boolean } | null;
+  /** Respawn all systems when everything is dead (preview-style looping). Default true. */
+  autoRespawn?: boolean;
+  /** When true (default), the effect's saved group `loop` flag overrides autoRespawn.
+   *  Hosts owning their own respawn timeline (the editor) pass false. */
+  respectEffectLoop?: boolean;
+  /** Share an existing ParticleSystemManager instead of creating one — lets a host
+   *  (e.g. the hz-editor) keep all its UI/config wiring while the overlay is the single
+   *  render path. The overlay then owns updateAllSystems/GLB-update/trail/draw each render(). */
+  manager?: ParticleSystemManager;
+}
+
+export interface HzFxOverlay {
+  manager: ParticleSystemManager;
+  device: GPUDevice;
+  context: GPUCanvasContext;
+  /** Column-major 4×4 matrices (e.g. three camera.projectionMatrix.elements /
+   *  camera.matrixWorldInverse.elements) + camera world position. */
+  setCamera(
+    projectionMatrix: Float32Array | number[],
+    viewMatrix: Float32Array | number[],
+    position?: [number, number, number] | { x: number; y: number; z: number },
+  ): void;
+  setCameraMVP(
+    mvp: Float32Array | number[],
+    position?: [number, number, number] | { x: number; y: number; z: number },
+  ): void;
+  setEmitters(emitters: HzFxEmitter[]): Promise<void>;
+  loadPreset(preset: SceneData, position?: [number, number, number]): Promise<void>;
+  /** Add a preset as a STATIC group at `position` (e.g. a map FX, a splash). Returns a
+   *  handle to remove exactly these systems. Any number coexist in the same overlay —
+   *  prefer this over reaching into `manager.addSystems` directly. */
+  addEmitter(preset: SceneData, position?: [number, number, number]): Promise<{ remove(): void }>;
+  /** Add a preset as a MOVING emitter (e.g. a ball trail); the trail echoes follow
+   *  the recorded path. Two ways to drive its position:
+   *   - PULL (recommended): pass `{ getPosition }` — the overlay reads it during its
+   *     own render(), once/frame at the right time, so the host never pushes per-frame
+   *     (no timing race vs the host loop). Return null to pause the emitter.
+   *   - PUSH: call the returned setPosition() each frame (for simple hosts). */
+  addMovingEmitter(
+    preset: SceneData,
+    opts?: { getPosition?: () => [number, number, number] | { x: number; y: number; z: number } | null },
+  ): Promise<{
+    setPosition(p: [number, number, number] | { x: number; y: number; z: number }): void;
+    remove(): void;
+  }>;
+  /** Simulate + render one frame (deltaTime in seconds). Inline mode: call AFTER the host scene render. */
+  render(deltaTime: number): void;
+  resize(): void;
+  /** Drop cached per-system bind groups. Call after a replaceSystems/addSystems that may
+   *  reuse a system id with a new system object (stale appearance/texture otherwise). */
+  clearCaches(): void;
+  /** Track existing manager systems (by id) as a path-history group so their trails use the
+   *  same curved `hasPathHistory` path as moving emitters — history ONLY (the host keeps
+   *  owning position/rotation/visibility/respawn). Used by the editor's simulate-move. */
+  trackHistoryGroup(
+    ids: Iterable<number>,
+    getPosition: () => [number, number, number] | { x: number; y: number; z: number } | null,
+  ): { remove(): void };
+  destroy(): void;
+}
+
+/**
+ * Engine-faithful FX rendering for host applications — the same render loop as
+ * the HZ Particles previews (library pipelines: shader shapes, per-system
+ * blending, GLB meshes, multi-pass bloom), driven by the host camera.
+ *
+ * Overlay mode: pass a canvas (own transparent WebGPU context, stack it above
+ * your scene). Inline mode: pass { device, context, canvas } from your own
+ * WebGPU renderer and call render() after your scene render each frame.
+ */
+export function initHzFxOverlay(
+  target: HTMLCanvasElement | { device: GPUDevice; context: GPUCanvasContext; canvas?: HTMLCanvasElement },
+  options?: HzFxOverlayOptions,
+): Promise<HzFxOverlay>;
+
+/**
+ * Build a `getSceneDepth` callback (for initHzFxOverlay inline mode) from a three.js
+ * WebGPURenderer, so the overlay occludes particles behind host geometry. Duck-typed —
+ * pass the renderer; no three import. Handles tone-mapping/sRGB internal framebuffers and
+ * returns null (no occlusion, FX stay visible) when the scene depth isn't reachable
+ * (e.g. a PostProcessing pass owns the output). Pass the result as `options.getSceneDepth`.
+ */
+export function makeThreeSceneDepth(
+  gl: unknown,
+): () => (GPUTexture | { view: GPUTextureView; multisampled?: boolean } | null);