@typeonce/ritmo-math 0.13.0 → 0.15.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 (113) hide show
  1. package/CHANGELOG.md +149 -0
  2. package/README.md +18 -13
  3. package/dist/Angle.d.ts +44 -0
  4. package/dist/Angle.d.ts.map +1 -0
  5. package/dist/Angle.js +62 -0
  6. package/dist/Angle.js.map +1 -0
  7. package/dist/Box2.d.ts +16 -4
  8. package/dist/Box2.d.ts.map +1 -1
  9. package/dist/Box2.js +16 -1
  10. package/dist/Box2.js.map +1 -1
  11. package/dist/Collide2.d.ts +59 -15
  12. package/dist/Collide2.d.ts.map +1 -1
  13. package/dist/Collide2.js +156 -18
  14. package/dist/Collide2.js.map +1 -1
  15. package/dist/FlowField.d.ts +24 -38
  16. package/dist/FlowField.d.ts.map +1 -1
  17. package/dist/FlowField.js +18 -5
  18. package/dist/FlowField.js.map +1 -1
  19. package/dist/Scalar.d.ts +19 -166
  20. package/dist/Scalar.d.ts.map +1 -1
  21. package/dist/Scalar.js +51 -51
  22. package/dist/Scalar.js.map +1 -1
  23. package/dist/Segment2.d.ts +56 -0
  24. package/dist/Segment2.d.ts.map +1 -0
  25. package/dist/Segment2.js +32 -0
  26. package/dist/Segment2.js.map +1 -0
  27. package/dist/Vec2.d.ts +47 -7
  28. package/dist/Vec2.d.ts.map +1 -1
  29. package/dist/Vec2.js +56 -8
  30. package/dist/Vec2.js.map +1 -1
  31. package/dist/index.d.ts +10 -21
  32. package/dist/index.d.ts.map +1 -1
  33. package/dist/index.js +10 -21
  34. package/dist/index.js.map +1 -1
  35. package/package.json +3 -3
  36. package/src/Angle.ts +60 -0
  37. package/src/Box2.ts +20 -4
  38. package/src/Collide2.ts +171 -24
  39. package/src/FlowField.ts +34 -10
  40. package/src/Scalar.ts +43 -165
  41. package/src/Segment2.ts +71 -0
  42. package/src/Vec2.ts +58 -8
  43. package/src/index.ts +10 -21
  44. package/dist/Aabb.d.ts +0 -182
  45. package/dist/Aabb.d.ts.map +0 -1
  46. package/dist/Aabb.js +0 -109
  47. package/dist/Aabb.js.map +0 -1
  48. package/dist/InputAxis.d.ts +0 -44
  49. package/dist/InputAxis.d.ts.map +0 -1
  50. package/dist/InputAxis.js +0 -71
  51. package/dist/InputAxis.js.map +0 -1
  52. package/dist/Ops.d.ts +0 -209
  53. package/dist/Ops.d.ts.map +0 -1
  54. package/dist/Ops.js +0 -210
  55. package/dist/Ops.js.map +0 -1
  56. package/dist/Random.d.ts +0 -124
  57. package/dist/Random.d.ts.map +0 -1
  58. package/dist/Random.js +0 -126
  59. package/dist/Random.js.map +0 -1
  60. package/dist/Size2.d.ts +0 -118
  61. package/dist/Size2.d.ts.map +0 -1
  62. package/dist/Size2.js +0 -54
  63. package/dist/Size2.js.map +0 -1
  64. package/dist/SpatialGrid.d.ts +0 -68
  65. package/dist/SpatialGrid.d.ts.map +0 -1
  66. package/dist/SpatialGrid.js +0 -112
  67. package/dist/SpatialGrid.js.map +0 -1
  68. package/dist/Vector2.d.ts +0 -214
  69. package/dist/Vector2.d.ts.map +0 -1
  70. package/dist/Vector2.js +0 -134
  71. package/dist/Vector2.js.map +0 -1
  72. package/dist/internal/aabb.d.ts +0 -27
  73. package/dist/internal/aabb.d.ts.map +0 -1
  74. package/dist/internal/aabb.js +0 -52
  75. package/dist/internal/aabb.js.map +0 -1
  76. package/dist/internal/codec.d.ts +0 -9
  77. package/dist/internal/codec.d.ts.map +0 -1
  78. package/dist/internal/codec.js +0 -16
  79. package/dist/internal/codec.js.map +0 -1
  80. package/dist/internal/fdlibm.d.ts +0 -43
  81. package/dist/internal/fdlibm.d.ts.map +0 -1
  82. package/dist/internal/fdlibm.js +0 -1291
  83. package/dist/internal/fdlibm.js.map +0 -1
  84. package/dist/internal/inputAxis.d.ts +0 -11
  85. package/dist/internal/inputAxis.d.ts.map +0 -1
  86. package/dist/internal/inputAxis.js +0 -13
  87. package/dist/internal/inputAxis.js.map +0 -1
  88. package/dist/internal/scalar.d.ts +0 -11
  89. package/dist/internal/scalar.d.ts.map +0 -1
  90. package/dist/internal/scalar.js +0 -68
  91. package/dist/internal/scalar.js.map +0 -1
  92. package/dist/internal/size2.d.ts +0 -22
  93. package/dist/internal/size2.d.ts.map +0 -1
  94. package/dist/internal/size2.js +0 -38
  95. package/dist/internal/size2.js.map +0 -1
  96. package/dist/internal/vector2.d.ts +0 -39
  97. package/dist/internal/vector2.d.ts.map +0 -1
  98. package/dist/internal/vector2.js +0 -78
  99. package/dist/internal/vector2.js.map +0 -1
  100. package/src/Aabb.ts +0 -180
  101. package/src/InputAxis.ts +0 -81
  102. package/src/Ops.ts +0 -232
  103. package/src/Random.ts +0 -225
  104. package/src/Size2.ts +0 -122
  105. package/src/SpatialGrid.ts +0 -172
  106. package/src/Vector2.ts +0 -216
  107. package/src/internal/aabb.ts +0 -81
  108. package/src/internal/codec.ts +0 -21
  109. package/src/internal/fdlibm.ts +0 -1256
  110. package/src/internal/inputAxis.ts +0 -21
  111. package/src/internal/scalar.ts +0 -104
  112. package/src/internal/size2.ts +0 -54
  113. package/src/internal/vector2.ts +0 -121
package/src/Scalar.ts CHANGED
@@ -1,190 +1,68 @@
1
1
  /**
2
- * Validated scalar brands and pure scalar helpers.
2
+ * One-dimensional helpers on plain numbers, for values a system moves toward
3
+ * a target every step: a speed, a zoom, a meter.
3
4
  *
4
- * This module is the numeric foundation for the branded geometry helpers.
5
- * Plain `number` values enter through explicit constructors such as
6
- * {@link Finite} and {@link NonNegative}. Once validated, downstream helpers
7
- * operate only on branded values.
8
- *
9
- * In game code this is useful whenever "just a number" is too weak: viewport
10
- * sizes, speeds, distances, durations, and geometry values often need explicit
11
- * non-negative or finite guarantees before they should be stored in the world.
5
+ * Every function is total over finite numbers and returns a plain `number`.
6
+ * Clamping stays `Math.min(Math.max(value, min), max)`, which is exact on
7
+ * every engine. Angles have their own module, `Angle`, because they wrap;
8
+ * vectors use the matching `Vec2` helpers.
12
9
  *
13
10
  * @example
14
11
  * ```ts
15
- * // Validate raw numbers before geometry or gameplay code relies on them.
16
- * const speed = Scalar.Finite.result(12)
17
- * const min = Scalar.Finite.result(0)
18
- * const max = Scalar.Finite.result(8)
19
- * if (!speed.ok || !min.ok || !max.ok) return
20
- *
21
- * // Operate on the branded values after the boundary has been crossed.
22
- * const clamped = Scalar.clamp(speed.value, min.value, max.value)
12
+ * // Accelerate toward the top speed by at most `acceleration * dt` per step.
13
+ * const speed = Scalar.moveToward(current, topSpeed, acceleration * dt)
14
+ * // Ease a zoom toward its target the same way at any step rate.
15
+ * const zoom = Scalar.decayToward(view.zoom, target, 8, dt)
23
16
  * ```
24
17
  *
25
18
  * @module Scalar
26
- * @docGroup data-structures
27
- *
28
- * @categoryDescription Scalar Types
29
- * Branded numeric shapes and shared scalar validation errors.
30
- *
31
- * @categoryDescription Constructors
32
- * Non-throwing validation boundaries for finite and constrained scalar values.
19
+ * @docGroup helpers
33
20
  *
34
21
  * @categoryDescription Operations
35
- * Pure scalar combinators that preserve branding after validation.
36
- */
37
- import type * as Brand from "@typeonce/ritmo/Brand"
38
- import * as internal from "./internal/scalar.ts"
39
- import type { StandardSchema } from "@typeonce/ritmo/Descriptor"
40
- import type * as Result from "@typeonce/ritmo/Result"
41
-
42
- /**
43
- * Finite number brand.
44
- *
45
- * Values of this type are guaranteed not to be `NaN`, `Infinity`, or
46
- * `-Infinity` when they come from a constructor (`result`, `option`) or a `codec`. The
47
- * arithmetic helpers here and in `Vector2` keep the brand without
48
- * re-validating, so their results are finite only while they stay within
49
- * `±Number.MAX_VALUE`: game-sized values never come close, but validate
50
- * again with `result` when inputs may be that large.
51
- *
52
- * @category Scalar Types
53
- */
54
- export type Finite = Brand.Branded<number, "Scalar/Finite">
55
- /**
56
- * Finite number brand constrained to `>= 0`.
57
- *
58
- * @category Scalar Types
59
- */
60
- export type NonNegative = Brand.Branded<number, "Scalar/NonNegative">
61
- /**
62
- * Finite number brand constrained to `> 0`.
63
- *
64
- * @category Scalar Types
22
+ * Moving one number toward another.
65
23
  */
66
- export type Positive = Brand.Branded<number, "Scalar/Positive">
24
+ import * as Ops from "@typeonce/ritmo/Ops"
67
25
 
68
26
  /**
69
- * Structured scalar validation failures.
27
+ * Moves `current` toward `target` by at most `maxDelta`, never overshooting:
28
+ * `target` itself once the gap is `maxDelta` or less, and `current` unchanged
29
+ * when `maxDelta` is 0 or less. For a constant rate (acceleration, a meter
30
+ * filling); for an ease that slows near the target use {@link decayToward},
31
+ * for vectors `Vec2.moveToward`, for angles `Angle.turnToward`.
70
32
  *
71
- * @category Scalar Types
72
- */
73
- export type Error =
74
- | { readonly tag: "Scalar/NotFinite"; readonly value: number }
75
- | { readonly tag: "Scalar/Negative"; readonly value: number }
76
- | { readonly tag: "Scalar/NonPositive"; readonly value: number }
77
-
78
- /**
79
- * Structured interpolation failure.
80
- *
81
- * @category Scalar Types
82
- */
83
- export type InterpolationError = {
84
- readonly tag: "Scalar/ZeroRange"
85
- readonly start: number
86
- readonly end: number
87
- }
88
-
89
- /**
90
- * The constructors, guard, and schema of one scalar brand.
91
- *
92
- * @category Constructors
33
+ * @category Operations
93
34
  */
94
- export interface Constructor<Value> {
95
- /** Validates one number and returns an explicit success/failure result. */
96
- readonly result: (raw: number) => Result.Result<Value, Error>
97
- /** Validates one number and returns `null` on failure. */
98
- readonly option: (raw: number) => Value | null
99
- /** Whether any value is a number of this brand. */
100
- readonly is: (raw: unknown) => raw is Value
101
- /** The Standard Schema for `Descriptor.ConstructedComponent(...)`: the saved form is the number itself. */
102
- readonly codec: StandardSchema<number, Value>
35
+ export const moveToward = (current: number, target: number, maxDelta: number): number => {
36
+ if (!(maxDelta > 0)) return current
37
+ const gap = target - current
38
+ if (Math.abs(gap) <= maxDelta) return target
39
+ return gap > 0 ? current + maxDelta : current - maxDelta
103
40
  }
104
41
 
105
42
  /**
106
- * Constructor for {@link Finite}: `result` (explicit failure), `option`
107
- * (`null` on failure), `is` (a type guard), and `codec`, for
108
- * `Descriptor.ConstructedComponent(Scalar.Finite.codec)`.
109
- *
110
- * @category Constructors
111
- */
112
- export const Finite: Constructor<Finite> = internal.Finite
113
- /**
114
- * Constructor for {@link NonNegative}: `result` (explicit failure), `option`
115
- * (`null` on failure), `is` (a type guard), and `codec`, for
116
- * `Descriptor.ConstructedComponent(Scalar.NonNegative.codec)`.
117
- *
118
- * @category Constructors
119
- */
120
- export const NonNegative: Constructor<NonNegative> = internal.NonNegative
121
- /**
122
- * Constructor for {@link Positive}: `result` (explicit failure), `option`
123
- * (`null` on failure), `is` (a type guard), and `codec`, for
124
- * `Descriptor.ConstructedComponent(Scalar.Positive.codec)`.
125
- *
126
- * @category Constructors
127
- */
128
- export const Positive: Constructor<Positive> = internal.Positive
129
-
130
- /**
131
- * Clamps one finite value between two finite bounds.
132
- *
133
- * The result stays branded because valid branded scalar input cannot produce an
134
- * invalid scalar output.
43
+ * The number `amount` of the way from `start` (at 0) to `end` (at 1). The
44
+ * amount is not clamped, so 1.5 goes past `end`. For a fixed blend between
45
+ * two values; to approach a target over time use {@link moveToward} or
46
+ * {@link decayToward}, for vectors `Vec2.lerp`.
135
47
  *
136
48
  * @category Operations
137
49
  */
138
- export const clamp: (value: Finite, min: Finite, max: Finite) => Finite = internal.clamp
139
- /**
140
- * Interpolates between two finite values by one finite amount.
141
- *
142
- * The amount is not clamped. This stays a pure interpolation primitive rather
143
- * than mixing interpolation with policy. The result keeps the `Finite` brand
144
- * without re-validating (see `Finite`).
145
- *
146
- * @category Operations
147
- */
148
- export const lerp: (start: Finite, end: Finite, amount: Finite) => Finite = internal.lerp
149
- /**
150
- * Moves one finite value toward a target by at most one non-negative delta.
151
- *
152
- * Use this for explicit interpolation-style updates where overshooting the
153
- * target should be impossible.
154
- *
155
- * @category Operations
156
- */
157
- export const approach: (current: Finite, target: Finite, maxDelta: NonNegative) => Finite = internal.approach
158
- /**
159
- * Returns the interpolation amount of one value within a finite input range.
160
- *
161
- * Fails explicitly when the input range has zero size.
162
- *
163
- * @category Operations
164
- */
165
- export const inverseLerp: (
166
- start: Finite,
167
- end: Finite,
168
- value: Finite
169
- ) => Result.Result<Finite, InterpolationError> = internal.inverseLerp
170
- /**
171
- * Remaps one finite value from one input range to one output range.
172
- *
173
- * Fails explicitly when the input range has zero size.
174
- *
175
- * @category Operations
176
- */
177
- export const remap: (
178
- value: Finite,
179
- inputStart: Finite,
180
- inputEnd: Finite,
181
- outputStart: Finite,
182
- outputEnd: Finite
183
- ) => Result.Result<Finite, InterpolationError> = internal.remap
50
+ export const lerp = (start: number, end: number, amount: number): number => start + (end - start) * amount
184
51
 
185
52
  /**
186
- * Common result shape returned by the scalar constructors.
53
+ * Moves `current` toward `target` by the share `rate` closes per second,
54
+ * over `dt` seconds: `target + (current - target) * exp(-rate * dt)`. The
55
+ * same total time gives the same result at any step rate, which `lerp` by a
56
+ * fixed amount per step does not. `current` unchanged when `rate * dt` is 0
57
+ * or less, `target` itself when `rate` is `Infinity` (and `dt` positive).
58
+ * It nears `target` without reaching it; when it must arrive, use
59
+ * {@link moveToward}. For vectors use `Vec2.decayToward`.
187
60
  *
188
- * @category Scalar Types
61
+ * @category Operations
189
62
  */
190
- export type FiniteResult = Result.Result<Finite, Error>
63
+ export const decayToward = (current: number, target: number, rate: number, dt: number): number => {
64
+ const k = rate * dt
65
+ if (!(k > 0)) return current
66
+ if (k === Infinity) return target
67
+ return target + (current - target) * Ops.exp(-k)
68
+ }
@@ -0,0 +1,71 @@
1
+ /**
2
+ * Plain line segments stored by their ends, for hot-path collision against
3
+ * walls that are not axis-aligned (a map traced from survey data, a slanted
4
+ * fence, a polygon's edges).
5
+ *
6
+ * Like `Box2`, it is the plain form the collision helpers (`Collide2`) read
7
+ * every frame, built once from whatever the game stores. A wall is
8
+ * two-sided: a circle is kept off it on both sides and around both ends.
9
+ *
10
+ * @example
11
+ * ```ts
12
+ * const fence = Segment2.between({ x: 0, y: 0 }, { x: 40, y: 30 })
13
+ * const moved = Collide2.moveCircle(position, delta, radius, { segments: [fence] })
14
+ * ```
15
+ *
16
+ * @module Segment2
17
+ * @docGroup helpers
18
+ *
19
+ * @categoryDescription Segment Types
20
+ * The structural segment shape.
21
+ *
22
+ * @categoryDescription Operations
23
+ * Building segments and measuring them against points and circles.
24
+ */
25
+ import type { Vec2 } from "./Vec2.ts"
26
+
27
+ /**
28
+ * The segment from (`ax`, `ay`) to (`bx`, `by`). Both ends may be the same
29
+ * point, which is then a round post.
30
+ *
31
+ * @category Segment Types
32
+ */
33
+ export interface Segment2 {
34
+ readonly ax: number
35
+ readonly ay: number
36
+ readonly bx: number
37
+ readonly by: number
38
+ }
39
+
40
+ /**
41
+ * The segment from `a` to `b`.
42
+ *
43
+ * @category Operations
44
+ */
45
+ export const between = (a: Vec2, b: Vec2): Segment2 => ({ ax: a.x, ay: a.y, bx: b.x, by: b.y })
46
+
47
+ /**
48
+ * The point of the segment nearest to `point`.
49
+ *
50
+ * @category Operations
51
+ */
52
+ export const closestPoint = (segment: Segment2, point: Vec2): Vec2 => {
53
+ const ex = segment.bx - segment.ax
54
+ const ey = segment.by - segment.ay
55
+ const lengthSquared = ex * ex + ey * ey
56
+ if (lengthSquared < 1e-12) return { x: segment.ax, y: segment.ay }
57
+ const along = Math.max(0, Math.min(1, ((point.x - segment.ax) * ex + (point.y - segment.ay) * ey) / lengthSquared))
58
+ return { x: segment.ax + ex * along, y: segment.ay + ey * along }
59
+ }
60
+
61
+ /**
62
+ * Whether a circle overlaps (or touches) the segment.
63
+ *
64
+ * @category Operations
65
+ */
66
+ export const overlapsCircle = (segment: Segment2, center: Vec2, radius: number): boolean => {
67
+ const nearest = closestPoint(segment, center)
68
+ const dx = center.x - nearest.x
69
+ const dy = center.y - nearest.y
70
+ return dx * dx + dy * dy <= radius * radius
71
+ }
package/src/Vec2.ts CHANGED
@@ -1,11 +1,10 @@
1
1
  /**
2
2
  * Plain two-dimensional vector arithmetic for hot paths.
3
3
  *
4
- * `Vector2` validates values at a boundary (authored data, saves, components);
5
- * `Vec2` is the arithmetic that runs every frame on numbers already known to
6
- * be sane. Values are immutable `{ x, y }` records and every helper returns a
7
- * new one. A branded `Vector2` is a `Vec2`, so validated values flow into
8
- * these helpers without conversion.
4
+ * Values are immutable `{ x, y }` records and every helper returns a new
5
+ * one, so a component's value (validated once by the game's schema when it
6
+ * entered the world) passes straight in. Lengths and angles go through
7
+ * `Ops`, so the results replay the same on every engine.
9
8
  *
10
9
  * @example
11
10
  * ```ts
@@ -24,7 +23,7 @@
24
23
  * Immutable arithmetic, measurement, and steering helpers.
25
24
  */
26
25
 
27
- import * as Ops from "./Ops.ts"
26
+ import * as Ops from "@typeonce/ritmo/Ops"
28
27
 
29
28
  /**
30
29
  * A two-dimensional vector in world units.
@@ -65,7 +64,8 @@ export const subtract = (a: Vec2, b: Vec2): Vec2 => ({ x: a.x - b.x, y: a.y - b.
65
64
  export const scale = (a: Vec2, factor: number): Vec2 => ({ x: a.x * factor, y: a.y * factor })
66
65
 
67
66
  /**
68
- * `a` turned by `angle` radians (counter-clockwise for a y-up frame).
67
+ * `a` turned by `angle` radians (counter-clockwise for a y-up frame). For a
68
+ * quarter turn use {@link perpendicular}, which is exact.
69
69
  *
70
70
  * @category Operations
71
71
  */
@@ -76,12 +76,43 @@ export const rotate = (a: Vec2, angle: number): Vec2 => {
76
76
  }
77
77
 
78
78
  /**
79
- * Dot product.
79
+ * `a` turned a quarter turn counter-clockwise (for a y-up frame):
80
+ * `{ x: -a.y, y: a.x }`. Exact. For the normal of a wall or a direction, a
81
+ * sideways push, and the signed side of a point: `dot(perpendicular(forward),
82
+ * offset)` is positive on the left of `forward`, negative on its right.
83
+ *
84
+ * @category Operations
85
+ */
86
+ export const perpendicular = (a: Vec2): Vec2 => ({ x: -a.y, y: a.x })
87
+
88
+ /**
89
+ * Dot product. With {@link perpendicular} it is also the 2D cross product:
90
+ * `dot(perpendicular(a), b)`.
80
91
  *
81
92
  * @category Operations
82
93
  */
83
94
  export const dot = (a: Vec2, b: Vec2): number => a.x * b.x + a.y * b.y
84
95
 
96
+ /**
97
+ * The unit vector at `angle` radians from the x axis (counter-clockwise for a
98
+ * y-up frame), through `Ops.cos` and `Ops.sin`. Multiply by a length with
99
+ * {@link scale}. The inverse of {@link angle}.
100
+ *
101
+ * @category Operations
102
+ */
103
+ export const fromAngle = (angle: number): Vec2 => ({ x: Ops.cos(angle), y: Ops.sin(angle) })
104
+
105
+ /**
106
+ * The angle of `a` from the x axis in radians, in (-π, π], through
107
+ * `Ops.atan2` (so no `y, x` argument order to get wrong). The zero vector
108
+ * gives 0, and so does `-0` in either coordinate where `Ops.atan2` would give
109
+ * `-0` or flip to -π. To keep it in `Angle`'s range [-π, π), use
110
+ * `Angle.wrap`; to turn toward it, `Angle.turnToward`.
111
+ *
112
+ * @category Operations
113
+ */
114
+ export const angle = (a: Vec2): number => Ops.atan2(a.y + 0, a.x + 0)
115
+
85
116
  /**
86
117
  * Length of `a`.
87
118
  *
@@ -155,3 +186,22 @@ export const clampLength = (a: Vec2, max: number): Vec2 => {
155
186
  const len = Ops.hypot(a.x, a.y)
156
187
  return len <= max ? a : { x: (a.x / len) * max, y: (a.y / len) * max }
157
188
  }
189
+
190
+ /**
191
+ * Moves `current` toward `target` by the share `rate` closes per second, over
192
+ * `dt` seconds, with one shared factor `exp(-rate * dt)` so the point moves
193
+ * along the straight line: the same total time gives the same result at any
194
+ * step rate. `current` unchanged when `rate * dt` is 0 or less, `target`
195
+ * itself when `rate` is `Infinity` (and `dt` positive). It nears `target`
196
+ * without reaching it; when it must arrive, use {@link moveToward}. For
197
+ * plain numbers use `Scalar.decayToward`.
198
+ *
199
+ * @category Operations
200
+ */
201
+ export const decayToward = (current: Vec2, target: Vec2, rate: number, dt: number): Vec2 => {
202
+ const k = rate * dt
203
+ if (!(k > 0)) return current
204
+ if (k === Infinity) return target
205
+ const factor = Ops.exp(-k)
206
+ return { x: target.x + (current.x - target.x) * factor, y: target.y + (current.y - target.y) * factor }
207
+ }
package/src/index.ts CHANGED
@@ -1,29 +1,18 @@
1
1
  /**
2
- * Math for game code.
2
+ * The 2D helpers most games would otherwise rewrite, as plain data in and
3
+ * plain data out, built on `Ops` so they replay the same on every engine.
3
4
  *
4
- * Validated values (`Scalar`, `Vector2`, `Size2`, `Aabb`) expose
5
- * Result-returning constructors, a guard (`is`), and one `codec` each, so
6
- * they plug into `Descriptor.ConstructedComponent(Vector2.codec)` /
7
- * `ConstructedResource(Random.codec)` and are validated once at the boundary. `InputAxis` normalizes directional input.
8
- *
9
- * Hot-path helpers work on plain numbers every frame: `Vec2` arithmetic,
10
- * `Box2` edges, `Collide2` swept circle collision, a `SpatialGrid` broad
11
- * phase, a `FlowField` for finding the way around walls, and a deterministic
12
- * `Random` whose state is one integer.
13
- *
14
- * `Ops` holds the math functions engines are allowed to approximate (`sin`,
15
- * `cos`, `atan2`, `exp`, `pow`, `hypot`, ...) as ports that return the same
16
- * bits everywhere: use them in simulation code instead of `Math`'s.
5
+ * `Vec2` arithmetic and angles of vectors, `Angle` for headings, `Scalar` for
6
+ * numbers moving toward a target, `Box2` edge boxes and `Segment2` walls at
7
+ * any angle, `Collide2` swept circle collision against both that slides
8
+ * along walls and never tunnels, and a `FlowField` that leads bodies around
9
+ * walls. Values are validated by the game's own schema when they enter the
10
+ * world; `Ops` and `Random` are in `@typeonce/ritmo`.
17
11
  */
18
- export * as Aabb from "./Aabb.ts"
12
+ export * as Angle from "./Angle.ts"
19
13
  export * as Box2 from "./Box2.ts"
20
14
  export * as Collide2 from "./Collide2.ts"
21
15
  export * as FlowField from "./FlowField.ts"
22
- export * as InputAxis from "./InputAxis.ts"
23
- export * as Ops from "./Ops.ts"
24
- export * as Random from "./Random.ts"
25
16
  export * as Scalar from "./Scalar.ts"
26
- export * as Size2 from "./Size2.ts"
27
- export * as SpatialGrid from "./SpatialGrid.ts"
17
+ export * as Segment2 from "./Segment2.ts"
28
18
  export * as Vec2 from "./Vec2.ts"
29
- export * as Vector2 from "./Vector2.ts"
package/dist/Aabb.d.ts DELETED
@@ -1,182 +0,0 @@
1
- /**
2
- * Branded axis-aligned bounding boxes built from validated vectors and sizes.
3
- *
4
- * The public shape is centered: each AABB is described by a center position and
5
- * a non-negative size. Geometry helpers derive edges and overlap relationships
6
- * without mutating the original value.
7
- *
8
- * In game code this is the natural helper for collision volumes, trigger
9
- * regions, camera bounds, and spatial authored data that should stay validated
10
- * and immutable after construction. For the per-frame collision tests of
11
- * `Collide2` and `FlowField`, build a plain `Box2` (edge form) from it once.
12
- *
13
- * @example
14
- * ```ts
15
- * // Build a collision volume from raw authored data.
16
- * const player = Aabb.result({
17
- * position: { x: 0, y: 0 },
18
- * size: { width: 16, height: 16 }
19
- * })
20
- * ```
21
- *
22
- * @module Aabb
23
- * @docGroup data-structures
24
- *
25
- * @categoryDescription AABB Types
26
- * Raw, branded, and error shapes for centered axis-aligned bounding boxes.
27
- *
28
- * @categoryDescription Construction
29
- * Non-throwing constructor boundaries for converting raw position and size input into branded AABBs.
30
- *
31
- * @categoryDescription Accessors
32
- * Pure readers that expose center, size, and derived edge positions.
33
- *
34
- * @categoryDescription Operations
35
- * Immutable geometry helpers for translation and overlap checks.
36
- */
37
- import type * as Brand from "@typeonce/ritmo/Brand";
38
- import type { StandardSchema } from "@typeonce/ritmo/Descriptor";
39
- import type * as Result from "@typeonce/ritmo/Result";
40
- import type * as Scalar from "./Scalar.ts";
41
- import type * as Size2 from "./Size2.ts";
42
- import type * as Vector2 from "./Vector2.ts";
43
- /**
44
- * Raw AABB input accepted by the public constructors.
45
- *
46
- * @category AABB Types
47
- */
48
- export type Raw = {
49
- readonly position: Vector2.Raw;
50
- readonly size: Size2.Raw;
51
- };
52
- /**
53
- * Validated centered axis-aligned bounding box.
54
- *
55
- * @category AABB Types
56
- */
57
- export type Aabb = Brand.Branded<{
58
- readonly position: Vector2.Vector2;
59
- readonly size: Size2.Size2;
60
- }, "Aabb">;
61
- /**
62
- * Structured AABB-construction failure.
63
- *
64
- * @category AABB Types
65
- */
66
- export type Error = {
67
- readonly tag: "Aabb/InvalidPosition";
68
- readonly error: Vector2.Error;
69
- readonly input: Raw;
70
- } | {
71
- readonly tag: "Aabb/InvalidSize";
72
- readonly error: Size2.Error;
73
- readonly input: Raw;
74
- };
75
- /**
76
- * Validates one raw AABB and returns an explicit result.
77
- *
78
- * @example
79
- * ```ts
80
- * const playerBox = Aabb.result({
81
- * position: { x: 24, y: 24 },
82
- * size: { width: 16, height: 16 }
83
- * })
84
- * ```
85
- *
86
- * @category Construction
87
- */
88
- export declare const result: (raw: Raw) => Result.Result<Aabb, Error>;
89
- /**
90
- * The codec of `Aabb` (a Standard Schema, see `Descriptor.Codec`): give it to
91
- * `Descriptor.ConstructedComponent(...)` so raw input and saves are validated.
92
- * Its saved form is the raw shape, so it needs no `encode`. To put a `Aabb`
93
- * inside your own object schema, use {@link is} with your library's guard
94
- * schema (`Schema.declare`, `z.custom`).
95
- *
96
- * @example
97
- * ```ts
98
- * const Position = Descriptor.ConstructedComponent(Aabb.codec)("Game/Position")
99
- * ```
100
- *
101
- * @category Construction
102
- */
103
- export declare const codec: StandardSchema<Raw, Aabb>;
104
- /**
105
- * Validates one raw AABB and returns `null` on failure.
106
- *
107
- * @category Construction
108
- */
109
- export declare const option: (raw: Raw) => Aabb | null;
110
- /**
111
- * Whether any value is a valid `Aabb`: a guard, also for building a
112
- * `Aabb` field in your own schema (`Schema.declare(Aabb.is)`).
113
- *
114
- * @category Construction
115
- */
116
- export declare const is: (raw: unknown) => raw is Aabb;
117
- /**
118
- * Reads the center position of one AABB.
119
- *
120
- * @category Accessors
121
- */
122
- export declare const position: (aabb: Aabb) => Vector2.Vector2;
123
- /**
124
- * Reads the size of one AABB.
125
- *
126
- * @category Accessors
127
- */
128
- export declare const size: (aabb: Aabb) => Size2.Size2;
129
- /**
130
- * Returns the left edge of one centered AABB.
131
- *
132
- * @category Accessors
133
- */
134
- export declare const left: (aabb: Aabb) => Scalar.Finite;
135
- /**
136
- * Returns the right edge of one centered AABB.
137
- *
138
- * @category Accessors
139
- */
140
- export declare const right: (aabb: Aabb) => Scalar.Finite;
141
- /**
142
- * Returns the top edge of one centered AABB.
143
- *
144
- * @category Accessors
145
- */
146
- export declare const top: (aabb: Aabb) => Scalar.Finite;
147
- /**
148
- * Returns the bottom edge of one centered AABB.
149
- *
150
- * @category Accessors
151
- */
152
- export declare const bottom: (aabb: Aabb) => Scalar.Finite;
153
- /**
154
- * Checks whether two AABBs overlap on both axes.
155
- *
156
- * @example
157
- * ```ts
158
- * const overlaps = Aabb.intersects(playerBox, wallBox)
159
- * ```
160
- *
161
- * @category Operations
162
- */
163
- export declare const intersects: (first: Aabb, second: Aabb) => boolean;
164
- /**
165
- * Checks whether two AABBs overlap on the horizontal axis.
166
- *
167
- * @category Operations
168
- */
169
- export declare const overlapsHorizontally: (first: Aabb, second: Aabb) => boolean;
170
- /**
171
- * Checks whether two AABBs overlap on the vertical axis.
172
- *
173
- * @category Operations
174
- */
175
- export declare const overlapsVertically: (first: Aabb, second: Aabb) => boolean;
176
- /**
177
- * Returns a translated copy of one AABB.
178
- *
179
- * @category Operations
180
- */
181
- export declare const translate: (aabb: Aabb, delta: Vector2.Vector2) => Aabb;
182
- //# sourceMappingURL=Aabb.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"Aabb.d.ts","sourceRoot":"","sources":["../src/Aabb.ts"],"names":[],"mappings":"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"}