hz-particles 1.0.15 → 1.2.0

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

@@ -12,6 +12,7 @@ export interface ParticleSystemConfig {
   lifetime?: number;
   emissionRate?: number;
   emissionDuration?: number;
+  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;
@@ -34,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;
@@ -51,16 +54,15 @@ export interface ParticleSystemConfig {
   emissionRotationX?: number;
   emissionRotationY?: number;
   emissionRotationZ?: number;
-  emissionTranslationX?: number;
-  emissionTranslationY?: number;
-  emissionTranslationZ?: 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;
@@ -84,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;
@@ -100,6 +108,7 @@ export interface ParticleSystemConfig {
   emissionTrailMinDistance?: number;
   emissionTrailMaxPoints?: number;
   emissionTrailSegments?: number;
+  emissionTrailMode?: 'ribbon' | 'particles';
   emissionTrailShape?: 'straight' | 'zigzag' | 'sine' | 'spiral';
   emissionTrailShapeAmplitude?: number;
   emissionTrailShapeFrequency?: number;
@@ -111,6 +120,7 @@ export interface ParticleSystemConfig {
   oneOnlyMode?: boolean;
   script?: string;
   glbModelData?: string;
+  displayUnit?: 'm' | 'cm';
   onAppearanceChange?: ((config: ParticleSystemConfig) => void) | null;
   onColorChange?: ((config: ParticleSystemConfig) => void) | null;
   onSizeChange?: ((config: ParticleSystemConfig) => void) | null;
@@ -190,6 +200,8 @@ export interface BindGroupLayouts {
 
 export interface RenderPipelines {
   particlePipeline: GPURenderPipeline;
+  particleAdditivePipeline: GPURenderPipeline;
+  particleDepthWritePipeline: GPURenderPipeline;
   blurPipeline: GPURenderPipeline;
   compositePipeline: GPURenderPipeline;
   directRenderPipeline: GPURenderPipeline;
@@ -247,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;
@@ -312,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;
@@ -325,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 {
@@ -601,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);