@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.
- package/CHANGELOG.md +149 -0
- package/README.md +18 -13
- package/dist/Angle.d.ts +44 -0
- package/dist/Angle.d.ts.map +1 -0
- package/dist/Angle.js +62 -0
- package/dist/Angle.js.map +1 -0
- package/dist/Box2.d.ts +16 -4
- package/dist/Box2.d.ts.map +1 -1
- package/dist/Box2.js +16 -1
- package/dist/Box2.js.map +1 -1
- package/dist/Collide2.d.ts +59 -15
- package/dist/Collide2.d.ts.map +1 -1
- package/dist/Collide2.js +156 -18
- package/dist/Collide2.js.map +1 -1
- package/dist/FlowField.d.ts +24 -38
- package/dist/FlowField.d.ts.map +1 -1
- package/dist/FlowField.js +18 -5
- package/dist/FlowField.js.map +1 -1
- package/dist/Scalar.d.ts +19 -166
- package/dist/Scalar.d.ts.map +1 -1
- package/dist/Scalar.js +51 -51
- package/dist/Scalar.js.map +1 -1
- package/dist/Segment2.d.ts +56 -0
- package/dist/Segment2.d.ts.map +1 -0
- package/dist/Segment2.js +32 -0
- package/dist/Segment2.js.map +1 -0
- package/dist/Vec2.d.ts +47 -7
- package/dist/Vec2.d.ts.map +1 -1
- package/dist/Vec2.js +56 -8
- package/dist/Vec2.js.map +1 -1
- package/dist/index.d.ts +10 -21
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +10 -21
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
- package/src/Angle.ts +60 -0
- package/src/Box2.ts +20 -4
- package/src/Collide2.ts +171 -24
- package/src/FlowField.ts +34 -10
- package/src/Scalar.ts +43 -165
- package/src/Segment2.ts +71 -0
- package/src/Vec2.ts +58 -8
- package/src/index.ts +10 -21
- package/dist/Aabb.d.ts +0 -182
- package/dist/Aabb.d.ts.map +0 -1
- package/dist/Aabb.js +0 -109
- package/dist/Aabb.js.map +0 -1
- package/dist/InputAxis.d.ts +0 -44
- package/dist/InputAxis.d.ts.map +0 -1
- package/dist/InputAxis.js +0 -71
- package/dist/InputAxis.js.map +0 -1
- package/dist/Ops.d.ts +0 -209
- package/dist/Ops.d.ts.map +0 -1
- package/dist/Ops.js +0 -210
- package/dist/Ops.js.map +0 -1
- package/dist/Random.d.ts +0 -124
- package/dist/Random.d.ts.map +0 -1
- package/dist/Random.js +0 -126
- package/dist/Random.js.map +0 -1
- package/dist/Size2.d.ts +0 -118
- package/dist/Size2.d.ts.map +0 -1
- package/dist/Size2.js +0 -54
- package/dist/Size2.js.map +0 -1
- package/dist/SpatialGrid.d.ts +0 -68
- package/dist/SpatialGrid.d.ts.map +0 -1
- package/dist/SpatialGrid.js +0 -112
- package/dist/SpatialGrid.js.map +0 -1
- package/dist/Vector2.d.ts +0 -214
- package/dist/Vector2.d.ts.map +0 -1
- package/dist/Vector2.js +0 -134
- package/dist/Vector2.js.map +0 -1
- package/dist/internal/aabb.d.ts +0 -27
- package/dist/internal/aabb.d.ts.map +0 -1
- package/dist/internal/aabb.js +0 -52
- package/dist/internal/aabb.js.map +0 -1
- package/dist/internal/codec.d.ts +0 -9
- package/dist/internal/codec.d.ts.map +0 -1
- package/dist/internal/codec.js +0 -16
- package/dist/internal/codec.js.map +0 -1
- package/dist/internal/fdlibm.d.ts +0 -43
- package/dist/internal/fdlibm.d.ts.map +0 -1
- package/dist/internal/fdlibm.js +0 -1291
- package/dist/internal/fdlibm.js.map +0 -1
- package/dist/internal/inputAxis.d.ts +0 -11
- package/dist/internal/inputAxis.d.ts.map +0 -1
- package/dist/internal/inputAxis.js +0 -13
- package/dist/internal/inputAxis.js.map +0 -1
- package/dist/internal/scalar.d.ts +0 -11
- package/dist/internal/scalar.d.ts.map +0 -1
- package/dist/internal/scalar.js +0 -68
- package/dist/internal/scalar.js.map +0 -1
- package/dist/internal/size2.d.ts +0 -22
- package/dist/internal/size2.d.ts.map +0 -1
- package/dist/internal/size2.js +0 -38
- package/dist/internal/size2.js.map +0 -1
- package/dist/internal/vector2.d.ts +0 -39
- package/dist/internal/vector2.d.ts.map +0 -1
- package/dist/internal/vector2.js +0 -78
- package/dist/internal/vector2.js.map +0 -1
- package/src/Aabb.ts +0 -180
- package/src/InputAxis.ts +0 -81
- package/src/Ops.ts +0 -232
- package/src/Random.ts +0 -225
- package/src/Size2.ts +0 -122
- package/src/SpatialGrid.ts +0 -172
- package/src/Vector2.ts +0 -216
- package/src/internal/aabb.ts +0 -81
- package/src/internal/codec.ts +0 -21
- package/src/internal/fdlibm.ts +0 -1256
- package/src/internal/inputAxis.ts +0 -21
- package/src/internal/scalar.ts +0 -104
- package/src/internal/size2.ts +0 -54
- package/src/internal/vector2.ts +0 -121
package/src/Scalar.ts
CHANGED
|
@@ -1,190 +1,68 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
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
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
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
|
-
* //
|
|
16
|
-
* const speed = Scalar.
|
|
17
|
-
*
|
|
18
|
-
* const
|
|
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
|
|
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
|
-
*
|
|
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
|
-
|
|
24
|
+
import * as Ops from "@typeonce/ritmo/Ops"
|
|
67
25
|
|
|
68
26
|
/**
|
|
69
|
-
*
|
|
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
|
|
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
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
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
|
-
*
|
|
107
|
-
*
|
|
108
|
-
*
|
|
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
|
|
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
|
-
*
|
|
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
|
|
61
|
+
* @category Operations
|
|
189
62
|
*/
|
|
190
|
-
export
|
|
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
|
+
}
|
package/src/Segment2.ts
ADDED
|
@@ -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
|
-
* `
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
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 "
|
|
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
|
-
*
|
|
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
|
-
*
|
|
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
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
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
|
|
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
|
|
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
|
package/dist/Aabb.d.ts.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"Aabb.d.ts","sourceRoot":"","sources":["../src/Aabb.ts"],"names":[],"mappings":"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"}
|