@inglorious/engine 0.1.0 → 0.2.0

package/src/utils/math/trigonometry.js

@@ -1,89 +1,89 @@
-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
-}
+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 +1,52 @@
-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)
-})
+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 +1,61 @@
-/**
- * @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 }
-}
+/**
+ * @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_DT = 1 // Default time delta 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 {number} dt - The time delta for the calculation. Defaults to 0.
+ * @returns {Object} - The updated acceleration, velocity, and position.
+ */
+export function applyAcceleration(params, dt = DEFAULT_DT) {
+  let {
+    maxAcceleration,
+    maxSpeed,
+    acceleration = zero(),
+    velocity = zero(),
+    position = zero(),
+    friction = NO_FRICTION,
+  } = params
+
+  // 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 }, dt)
+
+  // 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 +1,28 @@
-/**
- * @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
-}
+/**
+ * @typedef {import('@inglorious/utils/math/linear-algebra/types').Vector3} Vector3
+ */
+
+import {
+  magnitude,
+  setMagnitude,
+  zero,
+} from "@inglorious/utils/math/linear-algebra/vector.js"
+
+const DEFAULT_DT = 1 // Default time delta 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 {number} dt - The time delta for the calculation. Defaults to 1.
+ * @returns {Vector3} - The updated velocity vector after applying friction.
+ */
+export function applyFriction(params, dt = DEFAULT_DT) {
+  let { velocity = zero(), friction = NO_FRICTION } = params
+  const length = magnitude(velocity)
+
+  return length ? setMagnitude(velocity, length - friction * dt) : velocity
+}

package/src/utils/physics/friction.test.js

@@ -1,44 +1,42 @@
-import { expect, test } from "vitest"
-
-import { zero } from "../math/linear-algebra/vector.js"
-import { applyFriction } from "./friction.js"
-
-test("it should apply no friction on no velocity", () => {
-  const friction = 250
-  const dt = 1
-
-  expect(applyFriction({ friction }, { dt })).toStrictEqual(zero())
-})
-
-test("it should apply no friction if no friction is passed", () => {
-  const velocity = [0, 0, 0]
-  const dt = 1
-
-  expect(applyFriction({ velocity }, { dt })).toBe(velocity)
-})
-
-test("it should apply no friction if no time passed", () => {
-  const velocity = [0, 0, 0]
-  const friction = 5
-
-  expect(applyFriction({ velocity, friction })).toBe(velocity)
-})
-
-test("it should apply friction to some velocity", () => {
-  const velocity = [8, 0, 6]
-  const friction = 5
-  const dt = 1
-  const expectedResult = [4, 0, 3]
-
-  expect(applyFriction({ velocity, friction }, { dt })).toStrictEqual(
-    expectedResult,
-  )
-})
-
-test("it should stop movement when friction is equal to velocity", () => {
-  const velocity = [8, 0, 6]
-  const friction = 5
-  const dt = 2
-
-  expect(applyFriction({ velocity, friction }, { dt })).toStrictEqual(zero())
-})
+import { expect, test } from "vitest"
+
+import { zero } from "../math/linear-algebra/vector.js"
+import { applyFriction } from "./friction.js"
+
+test("it should apply friction to some velocity", () => {
+  const velocity = [8, 0, 6]
+  const friction = 5
+  const expectedResult = [4, 0, 3]
+
+  expect(applyFriction({ velocity, friction })).toStrictEqual(expectedResult)
+})
+
+test("it should stop movement when friction is equal to velocity", () => {
+  const velocity = [8, 0, 6]
+  const friction = 5
+  const dt = 2
+
+  expect(applyFriction({ velocity, friction }, dt)).toStrictEqual(zero())
+})
+
+test("it should apply no friction on no velocity", () => {
+  const velocity = zero()
+  const friction = 5
+
+  expect(applyFriction({ velocity, friction })).toBe(velocity)
+})
+
+test("it should apply no friction if no friction is passed", () => {
+  const velocity = [8, 0, 6]
+  const friction = 0
+
+  expect(applyFriction({ velocity, friction })).toStrictEqual(velocity)
+})
+
+test("it should apply no friction if no time passed", () => {
+  const velocity = [8, 0, 6]
+  const friction = 5
+  const dt = 0
+
+  expect(applyFriction({ velocity, friction }, dt)).toStrictEqual(velocity)
+})