@inglorious/engine 0.5.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/engine",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "A JavaScript game engine written with global state, immutability, and pure functions in mind. Have fun(ctional programming) with it!",
   "author": "IceOnFire <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",
@@ -32,8 +32,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@inglorious/utils": "1.1.0",
-    "@inglorious/store": "1.2.0"
+    "@inglorious/store": "2.0.0",
+    "@inglorious/utils": "1.1.0"
   },
   "devDependencies": {
     "prettier": "^3.5.3",

package/src/animation/ticker.js

@@ -2,37 +2,48 @@ const DEFAULT_STATE = "default"
 const DEFAULT_VALUE = 0
 const COUNTER_RESET = 0
 
-export const Ticker = { tick }
+export const Ticker = {
+  /**
+   * Ticks a counter and calls a function when a target interval is reached.
+   *
+   * @param {object} options The options for the tick.
+   * @param {object} options.target An object to hold the ticker's internal state.
+   * @param {number} options.target.speed The interval in milliseconds for the ticker to "tick".
+   * @param {number} options.dt The time elapsed since the last tick.
+   * @param {function} options.onTick The function to call when the ticker "ticks".
+   * @param {string} [options.state="default"] An optional state to track changes and reset the ticker.
+   * @param {number} [options.defaultValue=0] The default value for the target's counter.
+   */
+  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}`)
+    }
 
-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
 
-  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
+    }
 
-  // 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
 
-  // 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
 
-  // 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)
-  }
+    target.counter += dt
+    if (target.counter >= speed) {
+      target.counter = COUNTER_RESET
+      onTick?.(target, dt, options)
+    }
+  },
 }

package/src/behaviors/fsm.js

@@ -10,7 +10,7 @@ export function fsm(states) {
   return (type) => {
     return extend(type, {
       create(entity, event, api) {
-        type.start?.(entity, event, api)
+        type.create?.(entity, event, api)
 
         entity.state ??= DEFAULT_STATE
       },

package/src/behaviors/fsm.test.js

@@ -9,7 +9,7 @@ test("it should add a finite state machine", () => {
       kitty: [
         fsm({
           default: {
-            catMeow(entity) {
+            meow(entity) {
               entity.state = "meowing"
             },
           },
@@ -40,8 +40,8 @@ test("it should add a finite state machine", () => {
   }
 
   const store = createStore(config)
-  store.notify("start")
-  store.notify("catMeow")
+  store.notify("meow")
+  store.notify("update")
   store.update()
 
   const state = store.getState()

package/src/behaviors/physics/bouncy.js

@@ -11,7 +11,7 @@ export function bouncy(params) {
   return (type) =>
     extend(type, {
       create(entity) {
-        type.start?.(entity)
+        type.create?.(entity)
         defaults(entity, params)
       },
 

package/src/core/engine.js

@@ -5,9 +5,11 @@ import { extend } from "@inglorious/utils/data-structures/objects.js"
 
 import { coreEvents } from "./core-events.js"
 import { disconnectDevTools, initDevTools, sendAction } from "./dev-tools.js"
-import Loop from "./loop.js"
-import { applyMiddlewares } from "./middlewares.js"
-import { multiplayerMiddleware } from "./multiplayer.js"
+import { Loops } from "./loops/loops.js"
+import { entityPoolMiddleware } from "./middlewares/entity-pool/entity-pool-middleware.js"
+import { EntityPools } from "./middlewares/entity-pool/entity-pools.js"
+import { applyMiddlewares } from "./middlewares/middlewares.js"
+import { multiplayerMiddleware } from "./middlewares/multiplayer-middleware.js"
 
 // Default game configuration
 // loop.type specifies the type of loop to use (defaults to "animationFrame").
@@ -28,15 +30,10 @@ const DEFAULT_GAME_CONFIG = {
 
 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.
@@ -44,30 +41,46 @@ export class Engine {
   constructor(gameConfig) {
     this._config = extend(DEFAULT_GAME_CONFIG, gameConfig)
 
+    // Determine devMode from the entities config.
+    const devMode = this._config.entities.game?.devMode
+    this._devMode = devMode
+
+    // Add user-defined systems
     const systems = [...(this._config.systems ?? [])]
     if (this._config.renderer) {
       systems.push(...this._config.renderer.getSystems())
     }
 
-    let store = createStore({ ...this._config, systems })
+    this._store = createStore({ ...this._config, systems })
+
+    // Create API layer, with optional methods for debugging
+    this._api = createApi(this._store)
+
+    this._entityPools = new EntityPools()
+    this._api = applyMiddlewares(entityPoolMiddleware(this._entityPools))(
+      this._api,
+    )
+    this._api.getAllActivePoolEntities = () =>
+      this._entityPools.getAllActiveEntities()
+
+    if (this._devMode) {
+      this._api.getEntityPoolsStats = () => this._entityPools.getStats()
+    }
 
     // Apply multiplayer if specified.
     const multiplayer = this._config.entities.game?.multiplayer
     if (multiplayer) {
-      store = applyMiddlewares(multiplayerMiddleware(multiplayer))(store)
+      this._api = applyMiddlewares(multiplayerMiddleware(multiplayer))(
+        this._api,
+      )
     }
 
-    this._store = store
-    this._loop = new Loop[this._config.loop.type]()
-    this._api = createApi(this._store)
+    this._loop = new Loops[this._config.loop.type]()
 
     // 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) {
+    if (this._devMode) {
       initDevTools(this._store)
     }
   }
@@ -76,7 +89,7 @@ export class Engine {
    * Starts the game engine, initializing the loop and notifying the store.
    */
   start() {
-    this._store.notify("start")
+    this._api.notify("start")
     this._loop.start(this, ONE_SECOND / this._config.loop.fps)
     this.isRunning = true
   }
@@ -85,8 +98,8 @@ export class Engine {
    * Stops the game engine, halting the loop and notifying the store.
    */
   stop() {
-    this._store.notify("stop")
-    this._store.update(FINAL_UPDATE_DELTA_TIME, this._api)
+    this._api.notify("stop")
+    this._store.update(this._api)
     this._loop.stop()
     this.isRunning = false
   }
@@ -96,14 +109,15 @@ export class Engine {
    * @param {number} dt - Delta time since the last update in milliseconds.
    */
   update(dt) {
-    const processedEvents = this._store.update(dt, this._api)
+    this._api.notify("update", dt)
+    const processedEvents = this._store.update(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)
+        initDevTools(this._api)
       } else {
         disconnectDevTools()
       }

package/src/core/loops/loops.js

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

package/src/core/middlewares/entity-pool/entity-pool-middleware.js

@@ -0,0 +1,38 @@
+import { EventMap } from "@inglorious/store/event-map"
+
+export function entityPoolMiddleware(pools) {
+  return (api) => {
+    const types = api.getTypes()
+    const eventMap = new EventMap()
+
+    return (next) => (event) => {
+      switch (event.type) {
+        case "spawn": {
+          const entity = pools.acquire(event.payload)
+          const type = types[entity.type]
+          eventMap.addEntity(entity.id, type)
+          break
+        }
+
+        case "despawn": {
+          const entity = pools.recycle(event.payload)
+          const type = types[entity.type]
+          eventMap.removeEntity(entity.id, type)
+          break
+        }
+
+        default: {
+          const entityIds = eventMap.getEntitiesForEvent(event.type)
+          for (const id of entityIds) {
+            const entity = pools.activeEntitiesById.get(id)
+            const type = types[entity.type]
+            const handle = type[event.type]
+            handle?.(entity, event.payload, api)
+          }
+        }
+      }
+
+      return next(event)
+    }
+  }
+}

package/src/core/middlewares/entity-pool/entity-pool.js

@@ -0,0 +1,40 @@
+const INITIAL_ID = 0
+const NOT_FOUND = -1
+const ITEMS_TO_REMOVE = 1
+
+export class EntityPool {
+  _activeEntities = []
+  _inactiveEntities = []
+  _nextId = INITIAL_ID
+
+  populate(factory, count) {
+    for (let i = 0; i < count; i++) {
+      this._activeEntities.push(factory())
+    }
+  }
+
+  acquire(props) {
+    const entity = this._inactiveEntities.pop() || {
+      id: `entity-${this._nextId++}`,
+    }
+    Object.assign(entity, props)
+    this._activeEntities.push(entity)
+    return entity
+  }
+
+  recycle(entity) {
+    const index = this._activeEntities.indexOf(entity)
+    if (index !== NOT_FOUND) {
+      const [entity] = this._activeEntities.splice(index, ITEMS_TO_REMOVE)
+      this._inactiveEntities.push(entity)
+    }
+    return entity
+  }
+
+  getStats() {
+    return {
+      active: this._activeEntities.length,
+      inactive: this._inactiveEntities.length,
+    }
+  }
+}

package/src/core/middlewares/entity-pool/entity-pools.js

@@ -0,0 +1,42 @@
+import { EntityPool } from "./entity-pool"
+
+export class EntityPools {
+  _pools = new Map()
+  _activeEntitiesById = new Map()
+
+  get activeEntitiesById() {
+    return this._activeEntitiesById
+  }
+
+  acquire(props) {
+    this.lazyInit(props)
+    const entity = this._pools.get(props.type).acquire(props)
+    this._activeEntitiesById.set(entity.id, entity)
+    return entity
+  }
+
+  recycle(props) {
+    this.lazyInit(props)
+    const entity = this._pools.get(props.type).recycle(props)
+    this._activeEntitiesById.delete(entity.id)
+    return entity
+  }
+
+  getStats() {
+    const stats = {}
+    for (const [type, pool] of this._pools.entries()) {
+      stats[type] = pool.getStats()
+    }
+    return stats
+  }
+
+  lazyInit(entity) {
+    if (!this._pools.get(entity.type)) {
+      this._pools.set(entity.type, new EntityPool())
+    }
+  }
+
+  getAllActiveEntities() {
+    return Array.from(this._activeEntitiesById.values())
+  }
+}

package/src/core/{middlewares.js → middlewares/middlewares.js}

@@ -16,9 +16,9 @@ export function applyMiddlewares(...middlewares) {
 
     // The middleware API that can be passed to each middleware function.
     const api = {
+      ...store,
       dispatch: (...args) => dispatch(...args),
-      getState: store.getState,
-      setState: store.setState,
+      notify: (type, payload) => dispatch({ type, payload }),
     }
 
     // Create a chain of middleware functions.
@@ -27,10 +27,6 @@ export function applyMiddlewares(...middlewares) {
     // Compose the middleware chain to create the final dispatch function.
     dispatch = compose(...chain)(store.dispatch)
 
-    return {
-      ...store,
-      dispatch,
-      notify: (type, payload) => dispatch({ type, payload }),
-    }
+    return api
   }
 }

package/src/core/{multiplayer.js → middlewares/multiplayer-middleware.js}

@@ -1,6 +1,6 @@
 import { extend } from "@inglorious/utils/data-structures/objects.js"
 
-import { coreEvents } from "./core-events.js"
+import { coreEvents } from "../core-events.js"
 
 // A constant for the server's WebSocket URL.
 const DEFAULT_SERVER_URL = `ws://${window.location.hostname}:3000`

package/src/systems/entity-creator.js

@@ -0,0 +1,30 @@
+import { Ticker } from "@inglorious/engine/animation/ticker.js"
+
+const DEFAULT_SPAWN_INTERVAL = 1 // Time in seconds between spawning entities.
+
+/**
+ * A system responsible for creating new entities, like asteroids, at regular intervals.
+ *
+ * @param {object} params Configuration parameters for the system.
+ * @param {number} [params.spawnInterval=1] The time in seconds between spawning entities.
+ * @param {function} params.factory A function that returns the properties for a new entity.
+ * @returns {object} The configured entity creator system.
+ */
+export function entityCreator(params = {}) {
+  const spawnInterval = params.spawnInterval ?? DEFAULT_SPAWN_INTERVAL
+  const factory = params.factory
+
+  const ticker = { speed: spawnInterval }
+
+  return {
+    update(state, dt, api) {
+      Ticker.tick({
+        target: ticker,
+        dt,
+        onTick: () => {
+          api.notify("add", factory())
+        },
+      })
+    },
+  }
+}

package/src/core/loop.js

@@ -1,15 +0,0 @@
-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,
-}