@benev/math 0.1.0 → 0.2.0-1

package/README.md

@@ -1,26 +1,113 @@
 
 # @benev/math
-> benevolent's game math library.
-
-***TODO*** actual documentation coming soon.
-
-### numeric primitives
-- [Scalar](./s/concepts/scalar.ts)
-- [Vec2](./s/concepts/vec2.ts)
-- [Vec3](./s/concepts/vec3.ts)
-- [Vec4](./s/concepts/vec4.ts)
-- [Quat](./s/concepts/quat.ts)
-
-### cool utilities
-- [Randy](./s/concepts/randy.ts)
-- [Circular](./s/concepts/circular.ts)
-- [Noise](./s/concepts/noise.ts)
-- [spline](./s/concepts/spline.ts)
-
-### angular stuff
-- [angles.ts](./s/concepts/angles.ts)
-  - Radians
-  - Arcseconds
-  - Turns
-  - Degrees
+> benevolent's typescript math library for games
+
+<br/>
+
+## 🍋 CORE
+> common numerical structures
+
+> [!TIP]
+> until real docs are written, see the relevant sourcecode in [s/core/](./s/core/)
+
+### 🍏 conventions for all core classes
+- **mutable by default.**  
+    operations happen in-place, for efficiency (we're trying to reduce gc churn).  
+    ```ts
+    // allocate a single vector instance
+    const vector = new Vec2(0, 0)
+      .add({x: 1, y: 2})
+      .multiplyBy(2)
+    ```
+- **explicit cloning.**  
+    use `.clone()` to avoid mutating the original.  
+    ```ts
+    // modify a clone (not the original)
+    const vector2 = vector
+      .clone()
+      .normalize()
+    ```
+- **underscore-suffixed methods take direct args.**  
+  - methods normally take in other class instances:
+      ```ts
+      vectorA.add(vectorB)
+      ```
+  - but underscore-suffixed methods take raw naked args (helping you avoid making instances)
+      ```ts
+      vectorA.add_(x, y)
+      ```
+
+### 🍏 Vec2
+### 🍏 Vec3
+### 🍏 Vec4
+### 🍏 Quat
+
+<br/>
+
+## 🍋 TOOLS
+> handy utilities
+
+> [!TIP]
+> until real docs are written, see the relevant sourcecode in [s/tools/](./s/tools/)
+
+### 🍏 Scalar
+### 🍏 Circular
+### 🍏 Randy
+### 🍏 Noise
+### 🍏 Spline
+### 🍏 Angles
+- **Radians**
+- **Degrees**
+- **Turns**
+- **Arcseconds**
+
+<br/>
+
+## 🍋 SHAPES
+> geometric concepts
+
+> [!TIP]
+> until real docs are written, see the relevant sourcecode in [s/shapes/](./s/shapes/)
+
+### 🍏 2d shapes
+- **Edge** — a line segment
+- **Pill** — a fat line segment (like a sausage)
+- **Rect** — a rectangle
+- **Circle** — a point with a radius
+
+### 🍏 3d shapes
+- **Segment** — a line segment
+- **Capsule** — a fat line segment (like a hoagie)
+- **Box** — a cuboid
+- **Sphere** — a point with a radius
+
+<br/>
+
+## 🍋 OPTIMIZERS
+> spatial optimization data structures
+
+> [!TIP]
+> until real docs are written, see the relevant sourcecode in [s/optimizers/](./s/optimizers/)
+
+### 🍏 HashMap
+### 🍏 HashSet
+### 🍏 ZenGrid
+
+<br/>
+
+## 🍋 PHYSICS
+> functionality for doing basic physics
+
+> [!TIP]
+> until real docs are written, see the relevant sourcecode in [s/physics/](./s/physics/)
+
+### 🍏 collide2d
+### 🍏 collide3d
+### 🍏 intersect2d
+### 🍏 intersect3d
+
+<br/>
+
+## 👼 https://benevolent.games/
+star this on github if you use it 👍
 

package/package.json

@@ -1,10 +1,11 @@
 {
 	"name": "@benev/math",
-	"version": "0.1.0",
+	"version": "0.2.0-1",
 	"description": "game math toolkit",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",
 	"type": "module",
+	"sideEffects": false,
 	"main": "./x/index.js",
 	"exports": {
 		".": "./x/index.js"
@@ -21,6 +22,7 @@
 		"count": "find s -path '*/_archive' -prune -o -name '*.ts' -exec wc -l {} +"
 	},
 	"dependencies": {
+		"@e280/stz": "^0.1.0",
 		"simplex-noise": "^4.0.3"
 	},
 	"devDependencies": {

package/s/{concepts → core}/quat.ts

@@ -1,7 +1,7 @@
 
 import {Xyz} from "./vec3.js"
 
-export type QuatArray = [number, number, number, number]
+export type XyzwArray = [x: number, y: number, z: number, w: number]
 export type Xyzw = {x: number, y: number, z: number, w: number}
 
 export class Quat {
@@ -20,18 +20,10 @@ export class Quat {
 		return new this(0, 0, 0, 1)
 	}
 
-	static array(q: QuatArray) {
-		return new this(...q)
-	}
-
-	static import({x, y, z, w}: Xyzw) {
-		return new this(x, y, z, w)
-	}
-
-	static from(q: QuatArray | Xyzw) {
+	static from(q: XyzwArray | Xyzw) {
 		return Array.isArray(q)
-			? this.array(q)
-			: this.import(q)
+			? new this(...q)
+			: new this(q.x, q.y, q.z, q.w)
 	}
 
 	static rotate_(pitch: number, yaw: number, roll: number) {
@@ -42,7 +34,7 @@ export class Quat {
 		return this.identity().rotate(vec)
 	}
 
-	array(): QuatArray {
+	toJSON(): XyzwArray {
 		const {x, y, z, w} = this
 		return [x, y, z, w]
 	}
@@ -52,13 +44,61 @@ export class Quat {
 	}
 
 	clone() {
-		return new Quat(...this.array())
+		return new Quat(...this.toJSON())
+	}
+
+	lengthSquared() {
+		return this.x*this.x + this.y*this.y + this.z*this.z + this.w*this.w
+	}
+
+	length() {
+		return Math.sqrt(this.lengthSquared())
+	}
+
+	isUnit(epsilon=1e-6) {
+		return Math.abs(this.length() - 1) <= epsilon
+	}
+
+	ensureUnit(){
+		if (!this.isUnit()) this.normalize()
+		return this
+	}
+
+	normalize(){
+		const m = this.length()
+		if (!m) {
+			this.x = this.y = this.z = 0
+			this.w = 1
+			return this
+		}
+		this.x /= m
+		this.y /= m
+		this.z /= m
+		this.w /= m
+		return this
+	}
+
+	conjugate() {
+		this.x *= -1
+		this.y *= -1
+		this.z *= -1
+		return this
+	}
+
+	invert() {
+		const len2 = this.lengthSquared()
+		if (!len2) return this.set_(0, 0, 0, 1)
+		this.x = -this.x / len2
+		this.y = -this.y / len2
+		this.z = -this.z / len2
+		this.w = this.w / len2
+		return this
 	}
 
 	transform_(x: number, y: number, z: number, w: number, global = false) {
 		if (global) {
-			const original = this.array()
-			return this.set_(x, y, z, w).multiply_(...original)
+			const original = this.clone()
+			return this.set_(x, y, z, w).multiply(original)
 		}
 		else {
 			return this.multiply_(x, y, z, w)

package/s/{concepts → core}/vec2.ts

@@ -1,44 +1,31 @@
 
-import {Scalar} from "./scalar.js"
+import {Scalar} from "../tools/scalar.js"
 
-export type Vec2Array = [number, number]
+export type XyArray = [x: number, y: number]
 export type Xy = {x: number, y: number}
 
-/** https://github.com/microsoft/TypeScript/issues/5863 */
-type TsHack<T> = {new(...a: ConstructorParameters<typeof Vec2>): T}
-
 export class Vec2 implements Xy {
 	constructor(
 		public x: number,
 		public y: number,
 	) {}
 
-	///////////////////////////////////////////////////////////////////////
-
-	static new<T extends Vec2>(this: TsHack<T>, x: number, y: number): T {
+	static new(x: number, y: number) {
 		return new this(x, y)
 	}
 
-	static zero<T extends Vec2>(this: TsHack<T>) {
+	static zero() {
 		return new this(0, 0)
 	}
 
-	static all<T extends Vec2>(this: TsHack<T>, value: number) {
+	static all(value: number) {
 		return new this(value, value)
 	}
 
-	static array<T extends Vec2>(this: TsHack<T>, v: Vec2Array) {
-		return new this(...v)
-	}
-
-	static import<T extends Vec2>(this: TsHack<T>, {x, y}: Xy) {
-		return new this(x, y)
-	}
-
-	static from(v: Vec2Array | Xy) {
+	static from(v: XyArray | Xy) {
 		return Array.isArray(v)
-			? this.array(v)
-			: this.import(v)
+			? new this(...v)
+			: new this(v.x, v.y)
 	}
 
 	static magnitudeSquared(x: number, y: number) {
@@ -55,27 +42,37 @@ export class Vec2 implements Xy {
 			.divideBy(vectors.length)
 	}
 
-	static min(...vecs: Vec2[]) {
-		return new Vec2(
+	static min(...vecs: Xy[]) {
+		return new this(
 			Math.min(...vecs.map(v => v.x)),
 			Math.min(...vecs.map(v => v.y)),
 		)
 	}
 
-	static max(...vecs: Vec2[]) {
-		return new Vec2(
+	static max(...vecs: Xy[]) {
+		return new this(
 			Math.max(...vecs.map(v => v.x)),
 			Math.max(...vecs.map(v => v.y)),
 		)
 	}
 
-	///////////////////////////////////////////////////////////////////////
+	static fromAngle(radians: number) {
+		return new this(
+			Math.cos(radians),
+			Math.sin(radians),
+		)
+	}
 
 	clone() {
 		return new Vec2(this.x, this.y)
 	}
 
-	array(): Vec2Array {
+	*[Symbol.iterator]() {
+		yield this.x
+		yield this.y
+	}
+
+	toJSON(): XyArray {
 		return [this.x, this.y]
 	}
 
@@ -97,8 +94,6 @@ export class Vec2 implements Xy {
 		return this
 	}
 
-	///////////////////////////////////////////////////////////////////////
-
 	magnitudeSquared() {
 		return Vec2.magnitudeSquared(this.x, this.y)
 	}
@@ -122,6 +117,17 @@ export class Vec2 implements Xy {
 		return vecs.every(({x, y}) => this.equals_(x, y))
 	}
 
+	near_(x: number, y: number, epsilon = 1e-6) {
+		return (
+			Math.abs(this.x - x) <= epsilon &&
+			Math.abs(this.y - y) <= epsilon
+		)
+	}
+
+	near({x, y}: Xy, epsilon = 1e-6) {
+		return this.near_(x, y, epsilon)
+	}
+
 	dot_(x: number, y: number) {
 		return (this.x * x) + (this.y * y)
 	}
@@ -151,15 +157,15 @@ export class Vec2 implements Xy {
 	angleBetween_(x: number, y: number) {
 		const dot = this.dot_(x, y)
 		const magnitudes = this.magnitude() * Vec2.magnitude(x, y)
-		return Math.acos(dot / magnitudes)
+		if (magnitudes === 0) return 0
+		const ratio = Scalar.clamp(dot / magnitudes, -1, 1)
+		return Math.acos(ratio)
 	}
 
 	angleBetween({x, y}: Xy) {
 		return this.angleBetween_(x, y)
 	}
 
-	///////////////////////////////////////////////////////////////////////
-
 	/** mutator */
 	normalize() {
 		return this.divideBy(this.magnitude())
@@ -233,9 +239,17 @@ export class Vec2 implements Xy {
 	}
 
 	/** mutator */
-	clamp(min: number, max: number) {
-		const clamp = (val: number) => Math.max(min, Math.min(max, val))
-		return this.map(clamp)
+	clamp(min: Xy, max: Xy) {
+		this.x = Scalar.clamp(this.x, min.x, max.x)
+		this.y = Scalar.clamp(this.y, min.y, max.y)
+		return this
+	}
+
+	/** mutator */
+	clampBy(min: number, max: number) {
+		this.x = Scalar.clamp(this.x, min, max)
+		this.y = Scalar.clamp(this.y, min, max)
+		return this
 	}
 
 	/** mutator */
@@ -315,8 +329,8 @@ export class Vec2 implements Xy {
 
 	/** mutator */
 	divide_(x: number, y: number) {
-		this.x /= x
-		this.y /= y
+		if (x !== 0) this.x /= x
+		if (y !== 0) this.y /= y
 		return this
 	}
 
@@ -373,7 +387,7 @@ export class Vec2 implements Xy {
 	}
 
 	/** mutator */
-	rotateAroundPoint({x, y}: Vec2, radians: number) {
+	rotateAroundPoint({x, y}: Xy, radians: number) {
 		return this.rotateAroundPoint_(x, y, radians)
 	}
 

package/s/{concepts → core}/vec3.ts

@@ -1,12 +1,9 @@
 
-import {Scalar} from "./scalar.js"
+import {Scalar} from "../tools/scalar.js"
 
-export type Vec3Array = [number, number, number]
+export type XyzArray = [x: number, y: number, z: number]
 export type Xyz = {x: number, y: number, z: number}
 
-/** https://github.com/microsoft/TypeScript/issues/5863 */
-type TsHack<T> = {new(...a: ConstructorParameters<typeof Vec3>): T}
-
 export class Vec3 {
 	constructor(
 		public x: number,
@@ -14,32 +11,22 @@ export class Vec3 {
 		public z: number,
 	) {}
 
-	///////////////////////////////////////////////////////////////////////
-
-	static new<T extends Vec3>(this: TsHack<T>, x: number, y: number, z: number) {
+	static new(x: number, y: number, z: number) {
 		return new this(x, y, z)
 	}
 
-	static zero<T extends Vec3>(this: TsHack<T>) {
+	static zero() {
 		return new this(0, 0, 0)
 	}
 
-	static all<T extends Vec3>(this: TsHack<T>, value: number) {
+	static all(value: number) {
 		return new this(value, value, value)
 	}
 
-	static array<T extends Vec3>(this: TsHack<T>, v: Vec3Array) {
-		return new this(...v)
-	}
-
-	static import<T extends Vec3>(this: TsHack<T>, {x, y, z}: Xyz): Vec3 {
-		return new this(x, y, z)
-	}
-
-	static from(v: Vec3Array | Xyz) {
+	static from(v: XyzArray | Xyz) {
 		return Array.isArray(v)
-			? this.array(v)
-			: this.import(v)
+			? new this(...v)
+			: new this(v.x, v.y, v.z)
 	}
 
 	static magnitudeSquared(x: number, y: number, z: number) {
@@ -56,23 +43,23 @@ export class Vec3 {
 			.divideBy(vecs.length)
 	}
 
-	static min(...vecs: Vec3[]) {
-		return new Vec3(
+	static min(...vecs: Xyz[]) {
+		return new this(
 			Math.min(...vecs.map(v => v.x)),
 			Math.min(...vecs.map(v => v.y)),
 			Math.min(...vecs.map(v => v.z)),
 		)
 	}
 
-	static max(...vecs: Vec3[]) {
-		return new Vec3(
+	static max(...vecs: Xyz[]) {
+		return new this(
 			Math.max(...vecs.map(v => v.x)),
 			Math.max(...vecs.map(v => v.y)),
 			Math.max(...vecs.map(v => v.z)),
 		)
 	}
 
-	static hexColor(hex: string): Vec3 {
+	static fromHex(hex: string): Vec3 {
 		if (hex.startsWith("#") && hex.length === 7) {
 			const r = parseInt(hex.slice(1, 3), 16) / 255
 			const g = parseInt(hex.slice(3, 5), 16) / 255
@@ -83,13 +70,17 @@ export class Vec3 {
 		}
 	}
 
-	///////////////////////////////////////////////////////////////////////
-
 	clone() {
 		return new Vec3(this.x, this.y, this.z)
 	}
 
-	array(): Vec3Array {
+	*[Symbol.iterator]() {
+		yield this.x
+		yield this.y
+		yield this.z
+	}
+
+	toJSON(): XyzArray {
 		return [this.x, this.y, this.z]
 	}
 
@@ -111,8 +102,6 @@ export class Vec3 {
 		return this
 	}
 
-	///////////////////////////////////////////////////////////////////////
-
 	magnitudeSquared() {
 		return Vec3.magnitudeSquared(this.x, this.y, this.z)
 	}
@@ -121,14 +110,13 @@ export class Vec3 {
 		return Vec3.magnitude(this.x, this.y, this.z)
 	}
 
-	hexColor() {
-		const to255 = (val: number) => Math.round(val * 255)
+	/** rgb values from 0-1 */
+	toHex() {
+		const to255 = (val: number) => Math.round(Scalar.clamp(val * 255, 0, 255))
 		const toHex = (val: number) => to255(val).toString(16).padStart(2, '0')
 		return `#${toHex(this.x)}${toHex(this.y)}${toHex(this.z)}`
 	}
 
-	///////////////////////////////////////////////////////////////////////
-
 	equals_(x: number, y: number, z: number) {
 		return (
 			this.x === x &&
@@ -138,7 +126,19 @@ export class Vec3 {
 	}
 
 	equals(...vecs: Xyz[]) {
-		return vecs.every(v => this.equals_(v.x, v.y, v.z))
+		return vecs.every(({x, y, z}) => this.equals_(x, y, z))
+	}
+
+	near_(x: number, y: number, z: number, epsilon = 1e-6) {
+		return (
+			Math.abs(this.x - x) <= epsilon &&
+			Math.abs(this.y - y) <= epsilon &&
+			Math.abs(this.z - z) <= epsilon
+		)
+	}
+
+	near({x, y, z}: Xyz, epsilon = 1e-6) {
+		return this.near_(x, y, z, epsilon)
 	}
 
 	distanceSquared_(x: number, y: number, z: number) {
@@ -179,16 +179,16 @@ export class Vec3 {
 
 	angleBetween_(x: number, y: number, z: number) {
 		const dotProduct = this.dot_(x, y, z)
-		const magnitudes = this.magnitude() * Vec3.new(x, y, z).magnitude()
-		return Math.acos(dotProduct / magnitudes)
+		const magnitudes = this.magnitude() * Vec3.magnitude(x, y, z)
+		if (magnitudes === 0) return 0
+		const ratio = Scalar.clamp(dotProduct / magnitudes, -1, 1)
+		return Math.acos(ratio)
 	}
 
 	angleBetween({x, y, z}: Xyz) {
 		return this.angleBetween_(x, y, z)
 	}
 
-	///////////////////////////////////////////////////////////////////////
-
 	/** mutator */
 	add_(x: number, y: number, z: number) {
 		this.x += x
@@ -226,21 +226,21 @@ export class Vec3 {
 	}
 
 	/** mutator */
-	multiply(...vecs: Vec3[]) {
+	multiply(...vecs: Xyz[]) {
 		for (const {x, y, z} of vecs) this.multiply_(x, y, z)
 		return this
 	}
 
 	/** mutator */
 	divide_(x: number, y: number, z: number) {
-		this.x /= x
-		this.y /= y
-		this.z /= z
+		if (x !== 0) this.x /= x
+		if (y !== 0) this.y /= y
+		if (z !== 0) this.z /= z
 		return this
 	}
 
 	/** mutator */
-	divide(...vecs: Vec3[]) {
+	divide(...vecs: Xyz[]) {
 		for (const {x, y, z} of vecs) this.divide_(x, y, z)
 		return this
 	}
@@ -286,6 +286,14 @@ export class Vec3 {
 		return this
 	}
 
+	/** mutator */
+	subtractBy(delta: number) {
+		this.x -= delta
+		this.y -= delta
+		this.z -= delta
+		return this
+	}
+
 	/** mutator */
 	multiplyBy(delta: number) {
 		this.x *= delta
@@ -381,7 +389,9 @@ export class Vec3 {
 
 	/** mutator */
 	projectOnto_(x: number, y: number, z: number) {
-		const scalar = this.dot_(x, y, z) / Vec3.magnitudeSquared(x, y, z)
+		const m2 = Vec3.magnitudeSquared(x, y, z)
+		if (!m2) return this
+		const scalar = this.dot_(x, y, z) / m2
 		this.x = scalar * x
 		this.y = scalar * y
 		this.z = scalar * z
@@ -389,7 +399,7 @@ export class Vec3 {
 	}
 
 	/** mutator */
-	projectOnto({x, y, z}: Vec3) {
+	projectOnto({x, y, z}: Xyz) {
 		return this.projectOnto_(x, y, z)
 	}