@inglorious/engine 0.1.0 → 0.2.0

package/src/engine/core/api.js

@@ -0,0 +1,34 @@
+import { createSelector as _createSelector } from "./select.js"
+
+export function createApi(store) {
+  const createSelector = (inputSelectors, resultFunc) => {
+    const selector = _createSelector(inputSelectors, resultFunc)
+    return () => selector(store.getState())
+  }
+
+  const getTypes = () => store.getTypes()
+
+  const getEntities = () => store.getState().entities
+
+  const getEntity = (id) => getEntities()[id]
+
+  const notify = (type, payload) => {
+    store.notify(type, payload)
+  }
+
+  const dispatch = (action) => {
+    store.dispatch(action)
+  }
+
+  const getType = (id) => store.getOriginalTypes()?.[id]
+
+  return {
+    createSelector,
+    getTypes,
+    getEntities,
+    getEntity,
+    getType,
+    notify,
+    dispatch,
+  }
+}

package/src/engine/core/dev-tools.js

@@ -0,0 +1,135 @@
+export const ACTION_BLACKLIST = [
+  "update",
+  "gamepadAxis",
+  "gamepadPress",
+  "gamepadRelease",
+  "keyboardKeyDown",
+  "keyboardKeyUp",
+  "inputAxis",
+  "inputPress",
+  "inputRelease",
+  "mouseMove",
+  "mouseClick",
+  "spriteAnimationEnd",
+]
+
+const LAST_STATE = 1
+
+let devToolsInstance = null
+let unsubscribe = null
+
+export function initDevTools(store) {
+  // Prevent multiple connections
+  if (devToolsInstance) {
+    return
+  }
+
+  if (typeof window === "undefined" || !window.__REDUX_DEVTOOLS_EXTENSION__) {
+    return
+  }
+
+  devToolsInstance = window.__REDUX_DEVTOOLS_EXTENSION__.connect({
+    name: "Inglorious Engine",
+    predicate: (state, action) => !ACTION_BLACKLIST.includes(action.type),
+    actionCreators: {
+      jump: () => ({ type: "jump", payload: { inputId: "input0" } }),
+    },
+    // @see https://github.com/reduxjs/redux-devtools/blob/main/extension/docs/API/Arguments.md#features
+    features: {
+      pause: true, // start/pause recording of dispatched actions
+      lock: true, // lock/unlock dispatching actions and side effects
+      persist: true, // persist states on page reloading
+      export: true, // export history of actions in a file
+      import: "custom", // import history of actions from a file
+      jump: false, // jump back and forth (time travelling)
+      skip: false, // skip (cancel) actions
+      reorder: false, // drag and drop actions in the history list
+      dispatch: true, // dispatch custom actions or action creators
+      test: false, // generate tests for the selected actions
+    },
+  })
+
+  unsubscribe = devToolsInstance.subscribe((message) => {
+    switch (message.type) {
+      case "DISPATCH":
+        handleDispatch(message, store)
+        break
+
+      case "ACTION":
+        handleAction(message, store)
+        break
+    }
+  })
+
+  devToolsInstance.init(store.getState())
+}
+
+export function disconnectDevTools() {
+  // The `disconnect` method on the devToolsInstance is not available in all
+  // environments or versions of the extension.
+  // The safest way to "disconnect" is to unsubscribe from any listeners
+  // and release our reference to the instance, which prevents any further
+  // actions from being sent.
+  if (unsubscribe) {
+    unsubscribe()
+    unsubscribe = null
+    devToolsInstance = null
+  }
+}
+
+export function sendAction(action, state) {
+  if (devToolsInstance) {
+    devToolsInstance.send(action, state)
+  }
+}
+
+function handleDispatch(message, store) {
+  switch (message.payload.type) {
+    // reset button
+    case "RESET": {
+      store.reset()
+      devToolsInstance.init(store.getState())
+      break
+    }
+
+    // revert button
+    case "ROLLBACK": {
+      const newState = JSON.parse(message.state)
+      store.setState(newState)
+      break
+    }
+
+    // commit button
+    case "COMMIT": {
+      devToolsInstance.init(store.getState())
+      break
+    }
+
+    // import from file button
+    case "IMPORT_STATE": {
+      const { computedStates, actionsById } = message.payload.nextLiftedState
+
+      const [firstComputedState] = computedStates
+      const lastComputedState =
+        computedStates[computedStates.length - LAST_STATE]
+      if (lastComputedState) {
+        store.setState(lastComputedState.state)
+      }
+
+      const flattenedActions = Object.values(actionsById)
+        .flatMap(({ action }) => action.payload ?? action)
+        .map((action, index) => [index, action])
+
+      devToolsInstance.init(
+        firstComputedState.state,
+        Object.fromEntries(flattenedActions),
+      )
+      break
+    }
+  }
+}
+
+function handleAction(message, store) {
+  const action = JSON.parse(message.payload)
+  store.dispatch(action)
+}

package/src/engine/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/engine/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,26 +1,25 @@
-const ONE_SECOND = 1000
-
-export default class AnimationFrameLoop {
-  _id = null
-  _previousTime = new Date()
-
-  start(engine) {
-    this._tick(engine)
-  }
-
-  stop() {
-    window.cancelAnimationFrame(this._id)
-    this._id = null
-  }
-
-  _tick(engine) {
-    const currentTime = new Date()
-    this._id = window.requestAnimationFrame(() => this._tick(engine))
-    const dt = currentTime - this._previousTime
-
-    engine.update(dt / ONE_SECOND)
-    engine.render(dt / ONE_SECOND)
-
-    this._previousTime = currentTime
-  }
-}
+const ONE_SECOND = 1000
+
+export class AnimationFrameLoop {
+  _id = null
+  _previousTime = new Date()
+
+  start(engine) {
+    this._tick(engine)
+  }
+
+  stop() {
+    window.cancelAnimationFrame(this._id)
+    this._id = null
+  }
+
+  _tick(engine) {
+    const currentTime = new Date()
+    this._id = window.requestAnimationFrame(() => this._tick(engine))
+    const dt = currentTime - this._previousTime
+
+    engine.update(dt / ONE_SECOND)
+
+    this._previousTime = currentTime
+  }
+}

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

@@ -1,23 +1,22 @@
-const ONE_SECOND = 1000
-
-export default class ElapsedLoop {
-  _shouldStop = false
-
-  start(engine) {
-    let previousTime = Date.now()
-
-    while (!this._shouldStop) {
-      const currentTime = Date.now()
-      const dt = currentTime - previousTime
-
-      engine.update(dt / ONE_SECOND)
-      engine.render(dt / ONE_SECOND)
-
-      previousTime = currentTime
-    }
-  }
-
-  stop() {
-    this._shouldStop = true
-  }
-}
+const ONE_SECOND = 1000
+
+export class ElapsedLoop {
+  _shouldStop = false
+
+  start(engine) {
+    let previousTime = Date.now()
+
+    while (!this._shouldStop) {
+      const currentTime = Date.now()
+      const dt = currentTime - previousTime
+
+      engine.update(dt / ONE_SECOND)
+
+      previousTime = currentTime
+    }
+  }
+
+  stop() {
+    this._shouldStop = true
+  }
+}

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

@@ -1,28 +1,27 @@
-const ONE_SECOND = 1000
-
-export default class NapLoop {
-  _shouldStop = false
-
-  async start(engine, msPerUpdate) {
-    let previousTime = Date.now()
-
-    while (!this._shouldStop) {
-      const currentTime = Date.now()
-      const dt = currentTime - previousTime
-
-      engine.update(dt / ONE_SECOND)
-      engine.render(dt / ONE_SECOND)
-
-      previousTime = currentTime
-      await sleep(Date.now() - currentTime + msPerUpdate)
-    }
-  }
-
-  stop() {
-    this._shouldStop = true
-  }
-}
-
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms))
-}
+const ONE_SECOND = 1000
+
+export class FixedLoop {
+  _shouldStop = false
+
+  async start(engine, msPerUpdate) {
+    let previousTime = Date.now()
+
+    while (!this._shouldStop) {
+      const currentTime = Date.now()
+      const dt = currentTime - previousTime
+
+      engine.update(dt / ONE_SECOND)
+
+      previousTime = currentTime
+      await sleep(Date.now() - currentTime + msPerUpdate)
+    }
+  }
+
+  stop() {
+    this._shouldStop = true
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}

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

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

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

@@ -1,27 +1,26 @@
-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
-  }
-}
+const ONE_SECOND = 1000
+
+export 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)
+        lag -= msPerUpdate
+      }
+    }
+  }
+
+  stop() {
+    this._shouldStop = true
+  }
+}

package/src/engine/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
+  }
+}