@inglorious/engine 0.1.0

package/src/utils/data-structures/types.d.ts

@@ -0,0 +1,4 @@
+export interface Tree {
+  value: any
+  children: Tree[]
+}

package/src/utils/functions/functions.js

@@ -0,0 +1,19 @@
+/**
+ * Composes multiple functions from right to left, as if every function wraps the next one.
+ *
+ * @param {...Function} fns - Functions to compose.
+ * @returns {Function} A function that takes an initial value and applies the composed functions.
+ */
+export function compose(...fns) {
+  return (x) => fns.reduceRight((acc, fn) => fn(acc), x)
+}
+
+/**
+ * Pipes multiple functions from left to right, as if the functions are applied one by one.
+ *
+ * @param {...Function} fns - Functions to pipe.
+ * @returns {Function} A function that takes an initial value and applies the piped functions.
+ */
+export function pipe(...fns) {
+  return (x) => fns.reduce((acc, fn) => fn(acc), x)
+}

package/src/utils/functions/functions.test.js

@@ -0,0 +1,23 @@
+import { expect, test } from "vitest"
+
+import { compose, pipe } from "./functions.js"
+
+test("it should compose functions", () => {
+  const shout = (x) => x.toUpperCase()
+  const punctuate = (mark) => (x) => `${x}${mark}`
+  const html = (tag) => (x) => `<${tag}>${x}</${tag}>`
+
+  const fn = compose(html("p"), punctuate("!"), shout)
+
+  expect(fn("Hello world")).toBe("<p>HELLO WORLD!</p>")
+})
+
+test("it should pipe functions", () => {
+  const shout = (x) => x.toUpperCase()
+  const punctuate = (mark) => (x) => `${x}${mark}`
+  const html = (tag) => (x) => `<${tag}>${x}</${tag}>`
+
+  const fn = pipe(shout, punctuate("!"), html("p"))
+
+  expect(fn("Hello world")).toBe("<p>HELLO WORLD!</p>")
+})

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

@@ -0,0 +1,117 @@
+/**
+ * @typedef {import("./types").Point} Point
+ * @typedef {import("./types").Circle} Circle
+ * @typedef {import("./types").Rectangle} Rectangle
+ * @typedef {import("./types").Platform} Platform
+ */
+
+import { subtract } from "@inglorious/utils/math/linear-algebra/vectors.js"
+
+import { clamp } from "../numbers.js"
+import { intersectsCircle as platformIntersectsCircle } from "./platform.js"
+import {
+  intersectsCircle as pointIntersectsCircle,
+  intersectsRectangle as pointIntersectsRectangle,
+} from "./point.js"
+import { intersectsCircle as segmentIntersectsCircle } from "./segment.js"
+import { hypothenuse } from "./triangle.js"
+
+const SQUARED = 2
+const INITIAL_SUM = 0
+
+/**
+ * Checks if a circle intersects with a point.
+ * @param {Circle} circle - The circle to check.
+ * @param {Point} point - The point to check.
+ * @returns {boolean} True if the point intersects the circle, false otherwise.
+ */
+export function intersectsPoint(circle, point) {
+  return pointIntersectsCircle(point, circle)
+}
+
+/**
+ * Checks if two circles intersect.
+ * @param {Circle} circle1 - The first circle.
+ * @param {Circle} circle2 - The second circle.
+ * @returns {boolean} True if the circles intersect, false otherwise.
+ */
+export function intersectsCircle(circle1, circle2) {
+  return (
+    hypothenuse(...subtract(circle1.position, circle2.position)) <=
+    circle1.radius + circle2.radius
+  )
+}
+
+/**
+ * Checks if a circle intersects with a rectangle.
+ * @param {Circle} circle - The circle to check.
+ * @param {Rectangle} rectangle - The rectangle to check.
+ * @returns {boolean} True if the circle intersects the rectangle, false otherwise.
+ */
+export function intersectsRectangle(circle, rectangle) {
+  const [left, top, front] = rectangle.position
+  const [width, height, depth] = rectangle.size
+
+  const ltf = [left, top, front]
+  const rtf = [left + width, top, front]
+  const lbf = [left, top, front + depth]
+  const rbf = [left + width, top, front + depth]
+
+  const ltb = [left, top + height, front]
+  const rtb = [left + width, top + height, front]
+  const lbb = [left, top + height, front + depth]
+  const rbb = [left + width, top + height, front + depth]
+
+  return (
+    // Center
+    pointIntersectsRectangle(circle.position, rectangle) ||
+    // Front face
+    segmentIntersectsCircle({ from: ltf, to: rtf }, circle) ||
+    segmentIntersectsCircle({ from: rtf, to: rbf }, circle) ||
+    segmentIntersectsCircle({ from: rbf, to: lbf }, circle) ||
+    segmentIntersectsCircle({ from: lbf, to: ltf }, circle) ||
+    // Back face
+    segmentIntersectsCircle({ from: ltb, to: rtb }, circle) ||
+    segmentIntersectsCircle({ from: rtb, to: rbb }, circle) ||
+    segmentIntersectsCircle({ from: rbb, to: lbb }, circle) ||
+    segmentIntersectsCircle({ from: lbb, to: ltb }, circle) ||
+    // Connecting edges
+    segmentIntersectsCircle({ from: ltf, to: ltb }, circle) ||
+    segmentIntersectsCircle({ from: rtf, to: rtb }, circle) ||
+    segmentIntersectsCircle({ from: lbf, to: lbb }, circle) ||
+    segmentIntersectsCircle({ from: rbf, to: rbb }, circle) ||
+    // Corners
+    isCircleWithinRectangleRadius(circle, rectangle)
+  )
+}
+
+/**
+ * Checks if a circle intersects with a platform.
+ * @param {Circle} circle - The circle to check.
+ * @param {Platform} platform - The platform to check.
+ * @returns {boolean} True if the circle intersects the platform, false otherwise.
+ */
+export function intersectsPlatform(circle, platform) {
+  return platformIntersectsCircle(platform, circle)
+}
+
+function isCircleWithinRectangleRadius(circle, rectangle) {
+  const [left, top, front] = rectangle.position
+  const [width, height, depth] = rectangle.size
+
+  // Find the closest point on the rectangle to the circle's center
+  const [x, y, z] = circle.position
+  const closestPoint = [
+    clamp(x, left, left + width),
+    clamp(y, top, top + height),
+    clamp(z, front, front + depth),
+  ]
+
+  // Calculate the distance from the circle's center to the closest point
+  const distanceSquared = subtract(circle.position, closestPoint).reduce(
+    (sum, value) => sum + value ** SQUARED,
+    INITIAL_SUM,
+  )
+
+  return distanceSquared <= circle.radius ** SQUARED
+}

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

@@ -0,0 +1,97 @@
+import { expect, test } from "vitest"
+
+import {
+  intersectsCircle,
+  intersectsPoint,
+  intersectsRectangle,
+} from "./circle.js"
+
+test("it should prove that a circle around a point intersects with it", () => {
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+  const point = [1.5, 1.5, 0]
+
+  expect(intersectsPoint(circle, point)).toBe(true)
+})
+
+test("it should prove that two equal circles intersect", () => {
+  const circle1 = { position: [1, 1, 0], radius: 1 }
+  const circle2 = { position: [1, 1, 0], radius: 1 }
+
+  expect(intersectsCircle(circle1, circle2)).toBe(true)
+})
+
+test("it should prove that two circles shifted by a small x intersect", () => {
+  const circle1 = { position: [1, 1, 0], radius: 1 }
+  const circle2 = { position: [2, 1, 0], radius: 1 }
+
+  expect(intersectsCircle(circle1, circle2)).toBe(true)
+})
+
+test("it should prove that two touching circles intersect", () => {
+  const circle1 = { position: [1, 1, 0], radius: 1 }
+  const circle2 = { position: [3, 1, 0], radius: 1 }
+
+  expect(intersectsCircle(circle1, circle2)).toBe(true)
+})
+
+test("it should prove that two non-touching circles do not intersect", () => {
+  const circle1 = { position: [1, 1, 0], radius: 1 }
+  const circle2 = { position: [4, 1, 0], radius: 1 }
+
+  expect(intersectsCircle(circle1, circle2)).toBe(false)
+})
+
+test("it should prove that a circle inside of a rectangle intersects with it", () => {
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+  const rectangle = {
+    position: [-1, -1, 0],
+    size: [4, 4, 0],
+  }
+
+  expect(intersectsRectangle(circle, rectangle)).toBe(true)
+})
+
+test("it should prove that a circle on the border of a rectangle intersects with it", () => {
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+  const rectangle = {
+    position: [-2, 0, 0],
+    size: [2, 2, 0],
+  }
+
+  expect(intersectsRectangle(circle, rectangle)).toBe(true)
+})
+
+test("it should prove that a circle crossing a rectangle intersects with it", () => {
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+  const rectangle = {
+    position: [-1, -1, 0],
+    size: [2, 2, 0],
+  }
+
+  expect(intersectsRectangle(circle, rectangle)).toBe(true)
+})
+
+test("it should prove that a circle outside of a rectangle does not intersect with it", () => {
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+  const rectangle = {
+    position: [-3, 0, 0],
+    size: [2, 2, 0],
+  }
+
+  expect(intersectsRectangle(circle, rectangle)).toBe(false)
+})

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

@@ -0,0 +1,39 @@
+// @see https://jonathanwhiting.com/tutorial/collision/
+
+const LOWER_BOUND = 0
+const TOP_TILE_OFFSET = 1 // Offset to include the top boundary tile
+
+export function findCollisions(hitmask, target) {
+  const { position, tileSize, columns, heights } = hitmask
+  const [left, top, front] = position
+  const [tileWidth, tileHeight] = tileSize
+  const rows = heights.length / columns
+
+  const [x, y, z] = target.position
+  const [width, height, depth] = target.size
+
+  const leftTile = Math.floor((x - left) / tileWidth)
+  const rightTile = Math.floor((x - left + width) / tileWidth)
+  const bottomTile = Math.floor((z - front) / tileHeight)
+  const topTile = Math.floor((z - front + depth) / tileHeight)
+
+  if (
+    leftTile < LOWER_BOUND ||
+    rightTile > columns ||
+    bottomTile < LOWER_BOUND ||
+    topTile > rows
+  ) {
+    return false
+  }
+
+  for (let i = leftTile; i < rightTile; i++) {
+    for (let j = bottomTile; j <= topTile + TOP_TILE_OFFSET; j++) {
+      const heightAtTile = heights[i * columns + j]
+      if (y + height <= top + heightAtTile) {
+        return true
+      }
+    }
+  }
+
+  return false
+}

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

@@ -0,0 +1,84 @@
+import { expect, test } from "vitest"
+
+import { findCollisions } from "./hitmask"
+
+test("it should prove that a rectangle touching a wall intersects with it", () => {
+  const hitmask = {
+    position: [0, 0, 0],
+    tileSize: [1, 1],
+    columns: 4,
+    heights: [0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0],
+  }
+  const rectangle = {
+    shape: "rectangle",
+    position: [2.5, 0, 1.5],
+    size: [1, 1, 1],
+  }
+
+  expect(findCollisions(hitmask, rectangle)).toBe(true)
+})
+
+test("it should prove that shifting operands does not change the outcome", () => {
+  const SHIFT = 10
+  const hitmask = {
+    position: [0 + SHIFT, 0, 0 + SHIFT],
+    tileSize: [1, 1],
+    columns: 4,
+    heights: [0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0],
+  }
+  const rectangle = {
+    shape: "rectangle",
+    position: [2.5 + SHIFT, 0, 1.5 + SHIFT],
+    size: [1, 1, 1],
+  }
+
+  expect(findCollisions(hitmask, rectangle)).toBe(true)
+})
+
+test("it should prove that a rectangle not touching a wall does not intersect with it", () => {
+  const hitmask = {
+    position: [0, 0, 0],
+    tileSize: [1, 1],
+    columns: 4,
+    heights: [0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0],
+  }
+  const rectangle = {
+    shape: "rectangle",
+    position: [0.5, 0, 0.5],
+    size: [1, 1, 1],
+  }
+
+  expect(findCollisions(hitmask, rectangle)).toBe(false)
+})
+
+test("it should prove that a rectangle above the tile of a hitmask does not intersect with it", () => {
+  const hitmask = {
+    position: [0, 0, 0],
+    tileSize: [1, 1],
+    columns: 4,
+    heights: [0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0],
+  }
+  const rectangle = {
+    shape: "rectangle",
+    position: [2.5, 1, 1.5],
+    size: [1, 1, 1],
+  }
+
+  expect(findCollisions(hitmask, rectangle)).toBe(false)
+})
+
+test("it should prove that a rectangle outside of a hitmask does not intersect with it", () => {
+  const hitmask = {
+    position: [0, 0, 0],
+    tileSize: [1, 1],
+    columns: 4,
+    heights: [0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0],
+  }
+  const rectangle = {
+    shape: "rectangle",
+    position: [5, 0, 1],
+    size: [1, 1, 1],
+  }
+
+  expect(findCollisions(hitmask, rectangle)).toBe(false)
+})

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

@@ -0,0 +1,35 @@
+/**
+ * @typedef {import("./types").Line} Line
+ * @typedef {import("./types").Point} Point
+ * @typedef {import("./types").Circle} Circle
+ */
+
+import { abs } from "@inglorious/utils/math/numbers.js"
+
+import { hypothenuse } from "./triangle.js"
+
+/**
+ * Calculates the shortest distance from a point to a line in 2D space.
+ *
+ * @param {Line} line - The line represented by the equation ax + bz + c = 0, where `line` is [a, b, c].
+ * @param {Point} point - The point in 3D space represented as [x, y, z].
+ * @returns {number} The shortest distance from the point to the line.
+ */
+export function distanceFromPoint(line, point) {
+  const [a, b, c] = line
+  const [x, , z] = point
+
+  return abs(a * x + b * z + c) / hypothenuse(a, b)
+}
+
+// @see https://math.stackexchange.com/questions/275529/check-if-line-intersects-with-circles-perimeter
+/**
+ * Determines whether a line intersects with the perimeter of a circle.
+ *
+ * @param {Line} line - The line represented by the equation ax + bz + c = 0, where `line` is [a, b, c].
+ * @param {Circle} circle - The circle defined by its position (center) and radius.
+ * @returns {boolean} `true` if the line intersects the circle's perimeter, otherwise `false`.
+ */
+export function intersectsCircle(line, circle) {
+  return distanceFromPoint(line, circle.position) <= circle.radius
+}

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

@@ -0,0 +1,49 @@
+import { expect, test } from "vitest"
+
+import { distanceFromPoint, intersectsCircle } from "./line.js"
+
+test("it should compute the distance between a line and a point", () => {
+  const line = [-4, 3, 0]
+  const point = [5, 0, 0]
+  const expectedResult = 4
+
+  expect(distanceFromPoint(line, point)).toBe(expectedResult)
+})
+
+test("it should not compute the distance between a line and a point", () => {
+  const line = [-1, 1, 0]
+  const point = [2, 0, 2]
+  const expectedResult = 0
+
+  expect(distanceFromPoint(line, point)).toBe(expectedResult)
+})
+
+test("it should prove that a line that crosses a circle intersects with it", () => {
+  const line = [-2, 2, 0]
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(line, circle)).toBe(true)
+})
+
+test("it should prove that a line tangent to a circle intersects with it", () => {
+  const line = [-2, 0, 0]
+  const circle = {
+    position: [1, 0, 1],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(line, circle)).toBe(true)
+})
+
+test("it should prove that a line that does not cross a circle does not intersect with it", () => {
+  const line = [1, 1, 0]
+  const circle = {
+    position: [1, 0, 1],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(line, circle)).toBe(false)
+})

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

@@ -0,0 +1,42 @@
+/**
+ * Checks if a platform intersects with a circle in 3D space.
+ * @param {Platform} platform - The platform to check.
+ * @param {Circle} circle - The circle to check.
+ * @returns {boolean} True if the platform intersects the circle, false otherwise.
+ */
+export function intersectsCircle(platform, circle) {
+  const [left, top, front] = platform.position
+  const [extension, elevation, thickness] = platform.size
+
+  const [x, y, z] = circle.position
+
+  const lowestPoint = y - circle.radius
+  const isAbove = lowestPoint <= top && lowestPoint >= top - elevation
+
+  const isOverlappingX = x >= left && x <= left + extension
+  const isOverlappingZ = z >= front && z <= front + thickness
+
+  return isAbove && isOverlappingX && isOverlappingZ
+}
+
+/**
+ * Determines whether platform intersects with a rectangle in 3D space.
+ *
+ * @param {Platform} platform - The platform defined by its position (top-left-front corner) and size (extension, elevation, thickness).
+ * @param {Rectangle} rectangle - The rectangle defined by its position (top-left-front corner) and size (width, height, depth).
+ * @returns {boolean} True if the platform intersects the rectangle, false otherwise.
+ */
+export function intersectsRectangle(platform, rectangle) {
+  const [left, top, front] = platform.position
+  const [extension, elevation, thickness] = platform.size
+
+  const [x, y, z] = rectangle.position
+  const [width, , depth] = rectangle.size
+
+  const isAbove = y >= top && y <= top + elevation
+
+  const isOverlappingX = x + width >= left && x <= left + extension
+  const isOverlappingZ = z + depth >= front && z <= front + thickness
+
+  return isAbove && isOverlappingX && isOverlappingZ
+}

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

@@ -0,0 +1,133 @@
+import { expect, test } from "vitest"
+
+import { intersectsCircle, intersectsRectangle } from "./platform"
+
+test("it should prove that a circle right above a platform intersects with it", () => {
+  const platform = {
+    position: [-1, 0, 0],
+    size: [2, 1, 0],
+  }
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(platform, circle)).toBe(true)
+})
+
+test("it should prove that a circle way above a platform intersects with it", () => {
+  const platform = {
+    position: [0, 0, -2],
+    size: [2, 1, 0],
+  }
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(platform, circle)).toBe(false)
+})
+
+test("it should prove that a circle crossing a platform does not intersect with it", () => {
+  const platform = {
+    position: [-1, -1, 0],
+    size: [2, 2, 0],
+  }
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(platform, circle)).toBe(false)
+})
+
+test("it should prove that a circle below a platform does not intersect with it", () => {
+  const platform = {
+    position: [0, 2, 0],
+    size: [2, 1, 0],
+  }
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(platform, circle)).toBe(false)
+})
+
+test("it should prove that a circle not crossing a platform horizontally does not intersect with it", () => {
+  const platform = {
+    position: [-3, -1, 0],
+    size: [2, 1, 0],
+  }
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(platform, circle)).toBe(false)
+})
+
+test("it should prove that a rectangle crossing a platform from above intersects with it", () => {
+  const platform = {
+    position: [0, -1, 0],
+    size: [2, 2, 0],
+  }
+  const rectangle = {
+    position: [0, 0, 0],
+    size: [2, 2, 0],
+  }
+
+  expect(intersectsRectangle(platform, rectangle)).toBe(true)
+})
+
+test("it should prove that a rectangle right on top of a platform intersects with it", () => {
+  const platform = {
+    position: [0, -2, 0],
+    size: [2, 2, 0],
+  }
+  const rectangle = {
+    position: [0, 0, 0],
+    size: [2, 2, 0],
+  }
+
+  expect(intersectsRectangle(platform, rectangle)).toBe(true)
+})
+
+test("it should prove that a rectangle crossing a platform from below does not intersect with it", () => {
+  const platform = {
+    position: [0, 1, 0],
+    size: [2, 2, 0],
+  }
+  const rectangle = {
+    position: [0, 0, 0],
+    size: [2, 2, 0],
+  }
+
+  expect(intersectsRectangle(platform, rectangle)).toBe(false)
+})
+
+test("it should prove that a rectangle below a platform does not intersect with it", () => {
+  const platform = {
+    position: [0, -3, 0],
+    size: [2, 2, 0],
+  }
+  const rectangle = {
+    position: [0, 0, 0],
+    size: [2, 2, 0],
+  }
+
+  expect(intersectsRectangle(platform, rectangle)).toBe(false)
+})
+
+test("it should prove that a rectangle not crossing a platform horizontally does not intersect with it", () => {
+  const platform = {
+    position: [-3, 0, 0],
+    size: [2, 2, 0],
+  }
+  const rectangle = {
+    position: [0, 0, 0],
+    size: [2, 2, 0],
+  }
+
+  expect(intersectsRectangle(platform, rectangle)).toBe(false)
+})