@inglorious/engine 0.1.0

package/src/engine/loop/flash.js

@@ -0,0 +1,14 @@
+export default class FlashLoop {
+  _shouldStop = false
+
+  start(engine) {
+    while (!this._shouldStop) {
+      engine.update()
+      engine.render()
+    }
+  }
+
+  stop() {
+    this._shouldStop = true
+  }
+}

package/src/engine/loop/lag.js

@@ -0,0 +1,27 @@
+const ONE_SECOND = 1000
+
+export default class LagLoop {
+  _shouldStop = false
+
+  start(engine, msPerUpdate) {
+    let previousTime = Date.now()
+    let lag = 0
+
+    while (!this._shouldStop) {
+      const currentTime = Date.now()
+      const dt = currentTime - previousTime
+      previousTime = currentTime
+      lag += dt
+
+      while (lag >= msPerUpdate) {
+        engine.update(dt / ONE_SECOND)
+        engine.render(dt / ONE_SECOND)
+        lag -= msPerUpdate
+      }
+    }
+  }
+
+  stop() {
+    this._shouldStop = true
+  }
+}

package/src/engine/loop.js

@@ -0,0 +1,15 @@
+import AnimationFrameLoop from "./loop/animation-frame.js"
+import ElapsedLoop from "./loop/elapsed.js"
+import FixedLoop from "./loop/fixed.js"
+import FlashLoop from "./loop/flash.js"
+import LagLoop from "./loop/lag.js"
+
+// @see https://gameprogrammingpatterns.com/game-loop.html
+
+export default {
+  flash: FlashLoop,
+  fixed: FixedLoop,
+  elapsed: ElapsedLoop,
+  lag: LagLoop,
+  animationFrame: AnimationFrameLoop,
+}

package/src/engine/movement/dynamic/modern.js

@@ -0,0 +1,24 @@
+import {
+  angle,
+  magnitude,
+} from "@inglorious/utils/math/linear-algebra/vector.js"
+import { applyAcceleration } from "@inglorious/utils/physics/acceleration.js"
+
+const DEFAULT_ORIENTATION = 0
+
+const ORIENTATION_CHANGE_THRESHOLD = 4
+
+export default function modernMove(instance, options) {
+  const { acceleration, velocity, position } = applyAcceleration(
+    instance,
+    options,
+  )
+
+  let orientation = instance.orientation ?? DEFAULT_ORIENTATION
+  orientation =
+    magnitude(velocity) > ORIENTATION_CHANGE_THRESHOLD
+      ? angle(velocity)
+      : orientation
+
+  return { acceleration, velocity, position, orientation }
+}

package/src/engine/movement/dynamic/tank.js

@@ -0,0 +1,43 @@
+import {
+  clamp,
+  multiply,
+  rotate,
+  zero,
+} from "@inglorious/utils/math/linear-algebra/vector.js"
+import { sum } from "@inglorious/utils/math/linear-algebra/vectors.js"
+import { toRange } from "@inglorious/utils/math/trigonometry.js"
+import { applyFriction } from "@inglorious/utils/physics/friction.js"
+
+const DEFAULT_MAX_ACCELERATION = 0
+const DEFAULT_MAX_SPEED = 0
+const DEFAULT_FRICTION = 0
+
+const DEFAULT_ORIENTATION = 0
+
+const HALF_ACCELERATION = 0.5
+
+export default function tankMove(instance, { dt }) {
+  const maxAcceleration = instance.maxAcceleration ?? DEFAULT_MAX_ACCELERATION
+  const maxSpeed = instance.maxSpeed ?? DEFAULT_MAX_SPEED
+  const friction = instance.friction ?? DEFAULT_FRICTION
+
+  let orientation = instance.orientation ?? DEFAULT_ORIENTATION
+  orientation = toRange(orientation)
+
+  let acceleration = instance.acceleration ?? zero()
+  acceleration = rotate(acceleration, orientation)
+  acceleration = clamp(acceleration, -maxAcceleration, maxAcceleration)
+
+  let velocity = instance.velocity ?? zero()
+  velocity = sum(velocity, multiply(acceleration, dt))
+  velocity = clamp(velocity, -maxSpeed, maxSpeed)
+  velocity = applyFriction({ velocity, friction }, { dt })
+
+  const position = sum(
+    instance.position,
+    multiply(velocity, dt),
+    multiply(acceleration, HALF_ACCELERATION * dt * dt),
+  )
+
+  return { velocity, position, orientation }
+}

package/src/engine/movement/kinematic/modern.js

@@ -0,0 +1,16 @@
+import {
+  angle,
+  magnitude,
+} from "@inglorious/utils/math/linear-algebra/vector.js"
+import { applyVelocity } from "@inglorious/utils/physics/velocity.js"
+
+const DEFAULT_ORIENTATION = 0
+
+export default function modernMove(instance, options) {
+  const { velocity, position } = applyVelocity(instance, options)
+
+  let orientation = instance.orientation ?? DEFAULT_ORIENTATION
+  orientation = magnitude(velocity) ? angle(velocity) : orientation
+
+  return { velocity, position, orientation }
+}

package/src/engine/movement/kinematic/modern.test.js

@@ -0,0 +1,27 @@
+import { expect, test } from "vitest"
+
+import modernMove from "./modern.js"
+
+test("it should move following its velocity", () => {
+  const instance = { maxSpeed: 1, velocity: [1, 0, 0], position: [0, 0, 0] }
+  const options = { dt: 1 }
+  const expectedResult = {
+    velocity: [1, 0, 0],
+    position: [1, 0, 0],
+    orientation: 0,
+  }
+
+  expect(modernMove(instance, options)).toStrictEqual(expectedResult)
+})
+
+test("it should limit the velocity to the max speed", () => {
+  const instance = { maxSpeed: 1, velocity: [10, 0, 0], position: [0, 0, 0] }
+  const options = { dt: 1 }
+  const expectedResult = {
+    velocity: [1, 0, 0],
+    position: [1, 0, 0],
+    orientation: 0,
+  }
+
+  expect(modernMove(instance, options)).toStrictEqual(expectedResult)
+})

package/src/engine/movement/kinematic/tank.js

@@ -0,0 +1,27 @@
+import {
+  clamp,
+  multiply,
+  rotate,
+  zero,
+} from "@inglorious/utils/math/linear-algebra/vector.js"
+import { sum } from "@inglorious/utils/math/linear-algebra/vectors.js"
+import { toRange } from "@inglorious/utils/math/trigonometry.js"
+
+const DEFAULT_MAX_SPEED = 0
+
+const DEFAULT_ORIENTATION = 0
+
+export default function tankMove(instance, { dt }) {
+  const maxSpeed = instance.maxSpeed ?? DEFAULT_MAX_SPEED
+
+  let orientation = instance.orientation ?? DEFAULT_ORIENTATION
+  orientation = toRange(orientation)
+
+  let velocity = instance.velocity ?? zero()
+  velocity = rotate(velocity, orientation)
+  velocity = clamp(velocity, -maxSpeed, maxSpeed)
+
+  const position = sum(instance.position, multiply(velocity, dt))
+
+  return { velocity, position, orientation }
+}

package/src/engine/store.js

@@ -0,0 +1,174 @@
+import { enableGame } from "@inglorious/game/decorators/game.js"
+import { map } from "@inglorious/utils/data-structures/object.js"
+import { extend } from "@inglorious/utils/data-structures/objects.js"
+import { pipe } from "@inglorious/utils/functions/functions.js"
+import { produce } from "immer"
+
+const DEFAULT_TYPES = {
+  game: [enableGame()],
+}
+
+const DEFAULT_INSTANCES = {
+  // eslint-disable-next-line no-magic-numbers
+  game: { type: "game", bounds: [0, 0, 800, 600] }, // Default game instance with bounds.
+}
+
+const DEFAULT_LAYER = 0
+
+/**
+ * Creates a store to manage state and events.
+ * @param {Object} options - Configuration options for the store.
+ * @param {Object} options.instances - Initial instances to include in the store.
+ * @param {Object} options.originalConfig - Additional configuration for the store.
+ * @returns {Object} The store with methods to interact with state and events.
+ */
+export function createStore({
+  types: originalTypes,
+  instances: originalInstances,
+}) {
+  const listeners = new Set()
+  let incomingEvents = []
+
+  let types = extend(DEFAULT_TYPES, originalTypes)
+  types = augmentTypes(types)
+
+  let instances = extend(DEFAULT_INSTANCES, originalInstances)
+  instances = augmentInstances(instances)
+
+  let state = { events: [], instances }
+
+  return {
+    subscribe,
+    update,
+    notify,
+    dispatch: notify, // needed for react-redux
+    getTypes,
+    getState,
+  }
+
+  /**
+   * Subscribes a listener to state updates.
+   * @param {Function} listener - The listener function to call on updates.
+   * @returns {Function} A function to unsubscribe the listener.
+   */
+  function subscribe(listener) {
+    listeners.add(listener)
+
+    return function unsubscribe() {
+      listeners.delete(listener)
+    }
+  }
+
+  /**
+   * Updates the state based on elapsed time and processes events.
+   * @param {number} dt - The delta time since the last update.
+   */
+  function update(dt) {
+    state = { ...state }
+
+    state.events.push(...incomingEvents, { id: "game:update" })
+    incomingEvents = []
+
+    while (state.events.length) {
+      const event = state.events.shift()
+
+      if (event.id === "instance:add") {
+        add(event.payload.id, event.payload)
+      }
+
+      state.instances = map(state.instances, (_, instance, instances) => {
+        const type = types[instance.type]
+        const handle = type[event.id]
+        return (
+          handle?.(instance, event, {
+            dt,
+            type: originalTypes[instance.type],
+            instances,
+            notify,
+          }) ?? instance
+        )
+      })
+
+      if (event.id === "instance:remove") {
+        remove(event.payload)
+      }
+    }
+
+    listeners.forEach((onUpdate) => onUpdate())
+  }
+
+  /**
+   * Adds a new instance to the state.
+   * @param {string} id - The ID of the instance to add.
+   * @param {Object} instance - The instance object to add.
+   */
+  function add(id, instance) {
+    state = { ...state }
+    state.instances[id] = augmentInstance(id, instance)
+  }
+
+  /**
+   * Removes an instance from the state.
+   * @param {string} id - The ID of the instance to remove.
+   */
+  function remove(id) {
+    state = { ...state }
+    delete state.instances[id]
+  }
+
+  /**
+   * Notifies the store of a new event.
+   * @param {Object} event - The event object to notify.
+   */
+  function notify(event) {
+    incomingEvents.push(event)
+  }
+
+  /**
+   * Retrieves the types configuration.
+   * @returns {Object} The types configuration.
+   */
+  function getTypes() {
+    return types
+  }
+
+  /**
+   * Retrieves the current state.
+   * @returns {Object} The current state.
+   */
+  function getState() {
+    return state
+  }
+}
+
+function augmentTypes(types) {
+  return pipe(applyDecorators, enableMutability)(types)
+}
+
+function applyDecorators(types) {
+  return map(types, (_, type) => {
+    if (!Array.isArray(type)) {
+      return type
+    }
+
+    const decorators = type.map((fn) =>
+      typeof fn !== "function" ? (type) => extend(type, fn) : fn,
+    )
+    return pipe(...decorators)({})
+  })
+}
+
+function enableMutability(types) {
+  return map(types, (_, { draw, ...events }) => ({
+    draw,
+    ...map(events, (_, event) => produce(event)),
+  }))
+}
+
+function augmentInstances(instances) {
+  return map(instances, augmentInstance)
+}
+
+function augmentInstance(id, instance) {
+  return { ...instance, layer: instance.layer ?? DEFAULT_LAYER, id }
+}

package/src/engine/store.test.js

@@ -0,0 +1,256 @@
+import { expect, test } from "vitest"
+
+import { createStore } from "./store.js"
+
+test("it should add an event to the event queue", () => {
+  const event = { id: "something:happened" }
+  const config = {
+    types: {
+      kitty: {
+        [event.id](instance) {
+          return { ...instance, wasNotified: true }
+        },
+      },
+    },
+    instances: {
+      instance1: { type: "kitty" },
+    },
+  }
+  const store = createStore(config)
+  const afterState = {
+    events: [],
+    instances: {
+      game: {
+        id: "game",
+        type: "game",
+        layer: 0,
+        bounds: [0, 0, 800, 600],
+      },
+      instance1: {
+        id: "instance1",
+        type: "kitty",
+        layer: 0,
+        wasNotified: true,
+      },
+    },
+  }
+
+  store.notify(event)
+  store.update()
+
+  const state = store.getState()
+  expect(state).toStrictEqual(afterState)
+})
+
+test("it should process the event queue", () => {
+  const event = { id: "something:happened" }
+  const config = {
+    types: {
+      kitty: {
+        "game:update"(instance) {
+          return { ...instance, wasUpdated: true }
+        },
+
+        [event.id](instance) {
+          return { ...instance, wasNotified: true }
+        },
+      },
+    },
+    instances: {
+      instance1: { type: "kitty" },
+    },
+  }
+  const store = createStore(config)
+  store.notify(event)
+  const afterState = {
+    events: [],
+    instances: {
+      game: {
+        id: "game",
+        type: "game",
+        layer: 0,
+        bounds: [0, 0, 800, 600],
+      },
+      instance1: {
+        id: "instance1",
+        type: "kitty",
+        layer: 0,
+        wasNotified: true,
+        wasUpdated: true,
+      },
+    },
+  }
+
+  store.update()
+
+  const state = store.getState()
+  expect(state).toStrictEqual(afterState)
+})
+
+test("it should send an event from an instance", () => {
+  const event = {
+    id: "doge:message",
+    payload: { id: "inu", message: "Woof!" },
+  }
+  const config = {
+    types: {
+      doge: {
+        "game:update"(instance, event, { instances, notify }) {
+          if (instances.instance2.position === "near") {
+            notify(event)
+          }
+        },
+      },
+      kitty: {
+        [event.id](instance) {
+          if (event.payload.id === "inu" && event.payload.message === "Woof!") {
+            instance.position = "far"
+          }
+        },
+      },
+    },
+
+    instances: {
+      instance1: {
+        type: "doge",
+      },
+      instance2: {
+        type: "kitty",
+        position: "near",
+      },
+    },
+  }
+  const store = createStore(config)
+  const afterState = {
+    events: [],
+    instances: {
+      game: {
+        id: "game",
+        type: "game",
+        layer: 0,
+        bounds: [0, 0, 800, 600],
+      },
+      instance1: {
+        id: "instance1",
+        type: "doge",
+        layer: 0,
+      },
+      instance2: {
+        id: "instance2",
+        type: "kitty",
+        layer: 0,
+        position: "near", // should do nothing at first
+      },
+    },
+  }
+
+  store.update()
+
+  const state = store.getState()
+  expect(state).toStrictEqual(afterState)
+})
+
+test("it should receive an event from an instance", () => {
+  const event = {
+    id: "doge:message",
+    payload: { id: "inu", message: "Woof!" },
+  }
+  const config = {
+    types: {
+      doge: {
+        "game:update"(instance, event, { instances, notify }) {
+          if (instances.instance2.position === "near") {
+            notify(event)
+          }
+        },
+      },
+      kitty: {
+        [event.id](instance, event) {
+          if (event.payload.id === "inu" && event.payload.message === "Woof!") {
+            instance.position = "far"
+          }
+        },
+      },
+    },
+
+    instances: {
+      instance1: {
+        type: "doge",
+      },
+      instance2: {
+        type: "kitty",
+        position: "near",
+      },
+    },
+  }
+  const store = createStore(config)
+  store.notify(event)
+  const afterState = {
+    events: [],
+    instances: {
+      game: {
+        id: "game",
+        type: "game",
+        layer: 0,
+        bounds: [0, 0, 800, 600],
+      },
+      instance1: {
+        id: "instance1",
+        type: "doge",
+        layer: 0,
+      },
+      instance2: {
+        id: "instance2",
+        type: "kitty",
+        layer: 0,
+        position: "far", // position changed
+      },
+    },
+  }
+
+  store.update()
+
+  const state = store.getState()
+  expect(state).toStrictEqual(afterState)
+})
+
+test("it should mutate state in an immutable way", () => {
+  const config = {
+    types: {
+      kitty: {
+        "game:update"(instance) {
+          instance.wasUpdated = true
+        },
+      },
+    },
+
+    instances: {
+      instance1: {
+        type: "kitty",
+      },
+    },
+  }
+  const store = createStore(config)
+  const afterState = {
+    events: [],
+    instances: {
+      game: {
+        id: "game",
+        type: "game",
+        layer: 0,
+        bounds: [0, 0, 800, 600],
+      },
+      instance1: {
+        id: "instance1",
+        type: "kitty",
+        layer: 0,
+        wasUpdated: true,
+      },
+    },
+  }
+
+  store.update()
+
+  const state = store.getState()
+  expect(state).toStrictEqual(afterState)
+})

package/src/engine.js

@@ -0,0 +1,74 @@
+import { extend } from "@inglorious/utils/data-structures/objects.js"
+
+import Loop from "./engine/loop.js"
+import { createStore } from "./engine/store.js"
+
+// Default configuration for the engine
+// loop.type specifies the type of loop to use (defaults to "animationFrame").
+const DEFAULT_CONFIG = {
+  loop: { type: "animationFrame" },
+}
+const ONE_SECOND = 1000 // Number of milliseconds in one second.
+
+/**
+ * Engine class responsible for managing the game loop, state, and rendering.
+ */
+export default class Engine {
+  /**
+   * @param {Object} game - Game-specific configuration.
+   * @param {Object} ui - UI instance responsible for rendering.
+   */
+  constructor(game, ui) {
+    this._config = extend(DEFAULT_CONFIG, game)
+    this._store = createStore(this._config)
+    this._loop = new Loop[this._config.loop.type]()
+    this._ui = ui
+  }
+
+  /**
+   * Starts the game engine, initializing the loop and notifying the store.
+   */
+  start() {
+    this._store.notify({ id: "game:start" })
+    this._loop.start(this, ONE_SECOND / this._config.loop.fps)
+    this.isRunning = true
+  }
+
+  /**
+   * Updates the game state.
+   * @param {number} dt - Delta time since the last update in milliseconds.
+   */
+  update(dt) {
+    this._store.update(dt)
+  }
+
+  /**
+   * Renders the game state using the UI.
+   * @param {number} dt - Delta time since the last render in milliseconds.
+   */
+  render(dt) {
+    this._ui?.render({
+      dt,
+      types: this._store.getTypes(),
+      instances: this._store.getState().instances,
+    })
+  }
+
+  /**
+   * Notifies the store of an event.
+   * @param {Object} event - Event object to notify the store with.
+   */
+  notify = (event) => {
+    this._store.notify(event)
+  }
+
+  /**
+   * Stops the game engine, halting the loop and notifying the store.
+   */
+  stop() {
+    this._store.notify({ id: "game:stop" })
+    this._store.update()
+    this._loop.stop()
+    this.isRunning = false
+  }
+}