laymur 0.27.1 → 0.29.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 (138) hide show
  1. package/README.md +99 -5
  2. package/dist/core/constraints/UIAspectConstraint/UIAspectConstraint.d.ts +14 -3
  3. package/dist/core/constraints/UIAspectConstraint/UIAspectConstraint.js +40 -6
  4. package/dist/core/constraints/UICustomConstraint.js +2 -2
  5. package/dist/core/constraints/UIHeightConstraint/UIHeightConstraint.js +3 -2
  6. package/dist/core/constraints/UIHorizontalDistanceConstraint/UIHorizontalDistanceConstraint.js +3 -2
  7. package/dist/core/constraints/UIHorizontalInterpolationConstraint/UIHorizontalInterpolationConstraint.js +3 -2
  8. package/dist/core/constraints/UIHorizontalProportionConstraint/UIHorizontalProportionConstraint.js +3 -2
  9. package/dist/core/constraints/UISingleParameterConstraint/UISingleParameterConstraint.d.ts +6 -0
  10. package/dist/core/constraints/UISingleParameterConstraint/UISingleParameterConstraint.js +8 -0
  11. package/dist/core/constraints/UIVerticalDistanceConstraint/UIVerticalDistanceConstraint.js +3 -2
  12. package/dist/core/constraints/UIVerticalInterpolationConstraint/UIVerticalInterpolationConstraint.js +3 -2
  13. package/dist/core/constraints/UIVerticalProportionConstraint/UIVerticalProportionConstraint.js +3 -2
  14. package/dist/core/constraints/UIWidthConstraint/UIWidthConstraint.js +3 -2
  15. package/dist/core/constraints/constraintAsserts.d.ts +41 -0
  16. package/dist/core/constraints/constraintAsserts.js +171 -0
  17. package/dist/core/elements/UICanvasElement/UICanvasElement.d.ts +54 -0
  18. package/dist/core/elements/UICanvasElement/UICanvasElement.js +70 -0
  19. package/dist/core/elements/UIDummy/UIDummy.Internal.d.ts +2 -0
  20. package/dist/core/elements/UIDummy/UIDummy.d.ts +8 -5
  21. package/dist/core/elements/UIDummy/UIDummy.js +24 -11
  22. package/dist/core/elements/UIElement/UIElement.Internal.d.ts +6 -5
  23. package/dist/core/elements/UIElement/UIElement.Internal.js +0 -4
  24. package/dist/core/elements/UIElement/UIElement.d.ts +12 -6
  25. package/dist/core/elements/UIElement/UIElement.js +14 -7
  26. package/dist/core/elements/UIGraphics/UIGraphics.Internal.d.ts +42 -2
  27. package/dist/core/elements/UIGraphics/UIGraphics.Internal.js +2 -2
  28. package/dist/core/elements/UIGraphics/UIGraphics.d.ts +48 -34
  29. package/dist/core/elements/UIGraphics/UIGraphics.js +196 -93
  30. package/dist/core/elements/UIImage/UIImage.d.ts +11 -1
  31. package/dist/core/elements/UIImage/UIImage.js +14 -0
  32. package/dist/core/elements/UIScene/UIScene.Internal.d.ts +10 -1
  33. package/dist/core/elements/UIScene/UIScene.Internal.js +1 -0
  34. package/dist/core/elements/UIScene/UIScene.d.ts +11 -1
  35. package/dist/core/elements/UIScene/UIScene.js +29 -5
  36. package/dist/core/elements/UIText/UIText.Interfaces.d.ts +2 -2
  37. package/dist/core/elements/UIText/UIText.Internal.d.ts +14 -1
  38. package/dist/core/elements/UIText/UIText.Internal.js +12 -0
  39. package/dist/core/elements/UIText/UIText.Measuring.d.ts +9 -4
  40. package/dist/core/elements/UIText/UIText.Measuring.js +17 -6
  41. package/dist/core/elements/UIText/UIText.Rendering.d.ts +7 -16
  42. package/dist/core/elements/UIText/UIText.Rendering.js +212 -46
  43. package/dist/core/elements/UIText/UIText.d.ts +64 -29
  44. package/dist/core/elements/UIText/UIText.js +134 -149
  45. package/dist/core/index.d.ts +10 -4
  46. package/dist/core/index.js +5 -1
  47. package/dist/core/layers/UILayer/UILayer.d.ts +17 -3
  48. package/dist/core/layers/UILayer/UILayer.js +35 -4
  49. package/dist/core/layers/UIViewportLayer/UIViewportLayer.d.ts +2 -0
  50. package/dist/core/layers/UIViewportLayer/UIViewportLayer.js +4 -1
  51. package/dist/core/miscellaneous/UIBlendMode.d.ts +5 -0
  52. package/dist/core/miscellaneous/UIBlendMode.js +7 -0
  53. package/dist/core/miscellaneous/asserts.d.ts +0 -41
  54. package/dist/core/miscellaneous/asserts.js +0 -170
  55. package/dist/core/miscellaneous/canvas-surface/UICanvasSurface.d.ts +46 -0
  56. package/dist/core/miscellaneous/canvas-surface/UICanvasSurface.js +86 -0
  57. package/dist/core/miscellaneous/color/UIColor.d.ts +17 -0
  58. package/dist/core/miscellaneous/color/UIColor.js +22 -0
  59. package/dist/core/miscellaneous/color/canvasColor.d.ts +9 -0
  60. package/dist/core/miscellaneous/color/canvasColor.js +15 -0
  61. package/dist/core/miscellaneous/insets/UIInsets.d.ts +3 -0
  62. package/dist/core/miscellaneous/insets/UIInsets.js +15 -0
  63. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunctionCircular.d.ts +10 -7
  64. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunctionCircular.js +11 -8
  65. package/dist/core/miscellaneous/paint/UIGradient.Internal.d.ts +37 -0
  66. package/dist/core/miscellaneous/paint/UIGradient.Internal.js +14 -0
  67. package/dist/core/miscellaneous/paint/UIGradient.d.ts +18 -0
  68. package/dist/core/miscellaneous/paint/UIGradient.js +35 -0
  69. package/dist/core/miscellaneous/paint/UILinearGradient.d.ts +14 -0
  70. package/dist/core/miscellaneous/paint/UILinearGradient.js +22 -0
  71. package/dist/core/miscellaneous/paint/UIPaint.Internal.d.ts +21 -0
  72. package/dist/core/miscellaneous/paint/UIPaint.Internal.js +1 -0
  73. package/dist/core/miscellaneous/paint/UIPaint.d.ts +17 -0
  74. package/dist/core/miscellaneous/paint/UIPaint.js +21 -0
  75. package/dist/core/miscellaneous/paint/UIRadialGradient.d.ts +18 -0
  76. package/dist/core/miscellaneous/paint/UIRadialGradient.js +33 -0
  77. package/dist/core/miscellaneous/shared.d.ts +14 -0
  78. package/dist/core/miscellaneous/shared.js +11 -0
  79. package/dist/core/miscellaneous/text-style/UITextStyle.Internal.d.ts +91 -30
  80. package/dist/core/miscellaneous/text-style/UITextStyle.Internal.js +12 -8
  81. package/dist/core/miscellaneous/text-style/UITextStyle.d.ts +41 -63
  82. package/dist/core/miscellaneous/text-style/UITextStyle.js +165 -291
  83. package/dist/core/miscellaneous/texture/UITextureView.Internal.d.ts +2 -1
  84. package/dist/core/miscellaneous/texture/UITextureView.Internal.js +12 -3
  85. package/dist/core/shaders/UIProgressMaskFunctionCircular.js +1 -2
  86. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.Internal.d.ts +7 -3
  87. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.d.ts +2 -1
  88. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.js +19 -10
  89. package/dist/core/wrappers/UISolverWrapper/UISolverWrapper.Internal.d.ts +6 -2
  90. package/dist/core/wrappers/UISolverWrapper/UISolverWrapper.d.ts +41 -9
  91. package/dist/core/wrappers/UISolverWrapper/UISolverWrapper.js +97 -35
  92. package/dist/particles/behaviorModules/UIBehaviorAlignToVelocity.d.ts +44 -0
  93. package/dist/particles/behaviorModules/UIBehaviorAlignToVelocity.js +75 -0
  94. package/dist/particles/behaviorModules/UIBehaviorBounce.d.ts +51 -0
  95. package/dist/particles/behaviorModules/UIBehaviorBounce.js +107 -0
  96. package/dist/particles/behaviorModules/UIBehaviorOrbit.d.ts +39 -0
  97. package/dist/particles/behaviorModules/UIBehaviorOrbit.js +73 -0
  98. package/dist/particles/behaviorModules/UIBehaviorScaleOverLife.d.ts +7 -2
  99. package/dist/particles/behaviorModules/UIBehaviorScaleOverLife.js +9 -5
  100. package/dist/particles/behaviorModules/UIBehaviorSeek.d.ts +38 -0
  101. package/dist/particles/behaviorModules/UIBehaviorSeek.js +75 -0
  102. package/dist/particles/elements/UIEmitter.Internal.d.ts +48 -1
  103. package/dist/particles/elements/UIEmitter.Internal.js +26 -1
  104. package/dist/particles/elements/UIEmitter.Schedule.d.ts +31 -0
  105. package/dist/particles/elements/UIEmitter.Schedule.js +81 -0
  106. package/dist/particles/elements/UIEmitter.d.ts +79 -9
  107. package/dist/particles/elements/UIEmitter.js +241 -83
  108. package/dist/particles/index.d.ts +13 -1
  109. package/dist/particles/index.js +11 -1
  110. package/dist/particles/instancedParticle/UIInstancedParticle.Internal.d.ts +6 -0
  111. package/dist/particles/instancedParticle/UIInstancedParticle.Internal.js +27 -0
  112. package/dist/particles/instancedParticle/UIInstancedParticle.d.ts +7 -1
  113. package/dist/particles/instancedParticle/UIInstancedParticle.js +12 -1
  114. package/dist/particles/miscellaneous/miscellaneous.d.ts +22 -0
  115. package/dist/particles/miscellaneous/miscellaneous.js +38 -0
  116. package/dist/particles/renderingModules/UIRenderingFlipbook.d.ts +41 -0
  117. package/dist/particles/renderingModules/UIRenderingFlipbook.js +70 -0
  118. package/dist/particles/renderingModules/UIRenderingModule.d.ts +2 -1
  119. package/dist/particles/renderingModules/UIRenderingModule.js +2 -1
  120. package/dist/particles/renderingModules/UIRenderingRandomColor.d.ts +19 -0
  121. package/dist/particles/renderingModules/UIRenderingRandomColor.js +28 -0
  122. package/dist/particles/renderingModules/UIRenderingShape.d.ts +31 -0
  123. package/dist/particles/renderingModules/UIRenderingShape.js +54 -0
  124. package/dist/particles/renderingModules/UIRenderingTexture.d.ts +1 -1
  125. package/dist/particles/renderingModules/UIRenderingTexture.js +4 -28
  126. package/dist/particles/shaders/UIRenderingFlipbook.d.ts +5 -0
  127. package/dist/particles/shaders/UIRenderingFlipbook.js +19 -0
  128. package/dist/particles/shaders/UIRenderingRandomColor.d.ts +2 -0
  129. package/dist/particles/shaders/UIRenderingRandomColor.js +10 -0
  130. package/dist/particles/shaders/UIRenderingShape.d.ts +6 -0
  131. package/dist/particles/shaders/UIRenderingShape.js +15 -0
  132. package/dist/particles/shaders/UIRenderingTexture.d.ts +4 -2
  133. package/dist/particles/shaders/UIRenderingTexture.js +27 -2
  134. package/dist/particles/spawnModules/UISpawnCircle.d.ts +44 -0
  135. package/dist/particles/spawnModules/UISpawnCircle.js +81 -0
  136. package/dist/particles/spawnModules/UISpawnRadialVelocity.d.ts +37 -0
  137. package/dist/particles/spawnModules/UISpawnRadialVelocity.js +75 -0
  138. package/package.json +1 -1
@@ -9,7 +9,7 @@ export class UIInputWrapper {
9
9
  this.hoveringPointers = new Set();
10
10
  this.lastHandler = 0;
11
11
  }
12
- /** Bumped by every change to the draw order; compare with the last seen value */
12
+ /** Bumped by every change to the draw order, to compare with a value seen before */
13
13
  get version() {
14
14
  return this.versionInternal;
15
15
  }
@@ -97,7 +97,7 @@ export class UIInputWrapper {
97
97
  this.hoveringPointers.delete(identifier);
98
98
  const pointer = { catcher: null, x, y };
99
99
  this.pointers.set(identifier, pointer);
100
- const caught = this.dispatch(x, y, identifier, "catchPointerDown", pointer);
100
+ const caught = this.dispatch(identifier, (catcher) => catcher.catchPointerDown(x, y, identifier), pointer);
101
101
  if (this.pointers.get(identifier) !== pointer) {
102
102
  return;
103
103
  }
@@ -124,18 +124,26 @@ export class UIInputWrapper {
124
124
  if (pointer === undefined) {
125
125
  this.hoveringPointers.add(identifier);
126
126
  }
127
- this.cancelBelow(identifier, this.dispatch(x, y, identifier, "catchPointerMove"));
127
+ this.cancelBelow(identifier, this.dispatch(identifier, (catcher) => catcher.catchPointerMove(x, y, identifier)));
128
128
  }
129
- /** @internal */
130
- onPointerUp(x, y, identifier) {
129
+ /**
130
+ * @param hovering Whether the pointer stays over the page after the release, as a mouse does
131
+ * @internal
132
+ */
133
+ onPointerUp(x, y, identifier, hovering) {
131
134
  const pointer = this.pointers.get(identifier);
132
135
  this.pointers.delete(identifier);
133
- this.hoveringPointers.delete(identifier);
136
+ if (hovering) {
137
+ this.hoveringPointers.add(identifier);
138
+ }
139
+ else {
140
+ this.hoveringPointers.delete(identifier);
141
+ }
134
142
  if (pointer?.catcher) {
135
- pointer.catcher.catchPointerUp(x, y, identifier);
143
+ pointer.catcher.catchPointerUp(x, y, identifier, hovering);
136
144
  return;
137
145
  }
138
- this.cancelBelow(identifier, this.dispatch(x, y, identifier, "catchPointerUp"));
146
+ this.cancelBelow(identifier, this.dispatch(identifier, (catcher) => catcher.catchPointerUp(x, y, identifier, hovering)));
139
147
  }
140
148
  /**
141
149
  * A captured pointer is cancelled at its catcher. Any other one goes to every active catcher,
@@ -176,10 +184,11 @@ export class UIInputWrapper {
176
184
  /**
177
185
  * Passes a pointer event from the top catcher down until one catches it. A handler may
178
186
  * destroy elements, so the catchers are walked over a copy and a destroyed one is skipped.
187
+ * @param catchEvent Passes the event to a catcher; true if it caught it
179
188
  * @param pointer Pressed pointer the event belongs to: the walk stops once a handler ends it
180
189
  * @returns The catcher that caught the event, or null
181
190
  */
182
- dispatch(x, y, identifier, name, pointer) {
191
+ dispatch(identifier, catchEvent, pointer) {
183
192
  this.ensureSorted();
184
193
  const catchers = this.catchers.slice();
185
194
  for (let index = catchers.length - 1; index >= 0; index--) {
@@ -187,7 +196,7 @@ export class UIInputWrapper {
187
196
  return null;
188
197
  }
189
198
  const item = catchers[index];
190
- if (item.active && item[name](x, y, identifier)) {
199
+ if (item.active && catchEvent(item)) {
191
200
  return item;
192
201
  }
193
202
  }
@@ -1,9 +1,10 @@
1
1
  import type { Constraint, Variable } from "@lume/kiwi";
2
+ import type { UIConstraint } from "../../constraints/UIConstraint.js";
2
3
  import type { UIExpression } from "../../miscellaneous/UIExpression.js";
3
4
  import type { UIPriority } from "../../miscellaneous/UIPriority.js";
4
5
  import type { UIRelation } from "../../miscellaneous/UIRelation.js";
5
6
  export interface UISolverWrapperView {
6
- /** Bumped by every change to the variables or constraints; compare with the last seen value */
7
+ /** Bumped by every change to the variables or constraints, to compare with a value seen before */
7
8
  readonly version: number;
8
9
  createVariable(value: number, priority: UIPriority): number;
9
10
  removeVariable(index: number): void;
@@ -11,7 +12,7 @@ export interface UISolverWrapperView {
11
12
  suggestVariableValue(index: number, value: number): void;
12
13
  setVariablePriority(index: number, priority: UIPriority): void;
13
14
  readVariableValue(index: number): number;
14
- createConstraint(lhs: UIExpression, rhs: UIExpression, relation: UIRelation, priority: UIPriority, enabled: boolean): number;
15
+ createConstraint(lhs: UIExpression, rhs: UIExpression, relation: UIRelation, priority: UIPriority, enabled: boolean, owner: UIConstraint): number;
15
16
  removeConstraint(index: number): void;
16
17
  isConstraintUsingVariable(constraintIndex: number, variableIndex: number): boolean;
17
18
  setConstraintLHS(index: number, lhs: UIExpression): void;
@@ -19,6 +20,7 @@ export interface UISolverWrapperView {
19
20
  setConstraintRelation(index: number, relation: UIRelation): void;
20
21
  setConstraintPriority(index: number, priority: UIPriority): void;
21
22
  setConstraintEnabled(index: number, enabled: boolean): void;
23
+ isConstraintApplied(index: number): boolean;
22
24
  }
23
25
  /**
24
26
  * Internal description of a solver variable with its associated properties.
@@ -49,4 +51,6 @@ export interface ConstraintDescription {
49
51
  relation: UIRelation;
50
52
  /** Whether the constraint is currently active. */
51
53
  enabled: boolean;
54
+ /** Constraint that created it, named when it is rejected */
55
+ owner: UIConstraint;
52
56
  }
@@ -1,3 +1,4 @@
1
+ import type { UIConstraint } from "../../constraints/UIConstraint.js";
1
2
  import { UIExpression } from "../../miscellaneous/UIExpression.js";
2
3
  import { UIPriority } from "../../miscellaneous/UIPriority.js";
3
4
  import { UIRelation } from "../../miscellaneous/UIRelation.js";
@@ -15,7 +16,7 @@ import type { UISolverWrapperView } from "./UISolverWrapper.Internal.js";
15
16
  * - Index-based variable and constraint management
16
17
  * - Required variables with P0 priority (always satisfied)
17
18
  * - Dynamic constraint modification without full rebuilds
18
- * - Automatic solver recovery on constraint conflicts
19
+ * - Automatic solver recovery on constraint conflicts, with rejected constraints reported
19
20
  * - Lazy evaluation with recalculation flags
20
21
  *
21
22
  * @see {@link UIExpression} - Expression system for constraint definitions
@@ -23,6 +24,7 @@ import type { UISolverWrapperView } from "./UISolverWrapper.Internal.js";
23
24
  * @see {@link UIRelation} - Relational operators for constraints
24
25
  */
25
26
  export declare class UISolverWrapper implements UISolverWrapperView {
27
+ private readonly onConstraintsRejected;
26
28
  private versionInternal;
27
29
  /** The underlying Kiwi solver instance, undefined when solver needs rebuilding. */
28
30
  private solver?;
@@ -36,7 +38,22 @@ export declare class UISolverWrapper implements UISolverWrapperView {
36
38
  private readonly constraints;
37
39
  /** Counter for generating unique constraint indices. */
38
40
  private lastConstraintIndex;
39
- /** Bumped by every change to the variables or constraints; compare with the last seen value */
41
+ /** Enabled constraints the last rebuild could not add, see isConstraintApplied */
42
+ private readonly rejectedConstraints;
43
+ /**
44
+ * Bumped by the changes that can resolve a conflict of required constraints: any change of a
45
+ * constraint and of a required variable. Suggested values of other variables are not required
46
+ * and cannot.
47
+ */
48
+ private structureVersion;
49
+ /** Structure version as of the last rebuild */
50
+ private rebuiltStructureVersion;
51
+ /**
52
+ * @param onConstraintsRejected - Called after a rebuild with the constraints it newly found in
53
+ * conflict with required constraints. The solver is complete by then, so it may throw.
54
+ */
55
+ constructor(onConstraintsRejected: (constraints: readonly UIConstraint[]) => void);
56
+ /** Bumped by every change to the variables or constraints, to compare with a value seen before */
40
57
  get version(): number;
41
58
  /**
42
59
  * Creates a new solver variable with the specified value and priority.
@@ -102,6 +119,16 @@ export declare class UISolverWrapper implements UISolverWrapperView {
102
119
  * @throws Will throw an error if the variable doesn't exist
103
120
  */
104
121
  readVariableValue(index: number): number;
122
+ /**
123
+ * Whether the solver applies a constraint, that is, it is enabled and not rejected. A required
124
+ * constraint that conflicts with other required ones is rejected, the later created of them.
125
+ * Rejected constraints are tried again after any change of a constraint or a required variable.
126
+ *
127
+ * @param index - Index of the constraint
128
+ * @returns True if the constraint takes part in solving
129
+ * @throws Will throw an error if the constraint doesn't exist
130
+ */
131
+ isConstraintApplied(index: number): boolean;
105
132
  /**
106
133
  * Creates a new constraint between two expressions.
107
134
  *
@@ -113,9 +140,10 @@ export declare class UISolverWrapper implements UISolverWrapperView {
113
140
  * @param relation - Relational operator (equal, less than, greater than)
114
141
  * @param priority - Priority level for constraint solving
115
142
  * @param enabled - Whether the constraint is initially active
143
+ * @param owner - Constraint the solver constraint belongs to, named when it is rejected
116
144
  * @returns Unique index identifier for the created constraint
117
145
  */
118
- createConstraint(lhs: UIExpression, rhs: UIExpression, relation: UIRelation, priority: UIPriority, enabled: boolean): number;
146
+ createConstraint(lhs: UIExpression, rhs: UIExpression, relation: UIRelation, priority: UIPriority, enabled: boolean, owner: UIConstraint): number;
119
147
  /**
120
148
  * Removes a constraint from the solver system.
121
149
  *
@@ -224,18 +252,22 @@ export declare class UISolverWrapper implements UISolverWrapperView {
224
252
  * and preserves coefficients and constants.
225
253
  */
226
254
  private convertExpression;
255
+ /**
256
+ * Brings the solver up to date. Rebuilds it when it was dropped, or when rejected constraints
257
+ * exist and the structure changed since the last rebuild, so that they are tried again. Then
258
+ * recalculates the variables.
259
+ */
260
+ private ensureSolved;
227
261
  /**
228
262
  * Completely rebuilds the solver from scratch.
229
263
  *
230
264
  * Re-adds all variables and constraints to a fresh solver instance.
231
265
  * Used for recovery when the solver enters an invalid state.
232
266
  *
233
- * The solver is normally dropped because some constraint was rejected by kiwi,
234
- * and that same constraint is still registered here. Replaying it would throw
235
- * again, so every replay is guarded individually: a constraint kiwi refuses is
236
- * skipped and stays registered but unapplied, which is exactly the state it was
237
- * already in. The fresh solver is only published once the replay is complete,
238
- * so a rejection can never leave a half-built solver in place.
267
+ * The solver is normally dropped because kiwi rejected a constraint, and that constraint is
268
+ * still registered here. Each constraint kiwi refuses on replay is recorded as rejected and
269
+ * skipped, and the rest are added in order of creation. The fresh solver is published once the
270
+ * replay is complete, then the newly rejected constraints are reported.
239
271
  */
240
272
  private rebuildSolver;
241
273
  }
@@ -15,7 +15,7 @@ import { convertRelation, UIRelation } from "../../miscellaneous/UIRelation.js";
15
15
  * - Index-based variable and constraint management
16
16
  * - Required variables with P0 priority (always satisfied)
17
17
  * - Dynamic constraint modification without full rebuilds
18
- * - Automatic solver recovery on constraint conflicts
18
+ * - Automatic solver recovery on constraint conflicts, with rejected constraints reported
19
19
  * - Lazy evaluation with recalculation flags
20
20
  *
21
21
  * @see {@link UIExpression} - Expression system for constraint definitions
@@ -23,7 +23,12 @@ import { convertRelation, UIRelation } from "../../miscellaneous/UIRelation.js";
23
23
  * @see {@link UIRelation} - Relational operators for constraints
24
24
  */
25
25
  export class UISolverWrapper {
26
- constructor() {
26
+ /**
27
+ * @param onConstraintsRejected - Called after a rebuild with the constraints it newly found in
28
+ * conflict with required constraints. The solver is complete by then, so it may throw.
29
+ */
30
+ constructor(onConstraintsRejected) {
31
+ this.onConstraintsRejected = onConstraintsRejected;
27
32
  this.versionInternal = 0;
28
33
  /** The underlying Kiwi solver instance, undefined when solver needs rebuilding. */
29
34
  this.solver = new Solver();
@@ -37,8 +42,18 @@ export class UISolverWrapper {
37
42
  this.constraints = new Map();
38
43
  /** Counter for generating unique constraint indices. */
39
44
  this.lastConstraintIndex = 0;
45
+ /** Enabled constraints the last rebuild could not add, see isConstraintApplied */
46
+ this.rejectedConstraints = new Set();
47
+ /**
48
+ * Bumped by the changes that can resolve a conflict of required constraints: any change of a
49
+ * constraint and of a required variable. Suggested values of other variables are not required
50
+ * and cannot.
51
+ */
52
+ this.structureVersion = 0;
53
+ /** Structure version as of the last rebuild */
54
+ this.rebuiltStructureVersion = -1;
40
55
  }
41
- /** Bumped by every change to the variables or constraints; compare with the last seen value */
56
+ /** Bumped by every change to the variables or constraints, to compare with a value seen before */
42
57
  get version() {
43
58
  return this.versionInternal;
44
59
  }
@@ -78,6 +93,7 @@ export class UISolverWrapper {
78
93
  }
79
94
  }
80
95
  this.recalculationRequired = true;
96
+ this.structureVersion++;
81
97
  this.versionInternal++;
82
98
  return index;
83
99
  }
@@ -110,6 +126,7 @@ export class UISolverWrapper {
110
126
  }
111
127
  this.variables.delete(index);
112
128
  this.recalculationRequired = true;
129
+ this.structureVersion++;
113
130
  this.versionInternal++;
114
131
  }
115
132
  /**
@@ -146,6 +163,9 @@ export class UISolverWrapper {
146
163
  this.solver?.suggestValue(description.variable, value);
147
164
  }
148
165
  this.recalculationRequired = true;
166
+ if (description.constraint) {
167
+ this.structureVersion++;
168
+ }
149
169
  this.versionInternal++;
150
170
  }
151
171
  }
@@ -199,6 +219,7 @@ export class UISolverWrapper {
199
219
  this.rebuildVariable(index, description);
200
220
  }
201
221
  this.recalculationRequired = true;
222
+ this.structureVersion++;
202
223
  this.versionInternal++;
203
224
  }
204
225
  }
@@ -217,15 +238,26 @@ export class UISolverWrapper {
217
238
  if (description === undefined) {
218
239
  throw new Error(`UISolverWrapper.readVariableValue.index: variable ${index} does not exist; its element may be destroyed`);
219
240
  }
220
- if (this.solver === undefined) {
221
- this.rebuildSolver();
222
- }
223
- if (this.recalculationRequired) {
224
- this.solver?.updateVariables();
225
- this.recalculationRequired = false;
226
- }
241
+ this.ensureSolved();
227
242
  return description.variable.value();
228
243
  }
244
+ /**
245
+ * Whether the solver applies a constraint, that is, it is enabled and not rejected. A required
246
+ * constraint that conflicts with other required ones is rejected, the later created of them.
247
+ * Rejected constraints are tried again after any change of a constraint or a required variable.
248
+ *
249
+ * @param index - Index of the constraint
250
+ * @returns True if the constraint takes part in solving
251
+ * @throws Will throw an error if the constraint doesn't exist
252
+ */
253
+ isConstraintApplied(index) {
254
+ const description = this.constraints.get(index);
255
+ if (description === undefined) {
256
+ throw new Error(`UISolverWrapper.isConstraintApplied.index: constraint ${index} does not exist; it may be destroyed`);
257
+ }
258
+ this.ensureSolved();
259
+ return description.enabled && !this.rejectedConstraints.has(index);
260
+ }
229
261
  /**
230
262
  * Creates a new constraint between two expressions.
231
263
  *
@@ -237,9 +269,10 @@ export class UISolverWrapper {
237
269
  * @param relation - Relational operator (equal, less than, greater than)
238
270
  * @param priority - Priority level for constraint solving
239
271
  * @param enabled - Whether the constraint is initially active
272
+ * @param owner - Constraint the solver constraint belongs to, named when it is rejected
240
273
  * @returns Unique index identifier for the created constraint
241
274
  */
242
- createConstraint(lhs, rhs, relation, priority, enabled) {
275
+ createConstraint(lhs, rhs, relation, priority, enabled, owner) {
243
276
  const index = this.lastConstraintIndex++;
244
277
  const constraint = this.buildConstraint(lhs, rhs, relation, priority);
245
278
  this.constraints.set(index, {
@@ -249,6 +282,7 @@ export class UISolverWrapper {
249
282
  priority,
250
283
  relation,
251
284
  enabled,
285
+ owner,
252
286
  });
253
287
  if (enabled) {
254
288
  try {
@@ -258,6 +292,7 @@ export class UISolverWrapper {
258
292
  this.solver = undefined;
259
293
  }
260
294
  this.recalculationRequired = true;
295
+ this.structureVersion++;
261
296
  this.versionInternal++;
262
297
  }
263
298
  return index;
@@ -276,7 +311,7 @@ export class UISolverWrapper {
276
311
  if (description === undefined) {
277
312
  throw new Error(`UISolverWrapper.removeConstraint.index: constraint ${index} does not exist; it may be destroyed`);
278
313
  }
279
- if (description.enabled) {
314
+ if (description.enabled && !this.rejectedConstraints.has(index)) {
280
315
  try {
281
316
  this.solver?.removeConstraint(description.constraint);
282
317
  }
@@ -285,7 +320,9 @@ export class UISolverWrapper {
285
320
  }
286
321
  }
287
322
  this.constraints.delete(index);
323
+ this.rejectedConstraints.delete(index);
288
324
  this.recalculationRequired = true;
325
+ this.structureVersion++;
289
326
  this.versionInternal++;
290
327
  }
291
328
  /**
@@ -321,6 +358,7 @@ export class UISolverWrapper {
321
358
  description.lhs.copy(lhs);
322
359
  this.rebuildConstraintByDescription(description);
323
360
  this.recalculationRequired = true;
361
+ this.structureVersion++;
324
362
  this.versionInternal++;
325
363
  }
326
364
  /**
@@ -341,6 +379,7 @@ export class UISolverWrapper {
341
379
  description.rhs.copy(rhs);
342
380
  this.rebuildConstraintByDescription(description);
343
381
  this.recalculationRequired = true;
382
+ this.structureVersion++;
344
383
  this.versionInternal++;
345
384
  }
346
385
  /**
@@ -362,6 +401,7 @@ export class UISolverWrapper {
362
401
  description.relation = relation;
363
402
  this.rebuildConstraintByDescription(description);
364
403
  this.recalculationRequired = true;
404
+ this.structureVersion++;
365
405
  this.versionInternal++;
366
406
  }
367
407
  }
@@ -384,6 +424,7 @@ export class UISolverWrapper {
384
424
  description.priority = priority;
385
425
  this.rebuildConstraintByDescription(description);
386
426
  this.recalculationRequired = true;
427
+ this.structureVersion++;
387
428
  this.versionInternal++;
388
429
  }
389
430
  }
@@ -413,6 +454,7 @@ export class UISolverWrapper {
413
454
  this.solver = undefined;
414
455
  }
415
456
  this.recalculationRequired = true;
457
+ this.structureVersion++;
416
458
  this.versionInternal++;
417
459
  }
418
460
  }
@@ -515,18 +557,32 @@ export class UISolverWrapper {
515
557
  return [coefficient, description.variable];
516
558
  }), expression.constant);
517
559
  }
560
+ /**
561
+ * Brings the solver up to date. Rebuilds it when it was dropped, or when rejected constraints
562
+ * exist and the structure changed since the last rebuild, so that they are tried again. Then
563
+ * recalculates the variables.
564
+ */
565
+ ensureSolved() {
566
+ if (this.solver === undefined ||
567
+ (this.rejectedConstraints.size > 0 && this.rebuiltStructureVersion !== this.structureVersion)) {
568
+ this.solver = undefined;
569
+ this.rebuildSolver();
570
+ }
571
+ if (this.recalculationRequired) {
572
+ this.solver?.updateVariables();
573
+ this.recalculationRequired = false;
574
+ }
575
+ }
518
576
  /**
519
577
  * Completely rebuilds the solver from scratch.
520
578
  *
521
579
  * Re-adds all variables and constraints to a fresh solver instance.
522
580
  * Used for recovery when the solver enters an invalid state.
523
581
  *
524
- * The solver is normally dropped because some constraint was rejected by kiwi,
525
- * and that same constraint is still registered here. Replaying it would throw
526
- * again, so every replay is guarded individually: a constraint kiwi refuses is
527
- * skipped and stays registered but unapplied, which is exactly the state it was
528
- * already in. The fresh solver is only published once the replay is complete,
529
- * so a rejection can never leave a half-built solver in place.
582
+ * The solver is normally dropped because kiwi rejected a constraint, and that constraint is
583
+ * still registered here. Each constraint kiwi refuses on replay is recorded as rejected and
584
+ * skipped, and the rest are added in order of creation. The fresh solver is published once the
585
+ * replay is complete, then the newly rejected constraints are reported.
530
586
  */
531
587
  rebuildSolver() {
532
588
  if (this.solver) {
@@ -534,31 +590,37 @@ export class UISolverWrapper {
534
590
  }
535
591
  const solver = new Solver();
536
592
  for (const description of this.variables.values()) {
537
- try {
538
- if (description.constraint) {
539
- solver.addConstraint(description.constraint);
540
- }
541
- else {
542
- solver.addEditVariable(description.variable, convertPriority(description.priority));
543
- solver.suggestValue(description.variable, description.value);
544
- }
593
+ if (description.constraint) {
594
+ solver.addConstraint(description.constraint);
545
595
  }
546
- catch {
547
- continue;
596
+ else {
597
+ solver.addEditVariable(description.variable, convertPriority(description.priority));
598
+ solver.suggestValue(description.variable, description.value);
548
599
  }
549
600
  }
550
- for (const description of this.constraints.values()) {
551
- if (description.enabled) {
552
- try {
553
- solver.addConstraint(description.constraint);
554
- }
555
- catch {
556
- continue;
601
+ const newlyRejected = [];
602
+ for (const [index, description] of this.constraints) {
603
+ if (!description.enabled) {
604
+ this.rejectedConstraints.delete(index);
605
+ continue;
606
+ }
607
+ try {
608
+ solver.addConstraint(description.constraint);
609
+ this.rejectedConstraints.delete(index);
610
+ }
611
+ catch {
612
+ if (!this.rejectedConstraints.has(index)) {
613
+ this.rejectedConstraints.add(index);
614
+ newlyRejected.push(description.owner);
557
615
  }
558
616
  }
559
617
  }
560
618
  this.solver = solver;
561
619
  this.recalculationRequired = true;
562
620
  this.versionInternal++;
621
+ this.rebuiltStructureVersion = this.structureVersion;
622
+ if (newlyRejected.length > 0) {
623
+ this.onConstraintsRejected(newlyRejected);
624
+ }
563
625
  }
564
626
  }
@@ -0,0 +1,44 @@
1
+ import type { InstancedBufferAttribute } from "three";
2
+ import type { UIAspectConfig } from "../miscellaneous/miscellaneous.js";
3
+ import { UIBehaviorModule } from "./UIBehaviorModule.js";
4
+ /**
5
+ * Turns the X axis of particles along their velocity and stretches them along it with speed, as
6
+ * motion blur of sparks and streaks.
7
+ *
8
+ * Sets the rotation every frame, so torque has no effect. The length is derived from the Y scale,
9
+ * so the module composes with any scale source: put it after `UISpawnRandomScale` or
10
+ * `UIBehaviorScaleOverLife` in the sequence. A particle at rest keeps its rotation.
11
+ */
12
+ export declare class UIBehaviorAlignToVelocity extends UIBehaviorModule<{
13
+ builtin: "Matrix4";
14
+ }> {
15
+ readonly requiredProperties: {
16
+ readonly builtin: "Matrix4";
17
+ };
18
+ private stretchInternal;
19
+ private rotationOffsetInternal;
20
+ private aspectInternal;
21
+ /**
22
+ * @param stretch - Seconds of motion added to the length: the length grows by speed * stretch
23
+ * @param aspect - Width/height ratio at rest, the same as given to the scale module. Accepts
24
+ * number or texture
25
+ * @param rotationOffset - Angle in radians added to the direction, for sprites drawn along
26
+ * another axis
27
+ */
28
+ constructor(stretch?: number, aspect?: UIAspectConfig, rotationOffset?: number);
29
+ /** Seconds of motion added to the length */
30
+ get stretch(): number;
31
+ /** Width/height aspect ratio at rest */
32
+ get aspect(): number;
33
+ /** Angle in radians added to the direction */
34
+ get rotationOffset(): number;
35
+ /** Seconds of motion added to the length */
36
+ set stretch(value: number);
37
+ /** Width/height aspect ratio at rest */
38
+ set aspect(value: UIAspectConfig);
39
+ /** Angle in radians added to the direction */
40
+ set rotationOffset(value: number);
41
+ update(properties: {
42
+ builtin: InstancedBufferAttribute;
43
+ }, instanceCount: number): void;
44
+ }
@@ -0,0 +1,75 @@
1
+ import { assertValidNonNegativeNumber, assertValidNumber, assertValidPositiveNumber, } from "../../core/miscellaneous/asserts.js";
2
+ import { BUILTIN_OFFSET_ROTATION, BUILTIN_OFFSET_SCALE_X, BUILTIN_OFFSET_SCALE_Y, BUILTIN_OFFSET_VELOCITY_X, BUILTIN_OFFSET_VELOCITY_Y, resolveAspect, } from "../miscellaneous/miscellaneous.js";
3
+ import { UIBehaviorModule } from "./UIBehaviorModule.js";
4
+ /**
5
+ * Turns the X axis of particles along their velocity and stretches them along it with speed, as
6
+ * motion blur of sparks and streaks.
7
+ *
8
+ * Sets the rotation every frame, so torque has no effect. The length is derived from the Y scale,
9
+ * so the module composes with any scale source: put it after `UISpawnRandomScale` or
10
+ * `UIBehaviorScaleOverLife` in the sequence. A particle at rest keeps its rotation.
11
+ */
12
+ export class UIBehaviorAlignToVelocity extends UIBehaviorModule {
13
+ /**
14
+ * @param stretch - Seconds of motion added to the length: the length grows by speed * stretch
15
+ * @param aspect - Width/height ratio at rest, the same as given to the scale module. Accepts
16
+ * number or texture
17
+ * @param rotationOffset - Angle in radians added to the direction, for sprites drawn along
18
+ * another axis
19
+ */
20
+ constructor(stretch = 0, aspect = 1, rotationOffset = 0) {
21
+ super();
22
+ this.requiredProperties = { builtin: "Matrix4" };
23
+ this.stretchInternal = stretch;
24
+ this.aspectInternal = resolveAspect(aspect);
25
+ this.rotationOffsetInternal = rotationOffset;
26
+ assertValidNonNegativeNumber(stretch, "UIBehaviorAlignToVelocity.constructor.stretch");
27
+ assertValidPositiveNumber(this.aspectInternal, "UIBehaviorAlignToVelocity.constructor.aspect");
28
+ assertValidNumber(rotationOffset, "UIBehaviorAlignToVelocity.constructor.rotationOffset");
29
+ }
30
+ /** Seconds of motion added to the length */
31
+ get stretch() {
32
+ return this.stretchInternal;
33
+ }
34
+ /** Width/height aspect ratio at rest */
35
+ get aspect() {
36
+ return this.aspectInternal;
37
+ }
38
+ /** Angle in radians added to the direction */
39
+ get rotationOffset() {
40
+ return this.rotationOffsetInternal;
41
+ }
42
+ /** Seconds of motion added to the length */
43
+ set stretch(value) {
44
+ assertValidNonNegativeNumber(value, "UIBehaviorAlignToVelocity.stretch");
45
+ this.stretchInternal = value;
46
+ }
47
+ /** Width/height aspect ratio at rest */
48
+ set aspect(value) {
49
+ this.aspectInternal = resolveAspect(value);
50
+ assertValidPositiveNumber(this.aspectInternal, "UIBehaviorAlignToVelocity.aspect");
51
+ }
52
+ /** Angle in radians added to the direction */
53
+ set rotationOffset(value) {
54
+ assertValidNumber(value, "UIBehaviorAlignToVelocity.rotationOffset");
55
+ this.rotationOffsetInternal = value;
56
+ }
57
+ update(properties, instanceCount) {
58
+ const { builtin } = properties;
59
+ const { array, itemSize } = builtin;
60
+ for (let i = 0; i < instanceCount; i++) {
61
+ const itemOffset = i * itemSize;
62
+ const velocityX = array[itemOffset + BUILTIN_OFFSET_VELOCITY_X];
63
+ const velocityY = array[itemOffset + BUILTIN_OFFSET_VELOCITY_Y];
64
+ const speed = Math.hypot(velocityX, velocityY);
65
+ if (speed > 0) {
66
+ array[itemOffset + BUILTIN_OFFSET_ROTATION] =
67
+ Math.atan2(velocityY, velocityX) + this.rotationOffsetInternal;
68
+ }
69
+ array[itemOffset + BUILTIN_OFFSET_SCALE_X] =
70
+ array[itemOffset + BUILTIN_OFFSET_SCALE_Y] * this.aspectInternal +
71
+ speed * this.stretchInternal;
72
+ }
73
+ builtin.needsUpdate = true;
74
+ }
75
+ }
@@ -0,0 +1,51 @@
1
+ import type { InstancedBufferAttribute } from "three";
2
+ import type { Vector2Like } from "../../core/miscellaneous/math.js";
3
+ import type { UIVector2Config } from "../miscellaneous/miscellaneous.js";
4
+ import { UIBehaviorModule } from "./UIBehaviorModule.js";
5
+ /**
6
+ * Keeps particles on one side of a line and bounces them off it, as a floor or a wall.
7
+ *
8
+ * The line passes through a point, and its normal points to the free side. A particle behind it
9
+ * is put back on the line, the velocity into it is reflected and scaled by the restitution, and
10
+ * the velocity along it decays by the friction while in contact, as `UIBehaviorVelocityDamping`
11
+ * does. The point and the normal are in the particle space of the emitter.
12
+ */
13
+ export declare class UIBehaviorBounce extends UIBehaviorModule<{
14
+ builtin: "Matrix4";
15
+ }> {
16
+ readonly requiredProperties: {
17
+ readonly builtin: "Matrix4";
18
+ };
19
+ private pointInternal;
20
+ private normalX;
21
+ private normalY;
22
+ private restitutionInternal;
23
+ private frictionInternal;
24
+ /**
25
+ * @param point - A point of the line
26
+ * @param normal - Direction to the free side, normalized by the module
27
+ * @param restitution - Share of the speed into the line kept after a bounce, from 0 to 1
28
+ * @param friction - Share of the speed along the line lost per second of contact, from 0 to 1
29
+ */
30
+ constructor(point: UIVector2Config, normal?: UIVector2Config, restitution?: number, friction?: number);
31
+ /** A point of the line */
32
+ get point(): Vector2Like;
33
+ /** Unit direction to the free side */
34
+ get normal(): Vector2Like;
35
+ /** Share of the speed into the line kept after a bounce */
36
+ get restitution(): number;
37
+ /** Share of the speed along the line lost per second of contact */
38
+ get friction(): number;
39
+ /** A point of the line */
40
+ set point(value: UIVector2Config);
41
+ /** Direction to the free side, normalized by the module */
42
+ set normal(value: UIVector2Config);
43
+ /** Share of the speed into the line kept after a bounce */
44
+ set restitution(value: number);
45
+ /** Share of the speed along the line lost per second of contact */
46
+ set friction(value: number);
47
+ update(properties: {
48
+ builtin: InstancedBufferAttribute;
49
+ }, instanceCount: number, deltaTime: number): void;
50
+ private setNormal;
51
+ }