@inglorious/engine 0.1.1 → 0.3.0

package/src/core/engine.js

@@ -0,0 +1,119 @@
+import { game } from "@inglorious/engine/behaviors/game.js"
+import { extend } from "@inglorious/utils/data-structures/objects.js"
+
+import { createApi } from "./api.js"
+import {
+  ACTION_BLACKLIST,
+  disconnectDevTools,
+  initDevTools,
+  sendAction,
+} from "./dev-tools.js"
+import Loop from "./loop.js"
+import { createStore } from "./store.js"
+
+// Default game configuration
+// loop.type specifies the type of loop to use (defaults to "animationFrame").
+const DEFAULT_GAME_CONFIG = {
+  loop: { type: "animationFrame", fps: 60 },
+
+  systems: [],
+
+  types: {
+    game: [game()],
+  },
+
+  entities: {
+    // eslint-disable-next-line no-magic-numbers
+    game: { type: "game", bounds: [0, 0, 800, 600] },
+  },
+}
+
+const ONE_SECOND = 1000 // Number of milliseconds in one second.
+
+// Delta time for the final update call when stopping the engine.
+const FINAL_UPDATE_DELTA_TIME = 0 // This ensures any pending events (like 'stop') are processed before shutdown.
+
+/**
+ * Engine class responsible for managing the game loop, state, and rendering.
+ */
+export class Engine {
+  _devMode = false
+
+  /**
+   * @param {Object} [gameConfig] - Game-specific configuration.
+   * @param {Object} [renderer] - UI entity responsible for rendering. It must have a `render` method.
+   */
+  constructor(gameConfig) {
+    this._config = extend(DEFAULT_GAME_CONFIG, gameConfig)
+
+    const systems = [...(this._config.systems ?? [])]
+    if (this._config.renderer) {
+      systems.push(...this._config.renderer.getSystems())
+    }
+
+    this._store = createStore({ ...this._config, systems })
+    this._loop = new Loop[this._config.loop.type]()
+    this._api = createApi(this._store)
+
+    // The renderer might need the engine instance to initialize itself (e.g., to set up DOM events).
+    this._config.renderer?.init(this)
+
+    // Determine devMode from the entities config.
+    const devMode = this._config.entities.game?.devMode
+    this._devMode = devMode
+    if (devMode) {
+      initDevTools(this._store)
+    }
+  }
+
+  /**
+   * Starts the game engine, initializing the loop and notifying the store.
+   */
+  start() {
+    this._store.notify("start", this._api)
+    this._loop.start(this, ONE_SECOND / this._config.loop.fps)
+    this.isRunning = true
+  }
+
+  /**
+   * Stops the game engine, halting the loop and notifying the store.
+   */
+  stop() {
+    this._store.notify("stop", this._api)
+    this._store.update(FINAL_UPDATE_DELTA_TIME, this._api)
+    this._loop.stop()
+    this.isRunning = false
+  }
+
+  /**
+   * Updates the game state.
+   * @param {number} dt - Delta time since the last update in milliseconds.
+   */
+  update(dt) {
+    const processedEvents = this._store.update(dt, this._api)
+    const state = this._store.getState()
+
+    // Check for devMode changes and connect/disconnect dev tools accordingly.
+    const newDevMode = state.entities.game?.devMode
+    if (newDevMode !== this._devMode) {
+      if (newDevMode) {
+        initDevTools(this._store)
+      } else {
+        disconnectDevTools()
+      }
+      this._devMode = newDevMode
+    }
+
+    const eventsToLog = processedEvents.filter(
+      ({ type }) => !ACTION_BLACKLIST.includes(type),
+    )
+
+    if (eventsToLog.length) {
+      const action = {
+        type: eventsToLog.map(({ type }) => type).join("|"),
+        payload: eventsToLog,
+      }
+      sendAction(action, state)
+    }
+  }
+}

package/src/core/loop.js

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

package/src/{engine/loop → core/loops}/animation-frame.js

@@ -1,6 +1,6 @@
 const ONE_SECOND = 1000
 
-export default class AnimationFrameLoop {
+export class AnimationFrameLoop {
   _id = null
   _previousTime = new Date()
 
@@ -19,7 +19,6 @@ export default class AnimationFrameLoop {
     const dt = currentTime - this._previousTime
 
     engine.update(dt / ONE_SECOND)
-    engine.render(dt / ONE_SECOND)
 
     this._previousTime = currentTime
   }

package/src/{engine/loop → core/loops}/elapsed.js

@@ -1,6 +1,6 @@
 const ONE_SECOND = 1000
 
-export default class ElapsedLoop {
+export class ElapsedLoop {
   _shouldStop = false
 
   start(engine) {
@@ -11,7 +11,6 @@ export default class ElapsedLoop {
       const dt = currentTime - previousTime
 
       engine.update(dt / ONE_SECOND)
-      engine.render(dt / ONE_SECOND)
 
       previousTime = currentTime
     }

package/src/{engine/loop → core/loops}/fixed.js

@@ -1,6 +1,6 @@
 const ONE_SECOND = 1000
 
-export default class NapLoop {
+export class FixedLoop {
   _shouldStop = false
 
   async start(engine, msPerUpdate) {
@@ -11,7 +11,6 @@ export default class NapLoop {
       const dt = currentTime - previousTime
 
       engine.update(dt / ONE_SECOND)
-      engine.render(dt / ONE_SECOND)
 
       previousTime = currentTime
       await sleep(Date.now() - currentTime + msPerUpdate)

package/src/{engine/loop → core/loops}/flash.js

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

package/src/{engine/loop → core/loops}/lag.js

@@ -1,6 +1,6 @@
 const ONE_SECOND = 1000
 
-export default class LagLoop {
+export class LagLoop {
   _shouldStop = false
 
   start(engine, msPerUpdate) {
@@ -15,7 +15,6 @@ export default class LagLoop {
 
       while (lag >= msPerUpdate) {
         engine.update(dt / ONE_SECOND)
-        engine.render(dt / ONE_SECOND)
         lag -= msPerUpdate
       }
     }

package/src/core/select.js

@@ -0,0 +1,26 @@
+/**
+ * Creates a memoized selector function.
+ * NB: this implementation does not support spreading the input selectors for clarity, please just put them in an array.
+ * @param {Array<Function>} inputSelectors - An array of input selector functions.
+ * @param {Function} resultFunc - A function that receives the results of the input selectors and returns a computed value.
+ * @returns {Function} A memoized selector function that, when called, returns the selected state.
+ */
+export function createSelector(inputSelectors, resultFunc) {
+  let lastInputs = []
+  let lastResult = null
+
+  return (state) => {
+    const nextInputs = inputSelectors.map((selector) => selector(state))
+    const inputsChanged =
+      lastInputs.length !== nextInputs.length ||
+      nextInputs.some((input, index) => input !== lastInputs[index])
+
+    if (!inputsChanged) {
+      return lastResult
+    }
+
+    lastInputs = nextInputs
+    lastResult = resultFunc(...nextInputs)
+    return lastResult
+  }
+}

package/src/core/store.js

@@ -0,0 +1,178 @@
+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"
+
+/**
+ * Creates a store to manage state and events.
+ * @param {Object} config - Configuration options for the store.
+ * @param {Object} [config.types] - The initial types configuration.
+ * @param {Object} [config.entities] - The initial entities configuration.
+ * @returns {Object} The store with methods to interact with state and events.
+ */
+export function createStore({
+  types: originalTypes,
+  entities: originalEntities,
+  systems = [],
+}) {
+  const listeners = new Set()
+  let incomingEvents = []
+
+  let types = augmentTypes(originalTypes)
+  let entities = augmentEntities(originalEntities)
+
+  const initialState = { entities }
+  let state = initialState
+
+  return {
+    subscribe,
+    update,
+    notify,
+    dispatch, // needed for compatibility with Redux
+    getTypes,
+    getOriginalTypes,
+    getState,
+    setState,
+    reset,
+  }
+
+  /**
+   * 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 in milliseconds.
+   * @param {Object} api - The engine's public API.
+   */
+  function update(dt, api) {
+    const processedEvents = []
+
+    state = produce(state, (state) => {
+      incomingEvents.push({ type: "update", payload: dt })
+
+      while (incomingEvents.length) {
+        const event = incomingEvents.shift()
+        processedEvents.push(event)
+
+        if (event.type === "morph") {
+          const { id, type } = event.payload
+          originalTypes[id] = type
+          types = augmentTypes(originalTypes)
+        }
+
+        if (event.type === "add") {
+          const { id, ...entity } = event.payload
+          state.entities[id] = augmentEntity(id, entity)
+        }
+
+        if (event.type === "remove") {
+          const id = event.payload
+          delete state.entities[id]
+        }
+
+        for (const id in state.entities) {
+          const entity = state.entities[id]
+          const type = types[entity.type]
+          const handle = type[event.type]
+          handle?.(entity, event.payload, api)
+        }
+
+        systems.forEach((system) => {
+          const handle = system[event.type]
+          handle?.(state, event.payload, api)
+        })
+      }
+    })
+
+    listeners.forEach((onUpdate) => onUpdate())
+
+    return processedEvents
+  }
+
+  /**
+   * Notifies the store of a new event.
+   * @param {string} type - The event object type to notify.
+   * @param {any} payload - The event object payload to notify.
+   */
+  function notify(type, payload) {
+    dispatch({ type, payload })
+  }
+
+  /**
+   * Dispatches an event to be processed in the next update cycle.
+   * @param {Object} event - The event object.
+   * @param {string} event.type - The type of the event.
+   * @param {any} [event.payload] - The payload of the event.
+   */
+  function dispatch(event) {
+    incomingEvents.push(event)
+  }
+
+  /**
+   * Retrieves the augmented types configuration.
+   * This includes composed behaviors and event handlers wrapped for immutability.
+   * @returns {Object} The augmented types configuration.
+   */
+  function getTypes() {
+    return types
+  }
+
+  /**
+   * Retrieves the original, un-augmented types configuration.
+   * @returns {Object} The original types configuration.
+   */
+  function getOriginalTypes() {
+    return originalTypes
+  }
+
+  /**
+   * Retrieves the current state.
+   * @returns {Object} The current state.
+   */
+  function getState() {
+    return state
+  }
+
+  function setState(newState) {
+    state = newState
+  }
+
+  function reset() {
+    state = initialState // Reset state to its originally computed value
+  }
+}
+
+function augmentTypes(types) {
+  return pipe(applyBehaviors)(types)
+}
+
+function applyBehaviors(types) {
+  return map(types, (_, type) => {
+    if (!Array.isArray(type)) {
+      return type
+    }
+
+    const behaviors = type.map((fn) =>
+      typeof fn !== "function" ? (type) => extend(type, fn) : fn,
+    )
+    return pipe(...behaviors)({})
+  })
+}
+
+function augmentEntities(entities) {
+  return map(entities, augmentEntity)
+}
+
+function augmentEntity(id, entity) {
+  return { ...entity, id }
+}

package/src/core/store.test.js

@@ -0,0 +1,110 @@
+import { expect, test } from "vitest"
+
+import { createStore } from "./store.js"
+
+test("it should process events by mutating state inside handlers", () => {
+  const config = {
+    types: {
+      kitty: {
+        feed(entity) {
+          entity.isFed = true
+        },
+        update(entity) {
+          entity.isMeowing = true
+        },
+      },
+    },
+    entities: {
+      kitty1: { type: "kitty" },
+    },
+  }
+  const afterState = {
+    entities: {
+      kitty1: {
+        id: "kitty1",
+        type: "kitty",
+        isFed: true,
+        isMeowing: true,
+      },
+    },
+  }
+
+  const store = createStore(config)
+  store.notify("feed")
+  store.update(0, {})
+
+  const state = store.getState()
+  expect(state).toStrictEqual(afterState)
+})
+
+test("it should send an event from an entity and process it in the same update cycle", () => {
+  const config = {
+    types: {
+      doggo: {
+        update(entity, dt, api) {
+          api.notify("bark")
+        },
+      },
+      kitty: {
+        bark(entity) {
+          entity.position = "far"
+        },
+      },
+    },
+    entities: {
+      doggo1: { type: "doggo" },
+      kitty1: { type: "kitty", position: "near" },
+    },
+  }
+  const afterState = {
+    entities: {
+      doggo1: { id: "doggo1", type: "doggo" },
+      kitty1: { id: "kitty1", type: "kitty", position: "far" },
+    },
+  }
+
+  const store = createStore(config)
+  const api = { notify: store.notify }
+  store.update(0, api)
+
+  const state = store.getState()
+  expect(state).toStrictEqual(afterState)
+})
+
+test("it should add an entity via an 'add' event", () => {
+  const config = {
+    types: {
+      kitty: {},
+    },
+    entities: {},
+  }
+  const newEntity = { id: "kitty1", type: "kitty" }
+
+  const store = createStore(config)
+  store.notify("add", newEntity)
+  store.update(0, {})
+
+  const state = store.getState()
+  expect(state).toStrictEqual({
+    entities: {
+      kitty1: { id: "kitty1", type: "kitty" },
+    },
+  })
+})
+
+test("it should remove an entity via a 'remove' event", () => {
+  const config = {
+    types: {},
+    entities: {
+      kitty1: { type: "kitty" },
+    },
+  }
+  const store = createStore(config)
+
+  store.notify("remove", "kitty1")
+
+  store.update(0, {})
+
+  const state = store.getState()
+  expect(state.entities.kitty1).toBeUndefined()
+})

package/src/main.js

@@ -1,5 +1,10 @@
-import { start } from "@inglorious/ui/canvas.js"
+import { Engine } from "@inglorious/engine/core/engine.js"
+import { CanvasRenderer } from "@inglorious/renderer-2d/canvas-renderer.js"
 import game from "game"
 
 const canvas = document.getElementById("canvas")
-window.addEventListener("load", () => start(game, canvas))
+window.addEventListener("load", () => {
+  const renderer = new CanvasRenderer(canvas)
+  const engine = new Engine({ ...game, renderer })
+  engine.start()
+})

package/src/{engine/movement → movement}/dynamic/modern.js

@@ -8,13 +8,10 @@ const DEFAULT_ORIENTATION = 0
 
 const ORIENTATION_CHANGE_THRESHOLD = 4
 
-export default function modernMove(instance, options) {
-  const { acceleration, velocity, position } = applyAcceleration(
-    instance,
-    options,
-  )
+export function modernMove(entity, dt) {
+  const { acceleration, velocity, position } = applyAcceleration(entity, dt)
 
-  let orientation = instance.orientation ?? DEFAULT_ORIENTATION
+  let orientation = entity.orientation ?? DEFAULT_ORIENTATION
   orientation =
     magnitude(velocity) > ORIENTATION_CHANGE_THRESHOLD
       ? angle(velocity)

package/src/{engine/movement → movement}/dynamic/tank.js

@@ -16,25 +16,25 @@ 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
+export function tankMove(entity, dt) {
+  const maxAcceleration = entity.maxAcceleration ?? DEFAULT_MAX_ACCELERATION
+  const maxSpeed = entity.maxSpeed ?? DEFAULT_MAX_SPEED
+  const friction = entity.friction ?? DEFAULT_FRICTION
 
-  let orientation = instance.orientation ?? DEFAULT_ORIENTATION
+  let orientation = entity.orientation ?? DEFAULT_ORIENTATION
   orientation = toRange(orientation)
 
-  let acceleration = instance.acceleration ?? zero()
+  let acceleration = entity.acceleration ?? zero()
   acceleration = rotate(acceleration, orientation)
   acceleration = clamp(acceleration, -maxAcceleration, maxAcceleration)
 
-  let velocity = instance.velocity ?? zero()
+  let velocity = entity.velocity ?? zero()
   velocity = sum(velocity, multiply(acceleration, dt))
   velocity = clamp(velocity, -maxSpeed, maxSpeed)
-  velocity = applyFriction({ velocity, friction }, { dt })
+  velocity = applyFriction({ velocity, friction }, dt)
 
   const position = sum(
-    instance.position,
+    entity.position,
     multiply(velocity, dt),
     multiply(acceleration, HALF_ACCELERATION * dt * dt),
   )

package/src/{engine/movement → movement}/kinematic/modern.js

@@ -6,10 +6,10 @@ import { applyVelocity } from "@inglorious/utils/physics/velocity.js"
 
 const DEFAULT_ORIENTATION = 0
 
-export default function modernMove(instance, options) {
-  const { velocity, position } = applyVelocity(instance, options)
+export function modernMove(entity, dt) {
+  const { velocity, position } = applyVelocity(entity, dt)
 
-  let orientation = instance.orientation ?? DEFAULT_ORIENTATION
+  let orientation = entity.orientation ?? DEFAULT_ORIENTATION
   orientation = magnitude(velocity) ? angle(velocity) : orientation
 
   return { velocity, position, orientation }

package/src/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 entity = { maxSpeed: 1, velocity: [1, 0, 0], position: [0, 0, 0] }
+  const dt = 1
+  const expectedResult = {
+    velocity: [1, 0, 0],
+    position: [1, 0, 0],
+    orientation: 0,
+  }
+
+  expect(modernMove(entity, dt)).toStrictEqual(expectedResult)
+})
+
+test("it should limit the velocity to the max speed", () => {
+  const entity = { maxSpeed: 1, velocity: [10, 0, 0], position: [0, 0, 0] }
+  const dt = 1
+  const expectedResult = {
+    velocity: [1, 0, 0],
+    position: [1, 0, 0],
+    orientation: 0,
+  }
+
+  expect(modernMove(entity, dt)).toStrictEqual(expectedResult)
+})

package/src/{engine/movement → movement}/kinematic/tank.js

@@ -11,17 +11,17 @@ const DEFAULT_MAX_SPEED = 0
 
 const DEFAULT_ORIENTATION = 0
 
-export default function tankMove(instance, { dt }) {
-  const maxSpeed = instance.maxSpeed ?? DEFAULT_MAX_SPEED
+export function tankMove(entity, dt) {
+  const maxSpeed = entity.maxSpeed ?? DEFAULT_MAX_SPEED
 
-  let orientation = instance.orientation ?? DEFAULT_ORIENTATION
+  let orientation = entity.orientation ?? DEFAULT_ORIENTATION
   orientation = toRange(orientation)
 
-  let velocity = instance.velocity ?? zero()
+  let velocity = entity.velocity ?? zero()
   velocity = rotate(velocity, orientation)
   velocity = clamp(velocity, -maxSpeed, maxSpeed)
 
-  const position = sum(instance.position, multiply(velocity, dt))
+  const position = sum(entity.position, multiply(velocity, dt))
 
   return { velocity, position, orientation }
 }