@inglorious/engine 0.1.1 → 0.3.0

package/src/utils/math/linear-algebra/vectors.test.js

@@ -1,65 +0,0 @@
-import { expect, test } from "vitest"
-
-import { cross, distance, dot, subtract, sum } from "./vectors.js"
-
-test("it should compute the cross product between two vectors (aka vectorProduct)", () => {
-  const vector1 = [1, 2, 3]
-  const vector2 = [4, 5, 6]
-  const expectedResult = [-3, 6, -3]
-
-  expect(cross(vector1, vector2)).toStrictEqual(expectedResult)
-})
-
-test("it should compute the cross product of multiple vectors (aka vectorProduct)", () => {
-  const vectors = [
-    [1, 2, 3],
-    [4, 5, 6],
-    [7, 8, 9],
-  ]
-  const expectedResult = [78, 6, -66]
-
-  expect(cross(...vectors)).toStrictEqual(expectedResult)
-})
-
-test("it should compute the distance between multiple vectors", () => {
-  const vectors = [
-    [0, 0, 0],
-    [4, 0, 3],
-  ]
-  const expectedResult = 5
-
-  expect(distance(...vectors)).toStrictEqual(expectedResult)
-})
-
-test("it should compute the dot product of multiple vectors (aka scalarProduct)", () => {
-  const vectors = [
-    [1, 2, 3],
-    [4, 5, 6],
-    [7, 8, 9],
-  ]
-  const expectedResult = 270
-
-  expect(dot(...vectors)).toStrictEqual(expectedResult)
-})
-
-test("it should subtract multiple vectors", () => {
-  const vectors = [
-    [1, 2, 3],
-    [4, 5, 6],
-    [7, 8, 9],
-  ]
-  const expectedResult = [-10, -11, -12]
-
-  expect(subtract(...vectors)).toStrictEqual(expectedResult)
-})
-
-test("it should sum multiple vectors (aka add)", () => {
-  const vectors = [
-    [1, 2, 3],
-    [4, 5, 6],
-    [7, 8, 9],
-  ]
-  const expectedResult = [12, 15, 18]
-
-  expect(sum(...vectors)).toStrictEqual(expectedResult)
-})

package/src/utils/math/numbers.js

@@ -1,90 +0,0 @@
-const DEFAULT_PRECISION = 1 // Default precision used for snapping numbers.
-const DEFAULT_TOLERANCE = 0.1 // Default tolerance used for comparing numbers.
-const SQUARE_ROOT = 0.5 // Exponent used for calculating square roots.
-
-/**
- * Returns the absolute value of a number.
- * @param {number} num - The number to get the absolute value of.
- * @returns {number} The absolute value of the input number.
- */
-export function abs(num) {
-  return Math.abs(num)
-}
-
-/**
- * Clamps a number within the inclusive range specified by min and max.
- * @param {number} num - The number to clamp.
- * @param {number} min - The minimum value.
- * @param {number} max - The maximum value.
- * @returns {number} The clamped value.
- */
-export function clamp(num, min, max) {
-  if (num < min) {
-    return min
-  }
-
-  if (num > max) {
-    return max
-  }
-
-  return num
-}
-
-/**
- * Checks if two numbers are close to each other within a given tolerance.
- * @param {number} num1 - The first number.
- * @param {number} num2 - The second number.
- * @param {number} [tolerance=DEFAULT_TOLERANCE] - The tolerance for comparison.
- * @returns {boolean} True if the numbers are close, false otherwise.
- */
-export function isClose(num1, num2, tolerance = DEFAULT_TOLERANCE) {
-  return abs(num1 - num2) <= tolerance
-}
-
-/**
- * Computes the modulus of two numbers, ensuring a positive result.
- * @param {number} dividend - The number to be divided.
- * @param {number} divisor - The number to divide by.
- * @returns {number} The modulus result.
- */
-export function mod(dividend, divisor) {
-  return ((dividend % divisor) + divisor) % divisor
-}
-
-/**
- * Snaps a number to the nearest multiple of a given precision.
- * @param {number} num - The number to snap.
- * @param {number} [precision=DEFAULT_PRECISION] - The precision to snap to.
- * @returns {number} The snapped value.
- */
-export function snap(num, precision = DEFAULT_PRECISION) {
-  return Math.round(num / precision) * precision
-}
-
-/**
- * Alias for the `mod` function.
- * @type {typeof mod}
- */
-export const remainder = mod
-
-/**
- * Returns the sign of a number: 1 for positive, -1 for negative, and 0 for zero.
- * @param {number} num - The number to get the sign of.
- * @returns {number} The sign of the number.
- */
-export function sign(num) {
-  if (!num) {
-    return num
-  }
-
-  return num / abs(num)
-}
-
-/**
- * Computes the square root of a number.
- * @param {number} num - The number to compute the square root of.
- * @returns {number} The square root of the number.
- */
-export function sqrt(num) {
-  return num ** SQUARE_ROOT
-}

package/src/utils/math/numbers.test.js

@@ -1,137 +0,0 @@
-import { expect, test } from "vitest"
-
-import { abs, clamp, isClose, mod, sign, snap, sqrt } from "./numbers.js"
-
-test("it should return the same number if already positive", () => {
-  const num = 42
-  const expectedResult = 42
-
-  expect(abs(num)).toBe(expectedResult)
-})
-
-test("it should return the absolute value of a number", () => {
-  const num = -42
-  const expectedResult = 42
-
-  expect(abs(num)).toBe(expectedResult)
-})
-
-test("it should not clamp a number in the range", () => {
-  const num = 42
-  const min = 0
-  const max = 100
-  const expectedResult = 42
-
-  expect(clamp(num, min, max)).toBe(expectedResult)
-})
-
-test("it should clamp a number too small", () => {
-  const num = -42
-  const min = 0
-  const max = 100
-  const expectedResult = 0
-
-  expect(clamp(num, min, max)).toBe(expectedResult)
-})
-
-test("it should clamp a number too big", () => {
-  const num = 142
-  const min = 0
-  const max = 100
-  const expectedResult = 100
-
-  expect(clamp(num, min, max)).toBe(expectedResult)
-})
-
-test("it should check if two numbers are close given some tolerance", () => {
-  const num1 = 42
-  const num2 = 42.1
-  const tolerance = 0.2
-  const expectedResult = true
-
-  expect(isClose(num1, num2, tolerance)).toBe(expectedResult)
-})
-
-test("it should return zero if dividend equals divisor", () => {
-  const num = 2
-  const divisor = 2
-  const expectedResult = 0
-
-  expect(mod(num, divisor)).toBe(expectedResult)
-})
-
-test("it should return one if number is odd", () => {
-  const num = 3
-  const divisor = 2
-  const expectedResult = 1
-
-  expect(mod(num, divisor)).toBe(expectedResult)
-})
-
-test("it should return one if negative number turns to positive one", () => {
-  const num = -3
-  const divisor = 2
-  const expectedResult = 1
-
-  expect(mod(num, divisor)).toBe(expectedResult)
-})
-
-test("it should convert a float number greater than 1 to a range between -1 and 1", () => {
-  const num = 5 / 4
-  const divisor = 1
-  const expectedResult = 1 / 4
-
-  expect(mod(num, divisor)).toBe(expectedResult)
-})
-
-test("it should convert a float number greater than 2 to a range between -1 and 1", () => {
-  const num = 13 / 4
-  const divisor = 1
-  const expectedResult = 1 / 4
-
-  expect(mod(num, divisor)).toBe(expectedResult)
-})
-
-test("it should convert a negative float number to a range between -1 and 1", () => {
-  const num = -5 / 4
-  const divisor = 1
-  const expectedResult = 3 / 4
-
-  expect(mod(num, divisor)).toBe(expectedResult)
-})
-
-test("it should return one if number is positive", () => {
-  const num = 42
-  const expectedResult = 1
-
-  expect(sign(num)).toBe(expectedResult)
-})
-
-test("it should return minus one if number is negative", () => {
-  const num = -42
-  const expectedResult = -1
-
-  expect(sign(num)).toBe(expectedResult)
-})
-
-test("it should return the number itself if the sign is zero", () => {
-  const num = 0
-  const expectedResult = 0
-
-  expect(sign(num)).toBe(expectedResult)
-})
-
-test("it should snap the number to the given precision", () => {
-  const num = 42
-  const precision = 10
-  const expectedResult = 40
-
-  expect(snap(num, precision)).toBe(expectedResult)
-})
-
-test("it should compute the square root of the number", () => {
-  const num = 9
-  const expectedResult = 3
-
-  expect(sqrt(num)).toBe(expectedResult)
-})

package/src/utils/math/rng.js

@@ -1,44 +0,0 @@
-/* eslint-disable no-magic-numbers */
-
-/**
- * Generates a random number.
- * - If no arguments are provided, returns a random float between 0 (inclusive) and 1 (exclusive).
- * - If one argument is provided, returns a random integer between 0 and the given number (inclusive).
- * - If two or more arguments are provided, returns a random integer within the specified range and step.
- *
- * @param {number} [to] - The upper bound (inclusive) if one argument is provided.
- * @param {number} [from] - The lower bound (inclusive) if two arguments are provided.
- * @param {number} [step=1] - The step size if two or more arguments are provided.
- * @returns {number} A random number based on the provided arguments.
- */
-export function random(...args) {
-  let step, from, to
-
-  if (!args.length) {
-    return Math.random()
-  }
-
-  if (args.length === 1) {
-    step = 1
-    from = 0
-    to = args[0] + 1
-  }
-
-  if (args.length > 1) {
-    step = args[2] ?? 1
-    from = args[0] / step
-    to = (args[1] + 1) / step
-  }
-
-  return Math.floor(Math.random() * (to - from) + from) * step
-}
-
-/**
- * Generates a random binomial value.
- * The result is the difference between two random numbers.
- *
- * @returns {number} A random binomial value.
- */
-export function randomBinomial() {
-  return random() - random()
-}

package/src/utils/math/rng.test.js

@@ -1,39 +0,0 @@
-import { expect, test } from "vitest"
-
-import { random, randomBinomial } from "./rng.js"
-
-test("it should create a random number in the range [0, 1)", () => {
-  const randomNumber = random()
-
-  expect(randomNumber).toBeGreaterThanOrEqual(0)
-  expect(randomNumber).toBeLessThan(1)
-})
-
-test("it should create a random integer in the range [0, 6]", () => {
-  const randomNumber = random(6)
-
-  expect(randomNumber).toBeGreaterThanOrEqual(0)
-  expect(randomNumber).toBeLessThanOrEqual(6)
-})
-
-test("it should create a random integer in the range [1, 6]", () => {
-  const randomNumber = random(1, 6)
-
-  expect(randomNumber).toBeGreaterThanOrEqual(1)
-  expect(randomNumber).toBeLessThanOrEqual(6)
-})
-
-test("it should create a random even number in the range [2, 6]", () => {
-  const randomNumber = random(2, 6, 2)
-
-  expect(randomNumber).toBeGreaterThanOrEqual(1)
-  expect(randomNumber).toBeLessThanOrEqual(6)
-  expect(randomNumber % 2).toBe(0)
-})
-
-test("it should create a random number in the range (-1, 1)", () => {
-  const randomNumber = randomBinomial()
-
-  expect(randomNumber).toBeGreaterThan(-1)
-  expect(randomNumber).toBeLessThan(1)
-})

package/src/utils/math/statistics.js

@@ -1,43 +0,0 @@
-const HALF = 2
-const AROUND_INDEX = 1
-const NO_OCCURRENCES = 0
-
-export const average = mean
-
-export function mean(...numbers) {
-  return numbers.reduce((acc, num) => acc + num) / numbers.length
-}
-
-export function median(...numbers) {
-  const sortedNumbers = numbers.toSorted()
-  const middleIndex = numbers.length / HALF
-
-  if (Number.isInteger(middleIndex)) {
-    return mean(
-      ...sortedNumbers.slice(
-        middleIndex - AROUND_INDEX,
-        middleIndex + AROUND_INDEX,
-      ),
-    )
-  }
-
-  return sortedNumbers[Math.floor(middleIndex)]
-}
-
-export function mode(...values) {
-  const occurrences = values.reduce((acc, value) => {
-    acc[value] = acc[value] ?? NO_OCCURRENCES
-    acc[value]++
-    return acc
-  }, {})
-
-  return Object.entries(occurrences).reduce(
-    (acc, [value, occurrences]) => {
-      if (occurrences > acc.occurrences) {
-        acc = { value, occurrences }
-      }
-      return acc
-    },
-    { occurrences: 0 },
-  ).value
-}

package/src/utils/math/statistics.test.js

@@ -1,47 +0,0 @@
-import { expect, test } from "vitest"
-
-import { mean, median, mode } from "./statistics.js"
-
-test("it should return the average of the given numbers", () => {
-  const numbers = [1, 3, 2]
-  const expectedResult = 2
-
-  expect(mean(...numbers)).toBeCloseTo(expectedResult)
-})
-
-test("it should return the median value from an odd list of numbers", () => {
-  const numbers = [1, 3, 2]
-  const expectedResult = 2
-
-  expect(median(...numbers)).toBe(expectedResult)
-})
-
-test("it should return the median value from an even list of numbers", () => {
-  const numbers = [1, 3, 2, 4]
-  const expectedResult = 2.5
-
-  expect(median(...numbers)).toBe(expectedResult)
-})
-
-test("it should find the mode of a list of values", () => {
-  const values = [
-    "rarely",
-    "seldom",
-    "seldom",
-    "sometimes",
-    "sometimes",
-    "sometimes",
-    "often",
-    "often",
-    "often",
-    "often",
-    "always",
-    "always",
-    "always",
-    "always",
-    "always",
-  ]
-  const expectedResult = "always"
-
-  expect(mode(...values)).toBe(expectedResult)
-})

package/src/utils/math/trigonometry.js

@@ -1,89 +0,0 @@
-import { mod } from "./numbers.js"
-
-const HALF_CIRCLE_IN_DEGRESS = 180 // Half-circle in degrees (180°)
-const FULL_CIRCLE = 2 // Full circle multiplier for radians (2π)
-
-/**
- * Calculates the arctangent of the quotient of its arguments.
- * @param {number} y - The y-coordinate.
- * @param {number} x - The x-coordinate.
- * @returns {number} The angle in radians.
- */
-export function atan2(y, x) {
-  return Math.atan2(y, x)
-}
-
-/**
- * Calculates the cosine of an angle.
- * @param {number} angle - The angle in radians.
- * @returns {number} The cosine of the angle.
- */
-export function cos(angle) {
-  return Math.cos(angle)
-}
-
-/**
- * Alias for the `cos` function.
- * @type {typeof cos}.
- */
-export const cosine = cos
-
-/**
- * Returns the value of π (pi).
- * @returns {number} The value of π.
- */
-export function pi() {
-  return Math.PI
-}
-
-/**
- * Calculates the sine of an angle.
- * @param {number} angle - The angle in radians.
- * @returns {number} The sine of the angle.
- */
-export function sin(angle) {
-  return Math.sin(angle)
-}
-
-/**
- * Alias for the `sin` function.
- * @type {typeof sin}.
- */
-export const sine = sin
-
-/**
- * Converts an angle from radians to degrees.
- * @param {number} radians - The angle in radians.
- * @returns {number} The angle in degrees.
- */
-export function toDegrees(radians) {
-  return (radians * HALF_CIRCLE_IN_DEGRESS) / pi()
-}
-
-/**
- * Converts an angle from degrees to radians.
- * @param {number} degrees - The angle in degrees.
- * @returns {number} The angle in radians.
- */
-export function toRadians(degrees) {
-  return (degrees * pi()) / HALF_CIRCLE_IN_DEGRESS
-}
-
-/**
- * Normalizes an angle to the range [-π, π].
- * @param {number} angle - The angle in radians.
- * @returns {number} The normalized angle in radians.
- */
-export function toRange(angle) {
-  if (angle > -pi() && angle < pi()) {
-    return angle
-  }
-
-  angle = mod(angle, FULL_CIRCLE * pi())
-
-  if (angle > pi()) {
-    angle -= FULL_CIRCLE * pi()
-  }
-
-  return angle
-}

package/src/utils/math/trigonometry.test.js

@@ -1,52 +0,0 @@
-import { expect, test } from "vitest"
-
-import { pi, toDegrees, toRadians, toRange } from "./trigonometry.js"
-
-test("it should convert radians to degrees", () => {
-  const radians = pi() / 4
-  const expectedResult = 45
-
-  expect(toDegrees(radians)).toBeCloseTo(expectedResult)
-})
-
-test("it should convert radians to degrees", () => {
-  const degrees = 45
-  const expectedResult = pi() / 4
-
-  expect(toRadians(degrees)).toBeCloseTo(expectedResult)
-})
-
-test("it should convert an angle greater than pi to a range between -pi and pi", () => {
-  const angle = (5 / 4) * pi()
-  const expectedResult = (-3 / 4) * pi()
-
-  expect(toRange(angle)).toBeCloseTo(expectedResult)
-})
-
-test("it should convert an angle greater than 2pi to a range between -pi and pi", () => {
-  const angle = (13 / 4) * pi()
-  const expectedResult = (-3 / 4) * pi()
-
-  expect(toRange(angle)).toBeCloseTo(expectedResult)
-})
-
-test("it should convert an angle less than pi to a range between -pi and pi", () => {
-  const angle = (-5 / 4) * pi()
-  const expectedResult = (3 / 4) * pi()
-
-  expect(toRange(angle)).toBeCloseTo(expectedResult)
-})
-
-test("it should convert an angle less than 2pi to a range between -pi and pi", () => {
-  const angle = (-13 / 4) * pi()
-  const expectedResult = (3 / 4) * pi()
-
-  expect(toRange(angle)).toBeCloseTo(expectedResult)
-})
-
-test("it should not convert an angle already in the range [-pi, pi]", () => {
-  const angle = (3 / 4) * pi()
-  const expectedResult = (3 / 4) * pi()
-
-  expect(toRange(angle)).toBe(expectedResult)
-})

package/src/utils/physics/acceleration.js

@@ -1,63 +0,0 @@
-/**
- * @typedef {import('@inglorious/utils/math/linear-algebra/types').Vector3} Vector3
- */
-
-import {
-  clamp,
-  multiply,
-  zero,
-} from "@inglorious/utils/math/linear-algebra/vector.js"
-import { sum } from "@inglorious/utils/math/linear-algebra/vectors.js"
-
-import { applyFriction } from "./friction.js"
-
-const DEFAULT_OPTIONS = { dt: 0 } // Default options for the applyAcceleration function.
-const NO_FRICTION = 0 // No friction constant.
-const HALF_ACCELERATION = 0.5 // Half of the acceleration factor used in position calculation.
-
-/**
- * Applies acceleration to an object using Euler's integration method.
- *
- * Euler's Integration:
- * v += a * dt
- * p += v * dt + 1/2 * a * dt * dt
- *
- * @param {Object} params - The parameters for the function.
- * @param {number} params.maxAcceleration - The maximum allowed acceleration.
- * @param {number} params.maxSpeed - The maximum allowed speed.
- * @param {Vector3} [params.acceleration] - The current acceleration vector. Defaults to a zero vector.
- * @param {Vector3} [params.velocity] - The current velocity vector. Defaults to a zero vector.
- * @param {Vector3} [params.position] - The current position vector. Defaults to a zero vector.
- * @param {number} params.friction - The friction coefficient. Defaults to 0.
- * @param {Object} [options=DEFAULT_OPTIONS] - Additional options.
- * @param {number} options.dt - The time delta for the calculation. Defaults to 0.
- * @returns {Object} - The updated acceleration, velocity, and position.
- */
-export function applyAcceleration(params, options = DEFAULT_OPTIONS) {
-  let {
-    maxAcceleration,
-    maxSpeed,
-    acceleration = zero(),
-    velocity = zero(),
-    position = zero(),
-    friction = NO_FRICTION,
-  } = params
-  const { dt } = options
-
-  // Clamp acceleration to the maximum allowed range
-  acceleration = clamp(acceleration, -maxAcceleration, maxAcceleration)
-
-  // Update velocity with acceleration and clamp to the maximum allowed speed
-  velocity = sum(velocity, multiply(acceleration, dt))
-  velocity = clamp(velocity, -maxSpeed, maxSpeed)
-  velocity = applyFriction({ velocity, friction }, options)
-
-  // Update position with velocity and acceleration
-  position = sum(
-    position,
-    multiply(velocity, dt),
-    multiply(acceleration, HALF_ACCELERATION * dt * dt),
-  )
-
-  return { acceleration, velocity, position }
-}

package/src/utils/physics/friction.js

@@ -1,30 +0,0 @@
-/**
- * @typedef {import('@inglorious/utils/math/linear-algebra/types').Vector3} Vector3
- */
-
-import {
-  magnitude,
-  setMagnitude,
-  zero,
-} from "@inglorious/utils/math/linear-algebra/vector.js"
-
-const DEFAULT_OPTIONS = { dt: 0 } // Default options for the applyFriction function.
-const NO_FRICTION = 0 // No friction constant.
-
-/**
- * Applies friction to a given velocity vector.
- *
- * @param {Object} params - The parameters for the function.
- * @param {Vector3} params.velocity - The velocity vector. Defaults to a zero vector.
- * @param {number} params.friction - The friction coefficient. Defaults to 0.
- * @param {Object} [options=DEFAULT_OPTIONS] - Additional options.
- * @param {number} options.dt - The time delta for the calculation. Defaults to 0.
- * @returns {Vector3} - The updated velocity vector after applying friction.
- */
-export function applyFriction(params, options = DEFAULT_OPTIONS) {
-  let { velocity = zero(), friction = NO_FRICTION } = params
-  const { dt } = options
-  const length = magnitude(velocity)
-
-  return length ? setMagnitude(velocity, length - friction * dt) : velocity
-}