@inglorious/engine 0.1.1 → 0.2.0

package/src/engine/ai/movement/kinematic/seek.test.js

@@ -1,42 +1,42 @@
-import { expect, test } from "vitest"
-
-import seek from "./seek.js"
-
-test("it should move toward the target", () => {
-  const instance = { maxSpeed: 1, position: [0, 0, 0] }
-  const target = { position: [2, 0, 0] }
-  const options = { dt: 1 }
-  const expectedResult = {
-    position: [1, 0, 0],
-    velocity: [1, 0, 0],
-    orientation: 0,
-  }
-
-  expect(seek(instance, target, options)).toStrictEqual(expectedResult)
-})
-
-test("it should eventually reach the target", () => {
-  const instance = { maxSpeed: 1, position: [0, 0, 0] }
-  const target = { position: [2, 0, 0] }
-  const options = { dt: 2 }
-  const expectedResult = {
-    position: [2, 0, 0],
-    velocity: [1, 0, 0],
-    orientation: 0,
-  }
-
-  expect(seek(instance, target, options)).toStrictEqual(expectedResult)
-})
-
-test("it should overshoot when speed is too high", () => {
-  const instance = { maxSpeed: 10, position: [0, 0, 0] }
-  const target = { position: [2, 0, 0] }
-  const options = { dt: 1 }
-  const expectedResult = {
-    position: [10, 0, 0],
-    velocity: [10, 0, 0],
-    orientation: 0,
-  }
-
-  expect(seek(instance, target, options)).toStrictEqual(expectedResult)
-})
+import { expect, test } from "vitest"
+
+import { seek } from "./seek.js"
+
+test("it should move toward the target", () => {
+  const entity = { maxSpeed: 1, position: [0, 0, 0] }
+  const target = { position: [2, 0, 0] }
+  const dt = 1
+  const expectedResult = {
+    position: [1, 0, 0],
+    velocity: [1, 0, 0],
+    orientation: 0,
+  }
+
+  expect(seek(entity, target, dt)).toStrictEqual(expectedResult)
+})
+
+test("it should eventually reach the target", () => {
+  const entity = { maxSpeed: 1, position: [0, 0, 0] }
+  const target = { position: [2, 0, 0] }
+  const dt = 2
+  const expectedResult = {
+    position: [2, 0, 0],
+    velocity: [1, 0, 0],
+    orientation: 0,
+  }
+
+  expect(seek(entity, target, dt)).toStrictEqual(expectedResult)
+})
+
+test("it should overshoot when speed is too high", () => {
+  const entity = { maxSpeed: 10, position: [0, 0, 0] }
+  const target = { position: [2, 0, 0] }
+  const dt = 1
+  const expectedResult = {
+    position: [10, 0, 0],
+    velocity: [10, 0, 0],
+    orientation: 0,
+  }
+
+  expect(seek(entity, target, dt)).toStrictEqual(expectedResult)
+})

package/src/engine/ai/movement/kinematic/wander-as-seek.js

@@ -1,31 +1,31 @@
-import {
-  fromAngle,
-  multiply,
-} from "@inglorious/utils/math/linear-algebra/vector.js"
-import { sum } from "@inglorious/utils/math/linear-algebra/vectors.js"
-import { randomBinomial } from "@inglorious/utils/math/rng.js"
-
-import seek from "./seek.js"
-
-export const DEFAULT_WANDER_RADIUS = 10
-
-const DEFAULT_MAX_ANGULAR_SPEED = 0
-
-const DEFAULT_ORIENTATION = 0
-
-export default function wander(
-  instance,
-  { wanderRadius = DEFAULT_WANDER_RADIUS, ...options },
-) {
-  const maxAngularSpeed = instance.maxAngularSpeed ?? DEFAULT_MAX_ANGULAR_SPEED
-
-  let orientation = instance.orientation ?? DEFAULT_ORIENTATION
-  orientation += randomBinomial() * maxAngularSpeed
-
-  const position = sum(
-    instance.position,
-    multiply(fromAngle(orientation), wanderRadius),
-  )
-
-  return seek(instance, { position }, options)
-}
+import { seek } from "@inglorious/engine/ai/movement/kinematic/seek.js"
+import {
+  fromAngle,
+  multiply,
+} from "@inglorious/utils/math/linear-algebra/vector.js"
+import { sum } from "@inglorious/utils/math/linear-algebra/vectors.js"
+import { randomBinomial } from "@inglorious/utils/math/rng.js"
+
+export const DEFAULT_WANDER_RADIUS = 10
+
+const DEFAULT_MAX_ANGULAR_SPEED = 0
+
+const DEFAULT_ORIENTATION = 0
+
+export function wanderAsSeek(
+  entity,
+  dt,
+  { wanderRadius = DEFAULT_WANDER_RADIUS } = {},
+) {
+  const maxAngularSpeed = entity.maxAngularSpeed ?? DEFAULT_MAX_ANGULAR_SPEED
+
+  let orientation = entity.orientation ?? DEFAULT_ORIENTATION
+  orientation += randomBinomial() * maxAngularSpeed
+
+  const position = sum(
+    entity.position,
+    multiply(fromAngle(orientation), wanderRadius),
+  )
+
+  return seek(entity, { position }, dt)
+}

package/src/engine/ai/movement/kinematic/wander.js

@@ -1,27 +1,27 @@
-import {
-  angle,
-  createVector,
-  multiply,
-} from "@inglorious/utils/math/linear-algebra/vector.js"
-import { sum } from "@inglorious/utils/math/linear-algebra/vectors.js"
-import { randomBinomial } from "@inglorious/utils/math/rng.js"
-
-const DEFAULT_MAX_SPEED = 0
-const DEFAULT_MAX_ANGULAR_SPEED = 0
-
-const DEFAULT_ORIENTATION = 0
-
-export default function wander(instance, { dt }) {
-  const maxSpeed = instance.maxSpeed ?? DEFAULT_MAX_SPEED
-  const maxAngularSpeed = instance.maxAngularSpeed ?? DEFAULT_MAX_ANGULAR_SPEED
-
-  let orientation = instance.orientation ?? DEFAULT_ORIENTATION
-  orientation += randomBinomial() * maxAngularSpeed
-
-  const velocity = createVector(maxSpeed, orientation)
-
-  const position = sum(instance.position, multiply(velocity, dt))
-  orientation = angle(velocity)
-
-  return { velocity, position, orientation }
-}
+import {
+  angle,
+  createVector,
+  multiply,
+} from "@inglorious/utils/math/linear-algebra/vector.js"
+import { sum } from "@inglorious/utils/math/linear-algebra/vectors.js"
+import { randomBinomial } from "@inglorious/utils/math/rng.js"
+
+const DEFAULT_MAX_SPEED = 0
+const DEFAULT_MAX_ANGULAR_SPEED = 0
+
+const DEFAULT_ORIENTATION = 0
+
+export function wander(entity, dt) {
+  const maxSpeed = entity.maxSpeed ?? DEFAULT_MAX_SPEED
+  const maxAngularSpeed = entity.maxAngularSpeed ?? DEFAULT_MAX_ANGULAR_SPEED
+
+  let orientation = entity.orientation ?? DEFAULT_ORIENTATION
+  orientation += randomBinomial() * maxAngularSpeed
+
+  const velocity = createVector(maxSpeed, orientation)
+
+  const position = sum(entity.position, multiply(velocity, dt))
+  orientation = angle(velocity)
+
+  return { velocity, position, orientation }
+}

package/src/engine/animation/sprite.js

@@ -0,0 +1,101 @@
+/* eslint-disable no-magic-numbers */
+import { Ticker } from "@inglorious/engine/animation/ticker.js"
+import { mod } from "@inglorious/utils/math/numbers.js"
+import { pi, toRange } from "@inglorious/utils/math/trigonometry.js"
+
+export const Sprite = {
+  fromAngle,
+  move2,
+  move4,
+  move6,
+  move8,
+  play,
+}
+
+function move2(entity) {
+  return fromAngle(entity, ["right", "left"]) ?? "right"
+}
+
+function move4(entity) {
+  return fromAngle(entity, ["right", "up", "left", "down"]) ?? "down"
+}
+
+function move6(entity) {
+  return (
+    fromAngle(entity, [
+      "right",
+      "rightUp",
+      "leftUp",
+      "left",
+      "leftDown",
+      "rightDown",
+    ]) ?? "down"
+  )
+}
+
+function move8(entity) {
+  return (
+    fromAngle(entity, [
+      "right",
+      "rightUp",
+      "up",
+      "leftUp",
+      "left",
+      "leftDown",
+      "down",
+      "rightDown",
+    ]) ?? "down"
+  )
+}
+
+function play(animation, { entity, dt, notify }) {
+  const missing = [
+    animation == null && "'animation'",
+    entity == null && "'entity'",
+    dt == null && "'dt'",
+    notify == null && "'notify'",
+  ]
+    .filter(Boolean)
+    .join(", ")
+  if (missing.length) {
+    throw new Error(`Sprite.play is missing mandatory parameters: ${missing}`)
+  }
+
+  Ticker.tick({
+    target: entity.sprite,
+    state: animation,
+    dt,
+    onTick: (sprite) => {
+      const { frames, state: animation } = sprite
+      const framesLength = frames[animation].length
+      sprite.value = mod(sprite.value + 1, framesLength)
+      if (sprite.value === framesLength - 1) {
+        notify("spriteAnimationEnd", { entityId: entity.id, animation })
+      }
+    },
+  })
+}
+
+/**
+ * Determines a sprite state from an orientation angle, based on a list of states.
+ * The states are assumed to be ordered starting from the right (0 radians) and
+ * proceeding counter-clockwise.
+ *
+ * @param {object} entity - The entity with an orientation.
+ * @param {string[]} states - An array of state names corresponding to directions.
+ * @returns {string} The calculated state name.
+ */
+function fromAngle(entity, states) {
+  const directions = states.length
+  const slice = (2 * pi()) / directions
+
+  // Normalize orientation to [0, 2*PI)
+  const normalizedOrientation = mod(toRange(entity.orientation), 2 * pi())
+
+  // Shift by half a slice so that 0 rad is in the middle of the first slice, then find the index
+  const index = Math.floor(
+    mod(normalizedOrientation + slice / 2, 2 * pi()) / slice,
+  )
+
+  return states[index] ?? entity.sprite.state
+}

package/src/engine/animation/ticker.js

@@ -0,0 +1,38 @@
+const DEFAULT_STATE = "default"
+const DEFAULT_VALUE = 0
+const COUNTER_RESET = 0
+
+export const Ticker = { tick }
+
+function tick({ target, state = DEFAULT_STATE, dt, onTick, ...options }) {
+  const missing = [target == null && "'target'", dt == null && "'dt'"]
+    .filter(Boolean)
+    .join(", ")
+  if (missing.length) {
+    throw new Error(`Ticker.tick is missing mandatory parameters: ${missing}`)
+  }
+
+  const { speed, defaultValue = DEFAULT_VALUE } = target
+
+  // The `state` property on a sprite is used to declare the desired animation.
+  // The Ticker needs its own internal property to track the *current* animation
+  // to detect when it changes. We'll use `target.animation`.
+  if (state !== target.animation) {
+    target.animation = state
+    target.counter = COUNTER_RESET
+    target.value = defaultValue
+  }
+
+  // Always ensure the public `state` property reflects the intended animation for `onTick`.
+  target.state = state
+
+  // Ensure properties are initialized on the first run for a given target.
+  target.counter ??= COUNTER_RESET
+  target.value ??= defaultValue
+
+  target.counter += dt
+  if (target.counter >= speed) {
+    target.counter = COUNTER_RESET
+    onTick?.(target, dt, options)
+  }
+}

package/src/engine/behaviors/camera.js

@@ -0,0 +1,68 @@
+import { arrive } from "@inglorious/engine/ai/movement/dynamic/arrive.js"
+import {
+  defaults,
+  extend,
+  merge,
+} from "@inglorious/utils/data-structures/objects.js"
+import { lerp } from "@inglorious/utils/math/linear-interpolation.js"
+
+const DEFAULT_PARAMS = {
+  zoom: 1,
+  zoomSpeed: 0.1,
+  zoomSensitivity: 5,
+  minZoom: 0.5,
+  maxZoom: 4,
+  targetId: null,
+}
+
+const X = 0
+const Y = 1
+
+export function camera(params) {
+  params = extend(DEFAULT_PARAMS, params)
+
+  return {
+    start(entity) {
+      defaults(entity, params)
+      entity.targetZoom = entity.zoom
+      // Cache the initial size to calculate the viewport in dev mode
+      if (entity.size) {
+        entity.baseSize = [...entity.size]
+      }
+    },
+
+    update(entity, dt, api) {
+      // Follow target
+      if (entity.targetId) {
+        const target = api.getEntity(entity.targetId)
+        if (target) {
+          // The camera will "arrive" at the target's position.
+          // You can tweak the parameters in the entity definition
+          // to change how the camera follows the target.
+          merge(entity, arrive(entity, target, dt))
+        }
+      }
+
+      // Smooth zoom
+      if (entity.zoom !== entity.targetZoom) {
+        entity.zoom = lerp(entity.zoom, entity.targetZoom, entity.zoomSpeed)
+
+        // Update the visual size of the camera's viewport for dev mode
+        if (entity.baseSize) {
+          entity.size[X] = entity.baseSize[X] / entity.zoom
+          entity.size[Y] = entity.baseSize[Y] / entity.zoom
+        }
+      }
+    },
+
+    mouseWheel(entity, { deltaY }) {
+      const delta = Math.sign(deltaY)
+      // Scrolling down (positive deltaY) should zoom out (decrease zoom value)
+      entity.targetZoom -= delta * entity.zoomSpeed * entity.zoomSensitivity
+      entity.targetZoom = Math.max(
+        entity.minZoom,
+        Math.min(entity.maxZoom, entity.targetZoom),
+      )
+    },
+  }
+}

package/src/engine/behaviors/controls/dynamic/modern.js

@@ -0,0 +1,76 @@
+import { modernMove } from "@inglorious/engine/movement/dynamic/modern.js"
+import { extend, merge } from "@inglorious/utils/data-structures/objects.js"
+import { zero } from "@inglorious/utils/math/linear-algebra/vector.js"
+
+import { createMovementEventHandlers } from "../event-handlers.js"
+
+const DEFAULT_PARAMS = {
+  maxAcceleration: 500,
+}
+const X = 0
+const Z = 2
+
+export function modernAcceleration(params) {
+  params = extend(DEFAULT_PARAMS, params)
+
+  return (type) =>
+    extend(type, {
+      ...createMovementEventHandlers([
+        "moveLeft",
+        "moveRight",
+        "moveUp",
+        "moveDown",
+        "moveLeftRight",
+        "moveUpDown",
+      ]),
+
+      start(entity, api) {
+        type.start?.(entity, api)
+
+        entity.maxAcceleration ??= params.maxAcceleration
+        entity.movement ??= {}
+      },
+
+      update(entity, dt, api) {
+        type.update?.(entity, dt, api)
+
+        const { movement, maxAcceleration } = entity
+        entity.acceleration = zero()
+
+        if (movement.moveLeft) {
+          entity.acceleration[X] = -maxAcceleration
+        }
+        if (movement.moveRight) {
+          entity.acceleration[X] = maxAcceleration
+        }
+        if (movement.moveUp) {
+          entity.acceleration[Z] = maxAcceleration
+        }
+        if (movement.moveDown) {
+          entity.acceleration[Z] = -maxAcceleration
+        }
+
+        if (movement.moveLeftRight) {
+          entity.acceleration[X] += movement.moveLeftRight * maxAcceleration
+        }
+        if (movement.moveUpDown) {
+          entity.acceleration[Z] += -movement.moveUpDown * maxAcceleration
+        }
+      },
+    })
+}
+
+export function modernControls(params) {
+  const accelerationBehavior = modernAcceleration(params)
+
+  return (type) => {
+    const newType = accelerationBehavior(type)
+
+    return extend(newType, {
+      update(entity, dt, api) {
+        newType.update?.(entity, dt, api)
+        merge(entity, modernMove(entity, dt))
+      },
+    })
+  }
+}

package/src/engine/behaviors/controls/dynamic/shooter.js

@@ -0,0 +1,84 @@
+import { face } from "@inglorious/engine/ai/movement/dynamic/face.js"
+import { tankMove } from "@inglorious/engine/movement/dynamic/tank.js"
+import { extend, merge } from "@inglorious/utils/data-structures/objects.js"
+import { zero } from "@inglorious/utils/math/linear-algebra/vector.js"
+import { pi } from "@inglorious/utils/math/trigonometry.js"
+
+import { createMovementEventHandlers } from "../event-handlers.js"
+
+const FULL_CIRCLE = 2
+const DEFAULT_PARAMS = {
+  maxSpeed: 250,
+  maxAngularSpeed: FULL_CIRCLE * pi(),
+  maxAcceleration: 500,
+}
+const X = 0
+const Z = 2
+
+export function shooterControls(params) {
+  params = extend(DEFAULT_PARAMS, params)
+
+  const DEADZONE = 0.1
+  const NO_MOVEMENT = 0
+
+  return (type) =>
+    extend(type, {
+      ...createMovementEventHandlers([
+        "moveLeft",
+        "moveRight",
+        "moveUp",
+        "moveDown",
+        "strafe",
+        "move",
+        "turn",
+      ]),
+
+      start(entity, api) {
+        type.start?.(entity, api)
+
+        entity.maxSpeed ??= params.maxSpeed
+        entity.maxAngularSpeed ??= params.maxAngularSpeed
+        entity.maxAcceleration ??= params.maxAcceleration
+        entity.movement ??= {}
+      },
+
+      update(entity, dt, api) {
+        const mouse = api.getEntity("mouse")
+
+        const { movement, maxAngularSpeed, maxAcceleration } = entity
+        entity.acceleration = zero()
+
+        if (movement.moveLeft) {
+          entity.acceleration[Z] = -maxAcceleration
+        }
+        if (movement.moveRight) {
+          entity.acceleration[Z] = maxAcceleration
+        }
+        if (movement.moveUp) {
+          entity.acceleration[X] = maxAcceleration
+        }
+        if (movement.moveDown) {
+          entity.acceleration[X] = -maxAcceleration
+        }
+
+        if (movement.strafe) {
+          entity.acceleration[Z] += movement.strafe * maxAcceleration
+        }
+        if (movement.move) {
+          entity.acceleration[X] += -movement.move * maxAcceleration
+        }
+        if (movement.turn) {
+          entity.orientation += -movement.turn * maxAngularSpeed * dt
+        }
+
+        const isUsingAnalogMovement =
+          Math.abs(movement.move ?? NO_MOVEMENT) > DEADZONE ||
+          Math.abs(movement.strafe ?? NO_MOVEMENT) > DEADZONE
+
+        if (!isUsingAnalogMovement) {
+          merge(entity, face(entity, mouse, dt))
+        }
+        merge(entity, tankMove(entity, dt))
+      },
+    })
+}

package/src/engine/behaviors/controls/dynamic/tank.js

@@ -0,0 +1,69 @@
+import { tankMove } from "@inglorious/engine/movement/dynamic/tank.js"
+import { extend, merge } from "@inglorious/utils/data-structures/objects.js"
+import { zero } from "@inglorious/utils/math/linear-algebra/vector.js"
+
+import { createMovementEventHandlers } from "../event-handlers.js"
+
+const DEFAULT_PARAMS = {
+  maxSpeed: 250,
+  maxAngularSpeed: 10,
+  maxAcceleration: 500,
+}
+const X = 0
+const Z = 2
+
+export function tankControls(params) {
+  params = extend(DEFAULT_PARAMS, params)
+
+  return (type) =>
+    extend(type, {
+      ...createMovementEventHandlers([
+        "turnLeft",
+        "turnRight",
+        "moveForward",
+        "moveBackward",
+        "strafe",
+        "move",
+        "turn",
+      ]),
+
+      start(entity, api) {
+        type.start?.(entity, api)
+
+        entity.maxSpeed ??= params.maxSpeed
+        entity.maxAngularSpeed ??= params.maxAngularSpeed
+        entity.maxAcceleration ??= params.maxAcceleration
+        entity.movement ??= {}
+      },
+
+      update(entity, dt) {
+        const { movement, maxAngularSpeed, maxAcceleration } = entity
+        entity.acceleration = zero()
+
+        if (movement.turnLeft) {
+          entity.orientation += maxAngularSpeed * dt
+        }
+        if (movement.turnRight) {
+          entity.orientation -= maxAngularSpeed * dt
+        }
+        if (movement.moveForward) {
+          entity.acceleration[X] = maxAcceleration
+        }
+        if (movement.moveBackward) {
+          entity.acceleration[X] = -maxAcceleration
+        }
+
+        if (movement.strafe != null) {
+          entity.acceleration[Z] += movement.strafe * maxAcceleration
+        }
+        if (movement.move) {
+          entity.acceleration[X] += -movement.move * maxAcceleration
+        }
+        if (movement.turn) {
+          entity.orientation += -movement.turn * maxAngularSpeed * dt
+        }
+
+        merge(entity, tankMove(entity, dt))
+      },
+    })
+}

package/src/engine/behaviors/controls/event-handlers.js

@@ -0,0 +1,17 @@
+export function createMovementEventHandlers(events) {
+  return events.reduce((acc, eventName) => {
+    acc[eventName] = (entity, { entityId, value }) => {
+      if (entityId === entity.id) {
+        entity.movement[eventName] = value ?? true
+      }
+    }
+
+    acc[`${eventName}End`] = (entity, { entityId }) => {
+      if (entityId === entity.id) {
+        entity.movement[eventName] = false
+      }
+    }
+
+    return acc
+  }, {})
+}