@inglorious/engine 0.1.0

package/src/utils/math/geometry/point.js

@@ -0,0 +1,71 @@
+/**
+ * @typedef {import("./types").Point} Point
+ * @typedef {import("./types").Line} Line
+ * @typedef {import("./types").Circle} Circle
+ * @typedef {import("./types").Rectangle} Rectangle
+ */
+
+const SQUARED = 2
+const HALF = 2
+
+import { distanceFromPoint } from "./line.js"
+
+/**
+ * Calculates the distance from a point to a line.
+ * @param {Point} point - The point as a 3D coordinate [x, y, z].
+ * @param {Line} line - The line to calculate the distance from.
+ * @returns {number} The distance from the point to the line.
+ */
+export function getDistanceFromLine(point, line) {
+  return distanceFromPoint(line, point)
+}
+
+/**
+ * Checks if two points intersect.
+ * @param {Point} point1 - The first point as a 3D coordinate [x, y, z].
+ * @param {Point} point2 - The second point as a 3D coordinate [x, y, z].
+ * @returns {boolean} True if the points intersect, false otherwise.
+ */
+export function intersectsPoint(point1, point2) {
+  const [x1, y1, z1] = point1
+  const [x2, y2, z2] = point2
+  return x1 === x2 && y1 === y2 && z1 === z2
+}
+
+/**
+ * Checks if a point intersects with a circle.
+ * @param {Point} point - The point as a 3D coordinate [x, y, z].
+ * @param {Circle} circle - The circle with a position and radius.
+ * @returns {boolean} True if the point intersects the circle, false otherwise.
+ */
+export function intersectsCircle(point, circle) {
+  const [x, y, z] = point
+  const [left, top, front] = circle.position
+  const radius = circle.radius
+
+  return (
+    (x - left) ** SQUARED + (y - top) ** SQUARED + (z - front) ** SQUARED <=
+    radius ** SQUARED
+  )
+}
+
+/**
+ * Checks if a point intersects with a rectangle.
+ * @param {Point} point - The point as a 3D coordinate [x, y, z].
+ * @param {Rectangle} rectangle - The rectangle with a position and size.
+ * @returns {boolean} True if the point intersects the rectangle, false otherwise.
+ */
+export function intersectsRectangle(point, rectangle) {
+  const [x, y, z] = point
+  const [left, top, front] = rectangle.position
+  const [width, height, depth] = rectangle.size
+
+  return (
+    x >= left - width / HALF &&
+    x <= left + width / HALF &&
+    y >= top - height / HALF &&
+    y <= top + height / HALF &&
+    z >= front - depth / HALF &&
+    z <= front + depth / HALF
+  )
+}

package/src/utils/math/geometry/point.test.js

@@ -0,0 +1,81 @@
+import { expect, test } from "vitest"
+
+import {
+  intersectsCircle,
+  intersectsPoint,
+  intersectsRectangle,
+} from "./point.js"
+
+test("it should prove that two equal points intersect", () => {
+  const point1 = [1.5, 1.5, 0]
+  const point2 = [1.5, 1.5, 0]
+
+  expect(intersectsPoint(point1, point2)).toBe(true)
+})
+
+test("it should prove that two different points do not intersect", () => {
+  const point1 = [1.5, 1.5, 0]
+  const point2 = [2, 1, 0]
+
+  expect(intersectsPoint(point1, point2)).toBe(false)
+})
+
+test("it should prove that a point inside of a circle intersects with it", () => {
+  const point = [1.5, 1.5, 0]
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(point, circle)).toBe(true)
+})
+
+test("it should prove that a point on the border of a circle intersects with it", () => {
+  const point = [2, 1, 0]
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(point, circle)).toBe(true)
+})
+
+test("it should prove that a point outside of a circle does not intersect with it", () => {
+  const point = [2, 2, 0]
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(point, circle)).toBe(false)
+})
+
+test("it should prove that a point inside of a rectangle intersects with it", () => {
+  const point = [1.5, 1.5, 0]
+  const rectangle = {
+    position: [1, 1, 0],
+    size: [2, 2, 0],
+  }
+
+  expect(intersectsRectangle(point, rectangle)).toBe(true)
+})
+
+test("it should prove that a point on the border of a rectangle intersects with it", () => {
+  const point = [2, 1, 0]
+  const rectangle = {
+    position: [1, 1, 0],
+    size: [2, 2, 0],
+  }
+
+  expect(intersectsRectangle(point, rectangle)).toBe(true)
+})
+
+test("it should prove that a point outside of a rectangle does not intersect with it", () => {
+  const point = [2.5, 2.5, 0]
+  const rectangle = {
+    position: [1, 1, 0],
+    size: [2, 2, 0],
+  }
+
+  expect(intersectsRectangle(point, rectangle)).toBe(false)
+})

package/src/utils/math/geometry/rectangle.js

@@ -0,0 +1,45 @@
+/**
+ * @typedef {import("./types").Rectangle} Rectangle
+ * @typedef {import("./types").Platform} Platform
+ */
+
+import { intersectsRectangle as circleIntersectsRectangle } from "./circle.js"
+import { intersectsRectangle as platformIntersectsRectangle } from "./platform.js"
+
+export function intersectsCircle(rectangle, circle) {
+  return circleIntersectsRectangle(circle, rectangle)
+}
+
+/**
+ * Determines whether a rectangle intersects another in 3D space.
+ *
+ * @param {Rectangle} rectangle1 - The rectangle defined by its position (x, y, z) and size (width, height, depth).
+ * @param {Rectangle} rectangle2 - The other rectangle defined by its position (z, y, z) and size (width, height, depth).
+ * @returns {boolean} True if the two rectangles intersect, false otherwise.
+ */
+export function intersectsRectangle(rectangle1, rectangle2) {
+  const [x1, y1, z1] = rectangle1.position
+  const [w1, h1, d1] = rectangle1.size
+
+  const [x2, y2, z2] = rectangle2.position
+  const [w2, h2, d2] = rectangle2.size
+
+  return (
+    x1 <= x2 + w2 &&
+    x1 + w1 >= x2 &&
+    y1 <= y2 + h2 &&
+    y1 + h1 >= y2 &&
+    z1 <= z2 + d2 &&
+    z1 + d1 >= z2
+  )
+}
+
+/**
+ * Checks if a rectangle intersects with a platform.
+ * @param {Rectangle} rectangle - The rectangle to check.
+ * @param {Platform} platform - The platform to check.
+ * @returns {boolean} True if the rectangle intersects the platform, false otherwise.
+ */
+export function intersectsPlatform(rectangle, platform) {
+  return platformIntersectsRectangle(platform, rectangle)
+}

package/src/utils/math/geometry/rectangle.test.js

@@ -0,0 +1,42 @@
+import { expect, test } from "vitest"
+
+import { intersectsRectangle } from "./rectangle.js"
+
+test("it should prove that a rectangle crossing another one intersects with it", () => {
+  const rectangle1 = {
+    position: [0, 0, 0],
+    size: [2, 2, 2],
+  }
+  const rectangle2 = {
+    position: [1, 1, 1],
+    size: [2, 2, 2],
+  }
+
+  expect(intersectsRectangle(rectangle1, rectangle2)).toBe(true)
+})
+
+test("it should prove that a rectangle right on top of another intersects with it", () => {
+  const rectangle1 = {
+    position: [0, 0, 0],
+    size: [2, 2, 2],
+  }
+  const rectangle2 = {
+    position: [0, 0, 0],
+    size: [2, 0, 2],
+  }
+
+  expect(intersectsRectangle(rectangle1, rectangle2)).toBe(true)
+})
+
+test("it should prove that a rectangle not crossing another one does not intersect with it", () => {
+  const rectangle1 = {
+    position: [0, 0, 0],
+    size: [2, 2, 2],
+  }
+  const rectangle2 = {
+    position: [3, 3, 3],
+    size: [2, 2, 2],
+  }
+
+  expect(intersectsRectangle(rectangle1, rectangle2)).toBe(false)
+})

package/src/utils/math/geometry/segment.js

@@ -0,0 +1,80 @@
+/**
+ * @typedef {import("./types").Segment} Segment
+ * @typedef {import("./types").Point} Point
+ * @typedef {import("./types").Circle} Circle
+ */
+
+import {
+  magnitude,
+  setMagnitude,
+} from "@inglorious/utils/math/linear-algebra/vector.js"
+import {
+  distance,
+  dot,
+  subtract,
+  sum,
+} from "@inglorious/utils/math/linear-algebra/vectors.js"
+
+const BEFORE_SEGMENT = 0
+
+/**
+ * Calculates the coefficients [a, b, c] of the line equation ax + bz + c = 0
+ * for a given segment in 2D space.
+ *
+ * @param {Segment} segment - The segment defined by its start (`from`) and end (`to`) points.
+ * @returns {[number, number, number]} An array [a, b, c] representing the line equation.
+ */
+export function coefficients(segment) {
+  const [x1, , z1] = segment.from
+  const [x2, , z2] = segment.to
+  return [z1 - z2, x2 - x1, (x1 - x2) * z1 + x1 * (z2 - z1)]
+}
+
+/**
+ * Finds the closest point on a segment to a given point in 3D space.
+ *
+ * @param {Segment} segment - The segment defined by its start (`from`) and end (`to`) points.
+ * @param {Point} point - The point in 3D space represented as [x, y, z].
+ * @returns {Point} The closest point on the segment to the given point.
+ */
+export function closestPoint(segment, point) {
+  const shiftedSegment = subtract(segment.to, segment.from)
+  const shiftedPoint = subtract(point, segment.from)
+
+  const projectionLength =
+    dot(shiftedSegment, shiftedPoint) / magnitude(shiftedSegment)
+
+  if (projectionLength < BEFORE_SEGMENT) {
+    return segment.from
+  }
+
+  if (projectionLength > magnitude(shiftedSegment)) {
+    return segment.to
+  }
+
+  const projectedPoint = setMagnitude(shiftedSegment, projectionLength)
+  return sum(segment.from, projectedPoint)
+}
+
+/**
+ * Calculates the shortest distance from a point to a segment in 3D space.
+ *
+ * @param {Segment} segment - The segment defined by its start (`from`) and end (`to`) points.
+ * @param {Point} point - The point in 3D space represented as [x, y, z].
+ * @returns {number} The shortest distance from the point to the segment.
+ */
+export function distanceFromPoint(segment, point) {
+  const closest = closestPoint(segment, point)
+  return distance(point, closest)
+}
+
+/**
+ * Determines whether a segment intersects with the perimeter of a circle.
+ *
+ * @param {Segment} segment - The segment defined by its start (`from`) and end (`to`) points.
+ * @param {Circle} circle - The circle defined by its position (center) and radius.
+ * @returns {boolean} `true` if the segment intersects the circle's perimeter, otherwise `false`.
+ */
+export function intersectsCircle(segment, circle) {
+  return distanceFromPoint(segment, circle.position) <= circle.radius
+}

package/src/utils/math/geometry/segment.test.js

@@ -0,0 +1,183 @@
+import { expect, test } from "vitest"
+
+import { isClose } from "../numbers.js"
+import {
+  closestPoint,
+  coefficients,
+  distanceFromPoint,
+  intersectsCircle,
+} from "./segment.js"
+
+expect.extend({
+  toEqualVector(received, expected) {
+    const { isNot } = this
+    return {
+      pass: received.every((coord, index) => isClose(coord, expected[index])),
+      message: () =>
+        `${received} is ${isNot ? "" : "not"} close to ${expected}`,
+    }
+  },
+})
+
+test("it should retrieve values of *a*, *b*, and *c* from a segment, so it looks like a line in the form *ax + by + c = 0*", () => {
+  const segment = {
+    from: [0, 0, 0],
+    to: [1, 0, 2],
+  }
+  const expectedResult = [-2, 1, 0]
+
+  expect(coefficients(segment)).toEqual(expectedResult)
+})
+
+test("it should find the closest point in a segment to a point projectable on it", () => {
+  const segment = {
+    from: [0, 0, 0],
+    to: [2, 0, 2],
+  }
+  const point = [2, 0, 0]
+  const expectedResult = [1, 0, 1]
+
+  expect(closestPoint(segment, point)).toEqualVector(expectedResult)
+})
+
+test("it should find the closest point as the point itself when resting on the segment", () => {
+  const segment = {
+    from: [0, 0, 0],
+    to: [2, 0, 2],
+  }
+  const point = [1, 0, 1]
+  const expectedResult = [1, 0, 1]
+
+  expect(closestPoint(segment, point)).toEqualVector(expectedResult)
+})
+
+test("it return the start of a segment when the point is close to its start", () => {
+  const segment = {
+    from: [0, 0, 0],
+    to: [3, 0, 4],
+  }
+  const point = [-2, 0, 0]
+  const expectedResult = [0, 0, 0]
+
+  expect(closestPoint(segment, point)).toEqualVector(expectedResult)
+})
+
+test("it should return the end of a segment when the point is close to its end", () => {
+  const segment = {
+    from: [0, 0, 0],
+    to: [3, 0, 4],
+  }
+  const point = [5, 0, 4]
+  const expectedResult = [3, 0, 4]
+
+  expect(closestPoint(segment, point)).toEqualVector(expectedResult)
+})
+
+test("it should compute the distance between a segment and a point projectable on it", () => {
+  const segment = {
+    from: [0, 0, 0],
+    to: [3, 0, 4],
+  }
+  const point = [5, 0, 0]
+  const expectedResult = 4
+
+  expect(distanceFromPoint(segment, point)).toBe(expectedResult)
+})
+
+test("it should compute the distance between a segment and a point resting on it", () => {
+  const segment = {
+    from: [0, 0, 0],
+    to: [2, 0, 2],
+  }
+  const point = [1, 0, 1]
+  const expectedResult = 0
+
+  expect(distanceFromPoint(segment, point)).toBeCloseTo(expectedResult)
+})
+
+test("it should compute the distance between a segment and a point close to the start", () => {
+  const segment = {
+    from: [0, 0, 0],
+    to: [3, 0, 4],
+  }
+  const point = [-2, 0, 0]
+  const expectedResult = 2
+
+  expect(distanceFromPoint(segment, point)).toBe(expectedResult)
+})
+
+test("it should compute the distance between a segment and a point close to the end", () => {
+  const segment = {
+    from: [0, 0, 0],
+    to: [3, 0, 4],
+  }
+  const point = [5, 0, 4]
+  const expectedResult = 2
+
+  expect(distanceFromPoint(segment, point)).toBeCloseTo(expectedResult)
+})
+
+test("it should prove that a segment that crosses a circle intersects with it", () => {
+  const segment = {
+    from: [0, 0, 0],
+    to: [2, 0, 2],
+  }
+  const circle = {
+    position: [1, 0, 1],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(segment, circle)).toBe(true)
+})
+
+test("it should prove that a segment tangent to a circle intersects with it", () => {
+  const segment = {
+    from: [0, 0, 0],
+    to: [0, 0, 2],
+  }
+  const circle = {
+    position: [1, 0, 1],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(segment, circle)).toBe(true)
+})
+
+test("it should prove that a segment inside of a circle intersects with it", () => {
+  const segment = {
+    from: [0.5, 0, 0.5],
+    to: [1.5, 0, 1.5],
+  }
+  const circle = {
+    position: [1, 0, 1],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(segment, circle)).toBe(true)
+})
+
+test("it should prove that a segment that does not cross a circle does not intersect with it", () => {
+  const segment = {
+    from: [0, 0, 0],
+    to: [-2, 0, 2],
+  }
+  const circle = {
+    position: [1, 0, 1],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(segment, circle)).toBe(false)
+})
+
+test("it should prove that a segment that reaches outside of a circle does not intersect with it", () => {
+  const segment = {
+    from: [0, 0, 0],
+    to: [-1, 0, -2],
+  }
+  const circle = {
+    position: [1, 0, 1],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(segment, circle)).toBe(false)
+})

package/src/utils/math/geometry/triangle.js

@@ -0,0 +1,15 @@
+/**
+ * Calculates the length of the hypothenuse (or magnitude) for a given set of numbers
+ * using the Pythagorean theorem.
+ *
+ * @param {number[]} nums - A list of numbers representing the sides of a right triangle.
+ * @returns {number} The length of the hypothenuse.
+ */
+export function hypothenuse(...nums) {
+  return Math.hypot(...nums)
+}
+
+/**
+ * Alias for the `hypothenuse` function.
+ */
+export const pythagoras = hypothenuse

package/src/utils/math/geometry/triangle.test.js

@@ -0,0 +1,11 @@
+import { expect, test } from "vitest"
+
+import { hypothenuse } from "./triangle.js"
+
+test("it should compute the hypothenuse of two catheti (aka pythagoras)", () => {
+  const cat1 = 3
+  const cat2 = 4
+  const expectedResult = 5
+
+  expect(hypothenuse(cat1, cat2)).toBe(expectedResult)
+})

package/src/utils/math/geometry/types.d.ts

@@ -0,0 +1,23 @@
+export type Point = [number, number, number] // [x, y, z]
+export type Size = [number, number, number] // [width, height, depth]
+export type Line = [number, number, number] // [a, b, c]
+
+export interface Circle {
+  position: Point
+  radius: number
+}
+
+export interface Rectangle {
+  position: Point
+  size: Size
+}
+
+export interface Platform {
+  position: Point
+  size: Size
+}
+
+export interface Segment {
+  from: Point
+  to: Point
+}

package/src/utils/math/linear-algebra/2d.js

@@ -0,0 +1,28 @@
+/**
+ * @typedef {import('../../../types').Vector2} Vector2
+ * @typedef {import('../../../types').Vector3} Vector3
+ */
+
+const NO_Y = 0 // Default Y-coordinate value for 3D vectors derived from 2D vectors.
+
+/**
+ * Converts a 2D vector [x, z] into a 3D vector [x, 0, z].
+ *
+ * @param {Vector2} vector - A 2D vector represented as [x, z].
+ * @returns {Vector3} A 3D vector represented as [x, 0, z].
+ */
+export function from2D(vector) {
+  const [x, z] = vector
+  return [x, NO_Y, z]
+}
+
+/**
+ * Converts a 3D vector [x, y, z] into a 2D vector [x, z].
+ *
+ * @param {Vector3} vector - A 3D vector represented as [x, y, z].
+ * @returns {Vector2} A 2D vector represented as [x, z].
+ */
+export function to2D(vector) {
+  const [x, , z] = vector
+  return [x, z]
+}

package/src/utils/math/linear-algebra/2d.test.js

@@ -0,0 +1,17 @@
+import { expect, test } from "vitest"
+
+import { from2D, to2D } from "./2d.js"
+
+test("build a 3D vector from a 2D one", () => {
+  const vector = [3, 4]
+  const expectedResult = [3, 0, 4]
+
+  expect(from2D(vector)).toStrictEqual(expectedResult)
+})
+
+test("build a 2D vector from a 3D one", () => {
+  const vector = [3, 0, 4]
+  const expectedResult = [3, 4]
+
+  expect(to2D(vector)).toStrictEqual(expectedResult)
+})

package/src/utils/math/linear-algebra/quaternion.js

@@ -0,0 +1,22 @@
+/**
+ * @typedef {import('../../../types').Vector3} Vector3
+ * @typedef {import('../../../types').Quaternion} Quaternion
+ */
+
+import { cos, sin } from "@inglorious/utils/math/trigonometry.js"
+
+const DEFAULT_ANGLE = 0
+const HALF = 2 // Constant representing the divisor for halving an angle.
+// eslint-disable-next-line no-magic-numbers
+const Y_AXIS = [0, 1, 0] // Default axis of rotation (Y-axis).
+
+/**
+ * Computes a quaternion representing a rotation around a given axis.
+ *
+ * @param {number} [angle=0] - The angle of rotation in radians. Defaults to 0.
+ * @param {Vector3} [axis=Y_AXIS] - The axis of rotation as a 3D vector Defaults to the Y-axis.
+ * @returns {Quaternion} The quaternion as an array [w, x, y, z].
+ */
+export function quaternion(angle = DEFAULT_ANGLE, axis = Y_AXIS) {
+  return [cos(angle / HALF), ...axis.map((coord) => coord * sin(angle / HALF))]
+}

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

@@ -0,0 +1,25 @@
+import { cos, pi, sin } from "@inglorious/utils/math/trigonometry.js"
+import { expect, test } from "vitest"
+
+import { quaternion } from "./quaternion.js"
+
+test("it should return the quaternion for no rotation", () => {
+  const angle = 0
+  const expectedResult = [1, 0, 0, 0]
+
+  expect(quaternion(angle)).toStrictEqual(expectedResult)
+})
+
+test("it should return the quaternion for a rotation of pi/2", () => {
+  const angle = pi() / 2
+  const expectedResult = [cos(pi() / 4), 0, sin(pi() / 4), 0]
+
+  expect(quaternion(angle)).toStrictEqual(expectedResult)
+})
+
+test("it should return the quaternion for a rotation of negative pi/2", () => {
+  const angle = -pi() / 2
+  const expectedResult = [cos(-pi() / 4), -0, sin(-pi() / 4), -0]
+
+  expect(quaternion(angle)).toStrictEqual(expectedResult)
+})

package/src/utils/math/linear-algebra/quaternions.js

@@ -0,0 +1,20 @@
+/**
+ * @typedef {import('./types').Quaternion} Quaternion
+ */
+
+import { times } from "./vector.js"
+import { cross, dot, sum } from "./vectors.js"
+
+/**
+ * Combines two quaternions using the Hamilton product.
+ *
+ * @param {Quaternion} q1 - The first quaternion.
+ * @param {Quaternion} q2 - The second quaternion.
+ * @returns {Quaternion} - The resulting quaternion after combining q1 and q2.
+ */
+export function combine(q1, q2) {
+  const [s, ...v] = q1
+  const [t, ...w] = q2
+
+  return [s * t - dot(v, w), ...sum(times(w, s), times(v, t), cross(v, w))]
+}