@needle-tools/engine 4.13.0 → 4.13.1

package/src/engine-components/particlesystem/ParticleSystem.ts

@@ -24,11 +24,20 @@ const debugProgressiveLoading = getParam("debugprogressive");
 
 export type { Particle as QParticle, Behavior as QParticleBehaviour, TrailParticle as QTrailParticle } from "three.quarks"
 
+/**
+ * Defines when a sub-emitter spawns particles relative to the parent particle's lifecycle.  
+ * Used to create complex effects like explosions on impact or trails following particles.  
+ */
 export enum SubEmitterType {
+    /** Sub-emitter triggers when the parent particle is born */
     Birth = 0,
+    /** Sub-emitter triggers when the parent particle collides */
     Collision = 1,
+    /** Sub-emitter triggers when the parent particle dies */
     Death = 2,
+    /** Sub-emitter triggers when the parent particle enters a trigger zone */
     Trigger = 3,
+    /** Sub-emitter is triggered manually via code */
     Manual = 4,
 }
 
@@ -274,9 +283,33 @@ class ParticleSystemEmissionOverDistance extends BaseValueGenerator {
     }
 }
 
+/**
+ * Base class for custom particle behaviors. Extend this to create custom particle logic.  
+ *
+ * Override `initialize()` to set up per-particle state when particles spawn.  
+ * Override `update()` to modify particles each frame (position, velocity, color, size, etc.).  
+ * Override `frameUpdate()` for logic that runs once per frame (not per particle).  
+ *
+ * @example Custom wind effect
+ * ```ts
+ * class WindBehaviour extends ParticleSystemBaseBehaviour {
+ *   windStrength = 2;
+ *   windDirection = new Vector3(1, 0, 0);
+ *
+ *   update(particle: Particle, delta: number) {
+ *     particle.velocity.addScaledVector(this.windDirection, this.windStrength * delta);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link ParticleSystem.addBehaviour} to register your custom behavior
+ * @link https://github.com/Alchemist0823/three.quarks
+ */
 export abstract class ParticleSystemBaseBehaviour implements Behavior {
 
+    /** Reference to the particle system this behavior belongs to */
     system!: ParticleSystem;
+    /** Access to the engine context for timing, input, etc. */
     get context() { return this.system.context; }
 
     constructor(ps?: ParticleSystem) {
@@ -285,13 +318,18 @@ export abstract class ParticleSystemBaseBehaviour implements Behavior {
             this.system = ps;
     }
 
+    /** Behavior type identifier used by three.quarks */
     type: string;
 
+    /** Called once when a particle is spawned. Use to initialize per-particle state. */
     initialize(_particle: Particle): void { }
+    /** Called every frame for each active particle. Use to update particle properties. */
     update(_particle: Particle, _delta: number): void { }
+    /** Called once per frame before particle updates. Use for shared calculations. */
     frameUpdate(_delta: number): void { }
     toJSON() { throw new Error("Method not implemented."); }
     clone(): Behavior { throw new Error("Method not implemented."); }
+    /** Called when the particle system is reset. */
     reset() { }
 }
 
@@ -686,15 +724,56 @@ class ParticlesEmissionState implements EmissionState {
 }
 
 /**
- * The ParticleSystem component efficiently handles the motion and rendering of many individual particles.    
- * 
- * You can add custom behaviours to the particle system to fully customize the behaviour of the particles. See {@link ParticleSystemBaseBehaviour} and {@link ParticleSystem.addBehaviour} for more information.
- * 
- * Needle Engine uses [three.quarks](https://github.com/Alchemist0823/three.quarks) under the hood to handle particles.
+ * ParticleSystem efficiently handles the motion and rendering of many individual particles.  
+ * Use it for visual effects like fire, smoke, sparks, rain, magic spells, and more.  
  * 
+ * ![](https://cloud.needle.tools/-/media/qz5nO-raa7dNb_XCBNxHmA.gif)  
+ * ![](https://cloud.needle.tools/-/media/IKOrLhesy1dKTfQQxx_pLA.gif)
+ *
+ * **Modules:**
+ * Configure particle behavior through modules like {@link EmissionModule}, {@link ShapeModule},
+ * {@link ColorOverLifetimeModule}, {@link SizeOverLifetimeModule}, {@link VelocityOverLifetimeModule},
+ * {@link NoiseModule}, and {@link TrailModule}.
+ *
+ * **Custom behaviors:**  
+ * Add custom particle behaviors by extending {@link ParticleSystemBaseBehaviour} and  
+ * calling `addBehaviour()`. This gives you full control over particle initialization and updates.  
+ *
+ * **Performance:**  
+ * Particles are batched together for fast, performant rendering even on low-end devices.  
+ * Needle Engine uses [three.quarks](https://github.com/Alchemist0823/three.quarks) internally.  
+ *
+ * @example Basic playback control
+ * ```ts
+ * const ps = myObject.getComponent(ParticleSystem);
+ * ps.play();
+ * ps.emit(10); // Emit 10 particles immediately
+ * ps.pause();
+ * ps.stop(true, true); // Stop and clear all particles
+ * ```
+ *
+ * @example Custom particle behavior
+ * ```ts
+ * class GravityBehaviour extends ParticleSystemBaseBehaviour {
+ *   update(particle: Particle, delta: number) {
+ *     particle.velocity.y -= 9.8 * delta;
+ *   }
+ * }
+ * particleSystem.addBehaviour(new GravityBehaviour());
+ * ```
+ *
+ * - Example: https://engine.needle.tools/samples/particles
+ * - Example: https://engine.needle.tools/samples/particle-bursts
+ * - Example: https://engine.needle.tools/samples/particles-on-collision
+ *
  * @summary Handles the motion and rendering of many individual particles
  * @category Rendering
  * @group Components
+ * @see {@link ParticleSystemBaseBehaviour} for custom particle behaviors
+ * @see {@link EmissionModule} for emission configuration
+ * @see {@link ShapeModule} for emission shape control
+ * @see {@link TrailModule} for particle trails
+ * @link https://engine.needle.tools/docs/features/particles.html
  */
 export class ParticleSystem extends Behaviour implements IParticleSystem {
 

package/src/engine-components/postprocessing/Effects/Antialiasing.ts

@@ -17,6 +17,7 @@ export enum QualityLevel {
 }
 
 /**
+ * [Antialiasing](https://engine.needle.tools/docs/api/Antialiasing) provides SMAA (Subpixel Morphological Antialiasing) post-processing effect to smooth edges in the rendered scene.
  * @category Effects
  * @group Components
  */

package/src/engine-components/postprocessing/Effects/BloomEffect.ts

@@ -8,7 +8,7 @@ import { VolumeParameter } from "../VolumeParameter.js";
 import { registerCustomEffectType } from "../VolumeProfile.js";
 
 /**
- * Bloom can be used to make bright areas in the scene glow.  
+ * [BloomEffect](https://engine.needle.tools/docs/api/BloomEffect) can be used to make bright areas in the scene glow.  
  * @link Sample https://engine.needle.tools/samples/postprocessing
  * @example
  * ```typescript

package/src/engine-components/postprocessing/Effects/ChromaticAberration.ts

@@ -7,7 +7,7 @@ import { VolumeParameter } from "../VolumeParameter.js";
 import { registerCustomEffectType, VolumeProfile } from "../VolumeProfile.js";
 
 /**
- * Chromatic Aberration effect simulates the color fringing effect seen in real-world cameras.  
+ * [ChromaticAberration](https://engine.needle.tools/docs/api/ChromaticAberration) simulates the color fringing effect seen in real-world cameras.  
  * It offsets the red, green, and blue color channels to create a distorted, colorful edge around objects.  
  * This effect can enhance the visual appeal of scenes by adding a subtle or pronounced chromatic distortion.
  * @summary Chromatic Aberration Post-Processing Effect

package/src/engine-components/postprocessing/Effects/ColorAdjustments.ts

@@ -8,7 +8,7 @@ import { registerCustomEffectType } from "../VolumeProfile.js";
 import { ToneMappingEffect } from "./Tonemapping.js";
 
 /**
- * Color Adjustments effect allows you to modify the overall color properties of the rendered scene, including post-exposure, contrast, hue shift, and saturation.  
+ * [ColorAdjustments](https://engine.needle.tools/docs/api/ColorAdjustments) allows you to modify the overall color properties of the rendered scene, including post-exposure, contrast, hue shift, and saturation.  
  * These adjustments can be used to enhance the visual aesthetics of the scene or to achieve specific artistic effects.
  * @summary Color Adjustments Post-Processing Effect
  * @category Effects

package/src/engine-components/postprocessing/Effects/DepthOfField.ts

@@ -17,7 +17,7 @@ export enum DepthOfFieldMode {
 const debug = getParam("debugpost");
 
 /**
- * Depth of Field effect simulates the focusing behavior of real-world cameras by blurring objects that are outside the focal plane.  
+ * [DepthOfField](https://engine.needle.tools/docs/api/DepthOfField) simulates the focusing behavior of real-world cameras by blurring objects that are outside the focal plane.  
  * This effect enhances the sense of depth in a scene by mimicking how cameras focus on subjects at varying distances, creating a more immersive visual experience.  
  * It can be adjusted to achieve different artistic effects, from subtle background blurring to pronounced bokeh effects.
  * @summary Depth of Field Post-Processing Effect

package/src/engine-components/postprocessing/Effects/EffectWrapper.ts

@@ -3,6 +3,7 @@ import type { Effect } from "postprocessing";
 import { EffectProviderResult, PostProcessingEffect } from "../PostProcessingEffect.js";
 
 /**
+ * [EffectWrapper](https://engine.needle.tools/docs/api/EffectWrapper) wraps a custom postprocessing effect to integrate it with the Needle Engine post-processing pipeline.
  *
  * @category Effects
  * @group Components

package/src/engine-components/postprocessing/Effects/Pixelation.ts

@@ -7,7 +7,7 @@ import { VolumeParameter } from "../VolumeParameter.js";
 import { registerCustomEffectType } from "../VolumeProfile.js";
 
 /**
- * Pixelation effect simulates a pixelated look by enlarging pixels in the rendered scene.  
+ * [PixelationEffect](https://engine.needle.tools/docs/api/PixelationEffect) Pixelation effect simulates a pixelated look by enlarging pixels in the rendered scene.  
  * This effect can be used to achieve a retro or stylized visual aesthetic, reminiscent of early video games or low-resolution graphics.
  * @summary Pixelation Post-Processing Effect
  * @category Effects

package/src/engine-components/postprocessing/Effects/ScreenspaceAmbientOcclusion.ts

@@ -7,7 +7,7 @@ import { type EffectProviderResult, PostProcessingEffect } from "../PostProcessi
 import { VolumeParameter } from "../VolumeParameter.js";
 import { registerCustomEffectType } from "../VolumeProfile.js";
 
-/** Screenspace Ambient Occlusion post-processing effect.  
+/** [ScreenSpaceAmbientOcclusion](https://engine.needle.tools/docs/api/ScreenSpaceAmbientOcclusion) is a screenspace ambient occlusion post-processing effect.  
  * We recommend using ScreenSpaceAmbientOcclusionN8 instead.  
  * @category Effects
  * @group Components

package/src/engine-components/postprocessing/Effects/ScreenspaceAmbientOcclusionN8.ts

@@ -22,7 +22,7 @@ export enum ScreenSpaceAmbientOcclusionN8QualityMode {
     Ultra = 4,
 }
 
-/** Screen Space Ambient Occlusion (SSAO) effect.  
+/** [ScreenSpaceAmbientOcclusionN8](https://engine.needle.tools/docs/api/ScreenSpaceAmbientOcclusionN8) is a screen space ambient occlusion (SSAO) effect.
  * Ambient Occlusion is a shading method used to calculate how exposed each point in a scene is to ambient lighting.  
  * The effect enhances the depth and realism of 3D scenes by simulating the soft shadows that occur in crevices, corners, and areas where objects are close to each other.  
  * This implementation uses the N8AO library to provide high-quality SSAO with various quality settings.

package/src/engine-components/postprocessing/Effects/Sharpening.ts

@@ -14,7 +14,7 @@ import { PostProcessingEffectOrder } from "../utils.js";
 // }
 
 /**
- * Sharpening effect enhances the details and edges in the rendered scene by increasing the contrast between adjacent pixels.
+ * [SharpeningEffect](https://engine.needle.tools/docs/api/SharpeningEffect) Sharpening effect enhances the details and edges in the rendered scene by increasing the contrast between adjacent pixels.
  * This effect can make textures and fine details appear clearer and more defined, improving the overall visual quality of the scene.  
  * It is particularly useful in scenes where details may be lost due to blurriness or low resolution.
  * @summary Sharpening Post-Processing Effect

package/src/engine-components/postprocessing/Effects/TiltShiftEffect.ts

@@ -5,7 +5,7 @@ import { VolumeParameter } from "../VolumeParameter.js";
 import { registerCustomEffectType } from "../VolumeProfile.js";
 
 /**
- * Tilt Shift effect simulates a miniature scene by applying a selective focus blur to the rendered image.  
+ * [TiltShiftEffect](https://engine.needle.tools/docs/api/TiltShiftEffect) Tilt Shift effect simulates a miniature scene by applying a selective focus blur to the rendered image.  
  * This effect creates a shallow depth of field, making real-world scenes appear as if they are small-scale models.  
  * It is often used in photography and cinematography to draw attention to specific areas of the scene while blurring out the rest.
  * @summary Tilt Shift Post-Processing Effect

package/src/engine-components/postprocessing/Effects/Tonemapping.ts

@@ -14,7 +14,7 @@ const debug = getParam("debugpost");
 
 
 /**
- * Tonemapping effect adjusts the brightness and contrast of the rendered scene to map high dynamic range (HDR) colors to a displayable range.  
+ * [ToneMappingEffect](https://engine.needle.tools/docs/api/ToneMappingEffect) adjusts the brightness and contrast of the rendered scene to map high dynamic range (HDR) colors to a displayable range.  
  * This effect is essential for achieving realistic lighting and color representation in 3D scenes, as it helps to preserve details in both bright and dark areas.  
  * Various tonemapping algorithms can be applied to achieve different visual styles and effects.
  * @summary Tonemapping Post-Processing Effect

package/src/engine-components/postprocessing/Effects/Vignette.ts

@@ -7,7 +7,7 @@ import { VolumeParameter } from "../VolumeParameter.js";
 import { registerCustomEffectType } from "../VolumeProfile.js";
 
 /**
- * Vignette effect darkens the edges of the rendered scene to draw attention to the center.  
+ * [Vignette](https://engine.needle.tools/docs/api/Vignette) darkens the edges of the rendered scene to draw attention to the center.  
  * This effect simulates the natural vignetting that occurs in photography and cinematography, where the corners of an image are darker than the center.  
  * It can be used to enhance the visual focus on the main subject of the scene and create a more immersive viewing experience.
  * @summary Vignette Post-Processing Effect

package/src/engine-components/postprocessing/PostProcessingHandler.ts

@@ -24,7 +24,7 @@ const autoclearSetting = Symbol("needle:previous-autoclear-state");
 const previousToneMapping = Symbol("needle:previous-tone-mapping");
 
 /**
- * PostProcessingHandler is responsible for applying post processing effects to the scene. It is internally used by the {@link Volume} component
+ * [PostProcessingHandler](https://engine.needle.tools/docs/api/PostProcessingHandler) Is responsible for applying post processing effects to the scene. It is internally used by the {@link Volume} component
  */
 export class PostProcessingHandler {
 

package/src/engine-components/postprocessing/Volume.ts

@@ -16,7 +16,7 @@ import { VolumeProfile } from "./VolumeProfile.js";
 const debug = getParam("debugpost");
 
 
-/** The Volume/PostprocessingManager component is responsible for managing post processing effects.  
+/** [Volume](https://engine.needle.tools/docs/api/Volume) The Volume/PostprocessingManager component is responsible for managing post processing effects.  
  * Add this component to any object in your scene to enable post processing effects.  
  * 
  * @example Add bloom