@onerjs/core 8.54.4 → 8.54.6

package/Particles/gpuParticleSystem.pure.d.ts

@@ -271,9 +271,45 @@ export declare class GPUParticleSystem extends BaseParticleSystem implements IDi
      * @returns the current particle system
      */
     addColorGradient(gradient: number, color1: Color4, color2?: Color4): GPUParticleSystem;
+    /**
+     * Resyncs the color gradient state after a change.
+     * @param reorder true to re-sort the gradient list by position
+     * @returns true when the existing lookup texture was re-baked in place (value-only change — nothing to
+     * release, the live particle pool survives), false when the change is structural (family emptied, color2 row
+     * layout flipped, or no texture yet) and the caller must release the buffers; in that case the outdated
+     * texture is disposed for lazy recreation.
+     */
     private _refreshColorGradient;
-    /** Force the system to rebuild all gradients that need to be resync */
+    /**
+     * Force the system to rebuild all gradients that need to be resync.
+     *
+     * This is the live-edit entry point both Inspectors call from their gradient onChange handlers, so a
+     * value-only edit must preserve the running simulation: every family whose lookup texture can be re-baked
+     * in place is updated without touching the particle buffers. Only a STRUCTURAL change — a family that has
+     * no texture to re-bake yet, one that was emptied, or a color2 row-layout flip — rebuilds the pool.
+     *
+     * An ABSENT family is not a structural change: it has nothing to resync, and counting it as one would
+     * reset the pool on every call (the destruction this method exists to avoid). Absence has two spellings —
+     * see _gradientFamilyNeedsResync.
+     */
     forceRefreshGradients(): void;
+    /**
+     * Whether a gradient family still has anything for a resync pass to do.
+     *
+     * Absence has TWO spellings: a family that was never initialized is `null`, but one that has been emptied
+     * stays `[]`. Only the first is falsy, so a bare truthiness test reads an emptied family as unfinished
+     * business on every later call — its refresh finds nothing to re-bake, reports "structural", and
+     * forceRefreshGradients resets the live pool forever after, which is precisely the destruction it exists
+     * to prevent.
+     *
+     * Entries always mean work (re-bake in place, or build when there is no texture yet). An EMPTY family is
+     * work only while it still owns a texture: that is the just-emptied transition, whose stale texture must
+     * be disposed. `[]` with no texture is settled absence — nothing left to resync.
+     * @param gradients the gradient family to test, or null when it was never initialized
+     * @param textureName the name of the lookup texture property backing that family
+     * @returns true when the family still has work for a resync pass, false when its absence is settled
+     */
+    private _gradientFamilyNeedsResync;
     /**
      * Remove a specific color gradient
      * @param gradient defines the gradient to remove
@@ -308,6 +344,14 @@ export declare class GPUParticleSystem extends BaseParticleSystem implements IDi
      * @returns the current particle system
      */
     removeSizeGradient(gradient: number): GPUParticleSystem;
+    /**
+     * Resyncs a factor gradient family's lookup texture after a change.
+     * @param factorGradients defines the gradient family that changed
+     * @param textureName defines the name of the property holding the family's lookup texture
+     * @returns true when the existing texture was re-baked in place (value-only change — nothing to release, the
+     * live particle pool survives), false when the caller must release the buffers (no texture to re-bake, or the
+     * family was emptied); in that case the outdated texture is disposed for lazy recreation.
+     */
     private _refreshFactorGradient;
     /**
      * Adds a new angular speed gradient
@@ -490,6 +534,18 @@ export declare class GPUParticleSystem extends BaseParticleSystem implements IDi
      * @param preWarm defines if we are in the pre-warmimg phase
      */
     animate(preWarm?: boolean): void;
+    private _bakeFactorGradientData;
+    /**
+     * Re-bakes an active factor gradient family's lookup texture pixels in place. The texture identity is
+     * preserved, so retained bindings (e.g. the WebGPU update compute shader's) stay valid and no buffer
+     * release is needed — the live particle pool survives the edit. The texture layout is independent of the
+     * number of stops (fixed _rawTextureWidth x 1), so any change within an active family can be re-baked.
+     * @param factorGradients defines the gradient family to bake
+     * @param textureName defines the name of the property holding the family's lookup texture
+     * @returns false when there is nothing to re-bake (no texture yet, or the family was emptied) — callers
+     * fall back to the dispose + release path.
+     */
+    private _rebakeFactorGradientTexture;
     private _createFactorGradientTexture;
     private _createSizeGradientTexture;
     private _createAngularSpeedGradientTexture;
@@ -498,6 +554,15 @@ export declare class GPUParticleSystem extends BaseParticleSystem implements IDi
     private _createDragGradientTexture;
     private _disposeMeshEmitterTextures;
     private _createMeshEmitterTextures;
+    private _bakeColorGradientData;
+    /**
+     * Re-bakes the color gradient lookup texture pixels in place (same texture identity, so retained bindings —
+     * e.g. the WebGPU update compute shader's — stay valid and the live particle pool survives the edit). Only
+     * valid while the row layout is unchanged: a color2 range appearing or disappearing changes the texture
+     * height and the render vertex buffer layout, which must go through the structural dispose + release path.
+     * @returns false when the re-bake cannot handle the change (no texture yet, family emptied, or row layout flip)
+     */
+    private _rebakeColorGradientTexture;
     private _createColorGradientTexture;
     private _render;
     /** @internal */

package/Particles/gpuParticleSystem.pure.js

@@ -307,10 +307,19 @@ export class GPUParticleSystem extends BaseParticleSystem {
         }
         const colorGradient = new ColorGradient(gradient, color1, color2);
         this._colorGradients.push(colorGradient);
-        this._refreshColorGradient(true);
-        this._releaseBuffers();
+        if (!this._refreshColorGradient(true)) {
+            this._releaseBuffers();
+        }
         return this;
     }
+    /**
+     * Resyncs the color gradient state after a change.
+     * @param reorder true to re-sort the gradient list by position
+     * @returns true when the existing lookup texture was re-baked in place (value-only change — nothing to
+     * release, the live particle pool survives), false when the change is structural (family emptied, color2 row
+     * layout flipped, or no texture yet) and the caller must release the buffers; in that case the outdated
+     * texture is disposed for lazy recreation.
+     */
     _refreshColorGradient(reorder = false) {
         if (this._colorGradients) {
             if (reorder) {
@@ -334,6 +343,12 @@ export class GPUParticleSystem extends BaseParticleSystem {
                     break;
                 }
             }
+            // When the texture layout is unchanged, re-bake the existing texture's pixels in place: identity is
+            // preserved, so retained bindings (e.g. the WebGPU update compute shader's) stay valid and no buffer
+            // release is needed.
+            if (this._rebakeColorGradientTexture()) {
+                return true;
+            }
             if (this._colorGradientsTexture) {
                 this._colorGradientsTexture.dispose();
                 this._colorGradientsTexture = null;
@@ -342,16 +357,68 @@ export class GPUParticleSystem extends BaseParticleSystem {
         else {
             this._hasColorGradientColor2 = false;
         }
+        return false;
     }
-    /** Force the system to rebuild all gradients that need to be resync */
+    /**
+     * Force the system to rebuild all gradients that need to be resync.
+     *
+     * This is the live-edit entry point both Inspectors call from their gradient onChange handlers, so a
+     * value-only edit must preserve the running simulation: every family whose lookup texture can be re-baked
+     * in place is updated without touching the particle buffers. Only a STRUCTURAL change — a family that has
+     * no texture to re-bake yet, one that was emptied, or a color2 row-layout flip — rebuilds the pool.
+     *
+     * An ABSENT family is not a structural change: it has nothing to resync, and counting it as one would
+     * reset the pool on every call (the destruction this method exists to avoid). Absence has two spellings —
+     * see _gradientFamilyNeedsResync.
+     */
     forceRefreshGradients() {
-        this._refreshColorGradient();
-        this._refreshFactorGradient(this._sizeGradients, "_sizeGradientsTexture");
-        this._refreshFactorGradient(this._angularSpeedGradients, "_angularSpeedGradientsTexture");
-        this._refreshFactorGradient(this._velocityGradients, "_velocityGradientsTexture");
-        this._refreshFactorGradient(this._limitVelocityGradients, "_limitVelocityGradientsTexture");
-        this._refreshFactorGradient(this._dragGradients, "_dragGradientsTexture");
-        this.reset();
+        let structural = false;
+        if (this._gradientFamilyNeedsResync(this._colorGradients, "_colorGradientsTexture") && !this._refreshColorGradient()) {
+            structural = true;
+        }
+        if (this._gradientFamilyNeedsResync(this._sizeGradients, "_sizeGradientsTexture") && !this._refreshFactorGradient(this._sizeGradients, "_sizeGradientsTexture")) {
+            structural = true;
+        }
+        if (this._gradientFamilyNeedsResync(this._angularSpeedGradients, "_angularSpeedGradientsTexture") &&
+            !this._refreshFactorGradient(this._angularSpeedGradients, "_angularSpeedGradientsTexture")) {
+            structural = true;
+        }
+        if (this._gradientFamilyNeedsResync(this._velocityGradients, "_velocityGradientsTexture") &&
+            !this._refreshFactorGradient(this._velocityGradients, "_velocityGradientsTexture")) {
+            structural = true;
+        }
+        if (this._gradientFamilyNeedsResync(this._limitVelocityGradients, "_limitVelocityGradientsTexture") &&
+            !this._refreshFactorGradient(this._limitVelocityGradients, "_limitVelocityGradientsTexture")) {
+            structural = true;
+        }
+        if (this._gradientFamilyNeedsResync(this._dragGradients, "_dragGradientsTexture") && !this._refreshFactorGradient(this._dragGradients, "_dragGradientsTexture")) {
+            structural = true;
+        }
+        if (structural) {
+            this.reset();
+        }
+    }
+    /**
+     * Whether a gradient family still has anything for a resync pass to do.
+     *
+     * Absence has TWO spellings: a family that was never initialized is `null`, but one that has been emptied
+     * stays `[]`. Only the first is falsy, so a bare truthiness test reads an emptied family as unfinished
+     * business on every later call — its refresh finds nothing to re-bake, reports "structural", and
+     * forceRefreshGradients resets the live pool forever after, which is precisely the destruction it exists
+     * to prevent.
+     *
+     * Entries always mean work (re-bake in place, or build when there is no texture yet). An EMPTY family is
+     * work only while it still owns a texture: that is the just-emptied transition, whose stale texture must
+     * be disposed. `[]` with no texture is settled absence — nothing left to resync.
+     * @param gradients the gradient family to test, or null when it was never initialized
+     * @param textureName the name of the lookup texture property backing that family
+     * @returns true when the family still has work for a resync pass, false when its absence is settled
+     */
+    _gradientFamilyNeedsResync(gradients, textureName) {
+        if (!gradients) {
+            return false;
+        }
+        return gradients.length > 0 || !!this[textureName];
     }
     /**
      * Remove a specific color gradient
@@ -359,10 +426,12 @@ export class GPUParticleSystem extends BaseParticleSystem {
      * @returns the current particle system
      */
     removeColorGradient(gradient) {
-        this._removeGradientAndTexture(gradient, this._colorGradients, this._colorGradientsTexture);
-        this._colorGradientsTexture = null;
-        // The set of remaining gradients may no longer contain a color2; recompute the flag.
-        this._refreshColorGradient();
+        super._removeGradientAndTexture(gradient, this._colorGradients, null);
+        // The set of remaining gradients may no longer contain a color2; _refreshColorGradient recomputes the flag
+        // and either re-bakes the texture in place (value-only change) or signals a structural change.
+        if (!this._refreshColorGradient()) {
+            this._releaseBuffers();
+        }
         return this;
     }
     /**
@@ -386,8 +455,9 @@ export class GPUParticleSystem extends BaseParticleSystem {
             this._sizeGradients = [];
         }
         this._addFactorGradient(this._sizeGradients, gradient, factor, factor2);
-        this._refreshFactorGradient(this._sizeGradients, "_sizeGradientsTexture");
-        this._releaseBuffers();
+        if (!this._refreshFactorGradient(this._sizeGradients, "_sizeGradientsTexture")) {
+            this._releaseBuffers();
+        }
         return this;
     }
     /**
@@ -396,19 +466,33 @@ export class GPUParticleSystem extends BaseParticleSystem {
      * @returns the current particle system
      */
     removeSizeGradient(gradient) {
-        this._removeGradientAndTexture(gradient, this._sizeGradients, this._sizeGradientsTexture);
-        this._sizeGradientsTexture = null;
+        this._removeFactorGradient(this._sizeGradients, gradient);
+        if (!this._refreshFactorGradient(this._sizeGradients, "_sizeGradientsTexture")) {
+            this._releaseBuffers();
+        }
         return this;
     }
+    /**
+     * Resyncs a factor gradient family's lookup texture after a change.
+     * @param factorGradients defines the gradient family that changed
+     * @param textureName defines the name of the property holding the family's lookup texture
+     * @returns true when the existing texture was re-baked in place (value-only change — nothing to release, the
+     * live particle pool survives), false when the caller must release the buffers (no texture to re-bake, or the
+     * family was emptied); in that case the outdated texture is disposed for lazy recreation.
+     */
     _refreshFactorGradient(factorGradients, textureName) {
         if (!factorGradients) {
-            return;
+            return false;
+        }
+        if (this._rebakeFactorGradientTexture(factorGradients, textureName)) {
+            return true;
         }
         const that = this;
         if (that[textureName]) {
             that[textureName].dispose();
             that[textureName] = null;
         }
+        return false;
     }
     /**
      * Adds a new angular speed gradient
@@ -422,8 +506,9 @@ export class GPUParticleSystem extends BaseParticleSystem {
             this._angularSpeedGradients = [];
         }
         this._addFactorGradient(this._angularSpeedGradients, gradient, factor, factor2);
-        this._refreshFactorGradient(this._angularSpeedGradients, "_angularSpeedGradientsTexture");
-        this._releaseBuffers();
+        if (!this._refreshFactorGradient(this._angularSpeedGradients, "_angularSpeedGradientsTexture")) {
+            this._releaseBuffers();
+        }
         return this;
     }
     /**
@@ -432,8 +517,10 @@ export class GPUParticleSystem extends BaseParticleSystem {
      * @returns the current particle system
      */
     removeAngularSpeedGradient(gradient) {
-        this._removeGradientAndTexture(gradient, this._angularSpeedGradients, this._angularSpeedGradientsTexture);
-        this._angularSpeedGradientsTexture = null;
+        this._removeFactorGradient(this._angularSpeedGradients, gradient);
+        if (!this._refreshFactorGradient(this._angularSpeedGradients, "_angularSpeedGradientsTexture")) {
+            this._releaseBuffers();
+        }
         return this;
     }
     /**
@@ -448,8 +535,9 @@ export class GPUParticleSystem extends BaseParticleSystem {
             this._velocityGradients = [];
         }
         this._addFactorGradient(this._velocityGradients, gradient, factor, factor2);
-        this._refreshFactorGradient(this._velocityGradients, "_velocityGradientsTexture");
-        this._releaseBuffers();
+        if (!this._refreshFactorGradient(this._velocityGradients, "_velocityGradientsTexture")) {
+            this._releaseBuffers();
+        }
         return this;
     }
     /**
@@ -458,8 +546,10 @@ export class GPUParticleSystem extends BaseParticleSystem {
      * @returns the current particle system
      */
     removeVelocityGradient(gradient) {
-        this._removeGradientAndTexture(gradient, this._velocityGradients, this._velocityGradientsTexture);
-        this._velocityGradientsTexture = null;
+        this._removeFactorGradient(this._velocityGradients, gradient);
+        if (!this._refreshFactorGradient(this._velocityGradients, "_velocityGradientsTexture")) {
+            this._releaseBuffers();
+        }
         return this;
     }
     /**
@@ -474,8 +564,9 @@ export class GPUParticleSystem extends BaseParticleSystem {
             this._limitVelocityGradients = [];
         }
         this._addFactorGradient(this._limitVelocityGradients, gradient, factor, factor2);
-        this._refreshFactorGradient(this._limitVelocityGradients, "_limitVelocityGradientsTexture");
-        this._releaseBuffers();
+        if (!this._refreshFactorGradient(this._limitVelocityGradients, "_limitVelocityGradientsTexture")) {
+            this._releaseBuffers();
+        }
         return this;
     }
     /**
@@ -484,8 +575,10 @@ export class GPUParticleSystem extends BaseParticleSystem {
      * @returns the current particle system
      */
     removeLimitVelocityGradient(gradient) {
-        this._removeGradientAndTexture(gradient, this._limitVelocityGradients, this._limitVelocityGradientsTexture);
-        this._limitVelocityGradientsTexture = null;
+        this._removeFactorGradient(this._limitVelocityGradients, gradient);
+        if (!this._refreshFactorGradient(this._limitVelocityGradients, "_limitVelocityGradientsTexture")) {
+            this._releaseBuffers();
+        }
         return this;
     }
     /**
@@ -500,8 +593,9 @@ export class GPUParticleSystem extends BaseParticleSystem {
             this._dragGradients = [];
         }
         this._addFactorGradient(this._dragGradients, gradient, factor, factor2);
-        this._refreshFactorGradient(this._dragGradients, "_dragGradientsTexture");
-        this._releaseBuffers();
+        if (!this._refreshFactorGradient(this._dragGradients, "_dragGradientsTexture")) {
+            this._releaseBuffers();
+        }
         return this;
     }
     /**
@@ -510,8 +604,10 @@ export class GPUParticleSystem extends BaseParticleSystem {
      * @returns the current particle system
      */
     removeDragGradient(gradient) {
-        this._removeGradientAndTexture(gradient, this._dragGradients, this._dragGradientsTexture);
-        this._dragGradientsTexture = null;
+        this._removeFactorGradient(this._dragGradients, gradient);
+        if (!this._refreshFactorGradient(this._dragGradients, "_dragGradientsTexture")) {
+            this._releaseBuffers();
+        }
         return this;
     }
     /**
@@ -1330,11 +1426,7 @@ export class GPUParticleSystem extends BaseParticleSystem {
             this._update();
         }
     }
-    _createFactorGradientTexture(factorGradients, textureName) {
-        const texture = this[textureName];
-        if (!factorGradients || !factorGradients.length || texture) {
-            return;
-        }
+    _bakeFactorGradientData(factorGradients) {
         const data = new Float32Array(this._rawTextureWidth * 2);
         for (let x = 0; x < this._rawTextureWidth; x++) {
             const ratio = x / this._rawTextureWidth;
@@ -1345,6 +1437,32 @@ export class GPUParticleSystem extends BaseParticleSystem {
                 data[x * 2 + 1] = Lerp(cg.factor2 ?? cg.factor1, ng.factor2 ?? ng.factor1, scale);
             });
         }
+        return data;
+    }
+    /**
+     * Re-bakes an active factor gradient family's lookup texture pixels in place. The texture identity is
+     * preserved, so retained bindings (e.g. the WebGPU update compute shader's) stay valid and no buffer
+     * release is needed — the live particle pool survives the edit. The texture layout is independent of the
+     * number of stops (fixed _rawTextureWidth x 1), so any change within an active family can be re-baked.
+     * @param factorGradients defines the gradient family to bake
+     * @param textureName defines the name of the property holding the family's lookup texture
+     * @returns false when there is nothing to re-bake (no texture yet, or the family was emptied) — callers
+     * fall back to the dispose + release path.
+     */
+    _rebakeFactorGradientTexture(factorGradients, textureName) {
+        const texture = this[textureName];
+        if (!texture || !factorGradients || !factorGradients.length) {
+            return false;
+        }
+        texture.update(this._bakeFactorGradientData(factorGradients));
+        return true;
+    }
+    _createFactorGradientTexture(factorGradients, textureName) {
+        const texture = this[textureName];
+        if (!factorGradients || !factorGradients.length || texture) {
+            return;
+        }
+        const data = this._bakeFactorGradientData(factorGradients);
         this[textureName] = new RawTexture(data, this._rawTextureWidth, 1, 7, this._scene || this._engine, false, false, 1, 1);
         this[textureName].name = textureName.substring(1);
     }
@@ -1466,14 +1584,7 @@ export class GPUParticleSystem extends BaseParticleSystem {
         this._meshEmitterMeshId = mesh.uniqueId;
         this._meshEmitterUsedNormals = useNormals;
     }
-    _createColorGradientTexture() {
-        if (!this._colorGradients || !this._colorGradients.length || this._colorGradientsTexture) {
-            return;
-        }
-        // When any stop has a color2, pack color1 into row 0 and color2 into row 1. The render shader
-        // samples both rows and lerps using the particle's persistent seed.x for per-particle randomness.
-        const hasColor2 = this._hasColorGradientColor2;
-        const height = hasColor2 ? 2 : 1;
+    _bakeColorGradientData(height) {
         const data = new Uint8Array(this._rawTextureWidth * 4 * height);
         const tmpColor = TmpColors.Color4[0];
         for (let x = 0; x < this._rawTextureWidth; x++) {
@@ -1486,7 +1597,7 @@ export class GPUParticleSystem extends BaseParticleSystem {
                 data[x * 4 + 3] = tmpColor.a * 255;
             });
         }
-        if (hasColor2) {
+        if (height === 2) {
             const rowOffset = this._rawTextureWidth * 4;
             for (let x = 0; x < this._rawTextureWidth; x++) {
                 const ratio = x / this._rawTextureWidth;
@@ -1502,6 +1613,35 @@ export class GPUParticleSystem extends BaseParticleSystem {
                 });
             }
         }
+        return data;
+    }
+    /**
+     * Re-bakes the color gradient lookup texture pixels in place (same texture identity, so retained bindings —
+     * e.g. the WebGPU update compute shader's — stay valid and the live particle pool survives the edit). Only
+     * valid while the row layout is unchanged: a color2 range appearing or disappearing changes the texture
+     * height and the render vertex buffer layout, which must go through the structural dispose + release path.
+     * @returns false when the re-bake cannot handle the change (no texture yet, family emptied, or row layout flip)
+     */
+    _rebakeColorGradientTexture() {
+        const texture = this._colorGradientsTexture;
+        if (!texture || !this._colorGradients || !this._colorGradients.length) {
+            return false;
+        }
+        const height = this._hasColorGradientColor2 ? 2 : 1;
+        if (texture.getSize().height !== height) {
+            return false;
+        }
+        texture.update(this._bakeColorGradientData(height));
+        return true;
+    }
+    _createColorGradientTexture() {
+        if (!this._colorGradients || !this._colorGradients.length || this._colorGradientsTexture) {
+            return;
+        }
+        // When any stop has a color2, pack color1 into row 0 and color2 into row 1. The render shader
+        // samples both rows and lerps using the particle's persistent seed.x for per-particle randomness.
+        const height = this._hasColorGradientColor2 ? 2 : 1;
+        const data = this._bakeColorGradientData(height);
         this._colorGradientsTexture = RawTexture.CreateRGBATexture(data, this._rawTextureWidth, height, this._scene, false, false, 1);
         this._colorGradientsTexture.name = "colorGradients";
     }