@inglorious/engine 0.3.0 → 0.5.0

package/README.md

@@ -1,75 +1,122 @@
 # Inglorious Engine
 
+[![NPM version](https://img.shields.io/npm/v/@inglorious/engine.svg)](https://www.npmjs.com/package/@inglorious/engine)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A JavaScript game engine written with global state, immutability, and pure functions in mind. Have fun(ctional programming) with it!
+The core orchestrator for the [Inglorious Engine](https://github.com/IngloriousCoderz/inglorious-engine). This package provides a complete game loop, state management, and rendering pipeline in a single, cohesive unit. It is designed to be highly configurable and extensible, allowing you to build games with a functional, data-oriented approach.
 
-## Features
+---
 
-- **Functional & Data-Oriented**: Uses a single, immutable state object as the source of truth, inspired by functional programming principles.
-- **Composable by Design**: Build complex behaviors by composing pure functions and decorators, offering a powerful alternative to inheritance.
-- **Renderer Agnostic**: The engine is headless. You can use any rendering technology you like, from Canvas2D and HTML to React components.
-- **Zero Build Step**: Write plain JavaScript and run it directly in the browser. No complex build configurations to worry about.
+## Core Concepts
 
-## Documentation
+The `@inglorious/engine` package acts as the central hub that brings together all the engine's components. Its main responsibilities are:
 
-The best way to get started is with the official documentation, which includes a **[Quick Start Guide](https://inglorious-engine.vercel.app/?path=/docs/quick-start--docs)**.
+1.  **Orchestrating the Game Loop**: The `Engine` class manages the game loop, which is responsible for continuously updating the state and rendering the game. The loop can be configured to use different timing mechanisms, such as `animationFrame` or a fixed `fps`.
 
-Full documentation is available at: **[https://inglorious-engine.vercel.app/](https://inglorious-engine.vercel.app/)**
+2.  **State Management**: It leverages the `@inglorious/store` package to manage the game's state. It provides methods to start, stop, and update the state manager, processing a queue of events on each frame.
 
-## Why Functional Programming?
+3.  **Integrating the Renderer**: The engine is headless by design, but it can be configured with a renderer to display the game. The engine takes a renderer object in its configuration and integrates its systems and logic into the main game loop.
 
-What makes this engine different from all the others is that, instead of Object Oriented Programming (OOP), which seems the most obvious choice for a game engine, this one is based on Functional Programming (FP).
+4.  **Dev Tools Integration**: The engine automatically connects to a browser's dev tools for debugging and time-travel capabilities if `devMode` is enabled in the game's state.
 
-FP has many advantages:
+---
 
-1. **Single Source of Truth**: Your entire game state is a single, plain JavaScript object. This gives you complete control over your game's world at any moment, rather than having state scattered across countless objects. This is the core idea behind the Data-Oriented Design (DOD) paradigm that many modern engines are now adopting. With this engine, you get that benefit naturally.
+## Installation
 
-2. **Efficient Immutability**: A common misconception is that creating a new state on every change is slow. This engine uses structural sharing (via Immer), meaning only the parts of the state that actually change are copied. The rest of the state tree is shared by reference, making updates extremely fast. This provides a huge benefit:
-   - **Optimized Rendering**: Detecting changes becomes trivial and fast. A simple reference check (`prevState === nextState`) is all that's needed to determine if data has changed, enabling highly performant UIs (especially with libraries like React). This is much faster than the deep, recursive comparisons required in mutable systems.
+```bash
+npm install @inglorious/engine
+```
 
-3. **Pure Functions**: Game logic is built with pure functions — functions that return a value based only on their inputs, with no side effects. This makes your game logic predictable, easy to test in isolation, and highly reusable, freeing you from the complexity of class methods with hidden side effects.
+---
 
-4. **Composition over Inheritance**: Instead of complex class hierarchies, you build entities by composing functions. Think of it as a pipeline of operations applied to your data. This is a more flexible and powerful alternative to inheritance. You can mix and match behaviors (e.g., `canBeControlledByPlayer`, `canBeHurt`, `canShoot`) on the fly, avoiding the rigidity and common problems of deep inheritance chains.
+## API
 
-5. **Dynamic by Nature**: JavaScript objects are dynamic. You can add or remove properties from an entity at any time without being constrained by a rigid class definition. This is perfect for game development, where an entity's state can change unpredictably (e.g., gaining a temporary power-up). This flexibility allows for more emergent game mechanics.
+### `new Engine(gameConfig)`
 
-6. **Unparalleled Debugging and Tooling**: Because the entire game state is a single, serializable object, you can unlock powerful development patterns that are difficult to achieve in traditional OOP engines.
-   - **Time-Travel Debugging**: Save the state at any frame. You can step backward and forward through state changes to find exactly when a bug was introduced.
-   - **Hot-Reloading**: Modify your game's logic and instantly see the results without restarting. The engine can reload the code and re-apply it to the current state, dramatically speeding up iteration.
-   - **Simplified Persistence**: Saving and loading a game is as simple as serializing and deserializing a single JSON object.
-   - **Simplified Networking**: For multiplayer games, you don't need to synchronize complex objects. You just send small, serializable `event` objects over the network. Each client processes the same event with the same pure event handler, guaranteeing their game states stay in sync.
+Creates a new `Engine` instance.
 
-7. **Leverage the Full JavaScript Ecosystem**: As a pure JavaScript engine, you have immediate access to the world's largest software repository: npm. Need advanced physics, complex AI, or a specific UI library? Integrate it with a simple `npm install`. You aren't limited to the built-in features or proprietary plugin ecosystem of a monolithic engine like Godot or Unity.
+**Parameters:**
 
-## Architecture: State Management
+- `gameConfig` (object): The game-specific configuration. It is an object with the following properties:
+  - `loop` (object, optional): Configuration for the game loop.
+    - `type` (string, optional): The type of loop to use (`animationFrame` or `fixed`). Defaults to `animationFrame`.
+    - `fps` (number, optional): The target frames per second. Only used with the `fixed` loop type. Defaults to `60`.
+  - `systems` (array, optional): An array of system objects, which define behaviors for the whole state.
+  - `types` (object, optional): A map of entity types.
+  - `entities` (object, optional): A map of initial entities.
+  - `renderer` (object, optional): A renderer entity responsible for drawing the game. It must implement `getSystems()` and `init(engine)` methods.
 
-The engine's state management is inspired by Redux, but it's specifically tailored for the demands of game development. If you're familiar with Redux, you'll recognize the core pattern: the UI (or game view) is a projection of the state, and the only way to change the state is to dispatch an action.
+**Returns:**
 
-However, there are several key differences that make it unique:
+- A new `Engine` instance.
 
-1.  **Events, not Actions**: In Redux, you "dispatch actions." Here, we "notify of events." This is a deliberate semantic choice. An event handler is a function that reacts to a specific occurrence in the game world (e.g., `playerMove`, `enemyDestroy`). The naming convention is similar to standard JavaScript event handlers like `onClick`, where the handler name describes the event it's listening for.
+### `engine.start()`
 
-2.  **Asynchronous Event Queue**: Unlike Redux's synchronous dispatch, events are not processed immediately. They are added to a central event queue. The engine's main loop processes this queue once per frame. This approach has several advantages:
-    - It decouples game logic from state updates.
-    - It ensures state changes happen at a predictable point in the game loop, preventing race conditions or cascading updates within a single frame.
-    - It allows for event batching and provides a solid foundation for networking and time-travel debugging.
+Starts the game loop, triggering the first `update` and `render` calls.
 
-3.  **Core Engine Events & Naming Convention**: The engine has a few built-in, **single-word** events that drive its core functionality. To avoid conflicts, you should use **multi-word `camelCase`** names for your own custom game events (`playerJump`, `itemCollect`). This convention is similar to how custom HTML elements require a hyphen to distinguish them from standard elements. Key engine events include:
-    - `update`: Fired on every frame, typically carrying the `deltaTime` since the last frame. This is where you'll put most of your continuous game logic (like movement).
-    - `add`: Used to add a new entity to the game state.
-    - `remove`: Used to remove an entity from the game state.
-    - `morph`: Used to dynamically change the behaviors associated with an entity's type.
+### `engine.stop()`
 
-4.  **Ergonomic Immutability with Immer**: The state is immutable, but to make this easy to work with, we use Immer. Inside your event handlers, you can write code that looks like it's mutating the state directly. Immer handles the magic behind the scenes, producing a new, updated state with structural sharing, giving you the performance benefits of immutability with the developer experience of mutable code.
+Halts the game loop and cleans up any resources. This method also processes a final `stop` event to ensure a clean shutdown.
 
-5.  **Composable Handlers via Function Piping**: Instead of large, monolithic "reducers," you build event handlers by composing smaller, pure functions. The engine encourages a pipeline pattern where an event and the current state are passed through a series of decorators or transformations. This makes your logic highly modular, reusable, and easy to test in isolation.
+---
 
-6.  **Handlers Can Issue New Events (Controlled Side-Effects)**: In a strict Redux pattern, reducers must be pure. We relax this rule for a pragmatic reason: event handlers in this engine **can notify of new events**. This allows you to create powerful, reactive chains of logic. For example, an `enemy:take_damage` handler might check the enemy's health and, if it drops to zero, notify of a new `enemy:destroyed` event.
-    - **How it works**: Any event notified from within a handler is simply added to the end of the main event queue. It will be processed in a subsequent pass of the game loop, not immediately. This prevents synchronous, cascading updates within a single frame and makes the flow of logic easier to trace.
+## Basic Usage
 
-    - **A Word of Caution**: This power comes with responsibility. It is possible to create infinite loops (e.g., event A's handler notifies of event B, and event B's handler notifies of event A). Developers should be mindful of this when designing their event chains.
+Here is a complete example showing how to set up and run a game using the engine.
+
+```html
+<!doctype html>
+<html lang="en">
+   
+  <head>
+       
+    <meta charset="UTF-8" />
+       
+    <link rel="icon" type="image/svg+xml" href="/logo.png" />
+       
+    <link rel="stylesheet" href="/style.css" />
+       
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+
+       
+    <title>Inglorious Engine</title>
+     
+  </head>
+   
+  <body>
+        <canvas id="canvas"></canvas>
+
+       
+    <script type="text/javascript">
+      window.process = { env: "development" }
+    </script>
+
+       
+    <script type="importmap">
+      {
+        "imports": {
+          "immer": "https://unpkg.com/immer@10.1.1/dist/immer.mjs",
+          "@inglorious/utils/": "https://unpkg.com/@inglorious%2Futils@1.1.0/",
+          "@inglorious/store/": "https://unpkg.com/@inglorious%2Fstore@0.1.0/",
+          "@inglorious/engine/": "https://unpkg.com/@inglorious%2Fengine@0.4.0/",
+          "@inglorious/renderers/": "https://unpkg.com/@inglorious%2Frenderer-2d@0.2.0/",
+          "game": "/game.js"
+        }
+      }
+    </script>
+
+       
+    <script
+      type="module"
+      src="https://unpkg.com/@inglorious%2Fengine@0.2.0/src/main.js"
+    ></script>
+     
+  </body>
+</html>
+```
+
+---
 
 ## Contributing
 
-We welcome contributions from the community! Whether you're fixing a bug, adding a feature, or improving the documentation, your help is appreciated. Please read our Contributing Guidelines for details on how to get started.
+We welcome contributions from the community\! Whether you're fixing a bug, adding a feature, or improving the documentation, your help is appreciated. Please read our [Contributing Guidelines](https://github.com/IngloriousCoderz/inglorious-engine/blob/main/CONTRIBUTING.md) for details on how to get started.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/engine",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "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",
@@ -20,23 +20,22 @@
     "game-engine"
   ],
   "type": "module",
+  "exports": {
+    "./*": "./src/*"
+  },
   "files": [
     "src",
     "README.md",
     "LICENSE"
   ],
-  "exports": {
-    "./*": "./src/*"
-  },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "immer": "^10.1.1",
-    "@inglorious/utils": "1.1.0"
+    "@inglorious/utils": "1.1.0",
+    "@inglorious/store": "1.2.0"
   },
   "devDependencies": {
-    "husky": "^9.1.7",
     "prettier": "^3.5.3",
     "vite": "^7.1.3",
     "vitest": "^1.6.0"

package/src/behaviors/camera.js

@@ -22,7 +22,7 @@ export function camera(params) {
   params = extend(DEFAULT_PARAMS, params)
 
   return {
-    start(entity) {
+    create(entity) {
       defaults(entity, params)
       entity.targetZoom = entity.zoom
       // Cache the initial size to calculate the viewport in dev mode

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

@@ -24,8 +24,8 @@ export function modernAcceleration(params) {
         "moveUpDown",
       ]),
 
-      start(entity, api) {
-        type.start?.(entity, api)
+      create(entity, event, api) {
+        type.create?.(entity, event, api)
 
         entity.maxAcceleration ??= params.maxAcceleration
         entity.movement ??= {}

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

@@ -33,8 +33,8 @@ export function shooterControls(params) {
         "turn",
       ]),
 
-      start(entity, api) {
-        type.start?.(entity, api)
+      create(entity, event, api) {
+        type.create?.(entity, event, api)
 
         entity.maxSpeed ??= params.maxSpeed
         entity.maxAngularSpeed ??= params.maxAngularSpeed

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

@@ -27,8 +27,8 @@ export function tankControls(params) {
         "turn",
       ]),
 
-      start(entity, api) {
-        type.start?.(entity, api)
+      create(entity, event, api) {
+        type.create?.(entity, event, api)
 
         entity.maxSpeed ??= params.maxSpeed
         entity.maxAngularSpeed ??= params.maxAngularSpeed

package/src/behaviors/controls/kinematic/modern.js

@@ -24,8 +24,8 @@ export function modernVelocity(params) {
         "moveUpDown",
       ]),
 
-      start(entity, api) {
-        type.start?.(entity, api)
+      create(entity, event, api) {
+        type.create?.(entity, event, api)
 
         entity.maxSpeed ??= params.maxSpeed
         entity.movement ??= {}

package/src/behaviors/controls/kinematic/shooter.js

@@ -32,8 +32,8 @@ export function shooterControls(params) {
         "turn",
       ]),
 
-      start(entity, api) {
-        type.start?.(entity, api)
+      create(entity, event, api) {
+        type.create?.(entity, event, api)
 
         entity.maxSpeed ??= params.maxSpeed
         entity.maxAngularSpeed ??= params.maxAngularSpeed

package/src/behaviors/controls/kinematic/tank.js

@@ -26,8 +26,8 @@ export function tankControls(params) {
         "turn",
       ]),
 
-      start(entity, api) {
-        type.start?.(entity, api)
+      create(entity, event, api) {
+        type.create?.(entity, event, api)
 
         entity.maxSpeed ??= params.maxSpeed
         entity.maxAngularSpeed ??= params.maxAngularSpeed

package/src/behaviors/fps.js

@@ -12,7 +12,7 @@ export function fps(params) {
   params = extend(DEFAULT_PARAMS, params)
 
   return {
-    start(entity) {
+    create(entity) {
       entity.dt ??= { ...params }
     },
 

package/src/behaviors/fsm.js

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

package/src/behaviors/fsm.test.js

@@ -1,6 +1,6 @@
+import { createStore } from "@inglorious/store/store.js"
 import { expect, test } from "vitest"
 
-import { createStore } from "../core/store.js"
 import { fsm } from "./fsm.js"
 
 test("it should add a finite state machine", () => {

package/src/behaviors/input/gamepad.js

@@ -4,7 +4,7 @@ const DEFAULT_PARAMS = {
 
 export function gamepadsPoller() {
   return {
-    start(entity) {
+    create(entity) {
       entity.gamepadStateCache ??= {}
     },
 

package/src/behaviors/input/keyboard.js

@@ -7,7 +7,7 @@ export function keyboard() {
   let currentDocument = null
 
   return {
-    start(_, api) {
+    create(entity, event, api) {
       currentDocument = document.body.ownerDocument || document
 
       handleKeyDown = createKeyboardHandler("keyboardKeyDown", api)

package/src/behaviors/input/mouse.js

@@ -10,7 +10,7 @@ const NO_Y = 0
 
 export function mouse() {
   return {
-    start(entity) {
+    create(entity) {
       entity.collisions ??= {}
       entity.collisions.bounds ??= { shape: "point" }
     },

package/src/behaviors/physics/bouncy.js

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

package/src/behaviors/physics/clamped.js

@@ -11,8 +11,8 @@ export function clamped(params) {
 
   return (type) =>
     extend(type, {
-      start(entity, api) {
-        type.start?.(entity, api)
+      create(entity, event, api) {
+        type.create?.(entity, event, api)
 
         entity.collisions ??= {}
         entity.collisions[params.collisionGroup] ??= {}

package/src/behaviors/physics/jumpable.js

@@ -27,8 +27,8 @@ export function jumpable(params) {
 
   return (type) =>
     extend(type, {
-      start(entity, api) {
-        type.start?.(entity, api)
+      create(entity, event, api) {
+        type.create?.(entity, event, api)
         defaults(entity, params)
         entity.jumpsLeft ??= entity.maxJumps
 

package/src/core/core-events.js

@@ -0,0 +1,16 @@
+export const coreEvents = [
+  "create",
+  "update",
+  "destroy",
+  "gamepadAxis",
+  "gamepadPress",
+  "gamepadRelease",
+  "keyboardKeyDown",
+  "keyboardKeyUp",
+  "inputAxis",
+  "inputPress",
+  "inputRelease",
+  "mouseMove",
+  "mouseClick",
+  "spriteAnimationEnd",
+]

package/src/core/dev-tools.js

@@ -1,17 +1,4 @@
-export const ACTION_BLACKLIST = [
-  "update",
-  "gamepadAxis",
-  "gamepadPress",
-  "gamepadRelease",
-  "keyboardKeyDown",
-  "keyboardKeyUp",
-  "inputAxis",
-  "inputPress",
-  "inputRelease",
-  "mouseMove",
-  "mouseClick",
-  "spriteAnimationEnd",
-]
+import { coreEvents } from "./core-events.js"
 
 const LAST_STATE = 1
 
@@ -30,7 +17,7 @@ export function initDevTools(store) {
 
   devToolsInstance = window.__REDUX_DEVTOOLS_EXTENSION__.connect({
     name: "Inglorious Engine",
-    predicate: (state, action) => !ACTION_BLACKLIST.includes(action.type),
+    predicate: (state, action) => !coreEvents.includes(action.type),
     actionCreators: {
       jump: () => ({ type: "jump", payload: { inputId: "input0" } }),
     },

package/src/core/engine.js

@@ -1,15 +1,13 @@
 import { game } from "@inglorious/engine/behaviors/game.js"
+import { createApi } from "@inglorious/store/api.js"
+import { createStore } from "@inglorious/store/store.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 { coreEvents } from "./core-events.js"
+import { disconnectDevTools, initDevTools, sendAction } from "./dev-tools.js"
 import Loop from "./loop.js"
-import { createStore } from "./store.js"
+import { applyMiddlewares } from "./middlewares.js"
+import { multiplayerMiddleware } from "./multiplayer.js"
 
 // Default game configuration
 // loop.type specifies the type of loop to use (defaults to "animationFrame").
@@ -51,7 +49,15 @@ export class Engine {
       systems.push(...this._config.renderer.getSystems())
     }
 
-    this._store = createStore({ ...this._config, systems })
+    let store = createStore({ ...this._config, systems })
+
+    // Apply multiplayer if specified.
+    const multiplayer = this._config.entities.game?.multiplayer
+    if (multiplayer) {
+      store = applyMiddlewares(multiplayerMiddleware(multiplayer))(store)
+    }
+
+    this._store = store
     this._loop = new Loop[this._config.loop.type]()
     this._api = createApi(this._store)
 
@@ -70,7 +76,7 @@ export class Engine {
    * Starts the game engine, initializing the loop and notifying the store.
    */
   start() {
-    this._store.notify("start", this._api)
+    this._store.notify("start")
     this._loop.start(this, ONE_SECOND / this._config.loop.fps)
     this.isRunning = true
   }
@@ -79,7 +85,7 @@ export class Engine {
    * Stops the game engine, halting the loop and notifying the store.
    */
   stop() {
-    this._store.notify("stop", this._api)
+    this._store.notify("stop")
     this._store.update(FINAL_UPDATE_DELTA_TIME, this._api)
     this._loop.stop()
     this.isRunning = false
@@ -105,7 +111,7 @@ export class Engine {
     }
 
     const eventsToLog = processedEvents.filter(
-      ({ type }) => !ACTION_BLACKLIST.includes(type),
+      ({ type }) => !coreEvents.includes(type),
     )
 
     if (eventsToLog.length) {

package/src/core/middlewares.js

@@ -0,0 +1,36 @@
+import { compose } from "@inglorious/utils/functions/functions.js"
+
+/**
+ * Applies a list of middleware functions to a store's dispatch method.
+ *
+ * @param {...Function} middlewares The middleware functions to apply.
+ * @returns {Function} A store enhancer function.
+ */
+export function applyMiddlewares(...middlewares) {
+  return (store) => {
+    let dispatch = () => {
+      throw new Error(
+        "Dispatching while constructing your middleware is not allowed.",
+      )
+    }
+
+    // The middleware API that can be passed to each middleware function.
+    const api = {
+      dispatch: (...args) => dispatch(...args),
+      getState: store.getState,
+      setState: store.setState,
+    }
+
+    // Create a chain of middleware functions.
+    const chain = middlewares.map((middleware) => middleware(api))
+
+    // Compose the middleware chain to create the final dispatch function.
+    dispatch = compose(...chain)(store.dispatch)
+
+    return {
+      ...store,
+      dispatch,
+      notify: (type, payload) => dispatch({ type, payload }),
+    }
+  }
+}

package/src/core/multiplayer.js

@@ -0,0 +1,91 @@
+import { extend } from "@inglorious/utils/data-structures/objects.js"
+
+import { coreEvents } from "./core-events.js"
+
+// A constant for the server's WebSocket URL.
+const DEFAULT_SERVER_URL = `ws://${window.location.hostname}:3000`
+const DEFAULT_RECONNECTION_DELAY = 1000
+
+/**
+ * Creates and returns the multiplayer middleware.
+ * @returns {Function} The middleware function.
+ */
+export function multiplayerMiddleware(config = {}) {
+  const serverUrl = config.serverUrl ?? DEFAULT_SERVER_URL
+  const reconnectionDelay =
+    config.reconnectionDelay ?? DEFAULT_RECONNECTION_DELAY
+
+  let ws = null
+  const localQueue = []
+
+  // The middleware function that will be applied to the store.
+  return (api) => (next) => (event) => {
+    if (coreEvents.includes(event.type)) {
+      return next(event)
+    }
+
+    // Establish the connection on the first event.
+    if (!ws) {
+      establishConnection(api)
+    }
+
+    // Only send the event to the server if it didn't come from the server.
+    if (!event.fromServer) {
+      if (ws?.readyState === WebSocket.OPEN) {
+        // If the connection is open, send the event immediately.
+        ws.send(JSON.stringify(event))
+      } else {
+        // If the connection is not open, queue the event for later.
+        localQueue.push(event)
+      }
+    }
+
+    // Pass the event to the next middleware in the chain,
+    // which is eventually the store's original dispatch function.
+    return next(event)
+  }
+
+  /**
+   * Attempts to establish a WebSocket connection to the server.
+   */
+  function establishConnection(api) {
+    // If a connection already exists, close it first.
+    if (ws) {
+      ws.close()
+    }
+    ws = new WebSocket(serverUrl)
+
+    // =====================================================================
+    // WebSocket Event Handlers
+    // =====================================================================
+
+    ws.onopen = () => {
+      // Send any queued events to the server.
+      while (localQueue.length) {
+        ws.send(JSON.stringify(localQueue.shift()))
+      }
+    }
+
+    ws.onmessage = (event) => {
+      const serverEvent = JSON.parse(event.data)
+
+      if (serverEvent.type === "initialState") {
+        // Merge the server's initial state with the client's local state.
+        const nextState = extend(api.getState(), serverEvent.payload)
+        api.setState(nextState)
+      } else {
+        // Dispatch the event to the local store to update the client's state.
+        api.dispatch({ ...serverEvent, fromServer: true })
+      }
+    }
+
+    ws.onclose = () => {
+      // Attempt to reconnect after a short delay.
+      setTimeout(() => establishConnection(api), reconnectionDelay)
+    }
+
+    ws.onerror = () => {
+      ws.close() // The 'onclose' handler will trigger the reconnect.
+    }
+  }
+}

package/src/core/api.js

@@ -1,34 +0,0 @@
-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/core/select.js

@@ -1,26 +0,0 @@
-/**
- * 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

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

@@ -1,110 +0,0 @@
-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()
-})