@inglorious/engine 13.0.1 → 13.0.3

package/README.md

@@ -1,71 +1,191 @@
 # 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)
 
-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.
+A JavaScript game engine written with global state, immutability, and pure functions in mind. Have fun(ctional programming) with it!
 
----
+## Quick Start
 
-## Core Concepts
+The fastest way to start a new Inglorious Engine project is by using the official scaffolding tool.
 
-The `@inglorious/engine` package acts as the central hub that brings together all the engine's components. Its main responsibilities are:
+Run the following command in your terminal and follow the prompts to create a new game from a variety of templates (including plain JavaScript, TypeScript, and IngloriousScript):
 
-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`.
+```bash
+# with npm
+npm create @inglorious/game@latest
 
-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.
+# with pnpm
+pnpm create @inglorious/game
+```
 
-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.
+This will set up a complete project with a development server ready to go.
 
-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.
+## 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 Option**: Write plain JavaScript and run it directly in the browser. No complex build configurations required.
 
-## Installation
+## Documentation
 
-```bash
-npm install @inglorious/engine
+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)**.
+
+Full documentation is available at: **[https://inglorious-engine.vercel.app/](https://inglorious-engine.vercel.app/)**
+
+## Why Functional Programming?
+
+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).
+
+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-Driven Programming (DDP) paradigm that many modern engines are now adopting, and with this engine, you get that benefit naturally.
+
+2. **Efficient Immutability**: A common misconception is that creating a new state on every change is slow. This engine uses structural sharing (via Mutative), 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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+## Architecture: State Management
+
+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.
+
+However, there are several key differences that make it unique:
+
+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.
+
+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.
+
+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.
+
+4.  **Ergonomic Immutability with Mutative**: The state is immutable, but to make this easy to work with, we use Mutative. Inside your event handlers, you can write code that looks like it's mutating the state directly. Mutative 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.
+
+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.
+
+    - **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.
+
+## Frequently Unsolicited Complaints (FUCs)
+
+A few... recurring themes have popped up in discussions about the engine. Let's address them head-on.
+
+**"You just hate OOP."**
+
+Not at all! OOP is a powerful paradigm, and parts of this engine use it — the `Engine` itself is a class, for example. My main reservation is with deep **inheritance** hierarchies, which can become rigid and fragile. This engine's architecture strongly favors **composition over inheritance** by design, which I believe is a more flexible way to build complex and dynamic behaviors in games.
+
+**"This was made by a vibecoder who doesn't get cache optimization."**
+
+This engine is the product of countless hours of coding, smartly paired with AI assistance. If you're not leveraging AI in your workflow today, you're the one missing out.
+
+Now, let's talk performance. The critique often has two parts: garbage collection (GC) pressure from immutability, and cache performance compared to modern engines.
+
+1.  **Garbage Collection**: The concern is that creating new objects on every state change will flood the GC. This is mitigated by **structural sharing** (via Mutative). We don't deep-clone the state; only the changed data paths create new objects. For the most extreme cases (e.g., a bullet hell), the engine provides a dedicated **entity pooling system** as a pragmatic escape hatch, eliminating GC pressure in performance hotspots.
+
+2.  **Cache Performance & ECS**: The other critique is that modern engines like Unity or Godot use an Entity-Component-System (ECS) architecture to avoid deep object graphs (`player.inventory.getItem()`) and achieve better cache performance. **This is absolutely correct!** Those engines solve this problem very well.
+
+This engine achieves a similar architectural goal — separating data from behavior — but through a functional paradigm that is native to JavaScript. Instead of fighting with OOP class hierarchies, you get a data-centric, ECS-like pattern by default. Centralizing state in a single object leverages the JS engine's highly optimized property access, which, while not the same as a C++ SoA layout, is a massive improvement over the pointer-chasing that plagues naive OOP designs.
+
+**"JavaScript isn't a 'real' functional language."**
+
+You're right, it's not Haskell. JavaScript is a multi-paradigm language, and that's one of its strengths! This engine leverages its first-class functions, closures, and native support for data structures (objects and arrays) to enable a functional _style_. We get many of the benefits—pure functions, immutability (with help), and composition—without needing to be dogmatic about it.
+
+**"Data-Driven Programming is not the same as Data-Oriented Design."**
+
+This is a frequent point of confusion, so let's clarify. The engine uses [Data-Driven _Programming_](https://en.wikipedia.org/wiki/Data-driven_programming), but it's important to distinguish it from [Data-Oriented _Design_](https://en.wikipedia.org/wiki/Data-oriented_design).
+
+- **Data-Driven Programming (DDP)**: This is the architectural paradigm the engine is built on. It's about separating the data (your entities) from the logic that operates on it (your systems and event handlers). Your entire game state lives in one place, and your logic is a collection of pure functions that transform that data.
+
+- **Data-Oriented Design (DOD)**: This is a lower-level implementation strategy focused on CPU cache performance, common in ECS architectures. It involves organizing data in contiguous memory blocks (e.g., an array of all positions, an array of all velocities) to minimize cache misses during iteration.
+
+This engine does **not** implement a strict DOD memory layout. However, by centralizing all entities into a single, flat object, we get a pragmatic, "almost-DOD" benefit. We leverage the JavaScript engine's highly optimized internal object layout, which is significantly more cache-friendly than chasing pointers through a deeply nested OOP graph.
+
+**"Functional programming is just painful to read and write."**
+
+This is a common fear, especially for developers coming from a pure OOP background. The goal here isn't to force you to write Lisp in JavaScript. Instead, the API is intentionally designed to feel familiar and ergonomic:
+
+- **`types` are your "classes"**: They act as blueprints for your game objects.
+- **`entities` are your "instances"**: They are the concrete things in your game, created from a `type`.
+- **Composition feels like inheritance**: You can "extend" a type (which is just an array of behaviors) by adding behaviors to it, like `[baseType, someBehavior]`, and you "extend" a behavior by creating a function that composes new event handlers onto a base type, like `(type) => ({ eventName(...args) { type.eventName?.(...args) } })`. You get the code reuse you expect, but with the power and flexibility of composition.
+- **Immutable updates feel mutable**: Thanks to Mutative, you don't have to write complex functional updates. Inside your event handlers, you can write simple, direct code like `entity.health -= 10`, and the engine handles creating the new immutable state for you.
+
+The engine provides the benefits of FP (predictability, testability) without the steep learning curve. You get to think in terms of familiar concepts while the engine handles the functional magic for you.
+
+**"But I like my operators!"**
+
+We do too! That's why the engine includes **IngloriousScript**, an optional Babel plugin that overloads standard JavaScript operators for intuitive vector math.
+
+```javascript
+// Without IngloriousScript
+const newPosition = mod(add(position, scale(velocity, dt)), worldSize)
+
+// With IngloriousScript
+const newPosition = (position + velocity * dt) % worldSize
 ```
 
----
+It supports vector-vector, vector-scalar, and scalar-vector operations for `+`, `-`, `*`, `/`, `%`, and `**`, making your game logic clean, readable, and expressive.
 
-## API
+**"A good OOP developer just uses composition anyway. You don't need a new engine for that."**
 
-### `new Engine(...gameConfigs)`
+True, disciplined developers favor composition in any paradigm. The difference is that in many traditional OOP engines, inheritance is often presented as the default, easy path. This engine is designed so that **composition is the path of least resistance**. The architecture doesn't just allow for composition; it's built on it. You don't need discipline to avoid inheritance pitfalls when the framework naturally guides you to a better pattern.
 
-Creates a new `Engine` instance, given one or more configuration objects.
+**"This is fine for toy projects, but immutability will never scale."**
 
-**Parameters:**
+This critique usually misunderstands how modern immutability works. The engine uses structural sharing (via Mutative), which means we're not deep-copying the entire game state on every change. It's incredibly efficient.
 
-- `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`.
-  - `types` (object, optional): A map of entity types.
-  - `entities` (object, optional): A map of initial entities.
-  - `systems` (array, optional): An array of system objects, which define behaviors for the whole state.
+That said, we're pragmatic. For performance-critical scenarios like a bullet hell with thousands of short-lived objects, we provide an **entity pooling** system as an escape hatch. But for 99% of game logic, we believe the massive benefits of a predictable, testable, and debuggable state (hello, time-travel debugging!) are a worthwhile trade-off for a negligible performance cost.
 
-**Returns:**
+**"My favorite OOP engine can do all this too!"**
 
-- A new `Engine` instance.
+You're right. Modern engines like Unity (with DOTS) and Godot offer powerful, composition-based, ECS-like architectures out of the box. They are fantastic tools that have evolved to embrace these patterns.
 
-### `await engine.init()`
+To provide these features, however, they had to implement them within the constraints of a fundamentally object-oriented foundation. This sometimes results in systems that feel like they are working around the core OOP paradigm — almost to the point where it doesn't feel like OOP anymore.
 
-An asynchronous function that initializes the resources required for the game to load.
+The difference with this engine is that it was designed with functional and data-oriented principles from the very beginning. Composition, event-driven architecture, and data-centric patterns aren't features layered on top; they are the fundamental, native way of building things. The entire engine speaks one language, making these good practices the most natural and intuitive way to build your game.
 
-### `engine.start()`
+**"You'll never compete with Unity/Godot/Unreal."**
 
-Starts the game loop, triggering the first `update` and `render` calls.
+You're absolutely right. And we're not trying to.
 
-### `engine.stop()`
+This engine isn't for developers who want a massive, all-in-one, GUI-driven editor. It's for JavaScript developers who want to build games with the tools and ecosystem they already know and love. It's for those who are curious about applying functional programming principles to game development and who value architectural flexibility over a monolithic, proprietary feature set. It's a different tool for a different kind of developer.
 
-Halts the game loop and cleans up any resources. This method also processes a final `stop` event to ensure a clean shutdown.
+**"Why not just use an existing engine?"**
 
----
+Because building things is fun! This project is as much an exploration of software architecture as it is a tool for making games. It's for developers who are curious about functional programming and want to see how its principles can be applied to game development in a JavaScript environment.
+
+## Dependencies
+
+The core engine relies on a few key, lightweight packages:
+
+- [mutative](https://www.npmjs.com/package/mutative): For enabling ergonomic immutable updates with structural sharing.
+- [@inglorious/utils](https://www.npmjs.com/package/@inglorious/utils): A collection of small, pure utility functions for things like vector math and data manipulation.
+- [@inglorious/store](https://www.npmjs.com/package/@inglorious/store): The environment-agnostic core state management library.
+
+## Quick Start Example
 
-## Basic Usage
+## Usage without a Build Step
 
-Here is a complete example showing how to set up and run a game using the engine.
+If you prefer to avoid a build step, you can run the engine directly in the browser. The example below demonstrates how to set up a minimal game using ES modules, an `importmap`, and the 2D canvas renderer.
 
 ```html
 <!DOCTYPE html>
@@ -112,4 +232,4 @@ You're free to use, modify, and distribute this software. See [LICENSE](./LICENS
 
 ## 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](https://github.com/IngloriousCoderz/inglorious-engine/blob/main/CONTRIBUTING.md) 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](./CONTRIBUTING.md) for details on how to get started.

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@inglorious/engine",
-  "version": "13.0.1",
+  "version": "13.0.3",
   "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",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/IngloriousCoderz/inglorious-engine.git",
+    "url": "git+https://github.com/IngloriousCoderz/inglorious-forge.git",
     "directory": "packages/engine"
   },
   "homepage": "https://inglorious-engine.vercel.app/",
   "bugs": {
-    "url": "https://github.com/IngloriousCoderz/inglorious-engine/issues"
+    "url": "https://github.com/IngloriousCoderz/inglorious-forge/issues"
   },
   "keywords": [
     "data-oriented",
@@ -31,18 +31,18 @@
     "access": "public"
   },
   "dependencies": {
-    "@inglorious/utils": "3.7.0",
-    "@inglorious/store": "7.1.1"
+    "@inglorious/store": "7.1.3",
+    "@inglorious/utils": "3.7.0"
   },
   "peerDependencies": {
-    "@inglorious/store": "7.1.1",
+    "@inglorious/store": "7.1.3",
     "@inglorious/utils": "3.7.0"
   },
   "devDependencies": {
     "prettier": "^3.5.3",
     "vite": "^7.1.3",
     "vitest": "^1.6.0",
-    "@inglorious/eslint-config": "1.1.0"
+    "@inglorious/eslint-config": "1.1.1"
   },
   "engines": {
     "node": ">= 22"