laymur 0.27.0 → 0.28.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 (98) hide show
  1. package/README.md +48 -3
  2. package/dist/core/constraints/UIAspectConstraint/UIAspectConstraint.js +2 -1
  3. package/dist/core/constraints/UICustomConstraint.js +1 -1
  4. package/dist/core/constraints/UIHeightConstraint/UIHeightConstraint.js +2 -1
  5. package/dist/core/constraints/UIHorizontalDistanceConstraint/UIHorizontalDistanceConstraint.js +2 -1
  6. package/dist/core/constraints/UIHorizontalInterpolationConstraint/UIHorizontalInterpolationConstraint.js +2 -1
  7. package/dist/core/constraints/UIHorizontalProportionConstraint/UIHorizontalProportionConstraint.js +2 -1
  8. package/dist/core/constraints/UIVerticalDistanceConstraint/UIVerticalDistanceConstraint.js +2 -1
  9. package/dist/core/constraints/UIVerticalInterpolationConstraint/UIVerticalInterpolationConstraint.js +2 -1
  10. package/dist/core/constraints/UIVerticalProportionConstraint/UIVerticalProportionConstraint.js +2 -1
  11. package/dist/core/constraints/UIWidthConstraint/UIWidthConstraint.js +2 -1
  12. package/dist/core/constraints/constraintAsserts.d.ts +41 -0
  13. package/dist/core/constraints/constraintAsserts.js +171 -0
  14. package/dist/core/elements/UIDummy/UIDummy.d.ts +8 -5
  15. package/dist/core/elements/UIDummy/UIDummy.js +21 -10
  16. package/dist/core/elements/UIElement/UIElement.Internal.d.ts +6 -5
  17. package/dist/core/elements/UIElement/UIElement.Internal.js +0 -4
  18. package/dist/core/elements/UIElement/UIElement.d.ts +12 -6
  19. package/dist/core/elements/UIElement/UIElement.js +14 -7
  20. package/dist/core/elements/UIText/UIText.d.ts +6 -1
  21. package/dist/core/elements/UIText/UIText.js +22 -12
  22. package/dist/core/layers/UIViewportLayer/UIViewportLayer.js +1 -1
  23. package/dist/core/miscellaneous/UIBlendMode.d.ts +5 -0
  24. package/dist/core/miscellaneous/UIBlendMode.js +7 -0
  25. package/dist/core/miscellaneous/asserts.d.ts +0 -41
  26. package/dist/core/miscellaneous/asserts.js +0 -170
  27. package/dist/core/miscellaneous/canvas.js +3 -0
  28. package/dist/core/miscellaneous/generic-plane/UIGenericInstancedPlane/UIGenericInstancedPlane.Internal.js +2 -1
  29. package/dist/core/miscellaneous/mask/UIMaskMaterialPatch.js +2 -1
  30. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunctionCircular.d.ts +10 -7
  31. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunctionCircular.js +11 -8
  32. package/dist/core/miscellaneous/resize-policy/UIResizePolicyCover.d.ts +1 -1
  33. package/dist/core/miscellaneous/resize-policy/UIResizePolicyCover.js +1 -1
  34. package/dist/core/miscellaneous/resize-policy/UIResizePolicyFit.d.ts +1 -1
  35. package/dist/core/miscellaneous/resize-policy/UIResizePolicyFit.js +1 -1
  36. package/dist/core/miscellaneous/text-style/UITextStyle.Internal.d.ts +4 -1
  37. package/dist/core/miscellaneous/text-style/UITextStyle.d.ts +4 -1
  38. package/dist/core/miscellaneous/text-style/UITextStyle.js +4 -1
  39. package/dist/core/shaders/UIProgressMaskFunctionCircular.js +1 -2
  40. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.Internal.d.ts +6 -2
  41. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.d.ts +1 -0
  42. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.js +18 -9
  43. package/dist/debug/UIAspectDebug.js +4 -7
  44. package/dist/debug/UIHeightDebug.js +4 -4
  45. package/dist/debug/UIHorizontalDistanceDebug.js +4 -7
  46. package/dist/debug/UIHorizontalInterpolationDebug.js +11 -10
  47. package/dist/debug/UIVerticalDistanceDebug.js +4 -7
  48. package/dist/debug/UIVerticalInterpolationDebug.js +11 -10
  49. package/dist/debug/UIWidthDebug.js +4 -4
  50. package/dist/debug/miscellaneous.d.ts +7 -0
  51. package/dist/debug/miscellaneous.js +11 -1
  52. package/dist/particles/behaviorModules/UIBehaviorAlignToVelocity.d.ts +44 -0
  53. package/dist/particles/behaviorModules/UIBehaviorAlignToVelocity.js +75 -0
  54. package/dist/particles/behaviorModules/UIBehaviorBounce.d.ts +51 -0
  55. package/dist/particles/behaviorModules/UIBehaviorBounce.js +107 -0
  56. package/dist/particles/behaviorModules/UIBehaviorOrbit.d.ts +39 -0
  57. package/dist/particles/behaviorModules/UIBehaviorOrbit.js +73 -0
  58. package/dist/particles/behaviorModules/UIBehaviorScaleOverLife.d.ts +7 -2
  59. package/dist/particles/behaviorModules/UIBehaviorScaleOverLife.js +9 -5
  60. package/dist/particles/behaviorModules/UIBehaviorSeek.d.ts +38 -0
  61. package/dist/particles/behaviorModules/UIBehaviorSeek.js +75 -0
  62. package/dist/particles/elements/UIEmitter.Internal.d.ts +45 -1
  63. package/dist/particles/elements/UIEmitter.Internal.js +25 -1
  64. package/dist/particles/elements/UIEmitter.Schedule.d.ts +31 -0
  65. package/dist/particles/elements/UIEmitter.Schedule.js +81 -0
  66. package/dist/particles/elements/UIEmitter.d.ts +79 -9
  67. package/dist/particles/elements/UIEmitter.js +239 -82
  68. package/dist/particles/index.d.ts +13 -1
  69. package/dist/particles/index.js +11 -1
  70. package/dist/particles/instancedParticle/UIInstancedParticle.Internal.d.ts +6 -0
  71. package/dist/particles/instancedParticle/UIInstancedParticle.Internal.js +27 -0
  72. package/dist/particles/instancedParticle/UIInstancedParticle.d.ts +7 -1
  73. package/dist/particles/instancedParticle/UIInstancedParticle.js +12 -1
  74. package/dist/particles/miscellaneous/miscellaneous.d.ts +22 -0
  75. package/dist/particles/miscellaneous/miscellaneous.js +38 -0
  76. package/dist/particles/renderingModules/UIRenderingFlipbook.d.ts +41 -0
  77. package/dist/particles/renderingModules/UIRenderingFlipbook.js +70 -0
  78. package/dist/particles/renderingModules/UIRenderingModule.d.ts +2 -1
  79. package/dist/particles/renderingModules/UIRenderingModule.js +2 -1
  80. package/dist/particles/renderingModules/UIRenderingRandomColor.d.ts +19 -0
  81. package/dist/particles/renderingModules/UIRenderingRandomColor.js +28 -0
  82. package/dist/particles/renderingModules/UIRenderingShape.d.ts +31 -0
  83. package/dist/particles/renderingModules/UIRenderingShape.js +54 -0
  84. package/dist/particles/renderingModules/UIRenderingTexture.d.ts +1 -1
  85. package/dist/particles/renderingModules/UIRenderingTexture.js +4 -28
  86. package/dist/particles/shaders/UIRenderingFlipbook.d.ts +5 -0
  87. package/dist/particles/shaders/UIRenderingFlipbook.js +19 -0
  88. package/dist/particles/shaders/UIRenderingRandomColor.d.ts +2 -0
  89. package/dist/particles/shaders/UIRenderingRandomColor.js +10 -0
  90. package/dist/particles/shaders/UIRenderingShape.d.ts +6 -0
  91. package/dist/particles/shaders/UIRenderingShape.js +15 -0
  92. package/dist/particles/shaders/UIRenderingTexture.d.ts +4 -2
  93. package/dist/particles/shaders/UIRenderingTexture.js +27 -2
  94. package/dist/particles/spawnModules/UISpawnCircle.d.ts +44 -0
  95. package/dist/particles/spawnModules/UISpawnCircle.js +81 -0
  96. package/dist/particles/spawnModules/UISpawnRadialVelocity.d.ts +37 -0
  97. package/dist/particles/spawnModules/UISpawnRadialVelocity.js +75 -0
  98. package/package.json +24 -21
@@ -2,11 +2,49 @@ import { makeNoise2D } from "fast-simplex-noise";
2
2
  import { ClampToEdgeWrapping, DataTexture, LinearFilter, RGBAFormat, SRGBColorSpace, Texture, UnsignedByteType, UVMapping, } from "three";
3
3
  export { assertValidNonNegativeInteger, assertValidUnitNumber, } from "../../core/miscellaneous/asserts.js";
4
4
  import { getTextureImageSize } from "../../core/miscellaneous/texture/UITextureView.Internal.js";
5
+ /** Easing of an interpolation between two values */
6
+ export var UIEasing;
7
+ (function (UIEasing) {
8
+ /** Constant rate */
9
+ UIEasing[UIEasing["LINEAR"] = 0] = "LINEAR";
10
+ /** Starts slow, quadratic */
11
+ UIEasing[UIEasing["IN"] = 1] = "IN";
12
+ /** Ends slow, quadratic */
13
+ UIEasing[UIEasing["OUT"] = 2] = "OUT";
14
+ /** Starts and ends slow, smoothstep */
15
+ UIEasing[UIEasing["IN_OUT"] = 3] = "IN_OUT";
16
+ })(UIEasing || (UIEasing = {}));
17
+ /**
18
+ * Eases an interpolation factor
19
+ * @param t Factor in [0, 1]
20
+ * @returns Eased factor, 0 at t = 0 and 1 at t = 1
21
+ */
22
+ export function applyEasing(easing, t) {
23
+ switch (easing) {
24
+ case UIEasing.LINEAR:
25
+ return t;
26
+ case UIEasing.IN:
27
+ return t * t;
28
+ case UIEasing.OUT:
29
+ return t * (2 - t);
30
+ case UIEasing.IN_OUT:
31
+ return t * t * (3 - 2 * t);
32
+ }
33
+ }
5
34
  /** Formats a number as a GLSL float literal */
6
35
  export function toGLSLFloat(value) {
7
36
  const literal = String(value);
8
37
  return /[.e]/.test(literal) ? literal : `${literal}.0`;
9
38
  }
39
+ /**
40
+ * GLSL expression of a whole float in [0, count) from a fraction in [0, 1]: the index of the cell
41
+ * the fraction falls in, the last cell taking 1
42
+ */
43
+ export function buildIndexExpression(fraction, count) {
44
+ const size = toGLSLFloat(count);
45
+ // Clamped below the count: at mediump precision a value just below it can round up to it
46
+ return `floor(min(${fraction} * ${size}, ${size} - 0.5))`;
47
+ }
10
48
  /** GLSL expression of the u that samples a gradient texture of `size` texels at t in [0, 1] */
11
49
  export function buildGradientCoordinate(t, size) {
12
50
  // Texel centers: the first stop at t = 0, the last at t = 1.
@@ -0,0 +1,41 @@
1
+ import type { UIProperty, UIPropertyName } from "../../core/miscellaneous/generic-plane/shared.js";
2
+ import type { UITextureConfig } from "../../core/miscellaneous/texture/UITextureView.Internal.js";
3
+ import { UIRenderingModule } from "./UIRenderingModule.js";
4
+ /** How `UIRenderingFlipbook` picks the frame of a particle */
5
+ export declare enum UIFlipbookMode {
6
+ /** Plays all frames once over the particle's life */
7
+ LIFE = 0,
8
+ /** Plays frames at a frame rate, looped */
9
+ RATE = 1,
10
+ /** One random frame for the whole life */
11
+ RANDOM = 2
12
+ }
13
+ /** Configuration options for UIRenderingFlipbook */
14
+ export interface UIRenderingFlipbookOptions {
15
+ /** Number of frames, if the last row is not full. All cells by default. */
16
+ frameCount: number;
17
+ /** How the frame is picked */
18
+ mode: UIFlipbookMode;
19
+ /** Frames per second in RATE mode, 24 by default */
20
+ frameRate: number;
21
+ /** Whether each particle starts RATE playback at a random frame */
22
+ randomStartFrame: boolean;
23
+ }
24
+ /**
25
+ * Renders particles with frames of a sprite sheet: a grid of equal cells in one texture or atlas
26
+ * region, read row by row from the top left.
27
+ *
28
+ * The frame is computed in the shader, so the number of frames costs no uniforms.
29
+ */
30
+ export declare class UIRenderingFlipbook extends UIRenderingModule {
31
+ readonly requiredProperties: Record<string, UIPropertyName>;
32
+ readonly requiredUniforms: Record<string, UIProperty>;
33
+ readonly source: string;
34
+ /**
35
+ * @param config - Texture or atlas region holding the sheet
36
+ * @param columns - Cells per row
37
+ * @param rows - Rows of cells
38
+ * @param options - Frame count and playback
39
+ */
40
+ constructor(config: UITextureConfig, columns: number, rows: number, options?: Partial<UIRenderingFlipbookOptions>);
41
+ }
@@ -0,0 +1,70 @@
1
+ import { assertValidPositiveNumber } from "../../core/miscellaneous/asserts.js";
2
+ import { UITextureView } from "../../core/miscellaneous/texture/UITextureView.js";
3
+ import { assertValidNonNegativeInteger, buildIndexExpression, toGLSLFloat, } from "../miscellaneous/miscellaneous.js";
4
+ import { buildFlipbookSource } from "../shaders/UIRenderingFlipbook.js";
5
+ import { UIRenderingModule } from "./UIRenderingModule.js";
6
+ /** How `UIRenderingFlipbook` picks the frame of a particle */
7
+ export var UIFlipbookMode;
8
+ (function (UIFlipbookMode) {
9
+ /** Plays all frames once over the particle's life */
10
+ UIFlipbookMode[UIFlipbookMode["LIFE"] = 0] = "LIFE";
11
+ /** Plays frames at a frame rate, looped */
12
+ UIFlipbookMode[UIFlipbookMode["RATE"] = 1] = "RATE";
13
+ /** One random frame for the whole life */
14
+ UIFlipbookMode[UIFlipbookMode["RANDOM"] = 2] = "RANDOM";
15
+ })(UIFlipbookMode || (UIFlipbookMode = {}));
16
+ const FLIPBOOK_DEFAULT_FRAME_RATE = 24;
17
+ /**
18
+ * Renders particles with frames of a sprite sheet: a grid of equal cells in one texture or atlas
19
+ * region, read row by row from the top left.
20
+ *
21
+ * The frame is computed in the shader, so the number of frames costs no uniforms.
22
+ */
23
+ export class UIRenderingFlipbook extends UIRenderingModule {
24
+ /**
25
+ * @param config - Texture or atlas region holding the sheet
26
+ * @param columns - Cells per row
27
+ * @param rows - Rows of cells
28
+ * @param options - Frame count and playback
29
+ */
30
+ constructor(config, columns, rows, options = {}) {
31
+ super();
32
+ this.requiredProperties = {
33
+ builtin: "Matrix4",
34
+ };
35
+ assertValidNonNegativeInteger(columns, "UIRenderingFlipbook.constructor.columns");
36
+ assertValidPositiveNumber(columns, "UIRenderingFlipbook.constructor.columns");
37
+ assertValidNonNegativeInteger(rows, "UIRenderingFlipbook.constructor.rows");
38
+ assertValidPositiveNumber(rows, "UIRenderingFlipbook.constructor.rows");
39
+ const frameCount = options.frameCount ?? columns * rows;
40
+ assertValidNonNegativeInteger(frameCount, "UIRenderingFlipbook.constructor.frameCount");
41
+ assertValidPositiveNumber(frameCount, "UIRenderingFlipbook.constructor.frameCount");
42
+ if (frameCount > columns * rows) {
43
+ throw new Error(`UIRenderingFlipbook.constructor.frameCount: ${frameCount} frames do not fit ${columns}x${rows} cells`);
44
+ }
45
+ const frameRate = options.frameRate ?? FLIPBOOK_DEFAULT_FRAME_RATE;
46
+ assertValidPositiveNumber(frameRate, "UIRenderingFlipbook.constructor.frameRate");
47
+ const view = new UITextureView(config);
48
+ this.requiredUniforms = {
49
+ texture: view.texture,
50
+ textureTransform: view.calculateUVTransform(),
51
+ };
52
+ this.source = buildFlipbookSource(buildFrameExpression(options.mode ?? UIFlipbookMode.LIFE, frameCount, frameRate, options.randomStartFrame === true), columns, rows);
53
+ }
54
+ }
55
+ /** GLSL expression of the frame number, a whole float in [0, frameCount) */
56
+ function buildFrameExpression(mode, frameCount, frameRate, randomStartFrame) {
57
+ switch (mode) {
58
+ case UIFlipbookMode.LIFE:
59
+ return buildIndexExpression("clamp(PARTICLE_AGE / PARTICLE_LIFETIME, 0.0, 1.0)", frameCount);
60
+ case UIFlipbookMode.RANDOM:
61
+ return buildIndexExpression("PARTICLE_RANDOM", frameCount);
62
+ case UIFlipbookMode.RATE: {
63
+ const count = toGLSLFloat(frameCount);
64
+ const start = randomStartFrame ? ` + PARTICLE_RANDOM * ${count}` : "";
65
+ // Frames played so far, wrapped. mod divides, and at mediump precision a quotient just
66
+ // below a whole number gives the count itself, hence the clamp.
67
+ return `floor(min(mod(floor(PARTICLE_AGE * ${toGLSLFloat(frameRate)}${start}), ${count}), ${count} - 0.5))`;
68
+ }
69
+ }
70
+ }
@@ -4,7 +4,8 @@ import type { UIProperty, UIPropertyName } from "../../core/miscellaneous/generi
4
4
  *
5
5
  * The source defines `vec4 draw()`; the colors of all rendering modules are multiplied. It reads
6
6
  * `p_uv`, uniforms and properties as `p_<name>`, and builtin values through the `PARTICLE_*`
7
- * macros, which are cheaper than reading `p_builtin` as a whole. Uniforms belong to the module:
7
+ * macros, which are cheaper than reading `p_builtin` as a whole. `PARTICLE_RANDOM` is a random
8
+ * value of the module's own, constant over the particle's life, and needs the builtin property. Uniforms belong to the module:
8
9
  * the emitter renames them per module, so modules of one type keep their own values.
9
10
  */
10
11
  export declare abstract class UIRenderingModule {
@@ -3,7 +3,8 @@
3
3
  *
4
4
  * The source defines `vec4 draw()`; the colors of all rendering modules are multiplied. It reads
5
5
  * `p_uv`, uniforms and properties as `p_<name>`, and builtin values through the `PARTICLE_*`
6
- * macros, which are cheaper than reading `p_builtin` as a whole. Uniforms belong to the module:
6
+ * macros, which are cheaper than reading `p_builtin` as a whole. `PARTICLE_RANDOM` is a random
7
+ * value of the module's own, constant over the particle's life, and needs the builtin property. Uniforms belong to the module:
7
8
  * the emitter renames them per module, so modules of one type keep their own values.
8
9
  */
9
10
  export class UIRenderingModule {
@@ -0,0 +1,19 @@
1
+ import type { UIColor } from "../../core/index.js";
2
+ import type { UIProperty, UIPropertyName } from "../../core/miscellaneous/generic-plane/shared.js";
3
+ import { UIRenderingModule } from "./UIRenderingModule.js";
4
+ /**
5
+ * Colors each particle with one color of a palette, picked at random for its whole life.
6
+ *
7
+ * The palette is one texture, read at the texel center, so the number of colors costs no
8
+ * uniforms.
9
+ */
10
+ export declare class UIRenderingRandomColor extends UIRenderingModule {
11
+ readonly requiredProperties: Record<string, UIPropertyName>;
12
+ readonly requiredUniforms: Record<string, UIProperty>;
13
+ readonly source: string;
14
+ /**
15
+ * @param colors - Palette to pick from
16
+ */
17
+ constructor(colors: UIColor[]);
18
+ destroy(): void;
19
+ }
@@ -0,0 +1,28 @@
1
+ import { buildGradientTexture } from "../miscellaneous/miscellaneous.js";
2
+ import { buildRandomColorSource } from "../shaders/UIRenderingRandomColor.js";
3
+ import { UIRenderingModule } from "./UIRenderingModule.js";
4
+ /**
5
+ * Colors each particle with one color of a palette, picked at random for its whole life.
6
+ *
7
+ * The palette is one texture, read at the texel center, so the number of colors costs no
8
+ * uniforms.
9
+ */
10
+ export class UIRenderingRandomColor extends UIRenderingModule {
11
+ /**
12
+ * @param colors - Palette to pick from
13
+ */
14
+ constructor(colors) {
15
+ super();
16
+ this.requiredProperties = {
17
+ builtin: "Matrix4",
18
+ };
19
+ if (colors.length === 0) {
20
+ throw new Error("UIRenderingRandomColor.constructor.colors: colors array cannot be empty");
21
+ }
22
+ this.requiredUniforms = { paletteTexture: buildGradientTexture(colors) };
23
+ this.source = buildRandomColorSource(colors.length);
24
+ }
25
+ destroy() {
26
+ this.requiredUniforms.paletteTexture.dispose();
27
+ }
28
+ }
@@ -0,0 +1,31 @@
1
+ import type { UIProperty } from "../../core/miscellaneous/generic-plane/shared.js";
2
+ import { UIRenderingModule } from "./UIRenderingModule.js";
3
+ /** Shapes of `UIRenderingShape`, each filling the particle quad */
4
+ export declare enum UIParticleShape {
5
+ /** Disc touching the quad edges */
6
+ CIRCLE = 0,
7
+ /** Ring whose outer edge touches the quad edges */
8
+ RING = 1,
9
+ /** Four-point star with concave sides, its points at the quad edge centers */
10
+ SPARKLE = 2
11
+ }
12
+ /** Configuration options for UIRenderingShape */
13
+ export interface UIRenderingShapeOptions {
14
+ /** Part of the shape that fades out toward its edge, from 0 (hard edge) to 1 */
15
+ softness: number;
16
+ /** Ring width as a part of the radius, from 0 to 1 */
17
+ thickness: number;
18
+ }
19
+ /**
20
+ * Renders particles as a white shape computed in the shader, without a texture. Color modules
21
+ * tint it: the colors of all rendering modules are multiplied.
22
+ */
23
+ export declare class UIRenderingShape extends UIRenderingModule {
24
+ readonly requiredUniforms: Record<string, UIProperty>;
25
+ readonly source: string;
26
+ /**
27
+ * @param shape - Shape to draw
28
+ * @param options - Edge softness and ring thickness
29
+ */
30
+ constructor(shape: UIParticleShape, options?: Partial<UIRenderingShapeOptions>);
31
+ }
@@ -0,0 +1,54 @@
1
+ import { assertValidUnitNumber } from "../../core/miscellaneous/asserts.js";
2
+ import { toGLSLFloat } from "../miscellaneous/miscellaneous.js";
3
+ import { buildShapeSource } from "../shaders/UIRenderingShape.js";
4
+ import { UIRenderingModule } from "./UIRenderingModule.js";
5
+ /** Shapes of `UIRenderingShape`, each filling the particle quad */
6
+ export var UIParticleShape;
7
+ (function (UIParticleShape) {
8
+ /** Disc touching the quad edges */
9
+ UIParticleShape[UIParticleShape["CIRCLE"] = 0] = "CIRCLE";
10
+ /** Ring whose outer edge touches the quad edges */
11
+ UIParticleShape[UIParticleShape["RING"] = 1] = "RING";
12
+ /** Four-point star with concave sides, its points at the quad edge centers */
13
+ UIParticleShape[UIParticleShape["SPARKLE"] = 2] = "SPARKLE";
14
+ })(UIParticleShape || (UIParticleShape = {}));
15
+ /** Smallest softness: smoothstep is undefined for equal edges */
16
+ const SHAPE_MIN_SOFTNESS = 0.001;
17
+ /** Smallest ring thickness: the ring distance divides by it */
18
+ const SHAPE_MIN_THICKNESS = 0.001;
19
+ const SHAPE_DEFAULT_SOFTNESS = 0.2;
20
+ const SHAPE_DEFAULT_THICKNESS = 0.25;
21
+ /**
22
+ * Renders particles as a white shape computed in the shader, without a texture. Color modules
23
+ * tint it: the colors of all rendering modules are multiplied.
24
+ */
25
+ export class UIRenderingShape extends UIRenderingModule {
26
+ /**
27
+ * @param shape - Shape to draw
28
+ * @param options - Edge softness and ring thickness
29
+ */
30
+ constructor(shape, options = {}) {
31
+ super();
32
+ this.requiredUniforms = {};
33
+ const softness = options.softness ?? SHAPE_DEFAULT_SOFTNESS;
34
+ assertValidUnitNumber(softness, "UIRenderingShape.constructor.softness");
35
+ const thickness = options.thickness ?? SHAPE_DEFAULT_THICKNESS;
36
+ assertValidUnitNumber(thickness, "UIRenderingShape.constructor.thickness");
37
+ this.source = buildShapeSource(buildDistanceExpression(shape, Math.max(thickness, SHAPE_MIN_THICKNESS)), Math.max(softness, SHAPE_MIN_SOFTNESS));
38
+ }
39
+ }
40
+ /** GLSL expression of the shape distance in `p`, 1 on the edge */
41
+ function buildDistanceExpression(shape, thickness) {
42
+ switch (shape) {
43
+ case UIParticleShape.CIRCLE:
44
+ return "length(p)";
45
+ case UIParticleShape.RING: {
46
+ // Distance from the ring's middle line, in half widths
47
+ const halfWidth = toGLSLFloat(thickness / 2);
48
+ return `abs(length(p) - (1.0 - ${halfWidth})) / ${halfWidth}`;
49
+ }
50
+ case UIParticleShape.SPARKLE:
51
+ // sqrt|x| + sqrt|y| = 1 is an astroid-like star with its points on the axes
52
+ return "sqrt(abs(p.x)) + sqrt(abs(p.y))";
53
+ }
54
+ }
@@ -5,7 +5,7 @@ import { UIRenderingModule } from "./UIRenderingModule.js";
5
5
  * Renders particles with a texture.
6
6
  *
7
7
  * Accepts a single texture config or an array of configs from the same atlas.
8
- * When an array is provided, each particle picks one texture randomly using PARTICLE_RANDOM_A.
8
+ * When an array is provided, each particle picks one texture randomly using PARTICLE_RANDOM.
9
9
  * All configs in the array must share the same underlying Three.js Texture object.
10
10
  */
11
11
  export declare class UIRenderingTexture extends UIRenderingModule {
@@ -1,35 +1,11 @@
1
1
  import { UITextureView } from "../../core/miscellaneous/texture/UITextureView.js";
2
- import source from "../shaders/UIRenderingTexture.js";
2
+ import { buildMultiTextureSource, textureSource } from "../shaders/UIRenderingTexture.js";
3
3
  import { UIRenderingModule } from "./UIRenderingModule.js";
4
- function buildMultiTextureShader(count) {
5
- const branches = [];
6
- for (let i = 0; i < count; i++) {
7
- if (i === 0) {
8
- branches.push(` if (idx == 0) t = p_textureTransform0;`);
9
- }
10
- else if (i === count - 1) {
11
- branches.push(` else t = p_textureTransform${i};`);
12
- }
13
- else {
14
- branches.push(` else if (idx == ${i}) t = p_textureTransform${i};`);
15
- }
16
- }
17
- return [
18
- "vec4 draw() {",
19
- // Clamped: at mediump precision a value just below 1 can round up to 1
20
- ` int idx = int(min(PARTICLE_RANDOM_A * ${count}.0, ${count}.0 - 0.5));`,
21
- " mat3 t;",
22
- ...branches,
23
- " vec2 transformedUV = (t * vec3(p_uv, 1.0)).xy;",
24
- " return srgbTexture2D(p_texture, transformedUV);",
25
- "}",
26
- ].join("\n");
27
- }
28
4
  /**
29
5
  * Renders particles with a texture.
30
6
  *
31
7
  * Accepts a single texture config or an array of configs from the same atlas.
32
- * When an array is provided, each particle picks one texture randomly using PARTICLE_RANDOM_A.
8
+ * When an array is provided, each particle picks one texture randomly using PARTICLE_RANDOM.
33
9
  * All configs in the array must share the same underlying Three.js Texture object.
34
10
  */
35
11
  export class UIRenderingTexture extends UIRenderingModule {
@@ -40,7 +16,7 @@ export class UIRenderingTexture extends UIRenderingModule {
40
16
  super();
41
17
  if (!Array.isArray(config) || config.length === 1) {
42
18
  const view = new UITextureView(Array.isArray(config) ? config[0] : config);
43
- this.source = source;
19
+ this.source = textureSource;
44
20
  this.requiredUniforms = {
45
21
  texture: view.texture,
46
22
  textureTransform: view.calculateUVTransform(),
@@ -63,6 +39,6 @@ export class UIRenderingTexture extends UIRenderingModule {
63
39
  }
64
40
  this.requiredProperties = { builtin: "Matrix4" };
65
41
  this.requiredUniforms = uniforms;
66
- this.source = buildMultiTextureShader(views.length);
42
+ this.source = buildMultiTextureSource(views.length);
67
43
  }
68
44
  }
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Source of a flipbook: `frameExpression` gives the frame number as a whole float in
3
+ * [0, frameCount), frames read row by row from the top left of the sheet
4
+ */
5
+ export declare function buildFlipbookSource(frameExpression: string, columns: number, rows: number): string;
@@ -0,0 +1,19 @@
1
+ import { toGLSLFloat } from "../miscellaneous/miscellaneous.js";
2
+ /**
3
+ * Source of a flipbook: `frameExpression` gives the frame number as a whole float in
4
+ * [0, frameCount), frames read row by row from the top left of the sheet
5
+ */
6
+ export function buildFlipbookSource(frameExpression, columns, rows) {
7
+ const columnCount = toGLSLFloat(columns);
8
+ const rowCount = toGLSLFloat(rows);
9
+ return `
10
+ vec4 draw() {
11
+ float frame = ${frameExpression};
12
+ // Offset by half a frame, so that floor does not drop a whole quotient computed just below it
13
+ float row = floor((frame + 0.5) / ${columnCount});
14
+ float column = frame - row * ${columnCount};
15
+ vec2 cellUV = (vec2(column, ${rowCount} - 1.0 - row) + p_uv) / vec2(${columnCount}, ${rowCount});
16
+ return srgbTexture2D(p_texture, (p_textureTransform * vec3(cellUV, 1.0)).xy);
17
+ }
18
+ `;
19
+ }
@@ -0,0 +1,2 @@
1
+ /** Source that reads one texel of a palette texture by `PARTICLE_RANDOM` */
2
+ export declare function buildRandomColorSource(paletteSize: number): string;
@@ -0,0 +1,10 @@
1
+ import { buildIndexExpression, toGLSLFloat } from "../miscellaneous/miscellaneous.js";
2
+ /** Source that reads one texel of a palette texture by `PARTICLE_RANDOM` */
3
+ export function buildRandomColorSource(paletteSize) {
4
+ return `
5
+ vec4 draw() {
6
+ float index = ${buildIndexExpression("PARTICLE_RANDOM", paletteSize)};
7
+ return srgbTexture2D(p_paletteTexture, vec2((index + 0.5) / ${toGLSLFloat(paletteSize)}, 0.5));
8
+ }
9
+ `;
10
+ }
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Source of a white shape whose alpha falls off over `softness` of its edge distance
3
+ * @param distanceExpression GLSL expression of the distance in the quad point `p`, from -1 to 1:
4
+ * below 1 inside the shape, 1 on its edge
5
+ */
6
+ export declare function buildShapeSource(distanceExpression: string, softness: number): string;
@@ -0,0 +1,15 @@
1
+ import { toGLSLFloat } from "../miscellaneous/miscellaneous.js";
2
+ /**
3
+ * Source of a white shape whose alpha falls off over `softness` of its edge distance
4
+ * @param distanceExpression GLSL expression of the distance in the quad point `p`, from -1 to 1:
5
+ * below 1 inside the shape, 1 on its edge
6
+ */
7
+ export function buildShapeSource(distanceExpression, softness) {
8
+ return `
9
+ vec4 draw() {
10
+ vec2 p = p_uv * 2.0 - 1.0;
11
+ float shapeDistance = ${distanceExpression};
12
+ return vec4(1.0, 1.0, 1.0, 1.0 - smoothstep(${toGLSLFloat(1 - softness)}, 1.0, shapeDistance));
13
+ }
14
+ `;
15
+ }
@@ -1,2 +1,4 @@
1
- declare const source: string;
2
- export default source;
1
+ /** Source that draws one texture region */
2
+ export declare const textureSource = "\nvec4 draw() {\n vec2 transformedUV = (p_textureTransform * vec3(p_uv, 1.0)).xy;\n return srgbTexture2D(p_texture, transformedUV);\n}\n";
3
+ /** Source that draws one of `count` regions of a texture, picked by `PARTICLE_RANDOM` */
4
+ export declare function buildMultiTextureSource(count: number): string;
@@ -1,7 +1,32 @@
1
- const source = `
1
+ import { buildIndexExpression } from "../miscellaneous/miscellaneous.js";
2
+ /** Source that draws one texture region */
3
+ export const textureSource = `
2
4
  vec4 draw() {
3
5
  vec2 transformedUV = (p_textureTransform * vec3(p_uv, 1.0)).xy;
4
6
  return srgbTexture2D(p_texture, transformedUV);
5
7
  }
6
8
  `;
7
- export default source;
9
+ /** Source that draws one of `count` regions of a texture, picked by `PARTICLE_RANDOM` */
10
+ export function buildMultiTextureSource(count) {
11
+ const branches = [];
12
+ for (let i = 0; i < count; i++) {
13
+ if (i === 0) {
14
+ branches.push(` if (idx == 0) t = p_textureTransform0;`);
15
+ }
16
+ else if (i === count - 1) {
17
+ branches.push(` else t = p_textureTransform${i};`);
18
+ }
19
+ else {
20
+ branches.push(` else if (idx == ${i}) t = p_textureTransform${i};`);
21
+ }
22
+ }
23
+ return [
24
+ "vec4 draw() {",
25
+ ` int idx = int(${buildIndexExpression("PARTICLE_RANDOM", count)});`,
26
+ " mat3 t;",
27
+ ...branches,
28
+ " vec2 transformedUV = (t * vec3(p_uv, 1.0)).xy;",
29
+ " return srgbTexture2D(p_texture, transformedUV);",
30
+ "}",
31
+ ].join("\n");
32
+ }
@@ -0,0 +1,44 @@
1
+ import type { InstancedBufferAttribute } from "three";
2
+ import type { UIRange, UIRangeConfig } from "../miscellaneous/miscellaneous.js";
3
+ import { UISpawnModule } from "./UISpawnModule.js";
4
+ /** How `UISpawnCircle` places particles along its arc */
5
+ export declare enum UICircleDistribution {
6
+ /** Each particle at a random angle */
7
+ RANDOM = 0,
8
+ /** The particles of one spawn call, such as one burst, evenly spaced */
9
+ EVEN = 1
10
+ }
11
+ /**
12
+ * Spawns particles within a circle, a ring or a sector of them.
13
+ *
14
+ * Positions are uniform by area between the inner and the outer radius; equal radii give a
15
+ * circle line. Angles are in radians, counter-clockwise from the right.
16
+ */
17
+ export declare class UISpawnCircle extends UISpawnModule<{
18
+ builtin: "Matrix4";
19
+ }> {
20
+ readonly requiredProperties: {
21
+ readonly builtin: "Matrix4";
22
+ };
23
+ distribution: UICircleDistribution;
24
+ private radiusInternal;
25
+ private arcInternal;
26
+ /**
27
+ * @param radius - Inner and outer radius. Accepts number, tuple, or range object
28
+ * @param arc - Angle range in radians. Accepts number, tuple, or range object
29
+ * @param distribution - Random or even placement along the arc
30
+ */
31
+ constructor(radius?: UIRangeConfig, arc?: UIRangeConfig, distribution?: UICircleDistribution);
32
+ /** Inner and outer radius */
33
+ get radius(): UIRange;
34
+ /** Angle range in radians */
35
+ get arc(): UIRange;
36
+ /** Inner and outer radius */
37
+ set radius(value: UIRangeConfig);
38
+ /** Angle range in radians */
39
+ set arc(value: UIRangeConfig);
40
+ spawn(properties: {
41
+ builtin: InstancedBufferAttribute;
42
+ }, instanceBegin: number, instanceEnd: number, randomSalt: number): void;
43
+ private assertValid;
44
+ }
@@ -0,0 +1,81 @@
1
+ import { MathUtils } from "three";
2
+ import { assertValidNonNegativeNumber, assertValidNumber, } from "../../core/miscellaneous/asserts.js";
3
+ import { BUILTIN_OFFSET_POSITION_X, BUILTIN_OFFSET_POSITION_Y, particleRandom, particleRandomStream, resolveUIRangeConfig, } from "../miscellaneous/miscellaneous.js";
4
+ import { UISpawnModule } from "./UISpawnModule.js";
5
+ /** How `UISpawnCircle` places particles along its arc */
6
+ export var UICircleDistribution;
7
+ (function (UICircleDistribution) {
8
+ /** Each particle at a random angle */
9
+ UICircleDistribution[UICircleDistribution["RANDOM"] = 0] = "RANDOM";
10
+ /** The particles of one spawn call, such as one burst, evenly spaced */
11
+ UICircleDistribution[UICircleDistribution["EVEN"] = 1] = "EVEN";
12
+ })(UICircleDistribution || (UICircleDistribution = {}));
13
+ /**
14
+ * Spawns particles within a circle, a ring or a sector of them.
15
+ *
16
+ * Positions are uniform by area between the inner and the outer radius; equal radii give a
17
+ * circle line. Angles are in radians, counter-clockwise from the right.
18
+ */
19
+ export class UISpawnCircle extends UISpawnModule {
20
+ /**
21
+ * @param radius - Inner and outer radius. Accepts number, tuple, or range object
22
+ * @param arc - Angle range in radians. Accepts number, tuple, or range object
23
+ * @param distribution - Random or even placement along the arc
24
+ */
25
+ constructor(radius = { min: 0, max: 50 }, arc = { min: -Math.PI, max: Math.PI }, distribution = UICircleDistribution.RANDOM) {
26
+ super();
27
+ this.requiredProperties = { builtin: "Matrix4" };
28
+ this.radiusInternal = resolveUIRangeConfig(radius);
29
+ this.arcInternal = resolveUIRangeConfig(arc);
30
+ this.distribution = distribution;
31
+ this.assertValid("UISpawnCircle.constructor");
32
+ }
33
+ /** Inner and outer radius */
34
+ get radius() {
35
+ return this.radiusInternal;
36
+ }
37
+ /** Angle range in radians */
38
+ get arc() {
39
+ return this.arcInternal;
40
+ }
41
+ /** Inner and outer radius */
42
+ set radius(value) {
43
+ this.radiusInternal = resolveUIRangeConfig(value);
44
+ this.assertValid("UISpawnCircle");
45
+ }
46
+ /** Angle range in radians */
47
+ set arc(value) {
48
+ this.arcInternal = resolveUIRangeConfig(value);
49
+ this.assertValid("UISpawnCircle");
50
+ }
51
+ spawn(properties, instanceBegin, instanceEnd, randomSalt) {
52
+ const { builtin } = properties;
53
+ const { array, itemSize } = builtin;
54
+ const { min: arcMin, max: arcMax } = this.arcInternal;
55
+ const innerSquared = this.radiusInternal.min * this.radiusInternal.min;
56
+ const outerSquared = this.radiusInternal.max * this.radiusInternal.max;
57
+ const even = this.distribution === UICircleDistribution.EVEN;
58
+ const count = instanceEnd - instanceBegin;
59
+ const angleStream = particleRandomStream(randomSalt, 0);
60
+ const radiusStream = particleRandomStream(randomSalt, 1);
61
+ for (let i = instanceBegin; i < instanceEnd; i++) {
62
+ const itemOffset = i * itemSize;
63
+ // Cell centers: a full circle gets equal gaps, also between the last and the first.
64
+ const angleT = even
65
+ ? (i - instanceBegin + 0.5) / count
66
+ : particleRandom(array, itemOffset, angleStream);
67
+ const angle = MathUtils.lerp(arcMin, arcMax, angleT);
68
+ // Area grows with r^2, so r^2 is uniform for a uniform density.
69
+ const radius = Math.sqrt(MathUtils.lerp(innerSquared, outerSquared, particleRandom(array, itemOffset, radiusStream)));
70
+ array[itemOffset + BUILTIN_OFFSET_POSITION_X] = Math.cos(angle) * radius;
71
+ array[itemOffset + BUILTIN_OFFSET_POSITION_Y] = Math.sin(angle) * radius;
72
+ }
73
+ builtin.needsUpdate = true;
74
+ }
75
+ assertValid(subject) {
76
+ assertValidNonNegativeNumber(this.radiusInternal.min, `${subject}.radius.min`);
77
+ assertValidNonNegativeNumber(this.radiusInternal.max, `${subject}.radius.max`);
78
+ assertValidNumber(this.arcInternal.min, `${subject}.arc.min`);
79
+ assertValidNumber(this.arcInternal.max, `${subject}.arc.max`);
80
+ }
81
+ }