babylon.quarks 0.28.0 → 0.29.0

package/src/system/settingsSchema.ts

@@ -23,8 +23,12 @@ import {
     DEFAULT_SOFT_FAR_FADE,
     normalizeBursts,
     validCullingMode,
+    validLoopRange,
     validRenderFace,
+    validRingBufferMode,
+    validScalingMode,
     validSortMode,
+    validStopAction,
     validTileCount,
 } from './normalize';
 import type {
@@ -142,7 +146,7 @@ function vectorJSON(value: unknown): number[] | undefined {
 
 /** Every plain and generator setting, in the order `toJSON` writes them. */
 export const SETTINGS: ReadonlyArray<SettingDescriptor> = [
-    plain('autoDestroy', (s) => s.autoDestroy, false, boolean),
+    plain('stopAction', (s) => s.stopAction, 'none', validStopAction),
     plain('looping', (s) => s.looping, true, boolean),
     plain('prewarm', (s) => s.prewarm, false, boolean),
     plain('prewarmTime', (s) => s.prewarmTime, 0, number),
@@ -228,6 +232,15 @@ export const SETTINGS: ReadonlyArray<SettingDescriptor> = [
         clone: (value) => (value as BurstParameters[]).map((burst) => ({...burst, count: burst.count.clone()})),
     },
     plain('maxParticles', (s) => s.maxParticles, undefined, number),
+    plain('ringBufferMode', (s) => s.ringBufferMode, 'disabled', validRingBufferMode),
+    {
+        param: 'ringBufferLoopRange',
+        get: (s) => s.ringBufferLoopRange,
+        isDefault: (value) => (value as Vector2).x === 0 && (value as Vector2).y === 1,
+        toJSON: vectorJSON,
+        fromJSON: (json) => (Array.isArray(json) ? validLoopRange(new Vector2(json[0], json[1])) : undefined),
+        clone: (value) => (value as Vector2).clone(),
+    },
     plain('onlyUsedByOther', (s) => s.onlyUsedByOther, false, boolean),
     plain('renderMode', (s) => s.renderMode, RenderMode.BillBoard, number),
     plain('renderOrder', (s) => s.renderOrder, 0, number),
@@ -238,14 +251,15 @@ export const SETTINGS: ReadonlyArray<SettingDescriptor> = [
         true,
         (json) => json !== false
     ),
-    plain('playbackSpeed', (s) => s.playbackSpeed, 1, number),
-    plain('cullingMode', (s) => s.cullingMode, 'always', validCullingMode),
     plain(
-        'scalingMode',
-        (s) => s.scalingMode,
-        'shape',
-        (json) => (json === 'hierarchy' ? 'hierarchy' : 'shape')
+        'applyImageProcessing',
+        (s) => s.applyImageProcessing,
+        true,
+        (json) => json !== false
     ),
+    plain('playbackSpeed', (s) => s.playbackSpeed, 1, number),
+    plain('cullingMode', (s) => s.cullingMode, 'always', validCullingMode),
+    plain('scalingMode', (s) => s.scalingMode, 'local', validScalingMode),
     plain('seed', (s) => s.seed, undefined, number),
     plain('sortMode', (s) => s.sortMode, 'none', validSortMode),
     plain('renderFace', (s) => s.renderFace, 'both', validRenderFace),
@@ -326,6 +340,10 @@ export function settingsFromJSON(json: ParticleSystemJSONParameters): Partial<Pa
             parameters[setting.param] = read;
         }
     }
+    // Files before 0.29 wrote the stop action as `autoDestroy`.
+    if (parameters.stopAction === undefined && fields.autoDestroy === true) {
+        parameters.stopAction = 'destroy';
+    }
     return parameters as Partial<ParticleSystemParameters>;
 }
 

package/src/system/types.ts

@@ -101,18 +101,68 @@ export interface BurstParameters {
 export type CullingMode = 'always' | 'pause' | 'pauseAndCatchUp';
 
 /**
- * What the emitter's world scale does to a world-space system (Unity's
- * Scaling Mode, as far as it differs here). A local-space system lives in its
- * emitter's space, so its scale reaches everything either way.
+ * What a system does once it has finished, its emission over and its last particle dead (Unity's
+ * Stop Action):
  *
- * - `'shape'` (default): the scale sizes the emission shape and the
- *   particles; speeds, forces and speed limits stay in world units, so a
- *   scaled-down effect moves as far as the full-size one.
- * - `'hierarchy'`: the scale also multiplies start speeds (per axis),
- *   `ForceOverLife` and `LimitSpeedOverLife` (by the mean of the axes), so the
- *   whole effect, motion included, scales like a model would.
+ * - `'none'` (the default): nothing; {@link ParticleSystem.restart} plays it again.
+ * - `'disable'`: disables its emitter node (`setEnabled(false)`), and with it the nodes under it.
+ *   A disabled system is not advanced or drawn; enable the emitter again before playing it.
+ * - `'destroy'`: disposes the system and its emitter, as `ParticleSystem.dispose()` does.
+ *
+ * Unity's Callback is the system's `finished` event, which fires whatever the stop action. The
+ * action waits for the system's sub emitters, see {@link ParticleSystem.stopAction}. A disabled
+ * emitter is state like any other: saved as not visible, and copied disabled by `clone`.
+ */
+export type StopAction = 'none' | 'disable' | 'destroy';
+
+/**
+ * What a full system does with the particles it emits next (Unity's Ring Buffer Mode). It needs
+ * {@link ParticleSystemParameters.maxParticles}; without a limit it is ignored.
+ *
+ * - `'disabled'` (the default): particles die at the end of their life, and a full system drops
+ *   what it would emit.
+ * - `'pauseUntilReplaced'`: a particle at the end of its life stays where and as it is, frozen,
+ *   until a new particle replaces it, the oldest first. For footprints, decals and bullet holes.
+ * - `'loopUntilReplaced'`: a particle at the end of its life goes back to an earlier point of it
+ *   and plays that part again, over and over, until a new particle replaces it; see
+ *   {@link ParticleSystem.ringBufferLoopRange}.
+ *
+ * Particles are never killed by age, so a system in either mode keeps its particles and does not
+ * finish while it has any: a non-looping ring effect never fires `finished`, and an
+ * `EffectPool` copy of it returns to the pool only when it is released. A replaced particle
+ * does not fire `particleDied`, nor Death sub emitters, which never fire in either mode since
+ * no particle dies. Lowering `maxParticles` drops the oldest particles over the new limit, also
+ * without `particleDied`. Particles are replaced oldest first in the order they were emitted;
+ * switching a mode on in a system whose particles have already died in a different order
+ * replaces them in row order the first time round. `'oldestInFront'` and `'youngestInFront'`
+ * sorting reads age, so a looping particle sorts by its age in the loop. Applies in every
+ * render mode but Trail, whose particles always die at the end of their life.
+ */
+export type RingBufferMode = 'disabled' | 'pauseUntilReplaced' | 'loopUntilReplaced';
+
+/**
+ * What the emitter's scale does to the system, as Unity's Scaling Mode, in world and local space
+ * alike. The scale reaches the emission shape, the particles' size, their start speed and, in world
+ * space, `ForceOverLife`, `ApplyForce` and `LimitSpeedOverLife` (by the mean of the axes), so a
+ * scaled effect looks and moves like a scaled model, except where a mode leaves it out:
+ *
+ * - `'local'` (default, as in Unity): only the emitter's own `scaling`; its parents' scale is left
+ *   out, so an effect keeps its size under a scaled character or prop.
+ * - `'hierarchy'`: the emitter's whole world scale, its parents' included.
+ * - `'shape'`: the world scale sizes the emission shape alone; the particles keep their size and
+ *   speed, so a bigger emitter spreads the same particles over a larger area.
+ *
+ * Under every mode the emitter's position, rotation and any mirroring come from the whole
+ * hierarchy; only the length of each axis changes. A sub emission starts in its parent particle's
+ * frame and takes its size and speed from that, not from the sub emitter's scale; `'shape'` still
+ * scales its shape by the sub emitter's world scale. With a non-uniform scale `'shape'` stretches
+ * where particles start, not the directions the shape sends them.
+ *
+ * Known differences from Unity: a world force (`ForceOverLife`, `ApplyForce`, and so the gravity
+ * the Unity exporter writes) is scaled with the motion in `'local'` and `'hierarchy'`, where
+ * Unity's gravity is not.
  */
-export type ScalingMode = 'shape' | 'hierarchy';
+export type ScalingMode = 'local' | 'hierarchy' | 'shape';
 
 /**
  * Where a {@link RenderMode.Beam} system's quads end: a point in world space,
@@ -145,7 +195,12 @@ export type BeamEnd =
  * default named on it, the same default `fromJSON` gives a file that leaves it out.
  */
 export interface ParticleSystemParameters {
-    /** See {@link ParticleSystem.autoDestroy}. Default false. */
+    /** What the system does once it has finished, see {@link StopAction}. Default `'none'`. */
+    stopAction?: StopAction;
+    /**
+     * `true` is `stopAction: 'destroy'`; read only when `stopAction` is left out.
+     * @deprecated Use `stopAction: 'destroy'`.
+     */
     autoDestroy?: boolean;
     /** See {@link ParticleSystem.looping}. Default true. */
     looping?: boolean;
@@ -177,6 +232,10 @@ export interface ParticleSystemParameters {
     emissionBursts?: Array<BurstParameters>;
     /** Most particles alive at once; emission past it is dropped. Leave unset for no limit. */
     maxParticles?: number;
+    /** What a full system does with new particles, see {@link RingBufferMode}. Default `'disabled'`. */
+    ringBufferMode?: RingBufferMode;
+    /** See {@link ParticleSystem.ringBufferLoopRange}. Default the whole life, (0, 1). */
+    ringBufferLoopRange?: Vector2;
     /** See {@link ParticleSystem.onlyUsedByOther}. Default false. */
     onlyUsedByOther?: boolean;
     /** See {@link ParticleSystem.behaviors}. Default none. */
@@ -263,7 +322,7 @@ export interface ParticleSystemParameters {
     playbackSpeed?: number;
     /** What the system does while off screen, see {@link CullingMode}. Default `'always'`. */
     cullingMode?: CullingMode;
-    /** What the emitter's scale does to a world-space system, see {@link ScalingMode}. Default `'shape'`. */
+    /** What the emitter's scale does to the system, see {@link ScalingMode}. Default `'local'`. */
     scalingMode?: ScalingMode;
     /** Seed for this system's own random generator, see {@link ParticleSystem.seed}. Default none. */
     seed?: number;
@@ -281,6 +340,8 @@ export interface ParticleSystemParameters {
     renderingGroupId?: number;
     /** Whether the scene's fog applies, see {@link ParticleSystem.applyFog}. Default true. */
     applyFog?: boolean;
+    /** Whether the scene's image processing applies, see {@link ParticleSystem.applyImageProcessing}. Default true. */
+    applyImageProcessing?: boolean;
     /** Scene the emitter node is created in. Default Babylon's last created scene. */
     scene?: Scene;
 }
@@ -314,7 +375,9 @@ export interface BurstParametersJSON {
 export interface ParticleSystemJSONParameters {
     /** The quarks.core version line the system was written with. */
     version: string;
-    /** See {@link ParticleSystem.autoDestroy}. */
+    /** Written only when not `'none'`. */
+    stopAction?: StopAction;
+    /** Read from older files: `true` is `stopAction: 'destroy'`. No longer written. */
     autoDestroy?: boolean;
     /** See {@link ParticleSystem.looping}. */
     looping?: boolean;
@@ -346,6 +409,10 @@ export interface ParticleSystemJSONParameters {
     emissionBursts?: Array<BurstParametersJSON>;
     /** See {@link ParticleSystem.maxParticles}. */
     maxParticles?: number;
+    /** Written only when not `'disabled'`. */
+    ringBufferMode?: RingBufferMode;
+    /** `[start, end]`; written only when not `[0, 1]`. */
+    ringBufferLoopRange?: [number, number];
     /** See {@link ParticleSystem.onlyUsedByOther}. */
     onlyUsedByOther?: boolean;
     /**
@@ -363,11 +430,13 @@ export interface ParticleSystemJSONParameters {
     renderingGroupId?: number;
     /** Written only when false. */
     applyFog?: boolean;
+    /** Written only when false. */
+    applyImageProcessing?: boolean;
     /** Written only when not 1. */
     playbackSpeed?: number;
     /** Written only when not `'always'`. */
     cullingMode?: CullingMode;
-    /** Written only when not `'shape'`. */
+    /** Written only when not `'local'`. */
     scalingMode?: ScalingMode;
     /** Written only when set. */
     seed?: number;