@inglorious/utils 3.8.0 → 5.0.0

package/types/math/hitmask.d.ts

@@ -0,0 +1,20 @@
+import type { Point } from "./point"
+import type { Platform } from "./rectangle"
+
+/** Represents the width and depth of a hitmask tile. */
+export type TileSize = readonly [width: number, depth: number]
+
+/** Represents a tiled collision mask. */
+export interface Hitmask {
+  /** The center of the hitmask. */
+  position: Point
+  /** The dimensions of each tile. */
+  tileSize: TileSize
+  /** The number of tile columns. */
+  columns: number
+  /** The height of each tile. */
+  heights: number[]
+}
+
+/** Checks whether a platform collides with a hitmask. */
+export function findCollisions(hitmask: Hitmask, target: Platform): boolean

package/types/math/index.d.ts

@@ -0,0 +1,14 @@
+export * as circle from "./circle"
+export * as hitmask from "./hitmask"
+export * as line from "./line"
+export * as linearInterpolation from "./linear-interpolation"
+export * as number from "./number"
+export * as point from "./point"
+export * as quaternion from "./quaternion"
+export * as rectangle from "./rectangle"
+export * as rng from "./rng"
+export * as segment from "./segment"
+export * as statistics from "./statistics"
+export * as triangle from "./triangle"
+export * as trigonometry from "./trigonometry"
+export * as vector from "./vector"

package/types/math/line.d.ts

@@ -0,0 +1,11 @@
+import type { Circle } from "./circle"
+import type { Point } from "./point"
+
+/** Represents a 2D line as `ax + bz + c = 0`. */
+export type Line = readonly [a: number, b: number, c: number]
+
+/** Calculates the shortest distance from a point to a line. */
+export function distanceFromPoint(line: Line, point: Point): number
+
+/** Checks whether a line intersects a circle. */
+export function intersectsCircle(line: Line, circle: Circle): boolean

package/types/math/linear-interpolation.d.ts

@@ -0,0 +1,2 @@
+/** Linearly interpolates between two numbers. */
+export function lerp(a: number, b: number, t: number): number

package/types/math/number.d.ts

@@ -0,0 +1,26 @@
+/** Returns the absolute value of a number. */
+export function abs(num: number): number
+
+/** Clamps a number to an inclusive range. */
+export function clamp(num: number, min: number, max: number): number
+
+/** Checks whether a number is within an inclusive range. */
+export function isBetween(num: number, min: number, max: number): boolean
+
+/** Checks whether two numbers are within a tolerance. */
+export function isClose(num1: number, num2: number, tolerance?: number): boolean
+
+/** Computes a positive modulus, returning the dividend for a zero divisor. */
+export function mod(dividend: number, divisor: number): number
+
+/** Snaps a number to the nearest multiple of a precision. */
+export function snap(num: number, precision?: number): number
+
+/** Alias for `mod`. */
+export const remainder: typeof mod
+
+/** Returns the sign of a number. */
+export function sign(num: number): number
+
+/** Computes the square root of a number. */
+export function sqrt(num: number): number

package/types/math/point.d.ts

@@ -0,0 +1,50 @@
+import type { Vector3 } from "./vector"
+import type { Circle } from "./circle"
+import type { Line } from "./line"
+import type { Rectangle } from "./rectangle"
+
+/**
+ * A point in the Inglorious coordinate system: `[x, y, z]`.
+ *
+ * The world is **y-up**: the origin sits on the floor, and a bigger `y` is
+ * always a higher place in the world. Gravity subtracts from it, a jump adds to
+ * it, and an object resting on the ground has `y = 0`.
+ *
+ * `z` is the depth axis, and it is **y-up as well** — it is not screen-down, so
+ * both vertical axes grow upwards. Renderers are what turn them into screen
+ * coordinates: `@inglorious/renderer-2d` projects a point to
+ * `canvasY = viewportHeight - y - z`, which puts `(0, 0, 0)` at the bottom-left
+ * corner of the canvas and turns both axes upside down.
+ *
+ * @example Reading a position in a 2D game
+ * ```js
+ * // Ground level, and a hundred pixels above it.
+ * v(0, 0, 0) // the floor
+ * v(0, 100, 0) // a hundred pixels up
+ *
+ * // Falling means losing height, in 2D as well as in 3D.
+ * entity.velocity[1] -= GRAVITY * dt
+ *
+ * // Keep a body on the ground.
+ * entity.position[1] = 0
+ * ```
+ */
+export type Point = readonly [x: number, y: number, z: number]
+
+/** Accepts a 3D point, branded vector, or object with a point position. */
+export type PointInput = Point | Vector3 | { position: Point | Vector3 }
+
+/** Calculates the distance from a point to a line. */
+export function getDistanceFromLine(point: Point, line: Line): number
+
+/** Checks whether two points occupy the same position. */
+export function intersectsPoint(point1: PointInput, point2: PointInput): boolean
+
+/** Checks whether a point intersects a circle. */
+export function intersectsCircle(point: PointInput, circle: Circle): boolean
+
+/** Checks whether a point intersects a rectangle. */
+export function intersectsRectangle(
+  point: PointInput,
+  rectangle: Rectangle,
+): boolean

package/types/math/quaternion.d.ts

@@ -0,0 +1,10 @@
+import type { Vector, Vector3 } from "./vector"
+
+/** A quaternion represented as a four-dimensional vector. */
+export type Quaternion = Vector<readonly [number, number, number, number]>
+
+/** Combines two quaternions with the Hamilton product. */
+export function combine(q1: Quaternion, q2: Quaternion): Quaternion
+
+/** Creates a quaternion for a rotation around an axis. */
+export function quaternion(angle?: number, axis?: Vector3): Quaternion

package/types/math/rectangle.d.ts

@@ -0,0 +1,57 @@
+import type { Circle } from "./circle"
+import type { Point, PointInput } from "./point"
+
+/**
+ * The dimensions of a 3D object, as `[width, height, depth]`.
+ *
+ * `width` is the extent along `x`, `height` the extent along `y` and `depth` the
+ * extent along `z`. `height` and `depth` are **independent axes**, not halves of
+ * one screen dimension, so in a 2D game that plays on the `xy` plane a size reads
+ * as `v(w, h, 0)` — and an entity whose body is placed on the `xz` plane instead
+ * reads as `v(w, 0, h)`.
+ *
+ * When a renderer has to flatten both vertical axes onto the screen, it adds
+ * them: `@inglorious/renderer-2d` draws a rectangle `height + depth` tall. A
+ * collision shape never does — `intersectsRectangle` tests the two axes
+ * separately, which is why a body cannot collide with something that is merely
+ * "near it" on the other axis.
+ */
+export type Size = readonly [width: number, height: number, depth: number]
+
+/**
+ * Represents an axis-aligned rectangle.
+ *
+ * `position` is the point the box hangs off and `size` is its extent, so with
+ * the default centred anchor the position is the middle of the box. Set an
+ * `anchor` to describe the box by a different point, such as `[0, 0]` for its
+ * bottom-left corner, so that the box stands on its position.
+ */
+export interface Rectangle {
+  /** The center of the rectangle. */
+  position: Point
+  /** The dimensions of the rectangle. */
+  size: Size
+}
+
+/** Represents a rectangular platform. */
+export interface Platform {
+  /** The center of the platform. */
+  position: Point
+  /** The dimensions of the platform. */
+  size: Size
+}
+
+/** Checks whether a rectangle intersects a point. */
+export function intersectsPoint(
+  rectangle: Rectangle,
+  point: PointInput,
+): boolean
+
+/** Checks whether a rectangle intersects a circle. */
+export function intersectsCircle(rectangle: Rectangle, circle: Circle): boolean
+
+/** Checks whether two rectangles intersect. */
+export function intersectsRectangle(
+  rectangle1: Rectangle,
+  rectangle2: Rectangle,
+): boolean

package/types/math/rng.d.ts

@@ -0,0 +1,14 @@
+/** Returns `undefined` when no values are supplied. */
+export function choose(): undefined
+
+/** Chooses a random supplied value. */
+export function choose<T>(value: T, ...values: T[]): T
+
+/** Generates a random number for the supplied bounds and step. */
+export function random(): number
+export function random(to: number): number
+export function random(from: number, to: number): number
+export function random(from: number, to: number, step: number): number
+
+/** Generates a random value between two independent random values. */
+export function randomBinomial(): number

package/types/math/segment.d.ts

@@ -0,0 +1,23 @@
+import type { Circle } from "./circle"
+import type { Line } from "./line"
+import type { Point } from "./point"
+
+/** Represents a line segment between two points. */
+export interface Segment {
+  /** The starting point of the segment. */
+  from: Point
+  /** The ending point of the segment. */
+  to: Point
+}
+
+/** Calculates the coefficients of the line containing a segment. */
+export function coefficients(segment: Segment): Line
+
+/** Finds the closest point on a segment. */
+export function closestPoint(segment: Segment, point: Point): Point
+
+/** Calculates the shortest distance from a point to a segment. */
+export function distanceFromPoint(segment: Segment, point: Point): number
+
+/** Checks whether a segment intersects a circle. */
+export function intersectsCircle(segment: Segment, circle: Circle): boolean

package/types/math/statistics.d.ts

@@ -0,0 +1,11 @@
+/** Calculates the arithmetic mean of the supplied numbers. */
+export function mean(...numbers: number[]): number
+
+/** Alias for `mean`. */
+export const average: typeof mean
+
+/** Calculates the median of the supplied numbers. */
+export function median(...numbers: number[]): number
+
+/** Finds the most frequent supplied value. */
+export function mode(...values: unknown[]): string | undefined

package/types/math/triangle.d.ts

@@ -0,0 +1,5 @@
+/** Calculates the magnitude of the supplied numbers. */
+export function hypothenuse(...nums: number[]): number
+
+/** Alias for `hypothenuse`. */
+export const pythagoras: typeof hypothenuse

package/types/math/trigonometry.d.ts

@@ -0,0 +1,26 @@
+/** Calculates the arctangent of a quotient in radians. */
+export function atan2(y: number, x: number): number
+
+/** Calculates the cosine of an angle in radians. */
+export function cos(angle: number): number
+
+/** Alias for `cos`. */
+export const cosine: typeof cos
+
+/** Returns pi. */
+export function pi(): number
+
+/** Calculates the sine of an angle in radians. */
+export function sin(angle: number): number
+
+/** Alias for `sin`. */
+export const sine: typeof sin
+
+/** Converts radians to degrees. */
+export function toDegrees(radians: number): number
+
+/** Converts degrees to radians. */
+export function toRadians(degrees: number): number
+
+/** Normalizes an angle to the range [-π, π]. */
+export function toRange(angle: number): number

package/types/math/vector.d.ts

@@ -0,0 +1,219 @@
+/** Identifies a value created by the vector factory. */
+type IsVector = {
+  readonly __isVector__: true
+}
+
+/** A dynamically sized vector. */
+export type Vector<Coordinates extends readonly number[] = readonly number[]> =
+  IsVector & Coordinates
+
+/** A two-dimensional vector. */
+export type Vector2 = Vector<readonly [number, number]>
+
+/** A three-dimensional vector. */
+export type Vector3 = Vector<readonly [number, number, number]>
+
+/** A seven-dimensional vector. */
+export type Vector7 = Vector<
+  readonly [number, number, number, number, number, number, number]
+>
+
+/**
+ * The vector with every component at zero.
+ *
+ * Vectors are mutable, so copy it with `v(...ZERO_VECTOR)` before storing it
+ * where something writes to one.
+ */
+export const ZERO_VECTOR: Vector3
+
+/**
+ * The vector one unit long along the x axis.
+ *
+ * Vectors are mutable, so copy it with `v(...UNIT_VECTOR)` before storing it
+ * where something writes to one.
+ */
+export const UNIT_VECTOR: Vector3
+
+/** Returns the absolute value of each vector component. */
+export function abs<T extends Vector>(vector: T): T
+
+/** Alias for `sum`. */
+export const add: typeof sum
+
+/** Calculates the angle of a vector. */
+export function angle<T extends Vector>(vector: T): number
+
+/** Clamps a vector by scalar magnitude bounds. */
+export function clamp<T extends Vector>(vector: T, min: number, max: number): T
+
+/** Clamps a vector by component-wise vector bounds. */
+export function clamp<T extends Vector>(
+  vector: T,
+  min: readonly number[],
+  max: readonly number[],
+): T
+
+/** Returns the vector conjugate. */
+export function conjugate<T extends Vector>(vector: T): T
+
+/** Creates a 3D vector from a magnitude and angle. */
+export function createVector(magnitude: number, angle: number): Vector3
+
+/** Computes the cross product of same-width 3D or 7D vectors. */
+export function cross<T extends Vector3 | Vector7>(...vectors: [T, ...T[]]): T
+
+/** Computes the distance between same-width 2D or 3D vectors. */
+export function distance<T extends Vector2 | Vector3>(
+  ...vectors: [T, ...T[]]
+): number
+
+/** Divides same-width vectors component-wise. */
+export function divide<T extends Vector2 | Vector3>(...vectors: [T, ...T[]]): T
+
+/** Divides each vector component by a scalar. */
+export function divide<T extends Vector2 | Vector3>(
+  vector: T,
+  scalar: number,
+): T
+
+/** Divides a scalar by each vector component. */
+export function divideBy<T extends Vector>(scalar: number, vector: T): T
+
+/** Computes the dot product of same-width 2D or 3D vectors. */
+export function dot<T extends Vector2 | Vector3>(
+  ...vectors: [T, ...T[]]
+): number
+
+/** Converts a 2D vector to a 3D vector. */
+export function from2D(vector: Vector2): Vector3
+
+/** Creates a 3D unit vector from an angle. */
+export function fromAngle(angle: number): Vector3
+
+/** Alias for `multiply`. */
+export const hadamard: typeof multiply
+
+/** Checks whether a value is a vector. */
+export function isVector<T>(value: T): value is T & Vector
+
+/** Calculates a vector's magnitude. */
+export function magnitude<T extends Vector>(vector: T): number
+
+/** Alias for `magnitude`. */
+export const length: typeof magnitude
+
+/** Applies a component-wise modulus to same-width vectors. */
+export function mod<T extends Vector2 | Vector3>(...vectors: [T, ...T[]]): T
+
+/** Applies a modulus to each vector component. */
+export function mod<T extends Vector2 | Vector3>(vector: T, divisor: number): T
+
+/** Applies a scalar modulus to each vector component. */
+export function modOf<T extends Vector>(scalar: number, vector: T): T
+
+/** Multiplies same-width vectors component-wise. */
+export function multiply<T extends Vector2 | Vector3>(
+  ...vectors: [T, ...T[]]
+): T
+
+/** Multiplies each vector component by a scalar. */
+export function multiply<T extends Vector2 | Vector3>(
+  vector: T,
+  scalar: number,
+): T
+
+/** Normalizes a vector to unit magnitude. */
+/**
+ * Flips the direction of every component.
+ */
+export function negate<T extends Vector>(vector: T): T
+
+export function normalize<T extends Vector>(vector: T): T
+
+/** Alias for `power`. */
+export const pow: typeof power
+
+/** Raises same-width vectors component-wise to powers. */
+export function power<T extends Vector2 | Vector3>(...vectors: [T, ...T[]]): T
+
+/** Raises each vector component to a power. */
+export function power<T extends Vector2 | Vector3>(
+  vector: T,
+  exponent: number,
+): T
+
+/** Raises a scalar to each vector component. */
+export function powerOf<T extends Vector>(scalar: number, vector: T): T
+
+/**
+ * Draws a random vector, taking each component from its own range.
+ */
+export function randomVector(
+  low?: readonly number[],
+  high?: readonly number[],
+): Vector3
+
+/** Alias for `mod`. */
+export const remainder: typeof mod
+
+/** Rotates a 2D vector. */
+export function rotate<T extends Vector2>(vector: T, angle: number): T
+
+/** Rotates a 3D vector around the Y-axis. */
+export function rotate<T extends Vector3>(vector: T, angle: number): T
+
+/** Alias for `multiply`. */
+export const scale: typeof multiply
+
+/** Sets a vector's angle while preserving its magnitude. */
+export function setAngle(vector: Vector, angle: number): Vector3
+
+/** Alias for `setMagnitude`. */
+export const setLength: typeof setMagnitude
+
+/** Sets a vector's magnitude while preserving its direction. */
+export function setMagnitude<T extends Vector>(vector: T, length: number): T
+
+/** Rotates vector components by an index. */
+export function shift<T extends Vector>(vector: T, index: number): T
+
+/** Snaps each vector component to a precision. */
+export function snap<T extends Vector>(vector: T, precision?: number): T
+
+/** Subtracts same-width vectors component-wise. */
+export function subtract<T extends Vector2 | Vector3>(
+  ...vectors: [T, ...T[]]
+): T
+
+/** Sums same-width vectors component-wise. */
+export function sum<T extends Vector2 | Vector3>(...vectors: [T, ...T[]]): T
+
+/** Alias for `multiply`. */
+export const times: typeof multiply
+
+/** Converts a 3D vector to a 2D vector. */
+export function to2D(vector: Vector3): Vector2
+
+/** Converts 2D polar coordinates to Cartesian coordinates. */
+export function toCartesian<T extends Vector2>(vector: T): T
+
+/** Converts a 3D Cartesian vector to cylindrical coordinates. */
+export function toCylindrical<T extends Vector3>(vector: T): T
+
+/** Converts a 2D Cartesian vector to polar coordinates. */
+export function toPolar<T extends Vector2>(vector: T): T
+
+/** Formats a vector as a string. */
+export function toString<T extends Vector>(vector: T, decimals?: number): string
+
+/** Converts a 3D Cartesian vector to spherical coordinates. */
+export function toSpherical<T extends Vector3>(vector: T): T
+
+/** Creates a 3D unit vector. */
+export function unit(angle?: number): Vector3
+
+/** Alias for `cross`. */
+export const vectorProduct: typeof cross
+
+/** Creates a 3D zero vector. */
+export function zero(): Vector3

package/types/physics/acceleration.d.ts

@@ -0,0 +1,24 @@
+import type { Vector3 } from "../math/vector"
+
+export interface AccelerationParams {
+  acceleration?: Vector3
+  friction?: number
+  maxAcceleration: number
+  maxSpeed: number
+  position?: Vector3
+  velocity?: Vector3
+}
+
+export interface AccelerationResult {
+  acceleration: Vector3
+  position: Vector3
+  velocity: Vector3
+}
+
+/**
+ * Applies acceleration to an object using Euler integration.
+ */
+export function applyAcceleration(
+  params: AccelerationParams,
+  dt?: number,
+): AccelerationResult

package/types/physics/friction.d.ts

@@ -0,0 +1,11 @@
+import type { Vector3 } from "../math/vector"
+
+export interface FrictionParams {
+  friction: number
+  velocity?: Vector3
+}
+
+/**
+ * Applies friction to a velocity vector.
+ */
+export function applyFriction(params: FrictionParams, dt?: number): Vector3

package/types/physics/gravity.d.ts

@@ -0,0 +1,20 @@
+import type { Vector3 } from "../math/vector"
+
+export interface GravityParams {
+  maxJump?: number
+  maxLeap?: number
+  maxSpeed?: number
+  position?: Vector3
+  vy?: number
+}
+
+export interface GravityResult {
+  ay: number
+  position: Vector3
+  vy: number
+}
+
+/**
+ * Applies gravity to an object based on its current velocity and position.
+ */
+export function applyGravity(params: GravityParams, dt?: number): GravityResult

package/types/physics/index.d.ts

@@ -0,0 +1,5 @@
+export * as acceleration from "./acceleration"
+export * as friction from "./friction"
+export * as gravity from "./gravity"
+export * as jump from "./jump"
+export * as velocity from "./velocity"

package/types/physics/jump.d.ts

@@ -0,0 +1,10 @@
+export interface JumpParams {
+  maxJump?: number
+  maxLeap?: number
+  maxSpeed?: number
+}
+
+/**
+ * Calculates the vertical velocity of a jump.
+ */
+export function jump(params: JumpParams): number

package/types/physics/velocity.d.ts

@@ -0,0 +1,20 @@
+import type { Vector3 } from "../math/vector"
+
+export interface VelocityParams {
+  maxSpeed?: number
+  position?: Vector3
+  velocity?: Vector3
+}
+
+export interface VelocityResult {
+  position: Vector3
+  velocity: Vector3
+}
+
+/**
+ * Applies velocity to a position.
+ */
+export function applyVelocity(
+  params: VelocityParams,
+  dt?: number,
+): VelocityResult

package/types/v.d.ts

@@ -1,4 +1,4 @@
-import { Vector } from "./math"
+import type { Vector } from "./math/vector"
 
 /**
  * Ensures that a given value is a vector.
@@ -12,7 +12,9 @@ import { Vector } from "./math"
  * @param {T} value The value to check and potentially convert.
  * @returns {T extends number[] ? Vector : T} The value as a vector, or the original value if no conversion was needed.
  */
-export function ensureV<T>(value: T): T extends number[] ? Vector : T
+export function ensureV<T>(
+  value: T,
+): T extends readonly number[] ? Vector<T> : T
 
 /**
  * A utility function to create a vector from a list of coordinates.
@@ -22,4 +24,6 @@ export function ensureV<T>(value: T): T extends number[] ? Vector : T
  * @param {...number} coords - The coordinates of the vector.
  * @returns {Vector} The created vector.
  */
-export function v(...coords: number[]): Vector
+export function v<Coordinates extends number[]>(
+  ...coords: Coordinates
+): Vector<Coordinates>