babylon.quarks-editor 0.28.0 → 0.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/CHANGELOG.md +38 -0
  2. package/README.md +1 -1
  3. package/dist/core/collision.d.ts +2 -2
  4. package/dist/core/collision.js +3 -1
  5. package/dist/core/colors.d.ts +1 -8
  6. package/dist/core/colors.js +4 -10
  7. package/dist/core/defaultEffect.js +4 -2
  8. package/dist/core/editorSession.d.ts +0 -2
  9. package/dist/core/editorSession.js +0 -1
  10. package/dist/core/emitterShapeWireframe.js +11 -4
  11. package/dist/core/loadEffect.js +2 -0
  12. package/dist/core/shapes.d.ts +7 -1
  13. package/dist/core/shapes.js +13 -3
  14. package/dist/core/systems.js +6 -4
  15. package/dist/core/values.d.ts +23 -6
  16. package/dist/core/values.js +47 -9
  17. package/dist/index.d.ts +1 -1
  18. package/dist/index.js +1 -1
  19. package/dist/react/AxesCurveField.d.ts +21 -0
  20. package/dist/react/AxesCurveField.js +25 -0
  21. package/dist/react/LifeCurveField.d.ts +18 -0
  22. package/dist/react/LifeCurveField.js +26 -0
  23. package/dist/react/ValueField.d.ts +4 -4
  24. package/dist/react/ValueField.js +20 -6
  25. package/dist/react/behaviorModules.js +23 -20
  26. package/dist/react/index.d.ts +11 -1
  27. package/dist/react/inspectorHints.js +1 -1
  28. package/dist/react/modules.js +60 -29
  29. package/dist/session.d.ts +8 -0
  30. package/package.json +2 -2
  31. package/src/core/collision.ts +5 -3
  32. package/src/core/colors.ts +4 -11
  33. package/src/core/defaultEffect.ts +3 -2
  34. package/src/core/editorSession.ts +0 -3
  35. package/src/core/emitterShapeWireframe.ts +12 -4
  36. package/src/core/loadEffect.ts +2 -0
  37. package/src/core/shapes.ts +20 -2
  38. package/src/core/systems.ts +8 -6
  39. package/src/core/values.ts +73 -12
  40. package/src/index.ts +0 -1
  41. package/src/react/AxesCurveField.tsx +72 -0
  42. package/src/react/LifeCurveField.tsx +57 -0
  43. package/src/react/ValueField.tsx +46 -6
  44. package/src/react/behaviorModules.tsx +45 -35
  45. package/src/react/index.ts +19 -1
  46. package/src/react/inspectorHints.ts +1 -1
  47. package/src/react/modules.tsx +149 -51
  48. package/src/session.ts +16 -0
package/CHANGELOG.md CHANGED
@@ -4,6 +4,44 @@ All notable changes to the `babylon.quarks-editor` package are documented here.
4
4
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
5
5
  and the project follows the `quarks.core` 0.x version line.
6
6
 
7
+ ## [0.30.0] — 2026-10-24
8
+
9
+ ### Breaking
10
+
11
+ - `EffectEditorHostHandle.importGallery`, deprecated since it was renamed, is removed: call
12
+ `importAssets`.
13
+ - `rgbaToVector4` is removed, with quarks' own `Vector4` (see babylon.quarks 0.30): colours are
14
+ plain `{r, g, b, a}`.
15
+
16
+ ### Added
17
+
18
+ - The `./session` and `./react` entry points export the types their signatures use (`EffectAsset`,
19
+ `ProjectStore`, `EffectBinding`, `EffectHistory`, `SceneEntry`, `PlaybackState`, `CurvePiece`,
20
+ `GradientStop`, `ScalarGenerator`, `TimelineRow`, `ValueFieldBaseProps` and the rest), so a host
21
+ can name them from the entry point it imports. Each entry point's API is recorded in
22
+ `api/*.api.md` and checked in CI.
23
+
24
+ ## [0.29.0] — 2026-10-24
25
+
26
+ ### Changed
27
+
28
+ - **Renderer module** has an "Image processing" switch beside "Apply fog", for
29
+ `ParticleSystem.applyImageProcessing`.
30
+
31
+ - **Value fields** offer Random Between Two Curves, with a curve editor for each bound. Switching
32
+ between Curve and Random Between Two Curves keeps every segment.
33
+ - **Curve modules** (Size, Speed and Limit Speed over Lifetime, Size by Speed, Width over Trail,
34
+ Texture Sheet frames) have a "Two curves" switch and show both bounds of an imported Random
35
+ Between Two Curves; an edit used to drop the upper one.
36
+ - **Stop action** in Main and **Ring buffer** (with its loop range) beside Max particles, as
37
+ Unity's. The editor saves the stop action but does not apply it, so previews replay.
38
+ - **Separate axes** in Limit Speed over Lifetime (with its Space), Size over Lifetime and Size by
39
+ Speed: a curve for each of X, Y and Z, as Unity's Separate Axes.
40
+ - **Scaling mode** offers Local (the default), Hierarchy and Shape, as Unity's, for world- and
41
+ local-space systems alike.
42
+ - **Shape module:** a cone's Emit from (Base, Volume) and Length, shown for Volume only, and a
43
+ grid's Sampling (Random, Sequential).
44
+
7
45
  ## [0.28.0] — 2026-10-23
8
46
 
9
47
  ### Breaking
package/README.md CHANGED
@@ -11,7 +11,7 @@ npm install babylon.quarks-editor babylon.quarks @babylonjs/core @babylonjs/mate
11
11
  ```
12
12
 
13
13
  The editor is an ES module package (`import`, not `require`). Its version follows babylon.quarks:
14
- editor 0.28.x needs babylon.quarks 0.28.x.
14
+ editor 0.30.x needs babylon.quarks 0.30.x.
15
15
 
16
16
  ## Usage
17
17
 
@@ -1,4 +1,4 @@
1
- import { Vector3 } from 'babylon.quarks';
1
+ import { type Vector3Like } from 'babylon.quarks';
2
2
  /**
3
3
  * A horizontal ground plane collider for hosts/demos that opt in via ensureGroundResolver /
4
4
  * setPhysicsResolver. The editor never registers this automatically.
@@ -13,7 +13,7 @@ export declare class GroundPlaneResolver {
13
13
  /**
14
14
  * True when `position` is at or below the plane, with the plane's normal written to `normal`.
15
15
  */
16
- resolve(position: Vector3, normal: Vector3): boolean;
16
+ resolve(position: Vector3Like, normal: Vector3Like): boolean;
17
17
  }
18
18
  /**
19
19
  * Opt-in helper for hosts/demos that want a simple floor collider.
@@ -16,7 +16,9 @@ export class GroundPlaneResolver {
16
16
  */
17
17
  resolve(position, normal) {
18
18
  if (position.y <= this.y) {
19
- normal.set(0, 1, 0);
19
+ normal.x = 0;
20
+ normal.y = 1;
21
+ normal.z = 0;
20
22
  return true;
21
23
  }
22
24
  return false;
@@ -1,5 +1,5 @@
1
1
  import type { Behavior } from 'babylon.quarks';
2
- import { ColorOverLife, Gradient, Vector4 } from 'babylon.quarks';
2
+ import { ColorOverLife, Gradient } from 'babylon.quarks';
3
3
  /** One RGBA stop of the editable gradient (all channels 0..1, pos 0..1). */
4
4
  export interface GradientStop {
5
5
  /** Where the stop sits over the particle's life, 0..1. */
@@ -19,13 +19,6 @@ export declare const DEFAULT_GRADIENT_STOPS: GradientStop[];
19
19
  export declare function buildGradient(stops: GradientStop[]): Gradient;
20
20
  /** A Color over Lifetime behavior through `stops`. */
21
21
  export declare function buildColorOverLife(stops: GradientStop[]): ColorOverLife;
22
- /** An RGBA colour as a quarks `Vector4`. */
23
- export declare function rgbaToVector4(stop: {
24
- r: number;
25
- g: number;
26
- b: number;
27
- a: number;
28
- }): Vector4;
29
22
  /** A stop's colour as CSS `rgba()`. */
30
23
  export declare function stopToCss(stop: GradientStop): string;
31
24
  /** The stops as a left-to-right CSS `linear-gradient`, for a gradient preview. */
@@ -1,4 +1,4 @@
1
- import { ColorOverLife, Gradient, Vector3, Vector4 } from 'babylon.quarks';
1
+ import { ColorOverLife, Gradient } from 'babylon.quarks';
2
2
  /** The gradient a new Color over Lifetime starts with: warm yellow fading out through red. */
3
3
  export const DEFAULT_GRADIENT_STOPS = [
4
4
  { pos: 0, r: 1, g: 0.85, b: 0.4, a: 1 },
@@ -7,16 +7,12 @@ export const DEFAULT_GRADIENT_STOPS = [
7
7
  /** A quarks gradient through `stops`, sorted by position; colour and alpha share the stops. */
8
8
  export function buildGradient(stops) {
9
9
  const sorted = [...stops].sort((a, b) => a.pos - b.pos);
10
- return new Gradient(sorted.map((s) => [new Vector3(s.r, s.g, s.b), s.pos]), sorted.map((s) => [s.a, s.pos]));
10
+ return new Gradient(sorted.map((s) => [{ r: s.r, g: s.g, b: s.b }, s.pos]), sorted.map((s) => [s.a, s.pos]));
11
11
  }
12
12
  /** A Color over Lifetime behavior through `stops`. */
13
13
  export function buildColorOverLife(stops) {
14
14
  return new ColorOverLife(buildGradient(stops));
15
15
  }
16
- /** An RGBA colour as a quarks `Vector4`. */
17
- export function rgbaToVector4(stop) {
18
- return new Vector4(stop.r, stop.g, stop.b, stop.a);
19
- }
20
16
  /** A stop's colour as CSS `rgba()`. */
21
17
  export function stopToCss(stop) {
22
18
  const c = (v) => Math.round(v * 255);
@@ -53,13 +49,11 @@ export function readGradientStops(gradient) {
53
49
  for (const [, pos] of gradient.alpha.keys) {
54
50
  positions.add(Math.round(pos * 1000) / 1000);
55
51
  }
56
- const color = new Vector3();
57
52
  return [...positions]
58
53
  .sort((a, b) => a - b)
59
54
  .map((pos) => {
60
- gradient.color.genValue(color, pos);
61
- const alpha = gradient.alpha.genValue(0, pos);
62
- return { pos, r: color.x, g: color.y, b: color.z, a: alpha };
55
+ const { r, g, b, a } = gradient.evaluate(pos);
56
+ return { pos, r, g, b, a };
63
57
  });
64
58
  }
65
59
  /** Finds a behavior of the given quarks type string (e.g. 'ColorOverLife'). */
@@ -1,5 +1,5 @@
1
1
  import { TransformNode } from '@babylonjs/core/Meshes/transformNode.js';
2
- import { ColorOverLife, ConeEmitter, ConstantColor, ConstantValue, IntervalValue, ParticleSystem, RenderMode, Vector4, } from 'babylon.quarks';
2
+ import { ColorOverLife, ConeEmitter, ConstantColor, ConstantValue, IntervalValue, ParticleSystem, RenderMode, } from 'babylon.quarks';
3
3
  import { DEFAULT_GRADIENT_STOPS, buildGradient } from './colors.js';
4
4
  import { uniqueEntryName } from './sceneEntries.js';
5
5
  /** Creates a simple cone burst preset for new editor effects. */
@@ -11,7 +11,7 @@ export function createDefaultEffect(scene, resolveTexture, textureUrl) {
11
11
  startLife: new IntervalValue(1.2, 1.8),
12
12
  startSpeed: new IntervalValue(3, 5),
13
13
  startSize: new IntervalValue(0.25, 0.5),
14
- startColor: new ConstantColor(new Vector4(1, 1, 1, 1)),
14
+ startColor: new ConstantColor({ r: 1, g: 1, b: 1, a: 1 }),
15
15
  emissionOverTime: new ConstantValue(80),
16
16
  shape: new ConeEmitter({ radius: 0.3, angle: 0.25 }),
17
17
  renderMode: RenderMode.BillBoard,
@@ -19,6 +19,8 @@ export function createDefaultEffect(scene, resolveTexture, textureUrl) {
19
19
  transparent: true,
20
20
  blendMode: 1,
21
21
  });
22
+ // The editor previews over and over; the stop action is saved, not applied.
23
+ system.ignoreStopAction = true;
22
24
  system.addBehavior(new ColorOverLife(buildGradient(DEFAULT_GRADIENT_STOPS)));
23
25
  system.emitter.rotation.x = -Math.PI / 2;
24
26
  return system;
@@ -28,8 +28,6 @@ export interface EffectEditorHostHandle {
28
28
  importJson: (json: unknown) => void;
29
29
  /** Imports effect files (and the texture/geometry files they reference) into Assets. */
30
30
  importAssets: (files: FileList | File[]) => Promise<void>;
31
- /** @deprecated Renamed to `importAssets`. */
32
- importGallery: (files: FileList | File[]) => Promise<void>;
33
31
  /** The focused effect as quarks JSON; throws when no effect is focused. */
34
32
  exportJson: () => string;
35
33
  }
@@ -778,7 +778,6 @@ export function createEditorSession(options) {
778
778
  renderer,
779
779
  importJson,
780
780
  importAssets,
781
- importGallery: importAssets,
782
781
  exportJson: () => makeHandle().binding.exportJSON('EditorEffect'),
783
782
  });
784
783
  /** Adds `json` to Assets and returns its single instance; throws when it has no systems. */
@@ -2,6 +2,7 @@ import { Color3 } from '@babylonjs/core/Maths/math.color.js';
2
2
  import { Vector3 } from '@babylonjs/core/Maths/math.vector.js';
3
3
  import { MeshBuilder } from '@babylonjs/core/Meshes/meshBuilder.js';
4
4
  import { TransformNode } from '@babylonjs/core/Meshes/transformNode.js';
5
+ import { ConeEmitFrom } from 'babylon.quarks';
5
6
  import { EDITOR_SCENE_NODE_METADATA } from './editorScene.js';
6
7
  import './lineShaders.js';
7
8
  import { getShapeType, readShapeParams } from './shapes.js';
@@ -103,17 +104,23 @@ function buildEmitterWireframe(system, scene) {
103
104
  lines('wf-cone-spoke-a', [Vector3.Zero(), arcPoint(radius, 0)]);
104
105
  lines('wf-cone-spoke-b', [Vector3.Zero(), arcPoint(radius, arc)]);
105
106
  }
106
- const preview = Math.max(radius * 2, 1.25);
107
- const farRadius = radius + preview * Math.tan(angle);
107
+ // Emit from Volume draws the volume itself, out to its length; the base a stretch of the
108
+ // directions.
109
+ const preview = params.coneEmitFrom === ConeEmitFrom.Volume
110
+ ? Math.max(Number.isFinite(params.length) ? params.length : 0, 0.001)
111
+ : Math.max(radius * 2, 1.25);
112
+ // The rays and the far rim end at the same point, which a near-flat cone keeps in view.
113
+ const travel = preview / Math.max(Math.cos(angle), 0.05);
114
+ const farRadius = radius + Math.sin(angle) * travel;
115
+ const farZ = Math.cos(angle) * travel;
108
116
  const spokeCount = Math.max(4, Math.ceil((arc / (Math.PI * 2)) * 12));
109
117
  for (let i = 0; i <= spokeCount; i++) {
110
118
  const theta = (i / spokeCount) * arc;
111
119
  const rim = arcPoint(radius, theta);
112
120
  const dir = new Vector3(Math.sin(angle) * Math.cos(theta), Math.sin(angle) * Math.sin(theta), Math.cos(angle));
113
- const travel = preview / Math.max(Math.cos(angle), 0.05);
114
121
  lines(`wf-cone-ray-${i}`, [rim, rim.add(dir.scale(travel))], DIRECTION_COLOR);
115
122
  }
116
- lines('wf-cone-far', xyArc(farRadius, arc, 32, preview), DIRECTION_COLOR);
123
+ lines('wf-cone-far', xyArc(farRadius, arc, 32, farZ), DIRECTION_COLOR);
117
124
  break;
118
125
  }
119
126
  case 'sphere': {
@@ -79,6 +79,8 @@ export function parseEffectFromJson(scene, renderer, json, options = {}, baseUrl
79
79
  const systems = [];
80
80
  QuarksUtil.runOnAllParticleEmitters(root, (emitter) => {
81
81
  const system = emitter.system;
82
+ // The editor previews over and over; the stop action is saved, not applied.
83
+ system.ignoreStopAction = true;
82
84
  if (registerRenderer && renderer) {
83
85
  renderer.addSystem(system);
84
86
  }
@@ -1,6 +1,6 @@
1
1
  import type { Mesh } from '@babylonjs/core/Meshes/mesh.js';
2
2
  import type { EmitterShape } from 'babylon.quarks';
3
- import { BoxEmitFrom, EmitterMode } from 'babylon.quarks';
3
+ import { BoxEmitFrom, ConeEmitFrom, EmitterMode, GridSampling } from 'babylon.quarks';
4
4
  /** The emitter shapes the Shape module offers, by the `type` they serialise with. */
5
5
  export type ShapeType = 'point' | 'sphere' | 'hemisphere' | 'cone' | 'circle' | 'donut' | 'rectangle' | 'grid' | 'box' | 'edge' | 'mesh_surface';
6
6
  /** The Shape module's shape list, in menu order, with the label each shows. */
@@ -41,6 +41,12 @@ export interface ShapeParams {
41
41
  depth: number;
42
42
  /** Where a box emits from: its volume, its faces or its edges. */
43
43
  emitFrom: BoxEmitFrom;
44
+ /** Where a cone emits from: its base or its volume. */
45
+ coneEmitFrom: ConeEmitFrom;
46
+ /** Height of a cone's volume (Unity's Length), for Emit from Volume. */
47
+ length: number;
48
+ /** How a grid picks its cells: at random or in turn. */
49
+ sampling: GridSampling;
44
50
  /** How fast an edge emitter's loop / ping-pong point travels, in lengths per second. */
45
51
  speed: number;
46
52
  /** The mesh a mesh surface emitter emits from. */
@@ -1,4 +1,4 @@
1
- import { BoxEmitFrom, BoxEmitter, CircleEmitter, ConeEmitter, ConstantValue, DonutEmitter, EdgeEmitter, EmitterMode, GridEmitter, HemisphereEmitter, MeshSurfaceEmitter, PointEmitter, RectangleEmitter, SphereEmitter, } from 'babylon.quarks';
1
+ import { BoxEmitFrom, BoxEmitter, CircleEmitter, ConeEmitFrom, ConeEmitter, ConstantValue, DonutEmitter, EdgeEmitter, EmitterMode, GridEmitter, GridSampling, HemisphereEmitter, MeshSurfaceEmitter, PointEmitter, RectangleEmitter, SphereEmitter, } from 'babylon.quarks';
2
2
  /** The Shape module's shape list, in menu order, with the label each shows. */
3
3
  export const SHAPE_TYPES = [
4
4
  { value: 'cone', label: 'Cone' },
@@ -28,6 +28,9 @@ export const DEFAULT_SHAPE_PARAMS = {
28
28
  row: 10,
29
29
  depth: 1,
30
30
  emitFrom: BoxEmitFrom.Volume,
31
+ coneEmitFrom: ConeEmitFrom.Base,
32
+ length: 5,
33
+ sampling: GridSampling.Random,
31
34
  speed: 1,
32
35
  mesh: undefined,
33
36
  };
@@ -53,7 +56,11 @@ export function readShapeParams(shape) {
53
56
  column: num('column', DEFAULT_SHAPE_PARAMS.column),
54
57
  row: num('row', DEFAULT_SHAPE_PARAMS.row),
55
58
  depth: num('depth', DEFAULT_SHAPE_PARAMS.depth),
56
- emitFrom: num('emitFrom', DEFAULT_SHAPE_PARAMS.emitFrom),
59
+ // A box and a cone both name it emitFrom, with different enums: each keeps its own.
60
+ emitFrom: shape instanceof BoxEmitter ? shape.emitFrom : DEFAULT_SHAPE_PARAMS.emitFrom,
61
+ coneEmitFrom: shape instanceof ConeEmitter ? shape.emitFrom : DEFAULT_SHAPE_PARAMS.coneEmitFrom,
62
+ length: num('length', DEFAULT_SHAPE_PARAMS.length),
63
+ sampling: num('sampling', DEFAULT_SHAPE_PARAMS.sampling),
57
64
  speed: anyShape.speed instanceof ConstantValue ? anyShape.speed.value : DEFAULT_SHAPE_PARAMS.speed,
58
65
  mesh: anyShape.mesh,
59
66
  };
@@ -64,7 +71,7 @@ export const SHAPE_PARAM_KEYS = {
64
71
  point: [],
65
72
  sphere: ['radius', 'arc', 'thickness'],
66
73
  hemisphere: ['radius', 'arc', 'thickness'],
67
- cone: ['radius', 'arc', 'thickness', 'angle'],
74
+ cone: ['radius', 'arc', 'thickness', 'angle', 'length'],
68
75
  circle: ['radius', 'arc', 'thickness'],
69
76
  donut: ['radius', 'arc', 'thickness', 'donutRadius'],
70
77
  rectangle: ['width', 'height'],
@@ -100,6 +107,8 @@ export function createShape(type, params) {
100
107
  arc: params.arc,
101
108
  thickness: params.thickness,
102
109
  angle: params.angle,
110
+ emitFrom: params.coneEmitFrom,
111
+ length: params.length,
103
112
  mode: params.mode,
104
113
  spread: params.spread,
105
114
  });
@@ -133,6 +142,7 @@ export function createShape(type, params) {
133
142
  height: params.height,
134
143
  column: params.column,
135
144
  row: params.row,
145
+ sampling: params.sampling,
136
146
  });
137
147
  case 'box':
138
148
  return new BoxEmitter({
@@ -1,4 +1,4 @@
1
- import { ConeEmitter, ConstantColor, ConstantValue, IntervalValue, ParticleSystem, RenderMode, Vector4, } from 'babylon.quarks';
1
+ import { ConeEmitter, ConstantColor, ConstantValue, EmitSubParticleSystem, IntervalValue, ParticleSystem, RenderMode, } from 'babylon.quarks';
2
2
  /**
3
3
  * Creates a child system sharing the parent's scene/texture/blending, parented to the
4
4
  * parent emitter (or `options.parentNode` when given) — the Unity pattern where an effect is
@@ -13,7 +13,7 @@ export function createChildSystem(parent, options = {}) {
13
13
  startLife: new IntervalValue(0.3, oneShot ? 0.6 : 1.2),
14
14
  startSpeed: new IntervalValue(1, 3),
15
15
  startSize: new IntervalValue(0.05, 0.2),
16
- startColor: new ConstantColor(new Vector4(1, 0.9, 0.6, 1)),
16
+ startColor: new ConstantColor({ r: 1, g: 0.9, b: 0.6, a: 1 }),
17
17
  emissionOverTime: new ConstantValue(oneShot ? 0 : 30),
18
18
  emissionBursts: oneShot
19
19
  ? [{ time: 0, count: new ConstantValue(8), cycle: 1, interval: 0.01, probability: 1 }]
@@ -26,6 +26,8 @@ export function createChildSystem(parent, options = {}) {
26
26
  worldSpace: true,
27
27
  });
28
28
  child.emitter.name = options.name ?? (oneShot ? 'sub-emitter' : 'child-system');
29
+ // The editor previews over and over; the stop action is saved, not applied.
30
+ child.ignoreStopAction = true;
29
31
  if (oneShot) {
30
32
  child.onlyUsedByOther = true;
31
33
  }
@@ -43,8 +45,8 @@ export function unlinkSubEmitterReferences(systems, removed) {
43
45
  const behaviors = system.behaviors;
44
46
  for (let i = behaviors.length - 1; i >= 0; i--) {
45
47
  const behavior = behaviors[i];
46
- if (behavior.type === 'EmitSubParticleSystem' &&
47
- behavior.subParticleSystem &&
48
+ if (behavior instanceof EmitSubParticleSystem &&
49
+ typeof behavior.subParticleSystem === 'object' &&
48
50
  removedEmitters.has(behavior.subParticleSystem)) {
49
51
  behaviors.splice(i, 1);
50
52
  }
@@ -1,11 +1,14 @@
1
1
  import type { FunctionValueGenerator, RotationGenerator, ValueGenerator, Vector3Generator } from 'babylon.quarks';
2
- import { PiecewiseBezier } from 'babylon.quarks';
2
+ import { PiecewiseBezier, RandomBetweenCurves } from 'babylon.quarks';
3
3
  /** A generator of one number: a constant or random value, or a curve over the particle's life. */
4
4
  export type ScalarGenerator = ValueGenerator | FunctionValueGenerator;
5
5
  /** Any generator a value field can be pointed at; ones that are not scalar read as the default. */
6
6
  export type AnyGenerator = ScalarGenerator | Vector3Generator | RotationGenerator;
7
- /** How a value field produces its number: Unity's Constant, Random Between Two Constants or Curve. */
8
- export type ScalarMode = 'constant' | 'random' | 'curve';
7
+ /**
8
+ * How a value field produces its number: Unity's Constant, Random Between Two Constants, Curve or
9
+ * Random Between Two Curves.
10
+ */
11
+ export type ScalarMode = 'constant' | 'random' | 'curve' | 'curves';
9
12
  /** Editable snapshot of a scalar value generator. */
10
13
  export interface ScalarValueState {
11
14
  /** Which of the fields below is the value. */
@@ -16,8 +19,10 @@ export interface ScalarValueState {
16
19
  min: number;
17
20
  /** Upper end of the random range (mode: random). */
18
21
  max: number;
19
- /** Cubic bezier control values over normalized lifetime (mode: curve). */
22
+ /** Cubic bezier control values over normalized lifetime (mode: curve; the first curve of curves). */
20
23
  curve: [number, number, number, number];
24
+ /** The second curve's control values (mode: curves); the first curve's when left out. */
25
+ curve2?: [number, number, number, number];
21
26
  }
22
27
  /**
23
28
  * What a value field shows for `generator`: its constant, its range or its first curve segment.
@@ -36,10 +41,22 @@ export interface CurvePiece {
36
41
  /** The segment's four bezier control values. */
37
42
  p: [number, number, number, number];
38
43
  }
39
- /** Reads pieces from a PiecewiseBezier (or synthesizes one segment for other generators). */
40
- export declare function readPieces(generator: AnyGenerator | undefined): CurvePiece[];
44
+ /**
45
+ * Reads pieces from a PiecewiseBezier, or from the first curve of a RandomBetweenCurves (the
46
+ * second with `second`). A constant reads as a flat curve, a random range as a flat curve at its
47
+ * lower end (its upper with `second`), and other generators as one default segment.
48
+ */
49
+ export declare function readPieces(generator: AnyGenerator | undefined, second?: boolean): CurvePiece[];
41
50
  /** A piecewise bezier from segments, sorted by their start. */
42
51
  export declare function buildCurve(pieces: CurvePiece[]): PiecewiseBezier;
52
+ /**
53
+ * `generator` as one curve (`'curve'`) or two (`'curves'`, Unity's Random Between Two Curves),
54
+ * keeping every segment: one curve becomes both bounds of two, and two keep their first as one.
55
+ * A constant is a flat curve, and a random range flat curves at its ends.
56
+ */
57
+ export declare function withCurves(generator: AnyGenerator | undefined, mode: 'curve'): PiecewiseBezier;
58
+ export declare function withCurves(generator: AnyGenerator | undefined, mode: 'curves'): RandomBetweenCurves;
59
+ export declare function withCurves(generator: AnyGenerator | undefined, mode: 'curve' | 'curves'): PiecewiseBezier | RandomBetweenCurves;
43
60
  /** Splits the piece containing x into two exact halves using Bezier.split. */
44
61
  export declare function splitPieces(pieces: CurvePiece[], x: number): CurvePiece[];
45
62
  /** Removes the boundary at pieces[index].start by merging with the previous piece. */
@@ -1,10 +1,17 @@
1
- import { Bezier, ConstantValue, IntervalValue, PiecewiseBezier } from 'babylon.quarks';
1
+ import { Bezier, ConstantValue, IntervalValue, PiecewiseBezier, RandomBetweenCurves } from 'babylon.quarks';
2
2
  /**
3
3
  * What a value field shows for `generator`: its constant, its range or its first curve segment.
4
4
  * Anything else, including a missing generator, reads as the constant 1.
5
5
  */
6
6
  export function readScalar(generator) {
7
- const state = { mode: 'constant', value: 1, min: 0.5, max: 1.5, curve: [0, 1, 1, 0] };
7
+ const state = {
8
+ mode: 'constant',
9
+ value: 1,
10
+ min: 0.5,
11
+ max: 1.5,
12
+ curve: [0, 1, 1, 0],
13
+ curve2: [0, 1, 1, 0],
14
+ };
8
15
  if (generator instanceof ConstantValue) {
9
16
  state.mode = 'constant';
10
17
  state.value = generator.value;
@@ -19,14 +26,23 @@ export function readScalar(generator) {
19
26
  }
20
27
  else if (generator instanceof PiecewiseBezier) {
21
28
  state.mode = 'curve';
22
- const first = generator.functions[0]?.[0];
23
- if (first) {
24
- state.curve = [first.p[0], first.p[1], first.p[2], first.p[3]];
25
- state.value = first.p[0];
26
- }
29
+ state.curve = firstSegment(generator) ?? state.curve;
30
+ state.curve2 = state.curve;
31
+ state.value = state.curve[0];
32
+ }
33
+ else if (generator instanceof RandomBetweenCurves) {
34
+ state.mode = 'curves';
35
+ state.curve = firstSegment(generator.curve1) ?? state.curve;
36
+ state.curve2 = firstSegment(generator.curve2) ?? state.curve;
37
+ state.value = state.curve[0];
27
38
  }
28
39
  return state;
29
40
  }
41
+ /** The control values of a curve's first segment, if it has one. */
42
+ function firstSegment(curve) {
43
+ const first = curve.functions[0]?.[0];
44
+ return first ? [first.p[0], first.p[1], first.p[2], first.p[3]] : undefined;
45
+ }
30
46
  export function buildScalar(state) {
31
47
  switch (state.mode) {
32
48
  case 'constant':
@@ -35,10 +51,24 @@ export function buildScalar(state) {
35
51
  return new IntervalValue(Math.min(state.min, state.max), Math.max(state.min, state.max));
36
52
  case 'curve':
37
53
  return new PiecewiseBezier([[new Bezier(...state.curve), 0]]);
54
+ case 'curves':
55
+ return new RandomBetweenCurves(new PiecewiseBezier([[new Bezier(...state.curve), 0]]), new PiecewiseBezier([[new Bezier(...(state.curve2 ?? state.curve)), 0]]));
38
56
  }
39
57
  }
40
- /** Reads pieces from a PiecewiseBezier (or synthesizes one segment for other generators). */
41
- export function readPieces(generator) {
58
+ /**
59
+ * Reads pieces from a PiecewiseBezier, or from the first curve of a RandomBetweenCurves (the
60
+ * second with `second`). A constant reads as a flat curve, a random range as a flat curve at its
61
+ * lower end (its upper with `second`), and other generators as one default segment.
62
+ */
63
+ export function readPieces(generator, second = false) {
64
+ if (generator instanceof RandomBetweenCurves) {
65
+ return readPieces(second ? generator.curve2 : generator.curve1);
66
+ }
67
+ // A constant is a flat curve, and a random range two flat curves at its ends.
68
+ if (generator instanceof ConstantValue || generator instanceof IntervalValue) {
69
+ const value = generator instanceof ConstantValue ? generator.value : second ? generator.b : generator.a;
70
+ return [{ start: 0, p: [value, value, value, value] }];
71
+ }
42
72
  if (generator instanceof PiecewiseBezier && generator.functions.length > 0) {
43
73
  return generator.functions.map(([bezier, start]) => ({
44
74
  start,
@@ -53,6 +83,14 @@ export function buildCurve(pieces) {
53
83
  const sorted = [...pieces].sort((a, b) => a.start - b.start);
54
84
  return new PiecewiseBezier(sorted.map((piece) => [new Bezier(...piece.p), piece.start]));
55
85
  }
86
+ export function withCurves(generator, mode) {
87
+ const first = buildCurve(readPieces(generator));
88
+ if (mode === 'curve') {
89
+ return first;
90
+ }
91
+ const second = generator instanceof RandomBetweenCurves || generator instanceof IntervalValue;
92
+ return new RandomBetweenCurves(first, buildCurve(readPieces(generator, second)));
93
+ }
56
94
  /** Splits the piece containing x into two exact halves using Bezier.split. */
57
95
  export function splitPieces(pieces, x) {
58
96
  const sorted = [...pieces].sort((a, b) => a.start - b.start);
package/dist/index.d.ts CHANGED
@@ -3,7 +3,7 @@ export type { AssetDragPayload } from './core/assetTree.js';
3
3
  export { EffectBinding } from './core/binding.js';
4
4
  export type { EditorListener } from './core/binding.js';
5
5
  export { GroundPlaneResolver, ensureGroundResolver } from './core/collision.js';
6
- export { DEFAULT_GRADIENT_STOPS, buildColorOverLife, buildGradient, findBehavior, hexToRgb, rgbToHex, rgbaToVector4, stopToCss, stopsToCssGradient, } from './core/colors.js';
6
+ export { DEFAULT_GRADIENT_STOPS, buildColorOverLife, buildGradient, findBehavior, hexToRgb, rgbToHex, stopToCss, stopsToCssGradient, } from './core/colors.js';
7
7
  export type { GradientStop } from './core/colors.js';
8
8
  export { buildEffectTree, collectSystems, serializeEffectForest, serializeEffectTree } from './core/effectTree.js';
9
9
  export type { EffectTreeNode } from './core/effectTree.js';
package/dist/index.js CHANGED
@@ -1,6 +1,6 @@
1
1
  export { EffectBinding } from './core/binding.js';
2
2
  export { GroundPlaneResolver, ensureGroundResolver } from './core/collision.js';
3
- export { DEFAULT_GRADIENT_STOPS, buildColorOverLife, buildGradient, findBehavior, hexToRgb, rgbToHex, rgbaToVector4, stopToCss, stopsToCssGradient, } from './core/colors.js';
3
+ export { DEFAULT_GRADIENT_STOPS, buildColorOverLife, buildGradient, findBehavior, hexToRgb, rgbToHex, stopToCss, stopsToCssGradient, } from './core/colors.js';
4
4
  export { buildEffectTree, collectSystems, serializeEffectForest, serializeEffectTree } from './core/effectTree.js';
5
5
  export { EffectHistory } from './core/history.js';
6
6
  export { IndexedDbProjectStore } from './core/indexedDbProjectStore.js';
@@ -0,0 +1,21 @@
1
+ import { PiecewiseBezier, RandomBetweenCurves, Vector3Function } from 'babylon.quarks';
2
+ import React from 'react';
3
+ import { AnyGenerator } from '../core/values.js';
4
+ /** One curve or two, for one axis or for all of them. */
5
+ type AxisCurve = PiecewiseBezier | RandomBetweenCurves;
6
+ /** Props of an {@link AxesCurveField}. */
7
+ export interface AxesCurveFieldProps {
8
+ /** The generator shown: one curve (or two) for every axis, or a `Vector3Function` per axis. */
9
+ generator: AnyGenerator | undefined;
10
+ /** Top of the curve editors' value range. */
11
+ maxValue?: number;
12
+ /** Receives the edited generator. */
13
+ onChange: (generator: AxisCurve | Vector3Function) => void;
14
+ }
15
+ /**
16
+ * A curve over life with Unity's Separate Axes switch: off, one curve (or two) for all axes; on, a
17
+ * {@link Vector3Function} with its own for X, Y and Z. Switching on gives every axis the shared
18
+ * curve; switching off keeps the X one.
19
+ */
20
+ export declare function AxesCurveField(props: AxesCurveFieldProps): React.ReactElement;
21
+ export {};
@@ -0,0 +1,25 @@
1
+ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
2
+ import { IntervalValue, RandomBetweenCurves, Vector3Function } from 'babylon.quarks';
3
+ import { withCurves } from '../core/values.js';
4
+ import { CheckboxField, Row } from './fields.js';
5
+ import { LifeCurveField } from './LifeCurveField.js';
6
+ const captionStyle = { fontSize: 10.5, opacity: 0.6, marginTop: 6 };
7
+ /**
8
+ * The curve or curves `generator` holds, as a fresh copy: a constant as a flat curve, a random
9
+ * range as two flat ones.
10
+ */
11
+ function curveOf(generator) {
12
+ const two = generator instanceof RandomBetweenCurves || generator instanceof IntervalValue;
13
+ return withCurves(generator, two ? 'curves' : 'curve');
14
+ }
15
+ /**
16
+ * A curve over life with Unity's Separate Axes switch: off, one curve (or two) for all axes; on, a
17
+ * {@link Vector3Function} with its own for X, Y and Z. Switching on gives every axis the shared
18
+ * curve; switching off keeps the X one.
19
+ */
20
+ export function AxesCurveField(props) {
21
+ const { generator } = props;
22
+ const axes = generator instanceof Vector3Function ? generator : undefined;
23
+ const toggle = (on) => props.onChange(on ? new Vector3Function(curveOf(generator), curveOf(generator), curveOf(generator)) : curveOf(axes?.x));
24
+ return (_jsxs(_Fragment, { children: [_jsx(Row, { label: "Separate axes", hint: "A curve for each of X, Y and Z, as Unity's Separate Axes.", children: _jsx(CheckboxField, { value: axes !== undefined, onChange: toggle }) }), axes === undefined ? (_jsx(LifeCurveField, { generator: generator, maxValue: props.maxValue, onChange: props.onChange })) : (['x', 'y', 'z'].map((axis) => (_jsxs("div", { children: [_jsx("div", { style: captionStyle, children: axis.toUpperCase() }), _jsx(LifeCurveField, { generator: axes[axis], maxValue: props.maxValue, onChange: (curve) => props.onChange(new Vector3Function(axis === 'x' ? curve : axes.x, axis === 'y' ? curve : axes.y, axis === 'z' ? curve : axes.z)) })] }, axis))))] }));
25
+ }
@@ -0,0 +1,18 @@
1
+ import { PiecewiseBezier, RandomBetweenCurves } from 'babylon.quarks';
2
+ import React from 'react';
3
+ import { AnyGenerator } from '../core/values.js';
4
+ /** Props of a {@link LifeCurveField}. */
5
+ export interface LifeCurveFieldProps {
6
+ /** The generator shown: one curve, two curves, or anything else, read as one curve. */
7
+ generator: AnyGenerator | undefined;
8
+ /** Top of the curve editors' value range. */
9
+ maxValue?: number;
10
+ /** Receives the edited curve or curves. */
11
+ onChange: (generator: PiecewiseBezier | RandomBetweenCurves) => void;
12
+ }
13
+ /**
14
+ * A setting that is a curve over the particle's life, or two with a "Two curves" switch (Unity's
15
+ * Random Between Two Curves): each particle then follows its own curve between the lower and the
16
+ * upper one. Every segment of both curves is kept through edits and switches.
17
+ */
18
+ export declare function LifeCurveField(props: LifeCurveFieldProps): React.ReactElement;
@@ -0,0 +1,26 @@
1
+ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
2
+ import { IntervalValue, RandomBetweenCurves } from 'babylon.quarks';
3
+ import { buildCurve, readPieces, withCurves } from '../core/values.js';
4
+ import { CurveEditor } from './CurveEditor.js';
5
+ import { CheckboxField, Row } from './fields.js';
6
+ const captionStyle = { fontSize: 10.5, opacity: 0.6, flex: 'none' };
7
+ /**
8
+ * A setting that is a curve over the particle's life, or two with a "Two curves" switch (Unity's
9
+ * Random Between Two Curves): each particle then follows its own curve between the lower and the
10
+ * upper one. Every segment of both curves is kept through edits and switches.
11
+ */
12
+ export function LifeCurveField(props) {
13
+ const { generator } = props;
14
+ // A random range shows as two flat curves, and an edit turns it into them.
15
+ const two = generator instanceof RandomBetweenCurves || generator instanceof IntervalValue;
16
+ const edit = (pieces, upper) => {
17
+ if (!two) {
18
+ props.onChange(buildCurve(pieces));
19
+ return;
20
+ }
21
+ const lower = upper ? buildCurve(readPieces(generator)) : buildCurve(pieces);
22
+ const higher = upper ? buildCurve(pieces) : buildCurve(readPieces(generator, true));
23
+ props.onChange(new RandomBetweenCurves(lower, higher));
24
+ };
25
+ return (_jsxs(_Fragment, { children: [_jsx(Row, { label: "Two curves", hint: "Random between two curves: each particle follows its own curve between them.", children: _jsx(CheckboxField, { value: two, onChange: (on) => props.onChange(withCurves(generator, on ? 'curves' : 'curve')) }) }), (two ? ['lower', 'upper'] : ['curve']).map((bound) => (_jsxs("div", { style: { marginTop: 6 }, children: [two && _jsx("span", { style: captionStyle, children: bound }), _jsx(CurveEditor, { pieces: readPieces(generator, bound === 'upper'), maxValue: props.maxValue, onChange: (pieces) => edit(pieces, bound === 'upper') })] }, bound)))] }));
26
+ }
@@ -2,7 +2,7 @@ import type { ValueGenerator } from 'babylon.quarks';
2
2
  import React from 'react';
3
3
  import { AnyGenerator, ScalarGenerator } from '../core/values.js';
4
4
  /** Props every {@link ValueField} takes. */
5
- interface ValueFieldBaseProps {
5
+ export interface ValueFieldBaseProps {
6
6
  /** The row's label. */
7
7
  label: string;
8
8
  /** Tooltip text of the label. */
@@ -31,8 +31,8 @@ export interface ConstantValueFieldProps extends ValueFieldBaseProps {
31
31
  onChange: (generator: ValueGenerator) => void;
32
32
  }
33
33
  /**
34
- * Unity-like value field: Constant | Random Between Two Constants | Curve, bound to a quarks value
35
- * generator. With `curve={false}` it offers only the first two, for settings sampled once.
34
+ * Unity-like value field: Constant | Random Between Two Constants | Curve | Random Between Two
35
+ * Curves, bound to a quarks value generator. With `curve={false}` it offers only the first two,
36
+ * for settings sampled once.
36
37
  */
37
38
  export declare function ValueField(props: CurveValueFieldProps | ConstantValueFieldProps): React.ReactElement;
38
- export {};