@inglorious/engine 0.1.0 → 0.2.0

package/src/utils/physics/gravity.js

@@ -1,71 +1,69 @@
-/**
- * @typedef {import('@inglorious/utils/math/linear-algebra/types').Vector3} Vector3
- */
-
-/* eslint-disable no-magic-numbers */
-
-import { zero } from "@inglorious/utils/math/linear-algebra/vector.js"
-
-const DEFAULT_OPTIONS = { dt: 0 } // Default options for the applyGravity function.
-const DEFAULT_JUMP = 0 // Default maximum jump height.
-const DEFAULT_LEAP = 0 // Default maximum leap distance.
-const DEFAULT_SPEED = 0 // Default maximum speed.
-const NO_VELOCITY = 0 // No initial velocity.
-
-/**
- * Applies gravity to an object based on its current velocity and position.
- *
- * @see https://youtu.be/hG9SzQxaCm8
- *
- * Projectile equations:
- * 1. a(t) = g
- * 2. v(t) = g*t + v_0
- * 3. y(t) = 1/2*g*t^2 + v_0*t + y_0
- *
- * Known values:
- * 1. y_0 = 0
- * 2. v(t_h) = 0 -> 2. 0 = g*t_h + v_0 -> v_0 = -g*t_h
- * 3. y_h = h -> 3. h = 1/2*g*t_h^2 (-g*t_h)*t_h = -1/2*g*t_h^2 -> g = -2*h/t_h^2
- * 4. v_0 = -g*t_h = (-2*h/t_h^2)*t_h = 2*h/t_h
- *
- * Transforming time into space:
- * 1. t_h = x_h/v_x
- * 2. v0 = 2*h/t_h = 2*h*v_x/x_h
- * 3. g = -2*h/t_h^2 = -2*h*v_x^2/x_h^2
- *
- * Euler's Integration:
- * 1. v += a * dt
- * 2. p += v * dt + 1/2 * a * dt * dt
- *
- * @param {Object} params - Parameters for gravity calculation.
- * @param {number} params.maxJump - Maximum jump height. Defaults to 0.
- * @param {number} params.maxLeap - Maximum leap distance. Defaults to 0.
- * @param {number} params.maxSpeed - Maximum speed. Defaults to 0.
- * @param {number} params.vy - Current vertical velocity. Defaults to 0.
- * @param {Vector3} params.position - Current position vector.
- * @param {Object} [options=DEFAULT_OPTIONS] - Additional options.
- * @param {number} options.dt - Time delta for the calculation.
- * @returns {Object} Updated acceleration, velocity, and position.
- * @throws {Error} If maxLeap is not provided.
- */
-export function applyGravity(params, options = DEFAULT_OPTIONS) {
-  let {
-    maxJump = DEFAULT_JUMP,
-    maxLeap = DEFAULT_LEAP,
-    maxSpeed = DEFAULT_SPEED,
-    vy = NO_VELOCITY,
-    position = zero(),
-  } = params
-
-  if (!maxLeap) {
-    throw new Error("Missing maxLeap")
-  }
-
-  const { dt } = options
-  const ay = (-2 * maxJump * maxSpeed ** 2) / maxLeap ** 2
-  vy += ay * dt
-  const [x, y, z] = position
-  const py = y + vy * dt + 0.5 * ay * dt * dt
-
-  return { ay, vy, position: [x, py, z] }
-}
+/**
+ * @typedef {import('@inglorious/utils/math/linear-algebra/types').Vector3} Vector3
+ */
+
+/* eslint-disable no-magic-numbers */
+
+import { zero } from "@inglorious/utils/math/linear-algebra/vector.js"
+
+const DEFAULT_DT = 1 // Default delta time for the applyGravity function.
+const DEFAULT_JUMP = 0 // Default maximum jump height.
+const DEFAULT_LEAP = 0 // Default maximum leap distance.
+const DEFAULT_SPEED = 0 // Default maximum speed.
+const NO_VELOCITY = 0 // No initial velocity.
+
+/**
+ * Applies gravity to an object based on its current velocity and position.
+ *
+ * @see https://youtu.be/hG9SzQxaCm8
+ *
+ * Projectile equations:
+ * 1. a(t) = g
+ * 2. v(t) = g*t + v_0
+ * 3. y(t) = 1/2*g*t^2 + v_0*t + y_0
+ *
+ * Known values:
+ * 1. y_0 = 0
+ * 2. v(t_h) = 0 -> 2. 0 = g*t_h + v_0 -> v_0 = -g*t_h
+ * 3. y_h = h -> 3. h = 1/2*g*t_h^2 (-g*t_h)*t_h = -1/2*g*t_h^2 -> g = -2*h/t_h^2
+ * 4. v_0 = -g*t_h = (-2*h/t_h^2)*t_h = 2*h/t_h
+ *
+ * Transforming time into space:
+ * 1. t_h = x_h/v_x
+ * 2. v0 = 2*h/t_h = 2*h*v_x/x_h
+ * 3. g = -2*h/t_h^2 = -2*h*v_x^2/x_h^2
+ *
+ * Euler's Integration:
+ * 1. v += a * dt
+ * 2. p += v * dt + 1/2 * a * dt * dt
+ *
+ * @param {Object} params - Parameters for gravity calculation.
+ * @param {number} params.maxJump - Maximum jump height. Defaults to 0.
+ * @param {number} params.maxLeap - Maximum leap distance. Defaults to 0.
+ * @param {number} params.maxSpeed - Maximum speed. Defaults to 0.
+ * @param {number} params.vy - Current vertical velocity. Defaults to 0.
+ * @param {Vector3} params.position - Current position vector. Defaults to a zero vector.
+ * @param {number} dt - Time delta for the calculation. Defaults to 1.
+ * @returns {Object} Updated acceleration, velocity, and position.
+ * @throws {Error} If maxLeap is not provided.
+ */
+export function applyGravity(params, dt = DEFAULT_DT) {
+  let {
+    maxJump = DEFAULT_JUMP,
+    maxLeap = DEFAULT_LEAP,
+    maxSpeed = DEFAULT_SPEED,
+    vy = NO_VELOCITY,
+    position = zero(),
+  } = params
+
+  if (!maxLeap) {
+    throw new Error("Missing maxLeap")
+  }
+
+  const ay = (-2 * maxJump * maxSpeed ** 2) / maxLeap ** 2
+  vy += ay * dt
+  const [x, y, z] = position
+  const py = y + vy * dt + 0.5 * ay * dt * dt
+
+  return { ay, vy, position: [x, py, z] }
+}

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

@@ -1,80 +1,77 @@
-import { expect, test } from "vitest"
-
-import { applyGravity } from "./gravity.js"
-
-test("it should compute no gravity when max jump height is not set", () => {
-  const params = {
-    maxLeap: 10,
-    maxSpeed: 10,
-    vy: 10,
-    position: [0, 10, 0],
-  }
-  const dt = 1
-
-  expect(applyGravity(params, { dt })).toStrictEqual({
-    ay: -0,
-    vy: 10,
-    position: [0, 20, 0],
-  })
-})
-
-test("it should throw an error when max leap distance is not set", () => {
-  const params = {
-    maxJump: 10,
-    maxSpeed: 10,
-    vy: 10,
-    position: [0, 10, 0],
-  }
-  const dt = 1
-
-  expect(() => applyGravity(params, { dt })).toThrow()
-})
-
-test("it should compute no gravity when max movement speed is not set", () => {
-  const params = {
-    maxJump: 10,
-    maxLeap: 10,
-    vy: 10,
-    position: [0, 10, 0],
-  }
-  const dt = 1
-
-  expect(applyGravity(params, { dt })).toStrictEqual({
-    ay: -0,
-    vy: 10,
-    position: [0, 20, 0],
-  })
-})
-
-test("it should apply no gravity when no time has passed (gravity is calculated but not applied)", () => {
-  const params = {
-    maxJump: 10,
-    maxLeap: 10,
-    maxSpeed: 10,
-    vy: 10,
-    position: [0, 10, 0],
-  }
-
-  expect(applyGravity(params)).toStrictEqual({
-    ay: -20,
-    vy: 10,
-    position: [0, 10, 0],
-  })
-})
-
-test("it should apply gravity based on input parameters", () => {
-  const params = {
-    maxJump: 10,
-    maxLeap: 10,
-    maxSpeed: 10,
-    vy: 10,
-    position: [0, 10, 0],
-  }
-  const dt = 1
-
-  expect(applyGravity(params, { dt })).toStrictEqual({
-    ay: -20,
-    vy: -10,
-    position: [0, -10, 0],
-  })
-})
+import { expect, test } from "vitest"
+
+import { applyGravity } from "./gravity.js"
+
+test("it should apply gravity based on input parameters", () => {
+  const params = {
+    maxJump: 10,
+    maxLeap: 10,
+    maxSpeed: 10,
+    vy: 10,
+    position: [0, 10, 0],
+  }
+
+  expect(applyGravity(params)).toStrictEqual({
+    ay: -20,
+    vy: -10,
+    position: [0, -10, 0],
+  })
+})
+
+test("it should compute no gravity when max jump height is not set", () => {
+  const params = {
+    maxLeap: 10,
+    maxSpeed: 10,
+    vy: 10,
+    position: [0, 10, 0],
+  }
+
+  expect(applyGravity(params)).toStrictEqual({
+    ay: -0,
+    vy: 10,
+    position: [0, 20, 0],
+  })
+})
+
+test("it should compute no gravity when max movement speed is not set", () => {
+  const params = {
+    maxJump: 10,
+    maxLeap: 10,
+    vy: 10,
+    position: [0, 10, 0],
+  }
+
+  expect(applyGravity(params)).toStrictEqual({
+    ay: -0,
+    vy: 10,
+    position: [0, 20, 0],
+  })
+})
+
+test("it should apply no gravity when no time has passed", () => {
+  const params = {
+    maxJump: 10,
+    maxLeap: 10,
+    maxSpeed: 10,
+    vy: 10,
+    position: [0, 10, 0],
+  }
+  const dt = 0
+
+  expect(applyGravity(params, dt)).toStrictEqual({
+    ay: -20,
+    vy: 10,
+    position: [0, 10, 0],
+  })
+})
+
+test("it should throw an error when max leap distance is not set", () => {
+  const params = {
+    maxJump: 10,
+    maxSpeed: 10,
+    vy: 10,
+    position: [0, 10, 0],
+  }
+
+  expect(() => applyGravity(params)).toThrow()
+})

package/src/utils/physics/jump.js

@@ -1,41 +1,31 @@
-/**
- * @typedef {import('@inglorious/utils/math/linear-algebra/types').Vector3} Vector3
- */
-
-/* eslint-disable no-magic-numbers */
-
-import { zero } from "@inglorious/utils/math/linear-algebra/vector.js"
-
-const DEFAULT_OPTIONS = { dt: 0 } // Default options for the jump function.
-const DEFAULT_MAX_JUMP = 0 // Default maximum jump height.
-const DEFAULT_MAX_LEAP = 0 // Default maximum leap distance.
-const DEFAULT_MAX_SPEED = 0 // Default maximum speed.
-
-/**
- * Calculates the vertical velocity (vy) and updates the Y position
- * based on the provided parameters and options.
- *
- * @param {Object} params - Parameters for the jump calculation.
- * @param {number} params.maxJump - Maximum jump height. Defaults to 0.
- * @param {number} params.maxLeap - Maximum leap distance. Defaults to 0.
- * @param {number} params.maxSpeed - Maximum speed. Defaults to 0.
- * @param {Vector3} params.position - Current position vector.
- * @param {Object} [options=DEFAULT_OPTIONS] - Options for the jump calculation.
- * @param {number} options.dt - Delta time for the calculation. Defaults to 0.
- * @returns {Object} An object containing the vertical velocity (vy) and updated position.
- */
-export function jump(params, options = DEFAULT_OPTIONS) {
-  let {
-    maxJump = DEFAULT_MAX_JUMP,
-    maxLeap = DEFAULT_MAX_LEAP,
-    maxSpeed = DEFAULT_MAX_SPEED,
-    position = zero(),
-  } = params
-  const { dt } = options
-
-  const vy = (2 * maxJump * maxSpeed) / maxLeap
-  const [x, y, z] = position
-  const py = y + vy * dt
-
-  return { vy, position: [x, py, z] }
-}
+/**
+ * @typedef {import('@inglorious/utils/math/linear-algebra/types').Vector3} Vector3
+ */
+
+/* eslint-disable no-magic-numbers */
+
+const DEFAULT_MAX_JUMP = 0 // Default maximum jump height.
+const DEFAULT_MAX_LEAP = 0 // Default maximum leap distance.
+const DEFAULT_MAX_SPEED = 0 // Default maximum speed.
+
+/**
+ * Calculates the vertical velocity (vy) of a jump
+ * based on the provided parameters.
+ *
+ * @param {Object} params - Parameters for the jump calculation.
+ * @param {number} params.maxJump - Maximum jump height. Defaults to 0.
+ * @param {number} params.maxLeap - Maximum leap distance. Defaults to 0.
+ * @param {number} params.maxSpeed - Maximum speed. Defaults to 0.
+ * @returns {number} The computed vertical velocity (vy).
+ */
+export function jump(params) {
+  let {
+    maxJump = DEFAULT_MAX_JUMP,
+    maxLeap = DEFAULT_MAX_LEAP,
+    maxSpeed = DEFAULT_MAX_SPEED,
+  } = params
+
+  const vy = (2 * maxJump * maxSpeed) / maxLeap
+
+  return vy
+}

package/src/utils/physics/velocity.js

@@ -1,38 +1,36 @@
-/**
- * @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"
-
-const DEFAULT_OPTIONS = { dt: 0 } // Default options for the applyVelocity function.
-const DEFAULT_MAX_SPEED = 0 // Default maximum speed for velocity clamping.
-
-/**
- * Applies velocity to a position based on the given parameters and options.
- *
- * @param {Object} params - The parameters for velocity application.
- * @param {number} [params.maxSpeed] - The maximum speed for clamping the velocity. Defaults to 0.
- * @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 {Object} [options=DEFAULT_OPTIONS] - Additional options for velocity application.
- * @param {number} [options.dt=0] - The time delta for the calculation. Defaults to 0.
- * @returns {Object} The updated velocity and position.
- */
-export function applyVelocity(params, options = DEFAULT_OPTIONS) {
-  let {
-    maxSpeed = DEFAULT_MAX_SPEED,
-    velocity = zero(),
-    position = zero(),
-  } = params
-  const { dt } = options
-
-  velocity = clamp(velocity, -maxSpeed, maxSpeed)
-
-  position = sum(position, multiply(velocity, dt))
-  return { 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"
+
+const DEFAULT_DT = 1 // Default time delta for the applyVelocity function.
+const DEFAULT_MAX_SPEED = 0 // Default maximum speed for velocity clamping.
+
+/**
+ * Applies velocity to a position based on the given parameters and options.
+ *
+ * @param {Object} params - The parameters for velocity application.
+ * @param {number} [params.maxSpeed] - The maximum speed for clamping the velocity. Defaults to 0.
+ * @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} [dt=0] - The time delta for the calculation. Defaults to 0.
+ * @returns {Object} The updated velocity and position.
+ */
+export function applyVelocity(params, dt = DEFAULT_DT) {
+  let {
+    maxSpeed = DEFAULT_MAX_SPEED,
+    velocity = zero(),
+    position = zero(),
+  } = params
+
+  velocity = clamp(velocity, -maxSpeed, maxSpeed)
+
+  position = sum(position, multiply(velocity, dt))
+  return { velocity, position }
+}

package/src/docs/ai/movement/dynamic/align.js

@@ -1,131 +0,0 @@
-import align, {
-  DEFAULT_SLOW_RADIUS,
-  DEFAULT_TARGET_RADIUS,
-  DEFAULT_TIME_TO_TARGET,
-} from "@inglorious/engine/ai/movement/dynamic/align.js"
-import { clampToBounds } from "@inglorious/game/bounds.js"
-import { enableCharacter } from "@inglorious/game/decorators/character.js"
-import {
-  createControls,
-  enableControls,
-} from "@inglorious/game/decorators/input/controls.js"
-import { enableMouse } from "@inglorious/game/decorators/input/mouse.js"
-import { merge } from "@inglorious/utils/data-structures/objects.js"
-import { clamp } from "@inglorious/utils/math/numbers.js"
-import { pi } from "@inglorious/utils/math/trigonometry.js"
-
-export default {
-  types: {
-    mouse: [
-      enableMouse(),
-      {
-        "field:change"(instance, event) {
-          const { id, value } = event.payload
-          if (id === "targetOrientation") {
-            instance.orientation = -value * pi()
-          }
-        },
-
-        "game:update"(instance, event, options) {
-          const { input0 } = options.instances
-
-          if (input0.left || input0.up) {
-            instance.orientation += 0.1
-          } else if (input0.right || input0.down) {
-            instance.orientation -= 0.1
-          }
-          instance.orientation = clamp(instance.orientation, -pi(), pi())
-        },
-      },
-    ],
-
-    ...enableControls(),
-
-    character: [
-      enableCharacter(),
-      {
-        "game:update"(instance, event, { dt, instances }) {
-          const target = instances.mouse
-          const { fields } = instances.parameters.groups.align
-
-          merge(
-            instance,
-            align(instance, target, {
-              dt,
-              targetRadius: fields.targetRadius.value,
-              slowRadius: fields.slowRadius.value,
-              timeToTarget: fields.timeToTarget.value,
-            }),
-          )
-
-          clampToBounds(instance, instances.game.bounds)
-        },
-      },
-    ],
-
-    form: {
-      "field:change"(instance, event) {
-        const { id, value } = event.payload
-        instance.groups.align.fields[id].value = value
-      },
-    },
-  },
-
-  instances: {
-    mouse: {
-      type: "mouse",
-      position: [400, 0, 300],
-      orientation: 0,
-    },
-
-    ...createControls("input0", {
-      ArrowLeft: "left",
-      ArrowRight: "right",
-      ArrowDown: "down",
-      ArrowUp: "up",
-    }),
-
-    character: {
-      type: "character",
-      maxAngularSpeed: pi() / 4,
-      maxAngularAcceleration: 10,
-      position: [400, 0, 300],
-    },
-
-    parameters: {
-      type: "form",
-      position: [800 - 328, 0, 600],
-      groups: {
-        align: {
-          title: "Dynamic Align",
-          fields: {
-            targetRadius: {
-              label: "Target Radius",
-              inputType: "number",
-              defaultValue: DEFAULT_TARGET_RADIUS,
-            },
-            slowRadius: {
-              label: "Slow Radius",
-              inputType: "number",
-              defaultValue: DEFAULT_SLOW_RADIUS,
-            },
-            timeToTarget: {
-              label: "Time To Target",
-              inputType: "number",
-              step: 0.1,
-              defaultValue: DEFAULT_TIME_TO_TARGET,
-            },
-            targetOrientation: {
-              label: "Target Orientation",
-              inputType: "number",
-              step: 0.25,
-              min: -1,
-              max: 1,
-              defaultValue: 0,
-            },
-          },
-        },
-      },
-    },
-  },
-}

package/src/docs/ai/movement/dynamic/arrive.js

@@ -1,88 +0,0 @@
-import arrive, {
-  DEFAULT_SLOW_RADIUS,
-  DEFAULT_TARGET_RADIUS,
-  DEFAULT_TIME_TO_TARGET,
-} from "@inglorious/engine/ai/movement/dynamic/arrive.js"
-import { clampToBounds } from "@inglorious/game/bounds.js"
-import { enableCharacter } from "@inglorious/game/decorators/character.js"
-import { enableMouse } from "@inglorious/game/decorators/input/mouse.js"
-import { merge } from "@inglorious/utils/data-structures/objects.js"
-
-export default {
-  types: {
-    mouse: [enableMouse()],
-
-    character: [
-      enableCharacter(),
-      {
-        "game:update"(instance, event, { dt, instances }) {
-          const target = instances.mouse
-          const { fields } = instances.parameters.groups.arrive
-
-          merge(
-            instance,
-            arrive(instance, target, {
-              dt,
-              targetRadius: fields.targetRadius.value,
-              slowRadius: fields.slowRadius.value,
-              timeToTarget: fields.timeToTarget.value,
-            }),
-          )
-
-          clampToBounds(instance, instances.game.bounds)
-        },
-      },
-    ],
-
-    form: {
-      "field:change"(instance, event) {
-        const { id, value } = event.payload
-        instance.groups.arrive.fields[id].value = value
-      },
-    },
-  },
-
-  instances: {
-    mouse: {
-      type: "mouse",
-      position: [400, 0, 300],
-    },
-
-    character: {
-      type: "character",
-      maxAcceleration: 1000,
-      maxSpeed: 250,
-      position: [400, 0, 300],
-    },
-
-    parameters: {
-      type: "form",
-      position: [800 - 328, 0, 600],
-      groups: {
-        arrive: {
-          title: "Dynamic Arrive",
-          fields: {
-            targetRadius: {
-              label: "Target Radius",
-              inputType: "number",
-              step: 0.1,
-              defaultValue: DEFAULT_TARGET_RADIUS,
-            },
-            slowRadius: {
-              label: "Slow Radius",
-              inputType: "number",
-              step: 0.1,
-              defaultValue: DEFAULT_SLOW_RADIUS,
-            },
-            timeToTarget: {
-              label: "Time To Target",
-              inputType: "number",
-              step: 0.1,
-              defaultValue: DEFAULT_TIME_TO_TARGET,
-            },
-          },
-        },
-      },
-    },
-  },
-}