Merge pull request #35 from NewKrok/claude/fix-world-simulation-CfOH4

test: add world-space simulation invariant tests

Author: NewKrok

.claude/doc/architecture.md

@@ -149,7 +149,8 @@ createParticleSystem(config, externalNow)
   │     ├─ Blending mode, depth settings, transparency
   │     └─ Texture (user-provided, default white circle for POINTS/INSTANCED, or solid white 1×1 for MESH)
   │
-  ├─ 5. Create THREE.Points / THREE.Mesh (INSTANCED/MESH) (+ Gyroscope wrapper for WORLD space)
+  ├─ 5. Create THREE.Points / THREE.Mesh (INSTANCED/MESH)
+  │      For WORLD mode: matrixWorldAutoUpdate = false, matrixWorld held at identity
   │
   └─ 6. Push to createdParticleSystems[], return ParticleSystem handle
 ```
@@ -176,7 +177,8 @@ updateParticleSystems({ now, delta, elapsed })
       │     │
       │     ├─ Update position:
       │     │   position += velocity * delta
-      │     │   (+ worldPositionChange compensation for WORLD space)
+      │     │   (WORLD space: positions are stored in world coords,
+      │     │    so no per-frame emitter-motion compensation is needed)
       │     │
       │     ├─ Apply modifiers (if active):
       │     │   ├─ Linear velocity
@@ -394,16 +396,45 @@ LifetimeCurve       → evaluate curve at time, multiply by scale
 ## World vs Local Simulation Space
 
 ### Local Space (default)
-- Particles are children of the emitter
-- Moving the emitter moves all particles with it
-- No position compensation needed
-- Uses `THREE.Points` directly
+- Particles are children of the emitter in the Three.js scene graph
+- Moving or rotating the emitter moves/rotates all particles with it
+- Buffer stores positions in the emitter's local frame
+- Gravity and force field positions/directions are CPU-transformed into the emitter's local frame each frame so they stay world-aligned
 
 ### World Space
-- Particles stay fixed in world coordinates after emission
-- Emitter movement tracked via `Gyroscope` (from `@newkrok/three-utils`)
-- Each frame: `position -= worldPositionChange` to counteract emitter movement
-- Useful for: trails, smoke, fire that should persist in place
+- Buffer stores positions in **world coordinates** directly
+- `particleSystem.matrixWorld` is held at identity (via `matrixWorldAutoUpdate = false`) so the buffer renders as-is
+- `generalData.sourceWorldMatrix` captures the emitter pose each frame
+  (`parent.matrixWorld × particleSystem.matrix`) — used only to place new
+  particles and orient the emission shape; existing particles are not moved
+- No per-frame position compensation is required
+- Gravity is applied as a constant world vector; force field positions and directions flow through unchanged
+- `instance.position` / `instance.rotation` (Option 2 semantics, matching Unity)
+  offset the spawn origin under the parent but do not drag already-emitted particles
+
+### Parent-scale semantics (Unity Shape-module parity)
+- `generalData.worldScale` is decomposed from the emitter's full world
+  transform each frame (both WORLD and LOCAL modes).
+- **WORLD mode — spawn offsets scale with the parent.** The shape-emission
+  offset (`startPositions[i]`) is multiplied by `worldScale` before being
+  added to the emitter's world translation. This matches Unity's Shape
+  module with `Scaling Mode = Local/Hierarchy`: a sphere of radius 1 under
+  a ×3 parent spawns particles on a world-radius-3 sphere. **Already-emitted
+  particles are unaffected** by subsequent scale changes.
+- **LOCAL mode — gravity is divided by parent scale.** Gravity is authored
+  in world m/s² (`-9.81` fall etc.) but the LOCAL buffer stores velocity in
+  the emitter's local units. Dividing `gravityVelocity` by `worldScale`
+  keeps the rendered fall constant in world units regardless of how the
+  parent chain scales — matching Unity, whose `Physics.gravity` is a world
+  constant.
+- **Design rationale for `matrixWorldAutoUpdate = false` (WORLD mode).**
+  The alternative — re-parenting the `THREE.Points` to the scene root —
+  would hide the particle system from the user's `instance.parent`
+  references and break any scene traversal that expects the instance to
+  live under its intended parent. Forcing `matrixWorld = identity` keeps
+  the object tree intact (so Three.js frustum culling, raycasting, etc.
+  still see the particles under their owning parent) while decoupling the
+  particle render transform from the emitter's motion.
 
 ---
 
@@ -476,7 +507,7 @@ All fields optional — merged with defaults at creation:
 
 ```typescript
 {
-  instance: THREE.Points | THREE.Mesh | Gyroscope  // Add to scene (type depends on renderer + simulation space)
+  instance: THREE.Points | THREE.Mesh  // Add to scene (type depends on renderer)
   update(cycleData)                   // Call every frame
   dispose()                           // Cleanup
   pauseEmitter()                      // Stop emitting

CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to this project will be documented in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/) and uses [Conventional Commits](https://www.conventionalcommits.org/).
 
+## [Unreleased]
+
+### Changed (BREAKING)
+
+- **`SimulationSpace.WORLD` rewritten** to follow Unity's world-simulation-space model. The previous implementation wrapped the particle system in a `three/examples` `Gyroscope`, cancelled the parent rotation, and compensated buffer positions each frame by subtracting the emitter's world movement. The new path stores world coordinates directly in the particle buffer and holds `particleSystem.matrixWorld` at identity so rendering is decoupled from the emitter's scene-graph transform.
+- **Fixed** a gravity direction bug in WORLD mode: gravity is now applied as a constant world vector. Previously it was derived from the emitter's world position treated as a direction vector, causing particles to drift sideways or upward when the emitter moved or rotated.
+- **Fixed** a directional force field bug in WORLD mode: field directions now stay world-aligned regardless of emitter rotation. Previously the direction was pre-rotated by `particleSystem.getWorldQuaternion()`, which did not invoke the Gyroscope's rotation cancellation and therefore picked up the parent rotation.
+- **Fixed** frame-lag jitter on fast-moving emitters (no more `worldPositionChange` subtraction in the integrator, on either the CPU or the GPU compute path).
+- **Fixed** death/birth sub-emitter spawn position on moving emitters: the sub-emitter now spawns at the parent particle's world location, not at the parent emitter's current world position.
+- **Fixed** LOCAL-mode gravity magnitude under scaled parents: gravity is now divided by the emitter's world scale so the rendered fall matches world m/s² regardless of parent scale (Unity parity).
+- **Fixed** WORLD-mode shape-emission spawn offsets not honouring parent scale. Spawn offsets are now multiplied by the emitter's world scale (Unity Shape-module parity with `Scaling Mode = Local/Hierarchy`); live particles remain unaffected by post-spawn scale changes.
+- **Fixed** a stale-matrix bug in LOCAL-mode sub-emitter death/birth callbacks: `particleSystem.updateMatrixWorld()` is now called before `localToWorld(...)` so the sub-emitter spawns at the parent's current world position.
+- **Fixed** a silent CPU→GPU upload regression: the `positionNeedsUpdate` guard no longer flags re-uploads for stationary particles when the emitter moves (`worldPositionChange` conditions removed from the guard, matching the fact that the compensation subtraction was already gone).
+- **Color pipeline standardised to the three.js linear workflow.** User color inputs (`startColor`, `backgroundColor`) and color map textures are now treated as sRGB — the same convention every other three.js material uses. The library decodes to linear on input, shaders operate in linear, and the renderer's output pass converts back to sRGB on the way to the framebuffer. Previously the library wrote raw values to the framebuffer and required consumers to set `renderer.outputColorSpace = LinearSRGBColorSpace`, which broke every non-particle material in the same scene.
+  - GLSL fragment shaders (`particle-system`, `instanced-particle`, `mesh-particle`, `trail`) now include `<colorspace_fragment>` so they participate in the renderer's standard color-space conversion.
+  - TSL materials no longer force `map.colorSpace = NoColorSpace`; user-tagged sRGB textures get the hardware decode the rest of three.js expects.
+  - Per-particle color buffer writes now apply `sRGBToLinear` on user `startColor` values. `colorOverLifetime` multipliers are scalars and keep their existing semantics (applied in linear space).
+  - `backgroundColor` uniforms are converted to linear on upload so `discardBackgroundColor` compares against the (now linear) texture sample on equal footing.
+- **Fixed** `discardBackgroundColor` not firing in WebGPU TSL materials. `Discard()` was wrapped inside a TSL `Fn` helper, which prevented the fragment `discard` statement from propagating to the main shader — so black-background cutouts silently stopped working on the POINTS, INSTANCED, and MESH renderers (Shield, Fireworks, Magnetic Field, Implosion, Explosion with Smoke, etc.).
+- **Fixed** `updateConfig({ simulationSpace })` leaving the system in an inconsistent state. Live-switching simulation space now deactivates existing particles (their buffer positions are in the old frame and would render at random locations) and flips `matrixWorldAutoUpdate` to match what `createParticleSystem` would have set for the new frame. Previously the simulationSpace scalar was updated but the buffer and `matrixWorld` flags were not, causing particles to snap between origins and jump around after a LOCAL↔WORLD toggle.
+
+### Migration
+
+- `ParticleSystem.instance` is now always `THREE.Points | THREE.Mesh` — the union with `Gyroscope` is gone. Any code that checked `instance instanceof Gyroscope` or reached into `instance.children[0]` to find the inner `Points` must use `instance` directly.
+- `ParticleSystemInstance.wrapper` is removed.
+- In WORLD mode, `instance.matrixWorld` is identity. The emitter's pose is still read from the parent chain for emission; `instance.position` / `instance.rotation` act as a spawn-origin offset under the parent and do **not** drag already-emitted particles (matches Unity).
+- The dependency on `three/examples/jsm/misc/Gyroscope.js` is removed.
+- WebGPU-internal uniforms `worldPositionChange` and `simulationSpaceWorld` on the compute pipeline are removed; this only affects code that reached into the compute uniform object directly.
+- **Remove any `renderer.outputColorSpace = LinearSRGBColorSpace` override** that was added for this library. The three.js default (`SRGBColorSpace`) is now correct for both WebGL and WebGPU paths. Leaving the old override in place will double-darken the particles.
+- **`startColor`, `backgroundColor` values are now interpreted as sRGB.** `{ r: 1, g: 0, b: 0 }` renders as "CSS/Photoshop pure red," not as a raw linear 1.0. Configs authored under earlier versions will render slightly differently — to keep the old look exactly, run each color through `linearToSRGB` (exported from the package) once when loading a legacy config. Re-authoring in an updated editor against the new rendering is usually easier.
+- **User color map textures should be tagged `SRGBColorSpace`** (the three.js default when loading via `TextureLoader`). The library no longer overrides this. Non-color / data textures intended as masks should keep `NoColorSpace` as usual.
+
 ## [2.4.0] - 2025-05-20
 
 ### Added

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`.