@inglorious/engine 0.1.0 → 0.2.0

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

@@ -1,84 +1,155 @@
-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)
-})
+import { expect, test } from "vitest"
+
+import { findCollisions } from "./hitmask"
+
+/**
+ * Given a rectangle located at (x=1.5, y=0, z=2.5) with a size of (1, 1, 1),
+ * which is touching a wall tile, this test proves a collision is detected.
+ *
+ * Tilemap layout:
+ * ⬛️🟩🟩⬛️
+ * ⬛️⬛️⬛️⬛️
+ * ⬛️⬛️⬛️⬛️
+ *
+ * Rectangle position (X,Z): R at (1.5, 2.5)
+ *
+ * Expected outcome: true
+ */
+test("it should prove that a rectangle touching a wall intersects with it", () => {
+  const hitmask = {
+    position: [2, 0, 1.5],
+    tileSize: [1, 1],
+    columns: 4,
+    // The top row (indices 0, 1, 2, 3) now has the walls.
+    heights: [0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+  }
+  const rectangle = {
+    shape: "rectangle",
+    position: [1.5, 0, 2.5],
+    size: [1, 1, 1],
+  }
+
+  expect(findCollisions(hitmask, rectangle)).toBe(true)
+})
+
+/**
+ * Given the same scenario as the previous test, but all coordinates
+ * are shifted by a constant value, this test proves the outcome remains
+ * unchanged, ensuring the collision detection is relative.
+ *
+ * Tilemap layout:
+ * ⬛️🟩🟩⬛️
+ * ⬛️⬛️⬛️⬛️
+ * ⬛️⬛️⬛️⬛️
+ *
+ * Rectangle position (X,Z): R at (11.5, 12.5)
+ *
+ * Expected outcome: true
+ */
+test("it should prove that shifting operands does not change the outcome", () => {
+  const SHIFT = 10
+  const hitmask = {
+    position: [2 + SHIFT, 0, 1.5 + SHIFT],
+    tileSize: [1, 1],
+    columns: 4,
+    // The top row (indices 0, 1, 2, 3) now has the walls.
+    heights: [0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+  }
+  const rectangle = {
+    shape: "rectangle",
+    position: [11.5, 0, 12.5],
+    size: [1, 1, 1],
+  }
+
+  expect(findCollisions(hitmask, rectangle)).toBe(true)
+})
+
+/**
+ * Given a rectangle located at (x=0.5, y=0, z=0.5) with a size of (1, 1, 1),
+ * which is not touching any walls, this test proves no collision is detected.
+ *
+ * Tilemap layout:
+ * ⬛️🟩🟩⬛️
+ * ⬛️⬛️⬛️⬛️
+ * ⬛️⬛️⬛️⬛️
+ *
+ * Rectangle position (X,Z): R at (0.5, 0.5)
+ *
+ * Expected outcome: false
+ */
+test("it should prove that a rectangle not touching a wall does not intersect with it", () => {
+  const hitmask = {
+    position: [2, 0, 1.5],
+    tileSize: [1, 1],
+    columns: 4,
+    // The top row (indices 0, 1, 2, 3) now has the walls.
+    heights: [0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+  }
+  const rectangle = {
+    shape: "rectangle",
+    position: [0.5, 0, 0.5],
+    size: [1, 1, 1],
+  }
+
+  expect(findCollisions(hitmask, rectangle)).toBe(false)
+})
+
+/**
+ * Given a rectangle located above the tile, this test proves no
+ * collision is detected even when the X and Z positions overlap.
+ *
+ * Tilemap layout:
+ * ⬛️🟩🟩⬛️
+ * ⬛️⬛️⬛️⬛️
+ * ⬛️⬛️⬛️⬛️
+ *
+ * Rectangle position: R at (x=1.5, y=1.6, z=2.5)
+ *
+ * Expected outcome: false
+ */
+test("it should prove that a rectangle above the tile of a hitmask does not intersect with it", () => {
+  const hitmask = {
+    position: [2, 0, 1.5],
+    tileSize: [1, 1],
+    columns: 4,
+    // The top row (indices 0, 1, 2, 3) now has the walls.
+    heights: [0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+  }
+  const rectangle = {
+    shape: "rectangle",
+    position: [1.5, 1.6, 2.5],
+    size: [1, 1, 1],
+  }
+
+  expect(findCollisions(hitmask, rectangle)).toBe(false)
+})
+
+/**
+ * Given a rectangle located outside of the tilemap, this test proves
+ * no collision is detected.
+ *
+ * Tilemap layout:
+ * ⬛️🟩🟩⬛️
+ * ⬛️⬛️⬛️⬛️
+ * ⬛️⬛️⬛️⬛️
+ *
+ * Rectangle position: R at (x=5.5, y=0.5, z=1.5)
+ *
+ * Expected outcome: false
+ */
+test("it should prove that a rectangle outside of a hitmask does not intersect with it", () => {
+  const hitmask = {
+    position: [2, 0, 1.5],
+    tileSize: [1, 1],
+    columns: 4,
+    // The top row (indices 0, 1, 2, 3) now has the walls.
+    heights: [0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+  }
+  const rectangle = {
+    shape: "rectangle",
+    position: [5.5, 0.5, 1.5],
+    size: [1, 1, 1],
+  }
+
+  expect(findCollisions(hitmask, rectangle)).toBe(false)
+})

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

@@ -1,35 +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
-}
+/**
+ * @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

@@ -1,49 +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)
-})
+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/point.js

@@ -1,71 +1,78 @@
-/**
- * @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
-  )
-}
+/**
+ * @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 [cx, cy, cz] = circle.position
+  const radius = circle.radius
+
+  return (
+    (x - cx) ** SQUARED + (y - cy) ** SQUARED + (z - cz) ** 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 [rectX, rectY, rectZ] = rectangle.position
+  const [width, height, depth] = rectangle.size
+
+  const left = rectX - width / HALF
+  const right = rectX + width / HALF
+  const bottom = rectY - height / HALF
+  const top = rectY + height / HALF
+  const back = rectZ - depth / HALF
+  const front = rectZ + depth / HALF
+
+  return (
+    x >= left &&
+    x <= right &&
+    y >= bottom &&
+    y <= top &&
+    z >= back &&
+    z <= front
+  )
+}