@benev/math 0.0.0-0

package/license

@@ -0,0 +1,23 @@
+
+MIT License
+
+Copyright (c) 2025 Chase Moskal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "@benev/math",
+	"version": "0.0.0-0",
+	"description": "game math toolkit",
+	"license": "MIT",
+	"author": "Chase Moskal <chasemoskal@gmail.com>",
+	"type": "module",
+	"main": "x/index.js",
+	"files": [
+		"x",
+		"s"
+	],
+	"scripts": {
+		"build": "turtle build --out=x -v",
+		"start": "http-server x",
+		"test": "exit 0"
+	},
+	"dependencies": {
+		"@e280/stz": "^0.0.0-3",
+		"simplex-noise": "^4.0.3"
+	},
+	"devDependencies": {
+		"@benev/turtle": "^0.6.8",
+		"http-server": "^14.1.1",
+		"npm-run-all": "^4.1.5",
+		"typescript": "^5.8.3"
+	},
+	"keywords": [
+		"game",
+		"math",
+		"vectors"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/benevolent-games/math.git"
+	},
+	"bugs": {
+		"url": "https://github.com/benevolent-games/math/issues"
+	},
+	"homepage": "https://github.com/benevolent-games/math#readme"
+}

package/readme.md

@@ -0,0 +1,3 @@
+
+# @benev/math
+

package/s/concepts/angles.ts

@@ -0,0 +1,74 @@
+
+import {Scalar} from "./scalar.js"
+
+const pi = Math.PI
+const circle = 2 * Math.PI
+
+const to = {
+	degrees(r: number) {
+		return r * (180 / pi)
+	},
+	arcseconds(r: number) {
+		return to.degrees(r) * 3600
+	},
+	turns(r: number) {
+		return r / circle
+	},
+}
+
+const from = {
+	turns(t: number) {
+		return t * circle
+	},
+	degrees(d: number) {
+		return d * (pi / 180)
+	},
+	arcseconds(a: number) {
+		return from.degrees(a / 3600)
+	}
+}
+
+export const Radians = {
+	pi,
+	circle,
+
+	/** @deprecated use Radians.toDegrees instead */
+	to,
+
+	/** @deprecated use Degrees.toRadians instead */
+	from,
+
+	toDegrees(r: number) {
+		return r * (180 / pi)
+	},
+	toArcseconds(r: number) {
+		return to.degrees(r) * 3600
+	},
+	toTurns(r: number) {
+		return r / circle
+	},
+
+	circleDistance(radiansA: number, radiansB: number): number {
+		const diff = Math.abs(Scalar.wrap(radiansA - radiansB, 0, Radians.circle))
+		return Math.min(diff, Radians.circle - diff)
+	},
+}
+
+export const Turns = {
+	toRadians(t: number) {
+		return t * circle
+	},
+}
+
+export const Arcseconds = {
+	toRadians(a: number) {
+		return from.degrees(a / 3600)
+	},
+}
+
+export const Degrees = {
+	toRadians(d: number) {
+		return d * (pi / 180)
+	},
+}
+

package/s/concepts/circular.ts

@@ -0,0 +1,72 @@
+
+import {Scalar} from "./scalar.js"
+
+export class Circular {
+	constructor(public x: number) {}
+
+	clone() {
+		return new Circular(this.x)
+	}
+
+	set(x: number) {
+		this.x = x
+		return this
+	}
+
+	static value(x: number | Circular) {
+		return typeof x === "number"
+			? x
+			: x.x
+	}
+
+	static normalize(x: number) {
+		return Scalar.wrap(x, 0, 2 * Math.PI)
+	} normalize() {
+		this.x = Circular.normalize(this.x)
+		return this
+	}
+
+	static difference(x: number, y: number) {
+		x = this.normalize(x)
+		y = this.normalize(y)
+		let delta = y - x
+		if (delta > Math.PI) delta -= 2 * Math.PI
+		if (delta < -Math.PI) delta += 2 * Math.PI
+		return delta
+	} difference(y: number | Circular) {
+		return Circular.difference(this.x, Circular.value(y))
+	}
+
+	static lerp(x: number, y: number, fraction: number, max?: number) {
+		const difference = this.difference(x, y)
+		let delta = difference * fraction
+		if (max !== undefined && Math.abs(delta) > max)
+			delta = Math.sign(delta) * max
+		return this.normalize(x + delta)
+	} lerp(y: number | Circular, fraction: number, max?: number) {
+		this.x = Circular.lerp(this.x, Circular.value(y), fraction, max)
+		return this
+	}
+
+	static step(x: number, y: number, delta: number) {
+		const difference = this.difference(x, y)
+		return this.normalize(
+			Math.abs(difference) <= delta
+				? y
+				: x + (Math.sign(difference) * delta)
+		)
+	} step(y: number | Circular, delta: number) {
+		this.x = Circular.step(this.x, Circular.value(y), delta)
+		return this
+	}
+
+	static approach(x: number, y: number, speed: number, deltaTime: number, speedLimit?: number) {
+		const difference = this.difference(x, y)
+		const change = Scalar.creep(difference, speed, deltaTime, speedLimit)
+		return this.normalize(x + change)
+	} approach(y: number | Circular, speed: number, deltaTime: number, speedLimit?: number) {
+		this.x = Circular.approach(this.x, Circular.value(y), speed, deltaTime, speedLimit)
+		return this
+	}
+}
+

package/s/concepts/noise.ts

@@ -0,0 +1,23 @@
+
+import {Randy, Random} from "./randy.js"
+import {createNoise2D} from "simplex-noise"
+
+export class Noise {
+	static seed(seed: number = Randy.randomSeed()) {
+		const random = Randy.makeRandom(seed)
+		return new this(random)
+	}
+
+	#n2d: (x: number, y: number) => number
+
+	constructor(public readonly random: Random) {
+		this.#n2d = createNoise2D(random)
+	}
+
+	/** sample the noise field, returning a number from 0 to 1. */
+	sample(x: number, y = 0, scale = 1) {
+		const s = this.#n2d(x * scale, y * scale)
+		return (s + 1) / 2
+	}
+}
+

package/s/concepts/quat.ts

@@ -0,0 +1,131 @@
+
+import {Xyz} from "./vec3.js"
+
+export type QuatArray = [number, number, number, number]
+export type Xyzw = {x: number, y: number, z: number, w: number}
+
+export class Quat {
+	constructor(
+		public x: number,
+		public y: number,
+		public z: number,
+		public w: number,
+	) {}
+
+	static new(x: number, y: number, z: number, w: number) {
+		return new this(x, y, z, w)
+	}
+
+	static identity() {
+		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) {
+		return Array.isArray(q)
+			? this.array(q)
+			: this.import(q)
+	}
+
+	static rotate_(pitch: number, yaw: number, roll: number) {
+		return this.identity().rotate_(pitch, yaw, roll)
+	}
+
+	static rotate(vec: Xyz) {
+		return this.identity().rotate(vec)
+	}
+
+	array(): QuatArray {
+		const {x, y, z, w} = this
+		return [x, y, z, w]
+	}
+
+	toString() {
+		return `(Quat x${this.x.toFixed(2)}, y${this.y.toFixed(2)}, z${this.z.toFixed(2)}, w${this.w.toFixed(2)})`
+	}
+
+	clone() {
+		return new Quat(...this.array())
+	}
+
+	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)
+		}
+		else {
+			return this.multiply_(x, y, z, w)
+		}
+	}
+
+	transform({x, y, z, w}: Xyzw, global = false) {
+		return this.transform_(x, y, z, w, global)
+	}
+
+	rotate_(pitch: number, yaw: number, roll: number, global = false): Quat {
+		const cx = Math.cos(pitch * 0.5), sx = Math.sin(pitch * 0.5)
+		const cy = Math.cos(yaw * 0.5), sy = Math.sin(yaw * 0.5)
+		const cz = Math.cos(roll * 0.5), sz = Math.sin(roll * 0.5)
+		const x = sx * cy * cz + cx * sy * sz
+		const y = cx * sy * cz - sx * cy * sz
+		const z = cx * cy * sz + sx * sy * cz
+		const w = cx * cy * cz - sx * sy * sz
+		return this.transform_(x, y, z, w, global)
+	}
+
+	rotate({x: pitch, y: yaw, z: roll}: Xyz, global = false) {
+		return this.rotate_(pitch, yaw, roll, global)
+	}
+
+	rotateAroundAxis_(angle: number, axisX: number, axisY: number, axisZ: number, global = false): Quat {
+		const halfAngle = angle * 0.5
+		const sinHalf = Math.sin(halfAngle)
+		const x = axisX * sinHalf
+		const y = axisY * sinHalf
+		const z = axisZ * sinHalf
+		const w = Math.cos(halfAngle)
+		return this.transform_(x, y, z, w, global)
+	}
+
+	rotateAroundAxis(angle: number, axis: Xyz, global = false): Quat {
+		return this.rotateAroundAxis_(angle, axis.x, axis.y, axis.z, global)
+	}
+
+	set_(x: number, y: number, z: number, w: number) {
+		this.x = x
+		this.y = y
+		this.z = z
+		this.w = w
+		return this
+	}
+
+	set({x, y, z, w}: Xyzw) {
+		this.x = x
+		this.y = y
+		this.z = z
+		this.w = w
+		return this
+	}
+
+	multiply_(x2: number, y2: number, z2: number, w2: number): Quat {
+		const {x, y, z, w} = this
+		this.x = w * x2 + x * w2 + y * z2 - z * y2
+		this.y = w * y2 - x * z2 + y * w2 + z * x2
+		this.z = w * z2 + x * y2 - y * x2 + z * w2
+		this.w = w * w2 - x * x2 - y * y2 - z * z2
+		return this
+	}
+
+	multiply(...quats: Quat[]) {
+		for (const {x, y, z, w} of quats) this.multiply_(x, y, z, w)
+		return this
+	}
+}
+

package/s/concepts/randy.ts

@@ -0,0 +1,116 @@
+
+export type Random = () => number
+
+/** utility for generating and using random numbers. */
+export class Randy {
+	random: Random
+
+	constructor(public readonly seed: number = Randy.randomSeed()) {
+		this.random = Randy.makeRandom(seed)
+	}
+
+	/** obtain a random positive 32 bit integer. */
+	static randomSeed() {
+		return Math.floor(Math.random() * 2147483647)
+	}
+
+	/** seed a pseudo-random number generator function that produces numbers between 0 and 1. */
+	static makeRandom(seed: number): Random {
+		seed = (seed ^ 0x6D2B79F5) + 0x1E35A7BD
+		seed = (Math.abs(seed | 0) % 2147483647) || 1
+
+		function random() {
+			seed = (Math.imul(48271, seed) | 0) % 2147483647
+			return (seed & 2147483647) / 2147483648
+		}
+
+		random() // discard first value
+		return random
+	}
+
+	/** obtain a random positive integer. */
+	integer() {
+		return Math.floor(this.random() * 2147483647)
+	}
+
+	/** return true or false, given a 0 to 1 probability fraction. */
+	roll(chance = 0.5) {
+		return this.random() <= chance
+	}
+
+	/** generate a random number between two numbers. */
+	range(a: number, b: number) {
+		const difference = b - a
+		const value = difference * this.random()
+		return a + value
+	}
+
+	/** generate a random integer between two numbers (inclusive). */
+	integerRange(a: number, b: number) {
+		return Math.round(this.range(a, b))
+	}
+
+	/** randomly choose an index given an array length. */
+	index(length: number) {
+		return Math.floor(this.random() * length)
+	}
+
+	/** return a random item from the given array. */
+	choose<T>(array: T[]) {
+		return array[this.index(array.length)]
+	}
+
+	/** remove and return a random item from the given array. */
+	yoink<T>(array: T[]) {
+		const index = this.index(array.length)
+		const [item] = array.splice(index, 1)
+		return item
+	}
+
+	/** randomly select a number of array items. */
+	select<T>(count: number, array: T[]) {
+		const copy = [...array]
+		if (count >= array.length)
+			return copy
+
+		const selection: T[] = []
+		for (let i = 0; i < count; i++)
+			selection.push(this.yoink(copy))
+		return selection
+	}
+
+	/** remove and return a number of items from the given array. */
+	take<T>(count: number, array: T[]) {
+		const selection: T[] = []
+		for (let i = 0; i < count; i++) {
+			if (array.length === 0)
+				return selection
+			selection.push(this.yoink(array))
+		}
+		return selection
+	}
+
+	/** shuffle an array in-place using (fisher-yates) */
+	shuffle<T>(array: T[]) {
+		for (let i = array.length - 1; i > 0; i--) {
+			const j = Math.floor(this.random() * (i + 1))
+			;[array[i], array[j]] = [array[j], array[i]]
+		}
+		return array
+	}
+
+	/** @deprecated create an instance with the given seed number. */
+	static seed(seed: number): Randy {
+		return new this(seed)
+	}
+
+	/** @deprecated renamed to `take` */
+	extract<T>(count: number, array: T[]) { return this.take(count, array) }
+
+	/** @deprecated renamed to `range` */
+	between(a: number, b: number) { return this.range(a, b) }
+
+	/** @deprecated renamed to `integerRange` */
+	integerBetween(a: number, b: number) { return this.integerRange(a, b) }
+}
+

package/s/concepts/scalar.ts

@@ -0,0 +1,224 @@
+
+export class Scalar {
+	constructor(public x: number) {}
+
+	static new(x: number) {
+		return new this(x)
+	}
+
+	clone() {
+		return new Scalar(this.x)
+	}
+
+	set(x: number) {
+		this.x = x
+		return this
+	}
+
+	//
+	// queries
+	//
+
+	static isBetween(x: number, a: number = 0, b: number = 1) {
+		const min = Math.min(a, b)
+		const max = Math.max(a, b)
+		return (x >= min) && (x <= max)
+	} isBetween(a: number = 0, b: number = 1) {
+		return Scalar.isBetween(this.x, a, b)
+	}
+
+	static isNear(x: number, y: number, epsilon: number = 0.01) {
+		return Math.abs(x - y) <= epsilon
+	} isNear(y: number, epsilon: number = 0.01) {
+		return Scalar.isNear(this.x, y, epsilon)
+	}
+
+	//
+	// chainable transforms
+	//
+
+	static add(...nums: number[]) {
+		let x = 0
+		for (const n of nums)
+			x += n
+		return x
+	} add(...nums: number[]) {
+		this.x = Scalar.add(...nums)
+		return this
+	}
+
+	subtract(...nums: number[]) {
+		for (const n of nums)
+			this.x -= n
+		return this
+	}
+
+	static min(x: number, minimum: number = 0) {
+		return Math.max(x, minimum)
+	} min(minimum: number = 0) {
+		this.x = Scalar.min(this.x, minimum)
+		return this
+	}
+
+	static max(x: number, maximum: number = 1) {
+		return Math.min(x, maximum)
+	} max(maximum: number = 1) {
+		this.x = Scalar.max(this.x, maximum)
+		return this
+	}
+
+	static clamp(x: number, a: number = 0, b: number = 1) {
+		x = Scalar.min(x, Math.min(a, b))
+		x = Scalar.max(x, Math.max(a, b))
+		return x
+	} clamp(a: number = 0, b: number = 1) {
+		this.x = Scalar.clamp(this.x, a, b)
+		return this
+	}
+
+	static lerp(x: number, y: number, fraction: number, max?: number) {
+		const difference = y - x
+		let delta = difference * fraction
+		if (max !== undefined && Math.abs(delta) > max)
+			delta = Math.sign(delta) * max
+		return x + delta
+	} lerp(y: number, fraction: number, max?: number) {
+		this.x = Scalar.lerp(this.x, y, fraction, max)
+		return this
+	}
+
+	static step(x: number, y: number, delta: number) {
+		const difference = y - x
+		return (Math.abs(difference) <= delta)
+			? y
+			: x + (Math.sign(difference) * delta)
+	} step(y: number, delta: number) {
+		this.x = Scalar.step(this.x, y, delta)
+		return this
+	}
+
+	static creep(difference: number, speed: number, deltaTime: number, speedLimit?: number) {
+		let change = (difference * (1 - Math.exp(-speed * deltaTime)))
+		if (speedLimit !== undefined) {
+			const changeLimit = speedLimit * deltaTime
+			if (Math.abs(change) > changeLimit)
+				change = Math.sign(change) * changeLimit
+		}
+		return change
+	}
+
+	static approach(x: number, y: number, speed: number, deltaTime: number, speedLimit?: number) {
+		const difference = y - x
+		const change = this.creep(difference, speed, deltaTime, speedLimit)
+		return x + change
+	} approach(y: number, speed: number, deltaTime: number, speedLimit?: number) {
+		this.x = Scalar.approach(this.x, y, speed, deltaTime, speedLimit)
+		return this
+	}
+
+	static wrap(x: number, a: number = 0, b: number = 1) {
+		const min = Math.min(a, b)
+		const max = Math.max(a, b)
+		const span = max - min
+		const adjusted = x - min
+		const wrapped = (adjusted < 0)
+			? span - (-adjusted % span)
+			: adjusted % span
+		return min + wrapped
+	} wrap(a: number = 0, b: number = 1) {
+		this.x = Scalar.wrap(this.x, a, b)
+		return this
+	}
+
+	static constrainProximity(x: number, y: number, range: number) {
+		const trueDiff = y - x
+		const positiveDiff = Math.abs(trueDiff)
+		const cappedDiff = (positiveDiff > range)
+			? range
+			: positiveDiff
+		const newDiff = (trueDiff < 0) ? -cappedDiff : cappedDiff
+		return x + newDiff
+	} constrainProximity(y: number, range: number) {
+		this.x = Scalar.constrainProximity(this.x, y, range)
+		return this
+	}
+
+	static inverse(x: number) {
+		return 1 - x
+	} inverse() {
+		this.x = Scalar.inverse(this.x)
+		return this
+	}
+
+	static center(x: number) {
+		return (x * 2) - 1
+	} center() {
+		this.x = Scalar.center(this.x)
+		return this
+	}
+
+	static uncenter(x: number) {
+		return (x + 1) / 2
+	} uncenter() {
+		this.x = Scalar.uncenter(this.x)
+		return this
+	}
+
+	static map(x: number, a: number, b: number) {
+		const difference = b - a
+		const value = difference * x
+		return a + value
+	} map(a: number, b: number) {
+		this.x = Scalar.map(this.x, a, b)
+		return this
+	}
+
+	static remap(x: number, a1: number, a2: number, b1: number = 0, b2: number = 1, clamp = false) {
+		const fraction = (x - a1) / (a2 - a1)
+		const result = (fraction * (b2 - b1)) + b1
+		return clamp
+			? Scalar.clamp(result, b1, b2)
+			: result
+	} remap(a1: number, a2: number, b1: number = 0, b2: number = 1, clamp = false) {
+		this.x = Scalar.remap(this.x, a1, a2, b1, b2, clamp)
+		return this
+	}
+
+	static magnify(x: number) {
+		return 4 * Math.pow(x - 0.5, 3) + 0.5
+	} magnify() {
+		this.x = Scalar.magnify(this.x)
+		return this
+	}
+
+	static floor(x: number) {
+		return Math.floor(x)
+	} floor() {
+		this.x = Scalar.floor(this.x)
+		return this
+	}
+
+	static ceil(x: number) {
+		return Math.ceil(x)
+	} ceil() {
+		this.x = Scalar.ceil(this.x)
+		return this
+	}
+
+	static round(x: number) {
+		return Math.round(x)
+	} round() {
+		this.x = Scalar.round(this.x)
+		return this
+	}
+
+	static smooth(x: number, y: number, smoothing: number) {
+		return smoothing <= 1
+			? y
+			: x + ((y - x) / smoothing)
+	} smooth(y: number, smoothing: number) {
+		this.x = Scalar.smooth(this.x, y, smoothing)
+		return this
+	}
+}
+