aether-physics 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +79 -3
- package/dist/index.js +56 -0
- package/dist/math-DrI-pge3.js +502 -0
- package/dist/math.js +1 -0
- package/dist/types/engine/loop.d.ts +37 -0
- package/dist/types/index.d.ts +4 -0
- package/dist/types/math/geometry/mat3x3.d.ts +270 -0
- package/dist/types/math/geometry/mat3x4.d.ts +338 -0
- package/dist/types/math/geometry/quaternion.d.ts +377 -0
- package/dist/types/math/geometry/vec3.d.ts +171 -0
- package/dist/types/math/index.d.ts +6 -0
- package/dist/types/math/scalar.d.ts +3 -0
- package/dist/types/math/types.d.ts +15 -0
- package/package.json +48 -6
|
@@ -0,0 +1,377 @@
|
|
|
1
|
+
import type { QuatLike, Vec3Like } from "../types.js";
|
|
2
|
+
import type { Mat3x3 } from "./mat3x3.js";
|
|
3
|
+
import { Vec3 } from "./vec3.js";
|
|
4
|
+
/**
|
|
5
|
+
* A quaternion `[w, (x, y, z)]`, used to represent orientations and rotations.
|
|
6
|
+
*
|
|
7
|
+
* A rotation of angle `θ` about unit axis `n` is stored as `[cos(θ/2), sin(θ/2)·n]`, which
|
|
8
|
+
* has magnitude 1. `q` and `−q` represent the same rotation.
|
|
9
|
+
*
|
|
10
|
+
* Conventions:
|
|
11
|
+
*
|
|
12
|
+
* - **Component order.** The constructor takes `w` first, matching the `[w, v]` notation.
|
|
13
|
+
* This differs from `THREE.Quaternion`, which takes `(x, y, z, w)`.
|
|
14
|
+
* - **Plain public fields.** `w`, `x`, `y` and `z` are ordinary properties, not getters, so V8
|
|
15
|
+
* can optimize access in hot loops.
|
|
16
|
+
* - **Mutation.** Methods that modify this quaternion do it in place and return `this` for
|
|
17
|
+
* chaining. Use `clone()` first when you need to keep the original.
|
|
18
|
+
* - **Inputs.** Arguments are any `QuatLike` or `Vec3Like`, including `THREE.Quaternion`, and
|
|
19
|
+
* are never modified. An argument may be `this`: every method reads its inputs before
|
|
20
|
+
* writing.
|
|
21
|
+
*/
|
|
22
|
+
export declare class Quaternion implements QuatLike {
|
|
23
|
+
w: number;
|
|
24
|
+
x: number;
|
|
25
|
+
y: number;
|
|
26
|
+
z: number;
|
|
27
|
+
/**
|
|
28
|
+
* Creates a quaternion from its components. Defaults to the identity `[1, 0]`.
|
|
29
|
+
*
|
|
30
|
+
* @param w Scalar part.
|
|
31
|
+
* @param x X component of the vector part.
|
|
32
|
+
* @param y Y component of the vector part.
|
|
33
|
+
* @param z Z component of the vector part.
|
|
34
|
+
*/
|
|
35
|
+
constructor(w?: number, x?: number, y?: number, z?: number);
|
|
36
|
+
/**
|
|
37
|
+
* Sets this quaternion to the identity `[1, 0]`, the rotation that changes nothing.
|
|
38
|
+
*
|
|
39
|
+
* `[−1, 0]` also represents no rotation, but only `[1, 0]` leaves a quaternion
|
|
40
|
+
* unchanged when multiplied by it.
|
|
41
|
+
*/
|
|
42
|
+
identity(): this;
|
|
43
|
+
/**
|
|
44
|
+
* Sets all four components.
|
|
45
|
+
*
|
|
46
|
+
* @param w Scalar part.
|
|
47
|
+
* @param x X component of the vector part.
|
|
48
|
+
* @param y Y component of the vector part.
|
|
49
|
+
* @param z Z component of the vector part.
|
|
50
|
+
*/
|
|
51
|
+
set(w: number, x: number, y: number, z: number): this;
|
|
52
|
+
/**
|
|
53
|
+
* Returns true if every component is within `epsilon` of `q`'s, using `approxEqual`.
|
|
54
|
+
*
|
|
55
|
+
* Compares components, not rotations: `q` and `−q` are the same rotation but are not equal
|
|
56
|
+
* here.
|
|
57
|
+
*
|
|
58
|
+
* @param q Quaternion to compare against.
|
|
59
|
+
* @param epsilon Tolerance. Defaults to `EPSILON`.
|
|
60
|
+
*/
|
|
61
|
+
equals(q: QuatLike, epsilon?: number): boolean;
|
|
62
|
+
/**
|
|
63
|
+
* Returns true if this quaternion and `q` represent the same rotation: if every component
|
|
64
|
+
* is within `epsilon` of `q`'s, or of `−q`'s.
|
|
65
|
+
*
|
|
66
|
+
* The sign compared against is chosen from the dot product, so this costs about the same
|
|
67
|
+
* as `equals`. Comparing components keeps the tolerance meaningful for small angles,
|
|
68
|
+
* where `|dot| ≈ 1` alone is insensitive (it deviates from 1 only by about `φ²/8`).
|
|
69
|
+
*
|
|
70
|
+
* @param q Quaternion to compare against.
|
|
71
|
+
* @param epsilon Tolerance. Defaults to `EPSILON`.
|
|
72
|
+
*/
|
|
73
|
+
equalsRotation(q: QuatLike, epsilon?: number): boolean;
|
|
74
|
+
/**
|
|
75
|
+
* Copies the components of `q` into this quaternion.
|
|
76
|
+
*
|
|
77
|
+
* @param q Source quaternion.
|
|
78
|
+
*/
|
|
79
|
+
copy(q: QuatLike): this;
|
|
80
|
+
/**
|
|
81
|
+
* Returns a new quaternion with the same components as this one.
|
|
82
|
+
*/
|
|
83
|
+
clone(): Quaternion;
|
|
84
|
+
/**
|
|
85
|
+
* Returns the squared magnitude of this quaternion, `w² + x² + y² + z²`.
|
|
86
|
+
*
|
|
87
|
+
* Prefer this over `magnitude` when checking whether the quaternion is still unit length,
|
|
88
|
+
* since it avoids the square root.
|
|
89
|
+
*/
|
|
90
|
+
magnitudeSquared(): number;
|
|
91
|
+
/**
|
|
92
|
+
* Returns the magnitude of this quaternion, `√(w² + x² + y² + z²)`.
|
|
93
|
+
*
|
|
94
|
+
* Rotation quaternions have magnitude 1, but floating-point error makes it drift.
|
|
95
|
+
*/
|
|
96
|
+
magnitude(): number;
|
|
97
|
+
/**
|
|
98
|
+
* Scales this quaternion to unit length so it represents a pure rotation.
|
|
99
|
+
*
|
|
100
|
+
* Call it after integrating orientation, after long chains of multiplications, and
|
|
101
|
+
* after linear interpolation, since each one moves the length away from 1.
|
|
102
|
+
*
|
|
103
|
+
* A zero quaternion represents no rotation, so it becomes the identity instead of NaN.
|
|
104
|
+
*/
|
|
105
|
+
normalize(): this;
|
|
106
|
+
/**
|
|
107
|
+
* Multiplies every component by the scalar `k`: `this = k · this`.
|
|
108
|
+
*
|
|
109
|
+
* Scaling by a non-zero `k` does not change the rotation once normalized, so this is
|
|
110
|
+
* mainly useful as a building block, e.g. for interpolation.
|
|
111
|
+
*
|
|
112
|
+
* @param k Scale factor.
|
|
113
|
+
*/
|
|
114
|
+
scale(k: number): this;
|
|
115
|
+
/**
|
|
116
|
+
* Returns the 4D dot product `w·qw + x·qx + y·qy + z·qz`.
|
|
117
|
+
*
|
|
118
|
+
* For unit quaternions it is `cos(φ/2)`, where `φ` is the angle of the rotation between
|
|
119
|
+
* them. Its sign tells you whether `q` or `−q` is the shorter path, and `|dot| ≈ 1` means
|
|
120
|
+
* they are the same rotation.
|
|
121
|
+
*
|
|
122
|
+
* @param q The other quaternion.
|
|
123
|
+
*/
|
|
124
|
+
dot(q: QuatLike): number;
|
|
125
|
+
/**
|
|
126
|
+
* Negates the vector part: `this = [w, −v]`.
|
|
127
|
+
*
|
|
128
|
+
* For a unit quaternion the conjugate is the inverse: the same rotation in the opposite
|
|
129
|
+
* direction. It is cheaper than `inverse()`, so prefer it for rotations.
|
|
130
|
+
*/
|
|
131
|
+
conjugate(): this;
|
|
132
|
+
/**
|
|
133
|
+
* Sets this quaternion to its multiplicative inverse, `q⁻¹ = q* / |q|²`, so that
|
|
134
|
+
* `q · q⁻¹ = q⁻¹ · q = [1, 0]`.
|
|
135
|
+
*
|
|
136
|
+
* Works for any non-zero quaternion. For unit quaternions it equals `conjugate()`, which
|
|
137
|
+
* is cheaper.
|
|
138
|
+
*
|
|
139
|
+
* The zero quaternion has no inverse, so it stays zero instead of becoming NaN, matching
|
|
140
|
+
* how singular matrices invert to zero.
|
|
141
|
+
*/
|
|
142
|
+
inverse(): this;
|
|
143
|
+
/**
|
|
144
|
+
* Sets this quaternion to its natural logarithm:
|
|
145
|
+
* `log [w, v] = [ln |q|, (v / |v|) · atan2(|v|, w)]`.
|
|
146
|
+
*
|
|
147
|
+
* For a unit quaternion `[cos(θ/2), sin(θ/2)·n]` this is `[0, (θ/2)·n]`: half the rotation
|
|
148
|
+
* vector. That makes it the way to measure or scale a rotation, e.g.
|
|
149
|
+
* `exp(t · log(q))` is `q` raised to the power `t`. The angle `θ/2` is in `[0, π]`, so `q`
|
|
150
|
+
* and `−q` give different logarithms.
|
|
151
|
+
*
|
|
152
|
+
* Edge cases:
|
|
153
|
+
*
|
|
154
|
+
* - With no vector part and `w > 0` (the identity, up to scale), the vector part is zero.
|
|
155
|
+
* - With no vector part and `w < 0` (`[−1, 0]`, up to scale), any axis is valid. `+X` is
|
|
156
|
+
* used, giving `[ln |w|, (π, 0, 0)]`, so `exp` still recovers the original.
|
|
157
|
+
* - The zero quaternion has no logarithm: `w` becomes `−∞` and the vector part zero.
|
|
158
|
+
*
|
|
159
|
+
* Inverse of `exp`.
|
|
160
|
+
*/
|
|
161
|
+
log(): this;
|
|
162
|
+
/**
|
|
163
|
+
* Sets this quaternion to its exponential:
|
|
164
|
+
* `exp [w, v] = e^w · [cos |v|, (v / |v|) · sin |v|]`.
|
|
165
|
+
*
|
|
166
|
+
* With `w = 0` the result is a unit quaternion: `exp [0, (θ/2)·n]` is the rotation of
|
|
167
|
+
* angle `θ` about unit axis `n`. So `exp` turns half a rotation vector into a rotation,
|
|
168
|
+
* e.g. integrating angular velocity exactly with `exp [0, ½·ω·dt] · q`.
|
|
169
|
+
*
|
|
170
|
+
* Inverse of `log`.
|
|
171
|
+
*/
|
|
172
|
+
exp(): this;
|
|
173
|
+
/**
|
|
174
|
+
* Post-multiplies this quaternion by `q`: `this = this · q`.
|
|
175
|
+
*
|
|
176
|
+
* The result applies `q` first, then this.
|
|
177
|
+
*
|
|
178
|
+
* @param q Right-hand operand. May be `this`.
|
|
179
|
+
*/
|
|
180
|
+
multiply(q: QuatLike): this;
|
|
181
|
+
/**
|
|
182
|
+
* Pre-multiplies this quaternion by `q`: `this = q · this`.
|
|
183
|
+
*
|
|
184
|
+
* The result applies this first, then `q`.
|
|
185
|
+
*
|
|
186
|
+
* @param q Left-hand operand. May be `this`.
|
|
187
|
+
*/
|
|
188
|
+
premultiply(q: QuatLike): this;
|
|
189
|
+
/**
|
|
190
|
+
* Sets this quaternion to the Hamilton product `a · b`:
|
|
191
|
+
* `[a.w·b.w − a.v·b.v, a.w·b.v + b.w·a.v + a.v × b.v]`.
|
|
192
|
+
*
|
|
193
|
+
* @param a Left-hand operand. May be `this`.
|
|
194
|
+
* @param b Right-hand operand. May be `this`.
|
|
195
|
+
*/
|
|
196
|
+
multiplyQuaternions(a: QuatLike, b: QuatLike): this;
|
|
197
|
+
/**
|
|
198
|
+
* Sets this quaternion to the rotation of `angle` radians about `axis`:
|
|
199
|
+
* `[cos(angle/2), sin(angle/2)·n]`, where `n` is `axis` normalized.
|
|
200
|
+
*
|
|
201
|
+
* Positive angles rotate counter-clockwise when looking down the axis toward the origin
|
|
202
|
+
* (right-hand rule). `axis` need not be unit length and is not modified. A zero axis has
|
|
203
|
+
* no direction, so the result is the identity.
|
|
204
|
+
*
|
|
205
|
+
* @param axis Rotation axis, any non-zero length.
|
|
206
|
+
* @param angle Rotation angle in radians.
|
|
207
|
+
*/
|
|
208
|
+
setFromAxisAngle(axis: Vec3Like, angle: number): this;
|
|
209
|
+
/**
|
|
210
|
+
* Sets this quaternion to the rotation that takes `q` to this one: `this = q⁻¹ · this`,
|
|
211
|
+
* so that `q · (q⁻¹ · this)` is the original `this`.
|
|
212
|
+
*
|
|
213
|
+
* The difference is applied first, then `q`, so it is expressed in `q`'s local frame:
|
|
214
|
+
* for orientations, it is the rotation from `q` to this as seen by a body oriented by `q`.
|
|
215
|
+
*
|
|
216
|
+
* `q` is not modified. Uses the full inverse, so `q` need not be unit length; a zero `q`
|
|
217
|
+
* makes the result zero, as with `inverse()`.
|
|
218
|
+
*
|
|
219
|
+
* @param q The starting orientation. May be `this`.
|
|
220
|
+
*/
|
|
221
|
+
setToDifferenceQuaternion(q: QuatLike): this;
|
|
222
|
+
/**
|
|
223
|
+
* Rotates `v` by this quaternion and writes the result to `out`: the vector part of
|
|
224
|
+
* `q · [0, v] · q*`.
|
|
225
|
+
*
|
|
226
|
+
* Uses the expanded form `t = 2(u × v)`, `v' = v + w·t + u × t`, where `u` is the vector
|
|
227
|
+
* part, instead of two full products. The expansion relies on `w² + |u|² = 1`, so this
|
|
228
|
+
* quaternion must be unit length; it is not normalized here.
|
|
229
|
+
*
|
|
230
|
+
* For orientations, this takes a direction from body space to world space.
|
|
231
|
+
*
|
|
232
|
+
* @param v Vector to rotate.
|
|
233
|
+
* @param out Destination. Allocated if omitted. May be `v`.
|
|
234
|
+
*/
|
|
235
|
+
rotateVec3(v: Vec3Like, out?: Vec3): Vec3;
|
|
236
|
+
/**
|
|
237
|
+
* Rotates `v` by the inverse of this quaternion and writes the result to `out`: the
|
|
238
|
+
* vector part of `q* · [0, v] · q`.
|
|
239
|
+
*
|
|
240
|
+
* Same as `rotateVec3` with the vector part negated, so this quaternion is not modified.
|
|
241
|
+
* Assumes it is unit length, where the conjugate is the inverse.
|
|
242
|
+
*
|
|
243
|
+
* For orientations, this takes a direction from world space to body space.
|
|
244
|
+
*
|
|
245
|
+
* @param v Vector to rotate.
|
|
246
|
+
* @param out Destination. Allocated if omitted. May be `v`.
|
|
247
|
+
*/
|
|
248
|
+
inverseRotateVec3(v: Vec3Like, out?: Vec3): Vec3;
|
|
249
|
+
/**
|
|
250
|
+
* Spherically interpolates from this quaternion toward `q`: `this = slerp(this, q, t)`.
|
|
251
|
+
*
|
|
252
|
+
* See `slerpQuaternions` for the details and edge cases.
|
|
253
|
+
*
|
|
254
|
+
* @param q Target rotation, unit length. May be `this`.
|
|
255
|
+
* @param t Interpolation parameter. `0` gives this, `1` gives `q` (possibly as `−q`).
|
|
256
|
+
*/
|
|
257
|
+
slerp(q: QuatLike, t: number): this;
|
|
258
|
+
/**
|
|
259
|
+
* Sets this quaternion to the spherical linear interpolation from `a` to `b` at `t`: the
|
|
260
|
+
* rotation a fraction `t` of the way along the shortest arc between them, turning at
|
|
261
|
+
* constant angular speed.
|
|
262
|
+
*
|
|
263
|
+
* With `θ` the 4D angle between them (half the rotation angle from `a` to `b`), the
|
|
264
|
+
* result is `a · sin((1 − t)θ) / sin θ + b · sin(tθ) / sin θ`.
|
|
265
|
+
*
|
|
266
|
+
* Edge cases:
|
|
267
|
+
*
|
|
268
|
+
* - `a` and `b` must be unit length; the result then is too.
|
|
269
|
+
* - If `a · b < 0`, `−b` is used instead. It is the same rotation, and the shorter path,
|
|
270
|
+
* so the result at `t = 1` may be `−b`. `b` itself is not modified.
|
|
271
|
+
* - When `a` and `b` are nearly equal, `sin θ ≈ 0`, so this falls back to linear
|
|
272
|
+
* interpolation followed by `normalize()`. The two agree closely at such small angles.
|
|
273
|
+
* - `t` outside `[0, 1]` extrapolates along the same arc.
|
|
274
|
+
*
|
|
275
|
+
* @param a Start rotation, returned at `t = 0`. May be `this`.
|
|
276
|
+
* @param b End rotation, returned at `t = 1`. May be `this`.
|
|
277
|
+
* @param t Interpolation parameter, usually in `[0, 1]`.
|
|
278
|
+
*/
|
|
279
|
+
slerpQuaternions(a: QuatLike, b: QuatLike, t: number): this;
|
|
280
|
+
/**
|
|
281
|
+
* Advances this orientation by angular velocity `omega` over `dt` seconds:
|
|
282
|
+
* `q += ½·dt·[0, ω]·q`.
|
|
283
|
+
*
|
|
284
|
+
* This is a first-order step of `q̇ = ½·ω·q`, with `ω` in world space. It does not
|
|
285
|
+
* normalize, and each step moves the length slightly away from 1, so call `normalize()`
|
|
286
|
+
* afterwards (a rigid body does this when it recomputes its derived data). For an exact
|
|
287
|
+
* step, use `exp [0, ½·ω·dt] · q` instead.
|
|
288
|
+
*
|
|
289
|
+
* @param omega Angular velocity in world space, in radians per second.
|
|
290
|
+
* @param dt Time step in seconds.
|
|
291
|
+
*/
|
|
292
|
+
addScaledAngularVelocity(omega: Vec3Like, dt: number): this;
|
|
293
|
+
/**
|
|
294
|
+
* Sets this quaternion from the rotation matrix `m`, so that `rotateVec3(v)` equals
|
|
295
|
+
* `m.transformVec3(v)`.
|
|
296
|
+
*
|
|
297
|
+
* Uses Shepperd's method: it branches on the largest of the trace and the diagonal
|
|
298
|
+
* elements, so the square root is always of a value of at least 1 and the division is
|
|
299
|
+
* well conditioned. The sign of the result is not canonical; `q` and `−q` are the same
|
|
300
|
+
* rotation.
|
|
301
|
+
*
|
|
302
|
+
* `m` must be a pure rotation (orthonormal, determinant 1). Scale, shear or reflection
|
|
303
|
+
* give a meaningless result.
|
|
304
|
+
*
|
|
305
|
+
* @param m Rotation matrix.
|
|
306
|
+
*/
|
|
307
|
+
setFromRotationMatrix(m: Mat3x3): this;
|
|
308
|
+
/**
|
|
309
|
+
* Writes the rotation axis of this quaternion to `outAxis` and returns the rotation
|
|
310
|
+
* angle, so that `setFromAxisAngle(outAxis, angle)` gives back this rotation.
|
|
311
|
+
*
|
|
312
|
+
* The angle is in `[0, π]`: for `w < 0` the axis is flipped instead of returning an
|
|
313
|
+
* angle above π, so `q` and `−q` give the same result. The axis is unit length.
|
|
314
|
+
*
|
|
315
|
+
* Works for any non-zero quaternion, not only unit ones. With no rotation (zero vector
|
|
316
|
+
* part) any axis is valid; `+X` is written and the angle is 0.
|
|
317
|
+
*
|
|
318
|
+
* @param outAxis Destination for the unit axis. Allocated if omitted.
|
|
319
|
+
* @returns The rotation angle in radians, in `[0, π]`.
|
|
320
|
+
*/
|
|
321
|
+
getAxisAngle(outAxis?: Vec3): number;
|
|
322
|
+
/**
|
|
323
|
+
* Returns the angle of the rotation between this quaternion and `q`, in `[0, π]`: the
|
|
324
|
+
* smallest rotation that takes one orientation to the other.
|
|
325
|
+
*
|
|
326
|
+
* Computed as the angle of `this* · q`, using `atan2` so it stays accurate for small
|
|
327
|
+
* angles, where `2·acos(|dot|)` loses precision. `q` and `−q` give the same result.
|
|
328
|
+
*
|
|
329
|
+
* Both quaternions must be unit length.
|
|
330
|
+
*
|
|
331
|
+
* @param q The other rotation.
|
|
332
|
+
*/
|
|
333
|
+
angleTo(q: QuatLike): number;
|
|
334
|
+
/**
|
|
335
|
+
* Sets this quaternion from Euler angles in `XYZ` order: `qx · qy · qz`, where each is the
|
|
336
|
+
* rotation of the given angle about that axis.
|
|
337
|
+
*
|
|
338
|
+
* `qz` is applied first, then `qy`, then `qx`, all about the fixed world axes. Equivalently,
|
|
339
|
+
* the rotations are applied about the body's own axes in the order X, Y, Z. This matches
|
|
340
|
+
* Three.js's default `'XYZ'` order.
|
|
341
|
+
*
|
|
342
|
+
* @param x Rotation about X, in radians.
|
|
343
|
+
* @param y Rotation about Y, in radians.
|
|
344
|
+
* @param z Rotation about Z, in radians.
|
|
345
|
+
*/
|
|
346
|
+
setFromEulerXYZ(x: number, y: number, z: number): this;
|
|
347
|
+
/**
|
|
348
|
+
* Writes this rotation's Euler angles in `XYZ` order to `out`, the inverse of
|
|
349
|
+
* `setFromEulerXYZ`.
|
|
350
|
+
*
|
|
351
|
+
* The angles are in `x ∈ (−π, π]`, `y ∈ [−π/2, π/2]`, `z ∈ (−π, π]`. Many angle triples
|
|
352
|
+
* describe the same rotation, so the result may differ from the angles passed to
|
|
353
|
+
* `setFromEulerXYZ` while still representing the same rotation.
|
|
354
|
+
*
|
|
355
|
+
* At `y = ±π/2` (gimbal lock), X and Z rotate about the same axis and only their
|
|
356
|
+
* combination is defined. Then `z` is set to 0 and `x` carries the whole rotation.
|
|
357
|
+
*
|
|
358
|
+
* This quaternion must be unit length.
|
|
359
|
+
*
|
|
360
|
+
* @param out Destination for the angles `(x, y, z)` in radians. Allocated if omitted.
|
|
361
|
+
*/
|
|
362
|
+
getEulerXYZ(out?: Vec3): Vec3;
|
|
363
|
+
/**
|
|
364
|
+
* Sets this quaternion to the shortest rotation that takes direction `from` to direction
|
|
365
|
+
* `to`.
|
|
366
|
+
*
|
|
367
|
+
* The axis is `from × to` and the angle is the angle between them. When they are
|
|
368
|
+
* opposite, every axis perpendicular to them gives a shortest rotation (of π); one is
|
|
369
|
+
* built from the larger of `from`'s X and Z components, so it is never near zero.
|
|
370
|
+
*
|
|
371
|
+
* Both vectors must be unit length. They are not modified.
|
|
372
|
+
*
|
|
373
|
+
* @param from Unit start direction.
|
|
374
|
+
* @param to Unit end direction.
|
|
375
|
+
*/
|
|
376
|
+
setFromUnitVectors(from: Vec3Like, to: Vec3Like): this;
|
|
377
|
+
}
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
import type { Vec3Like } from "../types.js";
|
|
2
|
+
/**
|
|
3
|
+
* A 3D vector, used for points, directions, velocities, forces and other 3-component quantities.
|
|
4
|
+
*
|
|
5
|
+
* Conventions:
|
|
6
|
+
*
|
|
7
|
+
* - **Right-handed coordinates**, matching Three.js: `X × Y = Z`.
|
|
8
|
+
* - **Plain public fields.** `x`, `y` and `z` are ordinary properties, not getters, so V8 can
|
|
9
|
+
* optimize access in hot loops.
|
|
10
|
+
* - **Mutation.** Methods that modify this vector do it in place and return `this` for
|
|
11
|
+
* chaining, e.g. `v.add(w).scale(2)`. Use `clone()` first when you need to keep the original.
|
|
12
|
+
* - **Inputs.** Arguments are any `Vec3Like`, including `THREE.Vector3`, and are never
|
|
13
|
+
* modified. An argument may be `this`: every method reads its inputs before writing.
|
|
14
|
+
*/
|
|
15
|
+
export declare class Vec3 implements Vec3Like {
|
|
16
|
+
x: number;
|
|
17
|
+
y: number;
|
|
18
|
+
z: number;
|
|
19
|
+
/**
|
|
20
|
+
* Creates a vector from its components. Defaults to the zero vector.
|
|
21
|
+
*
|
|
22
|
+
* @param x X component.
|
|
23
|
+
* @param y Y component.
|
|
24
|
+
* @param z Z component.
|
|
25
|
+
*/
|
|
26
|
+
constructor(x?: number, y?: number, z?: number);
|
|
27
|
+
/**
|
|
28
|
+
* Sets all three components.
|
|
29
|
+
*
|
|
30
|
+
* @param x X component.
|
|
31
|
+
* @param y Y component.
|
|
32
|
+
* @param z Z component.
|
|
33
|
+
*/
|
|
34
|
+
set(x: number, y: number, z: number): this;
|
|
35
|
+
/**
|
|
36
|
+
* Copies the components of `vec3Like` into this vector.
|
|
37
|
+
*
|
|
38
|
+
* @param vec3Like Source vector.
|
|
39
|
+
*/
|
|
40
|
+
copy(vec3Like: Vec3Like): this;
|
|
41
|
+
/**
|
|
42
|
+
* Returns a new vector with the same components as this one.
|
|
43
|
+
*/
|
|
44
|
+
clone(): Vec3;
|
|
45
|
+
/**
|
|
46
|
+
* Returns the length of this vector, `√(x² + y² + z²)`.
|
|
47
|
+
*
|
|
48
|
+
* Prefer `magnitudeSquared` when only comparing lengths, since it avoids the square root.
|
|
49
|
+
*/
|
|
50
|
+
magnitude(): number;
|
|
51
|
+
/**
|
|
52
|
+
* Returns the squared length of this vector, `x² + y² + z²`.
|
|
53
|
+
*/
|
|
54
|
+
magnitudeSquared(): number;
|
|
55
|
+
/**
|
|
56
|
+
* Returns the distance between this point and `v`, `|this − v|`.
|
|
57
|
+
*
|
|
58
|
+
* Prefer `distanceToSquared` when only comparing distances, since it avoids the square root.
|
|
59
|
+
*
|
|
60
|
+
* @param v The other point.
|
|
61
|
+
*/
|
|
62
|
+
distanceTo(v: Vec3Like): number;
|
|
63
|
+
/**
|
|
64
|
+
* Returns the squared distance between this point and `v`, `|this − v|²`.
|
|
65
|
+
*
|
|
66
|
+
* @param v The other point.
|
|
67
|
+
*/
|
|
68
|
+
distanceToSquared(v: Vec3Like): number;
|
|
69
|
+
/**
|
|
70
|
+
* Adds `v` to this vector: `this = this + v`.
|
|
71
|
+
*
|
|
72
|
+
* @param v Vector to add.
|
|
73
|
+
*/
|
|
74
|
+
add(v: Vec3Like): this;
|
|
75
|
+
/**
|
|
76
|
+
* Subtracts `v` from this vector: `this = this − v`.
|
|
77
|
+
*
|
|
78
|
+
* @param v Vector to subtract.
|
|
79
|
+
*/
|
|
80
|
+
subtract(v: Vec3Like): this;
|
|
81
|
+
/**
|
|
82
|
+
* Multiplies every component by the scalar `s`: `this = this · s`.
|
|
83
|
+
*
|
|
84
|
+
* @param s Scale factor.
|
|
85
|
+
*/
|
|
86
|
+
scale(s: number): this;
|
|
87
|
+
/**
|
|
88
|
+
* Adds `v` scaled by `s` to this vector: `this = this + v · s`.
|
|
89
|
+
*
|
|
90
|
+
* The workhorse of integration, e.g. `position.addScaled(velocity, dt)`. Cheaper than
|
|
91
|
+
* `add(v.clone().scale(s))` and leaves `v` unchanged.
|
|
92
|
+
*
|
|
93
|
+
* @param v Vector to scale and add.
|
|
94
|
+
* @param s Scale applied to `v`.
|
|
95
|
+
*/
|
|
96
|
+
addScaled(v: Vec3Like, s: number): this;
|
|
97
|
+
/**
|
|
98
|
+
* Multiplies this vector by `v` component by component (the Hadamard product):
|
|
99
|
+
* `(x·vx, y·vy, z·vz)`.
|
|
100
|
+
*
|
|
101
|
+
* Not a dot or cross product. Useful for per-axis scaling.
|
|
102
|
+
*
|
|
103
|
+
* @param v Vector of per-component factors.
|
|
104
|
+
*/
|
|
105
|
+
componentWiseProduct(v: Vec3Like): this;
|
|
106
|
+
/**
|
|
107
|
+
* Reverses the direction of this vector: `this = −this`.
|
|
108
|
+
*/
|
|
109
|
+
negate(): this;
|
|
110
|
+
/**
|
|
111
|
+
* Moves this vector toward `v` by fraction `t`: `this + (v − this) · t`.
|
|
112
|
+
*
|
|
113
|
+
* `t = 0` leaves it unchanged and `t = 1` sets it to `v`. Values outside [0, 1]
|
|
114
|
+
* extrapolate.
|
|
115
|
+
*
|
|
116
|
+
* @param v Target vector.
|
|
117
|
+
* @param t Interpolation fraction.
|
|
118
|
+
*/
|
|
119
|
+
lerp(v: Vec3Like, t: number): this;
|
|
120
|
+
/**
|
|
121
|
+
* Returns true if every component is within `epsilon` of `v`'s, using `approxEqual`.
|
|
122
|
+
*
|
|
123
|
+
* The tolerance is absolute for components up to about 1 and relative above that.
|
|
124
|
+
*
|
|
125
|
+
* @param v Vector to compare against.
|
|
126
|
+
* @param epsilon Tolerance. Defaults to `EPSILON`.
|
|
127
|
+
*/
|
|
128
|
+
equals(v: Vec3Like, epsilon?: number): boolean;
|
|
129
|
+
/**
|
|
130
|
+
* Returns the dot product `this · v = x·vx + y·vy + z·vz`.
|
|
131
|
+
*
|
|
132
|
+
* Equals `|this| |v| cos θ`: positive when the vectors point the same way, zero when they
|
|
133
|
+
* are perpendicular, negative when they point apart. With a unit `v` it is the length of
|
|
134
|
+
* this vector's projection onto `v`.
|
|
135
|
+
*
|
|
136
|
+
* @param v The other vector.
|
|
137
|
+
*/
|
|
138
|
+
dot(v: Vec3Like): number;
|
|
139
|
+
/**
|
|
140
|
+
* Sets this vector to the cross product `this × v`.
|
|
141
|
+
*
|
|
142
|
+
* The result is perpendicular to both inputs, with length `|this| |v| sin θ` and direction
|
|
143
|
+
* given by the right-hand rule. It is zero for parallel vectors, and `a × b = −(b × a)`.
|
|
144
|
+
*
|
|
145
|
+
* @param v Right-hand operand. May be `this`.
|
|
146
|
+
*/
|
|
147
|
+
cross(v: Vec3Like): this;
|
|
148
|
+
/**
|
|
149
|
+
* Sets this vector to the cross product `a × b` without allocating.
|
|
150
|
+
*
|
|
151
|
+
* @param a Left-hand operand. May be `this`.
|
|
152
|
+
* @param b Right-hand operand. May be `this`.
|
|
153
|
+
*/
|
|
154
|
+
crossVectors(a: Vec3Like, b: Vec3Like): this;
|
|
155
|
+
/**
|
|
156
|
+
* Returns the cross product `v1 × v2` as a new vector, leaving both inputs unchanged.
|
|
157
|
+
*
|
|
158
|
+
* Allocates. On hot paths use `crossVectors` with a reused vector instead.
|
|
159
|
+
*
|
|
160
|
+
* @param v1 Left-hand operand.
|
|
161
|
+
* @param v2 Right-hand operand.
|
|
162
|
+
*/
|
|
163
|
+
static cross(v1: Vec3Like, v2: Vec3Like): Vec3;
|
|
164
|
+
/**
|
|
165
|
+
* Scales this vector to unit length, keeping its direction.
|
|
166
|
+
*
|
|
167
|
+
* The zero vector has no direction, so it stays zero instead of becoming NaN. Check
|
|
168
|
+
* `magnitudeSquared()` first if a zero input needs handling.
|
|
169
|
+
*/
|
|
170
|
+
normalize(): this;
|
|
171
|
+
}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
export type { QuatLike, Vec3Like } from "./types.js";
|
|
2
|
+
export { EPSILON, approxEqual, clamp } from "./scalar.js";
|
|
3
|
+
export { Vec3 } from "./geometry/vec3.js";
|
|
4
|
+
export { Mat3x3 } from "./geometry/mat3x3.js";
|
|
5
|
+
export { Mat3x4 } from "./geometry/mat3x4.js";
|
|
6
|
+
export { Quaternion } from "./geometry/quaternion.js";
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/** Any object with numeric `x`, `y` and `z` components. */
|
|
2
|
+
export interface Vec3Like {
|
|
3
|
+
x: number;
|
|
4
|
+
y: number;
|
|
5
|
+
z: number;
|
|
6
|
+
}
|
|
7
|
+
/**
|
|
8
|
+
* Any object with numeric `x`, `y`, `z`, and `w` components.
|
|
9
|
+
*/
|
|
10
|
+
export interface QuatLike {
|
|
11
|
+
x: number;
|
|
12
|
+
y: number;
|
|
13
|
+
z: number;
|
|
14
|
+
w: number;
|
|
15
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,48 @@
|
|
|
1
|
-
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "aether-physics",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "A 3D rigid-body physics engine built from scratch in TypeScript, with a Lit + Three.js playground.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"author": "Brandon Berisford",
|
|
7
|
+
"keywords": ["physics", "physics-engine", "rigid-body", "quaternion", "typescript"],
|
|
8
|
+
"homepage": "https://beyondbelief96.github.io/aether/",
|
|
9
|
+
"repository": {
|
|
10
|
+
"type": "git",
|
|
11
|
+
"url": "git+https://github.com/BeyondBelief96/aether.git"
|
|
12
|
+
},
|
|
13
|
+
"bugs": "https://github.com/BeyondBelief96/aether/issues",
|
|
14
|
+
"type": "module",
|
|
15
|
+
"sideEffects": ["./src/playground/**"],
|
|
16
|
+
"files": ["dist"],
|
|
17
|
+
"types": "./dist/types/index.d.ts",
|
|
18
|
+
"exports": {
|
|
19
|
+
".": {
|
|
20
|
+
"types": "./dist/types/index.d.ts",
|
|
21
|
+
"default": "./dist/index.js"
|
|
22
|
+
},
|
|
23
|
+
"./math": {
|
|
24
|
+
"types": "./dist/types/math/index.d.ts",
|
|
25
|
+
"default": "./dist/math.js"
|
|
26
|
+
}
|
|
27
|
+
},
|
|
28
|
+
"scripts": {
|
|
29
|
+
"dev": "vite",
|
|
30
|
+
"build": "tsc && vite build",
|
|
31
|
+
"preview": "vite preview",
|
|
32
|
+
"build:lib": "vite build --config vite.lib.config.ts && tsc -p tsconfig.build.json",
|
|
33
|
+
"prepublishOnly": "npm run typecheck && npm run test:run && npm run build:lib",
|
|
34
|
+
"typecheck": "tsc",
|
|
35
|
+
"test": "vitest",
|
|
36
|
+
"test:run": "vitest run"
|
|
37
|
+
},
|
|
38
|
+
"devEngines": {},
|
|
39
|
+
"devDependencies": {
|
|
40
|
+
"@types/three": "^0.186.0",
|
|
41
|
+
"fast-check": "^4.10.2",
|
|
42
|
+
"lit": "^3.3.3",
|
|
43
|
+
"three": "^0.186.1",
|
|
44
|
+
"typescript": "^7.0.2",
|
|
45
|
+
"vite": "^8.3.4",
|
|
46
|
+
"vitest": "^5.0.3"
|
|
47
|
+
}
|
|
48
|
+
}
|