@newkrok/three-particles 2.16.1 → 3.0.0

package/README.md

@@ -177,6 +177,10 @@ enableWebGPU();
 import * as THREE from "three/webgpu";
 const renderer = new THREE.WebGPURenderer({ antialias: true });
 await renderer.init();
+// No special outputColorSpace handling needed — the library follows the
+// standard three.js linear workflow (user colors sRGB, shader math linear,
+// renderer converts on output). Leave outputColorSpace at its default
+// (SRGBColorSpace).
 
 // 3. Create a GPU-accelerated particle system
 import { createParticleSystem, SimulationBackend } from "@newkrok/three-particles";
@@ -236,6 +240,22 @@ Automatically generated TypeDoc: [https://newkrok.github.io/three-particles/api/
 
 ## Important Notes
 
+### Color Conventions
+
+All RGB values in particle configs (`startColor`, `backgroundColor`) are
+**sRGB** — the same convention used everywhere else in three.js. Pass the
+value a color picker gives you (e.g. `{ r: 1, g: 0, b: 0 }` for pure red)
+and the renderer will display it correctly.
+
+Internally the library decodes these to linear for shader math and relies
+on the renderer's standard output pass to convert back to sRGB on the way
+to the framebuffer. No special `outputColorSpace` setup is required; the
+three.js default (`SRGBColorSpace`) works.
+
+User-supplied color map textures should also be tagged as sRGB
+(`texture.colorSpace = THREE.SRGBColorSpace`) — this is also the
+three.js default for color textures loaded via `TextureLoader`.
+
 ### Color Over Lifetime
 
 The `colorOverLifetime` feature uses a **multiplier-based approach** (similar to Unity's particle system), where each RGB channel curve acts as a multiplier applied to the particle's `startColor`.

package/dist/index.d.ts

@@ -1,7 +1,42 @@
 import * as THREE from 'three';
-import { Gyroscope } from 'three/examples/jsm/misc/Gyroscope.js';
 import { FBM } from 'three-noise/build/three-noise.module.js';
 
+declare const REVISION: string;
+
+/**
+ * Standard IEC 61966-2-1 sRGB → linear transfer function.
+ * Matches `THREE.ColorManagement.SRGBToLinear` and the GLSL
+ * `ShaderChunk.colorspace_fragment` implementation, so that user-provided
+ * colors go through the exact same conversion the rest of the Three.js
+ * pipeline uses for sRGB-tagged inputs.
+ *
+ * Input: a channel value in [0, 1] interpreted as sRGB.
+ * Output: the corresponding linear value in [0, 1].
+ */
+declare const sRGBToLinear: (c: number) => number;
+/**
+ * Standard IEC 61966-2-1 linear → sRGB transfer function.
+ * Inverse of {@link sRGBToLinear}. Useful for one-shot migration of
+ * legacy color values that were authored under the old raw-byte pipeline.
+ */
+declare const linearToSRGB: (c: number) => number;
+/**
+ * Converts an sRGB {r, g, b} triplet to linear space.
+ * Used when uploading user-authored colors (e.g. `backgroundColor`) as
+ * shader uniforms that must match the linear-space texture samples and
+ * vertex colors used elsewhere in the pipeline. Missing channels default
+ * to 0 to mirror the permissive shape of the `Rgb` config type.
+ */
+declare const rgbSRGBToLinear: (c: {
+    r?: number;
+    g?: number;
+    b?: number;
+}) => {
+    r: number;
+    g: number;
+    b: number;
+};
+
 /**
  * Defines the coordinate space in which particles are simulated.
  *
@@ -1829,9 +1864,27 @@ type GeneralData = {
     lastWorldPosition: THREE.Vector3;
     currentWorldPosition: THREE.Vector3;
     worldPositionChange: THREE.Vector3;
+    /**
+     * For WORLD simulation space: the full world transform of the emitter
+     * (parent.matrixWorld × particleSystem.matrix). Used to position new
+     * particles in world coordinates at emit time and to orient the
+     * emission shape. The particleSystem's own matrixWorld is forced to
+     * identity so the buffer coordinates render as world coordinates.
+     */
+    sourceWorldMatrix: THREE.Matrix4;
     wrapperQuaternion: THREE.Quaternion;
-    lastWorldQuaternion: THREE.Quaternion;
     worldQuaternion: THREE.Quaternion;
+    /**
+     * Emitter world scale (decomposed from the full parent chain). Used to
+     * match Unity's parent-scale semantics:
+     *   - WORLD mode: scales the shape-emission offset at spawn time (the
+     *     Shape module in Unity obeys parent scale when Scaling Mode is
+     *     Local/Hierarchy). Live particles are unaffected.
+     *   - LOCAL mode: gravity is stored in local units, so it is divided by
+     *     this scale so the rendered fall matches world -g m/s² regardless
+     *     of parent scale.
+     */
+    worldScale: THREE.Vector3;
     worldEuler: THREE.Euler;
     gravityVelocity: THREE.Vector3;
     startValues: Record<string, Array<number>>;
@@ -1910,7 +1963,6 @@ type MappedAttributes = {
 };
 type ParticleSystemInstance = {
     particleSystem: THREE.Points | THREE.Mesh;
-    wrapper?: Gyroscope;
     mappedAttributes: MappedAttributes;
     /** Shared interleaved Float32Array backing all scalar per-particle attributes. */
     scalarArray: Float32Array;
@@ -2007,7 +2059,7 @@ type ParticleSystemInstance = {
 /**
  * Represents a particle system instance, providing methods to control and manage its lifecycle.
  *
- * @property instance - The underlying Three.js `Points` object or a `Gyroscope` used for particle rendering.
+ * @property instance - The underlying Three.js `Points` or `Mesh` object used for particle rendering.
  * @property resumeEmitter - Resumes the particle emitter, allowing particles to be emitted again.
  * @property pauseEmitter - Pauses the particle emitter, stopping any new particles from being emitted.
  * @property dispose - Disposes of the particle system, cleaning up resources to free memory.
@@ -2025,7 +2077,7 @@ type ParticleSystemInstance = {
  * particleSystem.dispose(); // Cleanup the particle system
  */
 type ParticleSystem = {
-    instance: THREE.Points | THREE.Mesh | Gyroscope;
+    instance: THREE.Points | THREE.Mesh;
     resumeEmitter: () => void;
     pauseEmitter: () => void;
     dispose: () => void;
@@ -2715,4 +2767,4 @@ declare const getDefaultParticleSystemConfig: () => any;
 declare const createParticleSystem: (config?: ParticleSystemConfig, externalNow?: number) => ParticleSystem;
 declare const updateParticleSystems: (cycleData: CycleData) => void;
 
-export { type BezierCurve, type BezierPoint, type Box, type Burst, type BurstState, type Circle, type CollisionPlaneConfig, CollisionPlaneMode, type Cone, type Constant, type CurveBase, type CurveFunction, CurveFunctionId, type CycleData, type EasingCurve, type Emission, EmitFrom, type ForceFieldConfig, ForceFieldFalloff, ForceFieldType, type GeneralData, LifeTimeCurve, type LifetimeCurve, type MappedAttributes, type MeshConfig, type MinMaxColor, type Noise, type NoiseConfig, type NormalizedCollisionPlaneConfig, type NormalizedForceFieldConfig, type NormalizedParticleSystemConfig, type ParticleSystem, type ParticleSystemConfig, type ParticleSystemInstance, type Point3D, type RandomBetweenTwoConstants, type Rectangle, type Renderer, RendererType, type Rgb, SCALAR_STRIDE, S_COLOR_A, S_COLOR_B, S_COLOR_G, S_COLOR_R, S_IS_ACTIVE, S_LIFETIME, S_ROTATION, S_SIZE, S_START_FRAME, S_START_LIFETIME, Shape, type ShapeConfig, SimulationBackend, SimulationSpace, type SoftParticlesConfig, type Sphere, type SubEmitterConfig, SubEmitterTrigger, type TextureSheetAnimation, TimeMode, type TrailConfig, type Transform, type VelocityOverLifetime, applyModifiers, blendingMap, calculateRandomPositionAndVelocityOnBox, calculateRandomPositionAndVelocityOnCircle, calculateRandomPositionAndVelocityOnCone, calculateRandomPositionAndVelocityOnRectangle, calculateRandomPositionAndVelocityOnSphere, calculateValue, createBezierCurveFunction, createDefaultMeshTexture, createDefaultParticleTexture, createParticleSystem, curveFunctionIdMap, deserializeParticleSystem, getBezierCacheSize, getCurveFunction, getCurveFunctionFromConfig, getDefaultParticleSystemConfig, isComputeCapableRenderer, isLifeTimeCurve, registerTSLMaterialFactory, removeBezierCurveFunction, resolveSimulationBackend, serializeParticleSystem, updateParticleSystems };
+export { type BezierCurve, type BezierPoint, type Box, type Burst, type BurstState, type Circle, type CollisionPlaneConfig, CollisionPlaneMode, type Cone, type Constant, type CurveBase, type CurveFunction, CurveFunctionId, type CycleData, type EasingCurve, type Emission, EmitFrom, type ForceFieldConfig, ForceFieldFalloff, ForceFieldType, type GeneralData, LifeTimeCurve, type LifetimeCurve, type MappedAttributes, type MeshConfig, type MinMaxColor, type Noise, type NoiseConfig, type NormalizedCollisionPlaneConfig, type NormalizedForceFieldConfig, type NormalizedParticleSystemConfig, type ParticleSystem, type ParticleSystemConfig, type ParticleSystemInstance, type Point3D, REVISION, type RandomBetweenTwoConstants, type Rectangle, type Renderer, RendererType, type Rgb, SCALAR_STRIDE, S_COLOR_A, S_COLOR_B, S_COLOR_G, S_COLOR_R, S_IS_ACTIVE, S_LIFETIME, S_ROTATION, S_SIZE, S_START_FRAME, S_START_LIFETIME, Shape, type ShapeConfig, SimulationBackend, SimulationSpace, type SoftParticlesConfig, type Sphere, type SubEmitterConfig, SubEmitterTrigger, type TextureSheetAnimation, TimeMode, type TrailConfig, type Transform, type VelocityOverLifetime, applyModifiers, blendingMap, calculateRandomPositionAndVelocityOnBox, calculateRandomPositionAndVelocityOnCircle, calculateRandomPositionAndVelocityOnCone, calculateRandomPositionAndVelocityOnRectangle, calculateRandomPositionAndVelocityOnSphere, calculateValue, createBezierCurveFunction, createDefaultMeshTexture, createDefaultParticleTexture, createParticleSystem, curveFunctionIdMap, deserializeParticleSystem, getBezierCacheSize, getCurveFunction, getCurveFunctionFromConfig, getDefaultParticleSystemConfig, isComputeCapableRenderer, isLifeTimeCurve, linearToSRGB, registerTSLMaterialFactory, removeBezierCurveFunction, resolveSimulationBackend, rgbSRGBToLinear, sRGBToLinear, serializeParticleSystem, updateParticleSystems };