@inglorious/engine 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2025 Inglorious Coderz Srl.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# 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!
+
+## 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.
+
+## Documentation
+
+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. A single source of truth means that the game state is just one huge JSON structure. This entails that you have control over the whole game state at every moment, instead of having pieces of state scattered through multiple objects. To overcome the issue of scattered state, many modern game engines use an approach that is called Data-Oriented. Well, guess what: functional programming has always used it.
+2. Immutability of state means that every time you want to change something a new state will be created with that change, instead of modifying the state directly. Isn't that slow? Nope, the new state is a shallow copy of the old one. Also, immutability makes it easier to compare what was before with what is now, and in certain scenarios (such as webapps) it allows for very performant re-rendering techniques.
+3. Pure functions are functions that return a value that depends only on the input parameters, no side-effects involved. They are the most predictable, testable, and reusable functions, so why should we rely on void methods belonging to a specific class?
+4. Another important concept related to FP is function composition, which means combining multiple functions together and then applying them to some input. Think of it as a pipeline of operations: you take x, then do some transformation on it, then pass the result to some other function, and so on. This can be used as a way more powerful tool than object inheritance: you can combine multiple behaviours on some object, in a way that is very similar to the Decorator pattern we have in OOP.
+
+## Contributing
+
+We welcome contributions from the community! Whether you're fixing a bug, adding a feature, or improving the documentation, your help is appreciated.
+
+### Development Setup
+
+1.  Fork and clone the repository.
+2.  Install dependencies using pnpm:
+    ```bash
+    pnpm install
+    ```
+3.  Run the Storybook documentation locally:
+    ```bash
+    pnpm storybook
+    ```
+4.  Run the unit tests:
+    ```bash
+    pnpm test
+    ```
+
+### Code Style
+
+The project uses ESLint for linting and Prettier for formatting. Please ensure your code adheres to the project's style to avoid introducing errors.
+
+A note on code style, particularly regarding "magic numbers" for vector components:
+
+```js
+const X = 0
+const Y = 1
+const Z = 2
+const x = instance.position[X]
+const y = instance.position[Y]
+const z = instance.position[Z]
+```
+
+I find it cleaner to do like so:
+
+```js
+const [x, y, z] = instance.position
+```
+
+There are a few exceptions: in the `/docs` folder I prefer the first version because not everyone is used to destructuring and I wanted to make the examples as readable as possible for people coming from, say, Godot. In that case I would put the `X`, `Y`, and `Z` constants on top of the file, right below the imports.

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@inglorious/engine",
+  "version": "0.1.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IngloriousCoderz/inglorious-engine.git"
+  },
+  "homepage": "https://inglorious-engine.vercel.app/",
+  "keywords": [
+    "game-engine",
+    "functional-programming",
+    "gamedev",
+    "javascript",
+    "ecs",
+    "data-oriented"
+  ],
+  "type": "module",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./*": "./src/*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "lint": "eslint . --ext js,jsx --report-unused-disable-directives --max-warnings 0",
+    "format": "prettier --write '**/*.{js,jsx}'",
+    "test:watch": "vitest",
+    "test": "vitest run",
+    "start": "serve",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "immer": "^10.1.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-redux": "^9.2.0"
+  },
+  "devDependencies": {
+    "@chromatic-com/storybook": "^3.2.6",
+    "@eslint/js": "^9.23.0",
+    "@storybook/addon-essentials": "^8.6.12",
+    "@storybook/addon-interactions": "^8.6.12",
+    "@storybook/addon-links": "^8.6.12",
+    "@storybook/blocks": "^8.6.12",
+    "@storybook/manager-api": "^8.6.12",
+    "@storybook/react": "^8.6.12",
+    "@storybook/react-vite": "^8.6.12",
+    "@storybook/test": "^8.6.12",
+    "@storybook/theming": "^8.6.12",
+    "@types/react": "^18.2.15",
+    "@types/react-dom": "^18.2.7",
+    "@vitejs/plugin-react": "^4.0.3",
+    "eslint": "^9.23.0",
+    "eslint-plugin-react": "^7.37.4",
+    "eslint-plugin-simple-import-sort": "^10.0.0",
+    "eslint-plugin-storybook": "^0.12.0",
+    "globals": "^16.0.0",
+    "husky": "^9.1.7",
+    "prettier": "^3.5.3",
+    "sass": "^1.66.1",
+    "serve": "^14.2.4",
+    "storybook": "^8.6.12",
+    "vite": "^4.4.5",
+    "vitest": "^0.34.3"
+  }
+}

package/src/docs/ai/movement/dynamic/align.js

@@ -0,0 +1,131 @@
+import align, {
+  DEFAULT_SLOW_RADIUS,
+  DEFAULT_TARGET_RADIUS,
+  DEFAULT_TIME_TO_TARGET,
+} from "@inglorious/engine/ai/movement/dynamic/align.js"
+import { clampToBounds } from "@inglorious/game/bounds.js"
+import { enableCharacter } from "@inglorious/game/decorators/character.js"
+import {
+  createControls,
+  enableControls,
+} from "@inglorious/game/decorators/input/controls.js"
+import { enableMouse } from "@inglorious/game/decorators/input/mouse.js"
+import { merge } from "@inglorious/utils/data-structures/objects.js"
+import { clamp } from "@inglorious/utils/math/numbers.js"
+import { pi } from "@inglorious/utils/math/trigonometry.js"
+
+export default {
+  types: {
+    mouse: [
+      enableMouse(),
+      {
+        "field:change"(instance, event) {
+          const { id, value } = event.payload
+          if (id === "targetOrientation") {
+            instance.orientation = -value * pi()
+          }
+        },
+
+        "game:update"(instance, event, options) {
+          const { input0 } = options.instances
+
+          if (input0.left || input0.up) {
+            instance.orientation += 0.1
+          } else if (input0.right || input0.down) {
+            instance.orientation -= 0.1
+          }
+          instance.orientation = clamp(instance.orientation, -pi(), pi())
+        },
+      },
+    ],
+
+    ...enableControls(),
+
+    character: [
+      enableCharacter(),
+      {
+        "game:update"(instance, event, { dt, instances }) {
+          const target = instances.mouse
+          const { fields } = instances.parameters.groups.align
+
+          merge(
+            instance,
+            align(instance, target, {
+              dt,
+              targetRadius: fields.targetRadius.value,
+              slowRadius: fields.slowRadius.value,
+              timeToTarget: fields.timeToTarget.value,
+            }),
+          )
+
+          clampToBounds(instance, instances.game.bounds)
+        },
+      },
+    ],
+
+    form: {
+      "field:change"(instance, event) {
+        const { id, value } = event.payload
+        instance.groups.align.fields[id].value = value
+      },
+    },
+  },
+
+  instances: {
+    mouse: {
+      type: "mouse",
+      position: [400, 0, 300],
+      orientation: 0,
+    },
+
+    ...createControls("input0", {
+      ArrowLeft: "left",
+      ArrowRight: "right",
+      ArrowDown: "down",
+      ArrowUp: "up",
+    }),
+
+    character: {
+      type: "character",
+      maxAngularSpeed: pi() / 4,
+      maxAngularAcceleration: 10,
+      position: [400, 0, 300],
+    },
+
+    parameters: {
+      type: "form",
+      position: [800 - 328, 0, 600],
+      groups: {
+        align: {
+          title: "Dynamic Align",
+          fields: {
+            targetRadius: {
+              label: "Target Radius",
+              inputType: "number",
+              defaultValue: DEFAULT_TARGET_RADIUS,
+            },
+            slowRadius: {
+              label: "Slow Radius",
+              inputType: "number",
+              defaultValue: DEFAULT_SLOW_RADIUS,
+            },
+            timeToTarget: {
+              label: "Time To Target",
+              inputType: "number",
+              step: 0.1,
+              defaultValue: DEFAULT_TIME_TO_TARGET,
+            },
+            targetOrientation: {
+              label: "Target Orientation",
+              inputType: "number",
+              step: 0.25,
+              min: -1,
+              max: 1,
+              defaultValue: 0,
+            },
+          },
+        },
+      },
+    },
+  },
+}

package/src/docs/ai/movement/dynamic/arrive.js

@@ -0,0 +1,88 @@
+import arrive, {
+  DEFAULT_SLOW_RADIUS,
+  DEFAULT_TARGET_RADIUS,
+  DEFAULT_TIME_TO_TARGET,
+} from "@inglorious/engine/ai/movement/dynamic/arrive.js"
+import { clampToBounds } from "@inglorious/game/bounds.js"
+import { enableCharacter } from "@inglorious/game/decorators/character.js"
+import { enableMouse } from "@inglorious/game/decorators/input/mouse.js"
+import { merge } from "@inglorious/utils/data-structures/objects.js"
+
+export default {
+  types: {
+    mouse: [enableMouse()],
+
+    character: [
+      enableCharacter(),
+      {
+        "game:update"(instance, event, { dt, instances }) {
+          const target = instances.mouse
+          const { fields } = instances.parameters.groups.arrive
+
+          merge(
+            instance,
+            arrive(instance, target, {
+              dt,
+              targetRadius: fields.targetRadius.value,
+              slowRadius: fields.slowRadius.value,
+              timeToTarget: fields.timeToTarget.value,
+            }),
+          )
+
+          clampToBounds(instance, instances.game.bounds)
+        },
+      },
+    ],
+
+    form: {
+      "field:change"(instance, event) {
+        const { id, value } = event.payload
+        instance.groups.arrive.fields[id].value = value
+      },
+    },
+  },
+
+  instances: {
+    mouse: {
+      type: "mouse",
+      position: [400, 0, 300],
+    },
+
+    character: {
+      type: "character",
+      maxAcceleration: 1000,
+      maxSpeed: 250,
+      position: [400, 0, 300],
+    },
+
+    parameters: {
+      type: "form",
+      position: [800 - 328, 0, 600],
+      groups: {
+        arrive: {
+          title: "Dynamic Arrive",
+          fields: {
+            targetRadius: {
+              label: "Target Radius",
+              inputType: "number",
+              step: 0.1,
+              defaultValue: DEFAULT_TARGET_RADIUS,
+            },
+            slowRadius: {
+              label: "Slow Radius",
+              inputType: "number",
+              step: 0.1,
+              defaultValue: DEFAULT_SLOW_RADIUS,
+            },
+            timeToTarget: {
+              label: "Time To Target",
+              inputType: "number",
+              step: 0.1,
+              defaultValue: DEFAULT_TIME_TO_TARGET,
+            },
+          },
+        },
+      },
+    },
+  },
+}

package/src/docs/ai/movement/dynamic/dynamic.mdx

@@ -0,0 +1,99 @@
+import { Canvas, Meta, Source } from '@storybook/blocks'
+import * as Dynamic from './dynamic.stories'
+
+import arrive from './arrive?raw'
+import flee from './flee?raw'
+import pursue from './pursue?raw'
+import evade from './evade?raw'
+import seek from './seek?raw'
+import wander from './wander?raw'
+import lookWhereYoureGoing from './look-where-youre-going?raw'
+import face from './face?raw'
+import align from './align?raw'
+import matchVelocity from './match-velocity?raw'
+
+<Meta of={Dynamic} />
+
+# Dynamic Movement
+
+The algorithms described here make an NPC instance move by applying forces, which in turn affect its acceleration and velocity. The movement is much smoother and more realistic than its [kinematic](/docs/ai-movement-kinematic--docs) counterpart.
+
+Every algorithm returns a steering object, which contains a linear and an angular acceleration. These can be used to update the instance's velocity and orientation.
+
+Most examples here make use of user [input](/?path=/docs/games-input--docs), so check those out if you haven't already.
+
+## Seek
+
+The seek algorithm makes the instance chase a target. The movement is much smoother than its kinematic counterpart.
+
+<Source dark code={seek} />
+
+<Canvas of={Dynamic.Seek} />
+
+## Flee
+
+The flee algorithm is the exact opposite of seek: the instance will run away from the target.
+
+<Source dark code={flee} />
+
+<Canvas of={Dynamic.Flee} />
+
+## Arrive
+
+The arrive algorithm is a more refined version of seek: the instance will slow down as it approaches the target, and the movement is much smoother.
+
+<Source dark code={arrive} />
+
+<Canvas of={Dynamic.Arrive} />
+
+## Pursue
+
+The pursue algorithm is an enhanced version of seek. It predicts the future position of a moving target and seeks that position.
+
+<Source dark code={pursue} />
+
+<Canvas of={Dynamic.Pursue} />
+
+## Evade
+
+Evade is the opposite of pursue. It predicts the future position of a moving target and flees from it.
+
+<Source dark code={evade} />
+
+<Canvas of={Dynamic.Evade} />
+
+## Wander
+
+The wander algorithm makes the instance move around randomly, but in a smooth and realistic way.
+
+<Source dark code={wander} />
+
+<Canvas of={Dynamic.Wander} />
+
+## Look Where You're Going
+
+A simple but effective algorithm that aligns the character's orientation with its direction of movement.
+
+<Source dark code={lookWhereYoureGoing} />
+
+<Canvas of={Dynamic.LookWhereYoureGoing} />
+
+## Align and Face
+
+The `align` algorithm makes the instance rotate to match the target's orientation, while `face` makes it rotate to look at the target's position. They are smoother versions of their kinematic counterparts.
+
+<Source dark code={align} />
+
+<Canvas of={Dynamic.Align} />
+
+<Source dark code={face} />
+
+<Canvas of={Dynamic.Face} />
+
+## Match Velocity
+
+This algorithm adjusts the instance's velocity to match the target's velocity. It's a key component for flocking behaviors.
+
+<Source dark code={matchVelocity} />
+
+<Canvas of={Dynamic.MatchVelocity} />

package/src/docs/ai/movement/dynamic/dynamic.stories.js

@@ -0,0 +1,58 @@
+import UiChooser from "@inglorious/docs/ui-chooser.jsx"
+
+import align from "./align.js"
+import arrive from "./arrive.js"
+import evade from "./evade.js"
+import face from "./face.js"
+import flee from "./flee.js"
+import lookWhereYoureGoing from "./look-where-youre-going.js"
+import matchVelocity from "./match-velocity.js"
+import pursue from "./pursue.js"
+import seek from "./seek.js"
+import wander from "./wander.js"
+
+export default {
+  title: "Engine/AI/Movement/Dynamic",
+  component: UiChooser,
+}
+
+export const Seek = {
+  args: { config: seek },
+}
+
+export const Flee = {
+  args: { config: flee },
+}
+
+export const Arrive = {
+  args: { config: arrive },
+}
+
+export const Pursue = {
+  args: { config: pursue },
+}
+
+export const Evade = {
+  args: { config: evade },
+}
+
+export const Wander = {
+  args: { config: wander },
+}
+
+export const LookWhereYoureGoing = {
+  name: "Look Where You're Going",
+  args: { config: lookWhereYoureGoing },
+}
+
+export const Align = {
+  args: { config: align },
+}
+
+export const Face = {
+  args: { config: face },
+}
+
+export const MatchVelocity = {
+  args: { config: matchVelocity },
+}

package/src/docs/ai/movement/dynamic/evade.js

@@ -0,0 +1,72 @@
+import evade, {
+  DEFAULT_MAX_PREDICTION,
+} from "@inglorious/engine/ai/movement/dynamic/evade.js"
+import { clampToBounds } from "@inglorious/game/bounds.js"
+import { enableCharacter } from "@inglorious/game/decorators/character.js"
+import { enableMouse } from "@inglorious/game/decorators/input/mouse.js"
+import { merge } from "@inglorious/utils/data-structures/objects.js"
+
+export default {
+  types: {
+    mouse: [enableMouse()],
+
+    character: [
+      enableCharacter(),
+      {
+        "game:update"(instance, event, { dt, instances }) {
+          const target = instances.mouse
+          const { fields } = instances.parameters.groups.evade
+
+          merge(
+            instance,
+            evade(instance, target, {
+              dt,
+              maxPrediction: fields.maxPrediction.value,
+            }),
+          )
+
+          clampToBounds(instance, instances.game.bounds)
+        },
+      },
+    ],
+
+    form: {
+      "field:change"(instance, event) {
+        const { id, value } = event.payload
+        instance.groups.evade.fields[id].value = value
+      },
+    },
+  },
+
+  instances: {
+    mouse: {
+      type: "mouse",
+      position: [400, 0, 300],
+      velocity: [0, 0, 0],
+    },
+
+    character: {
+      type: "character",
+      maxAcceleration: 1000,
+      maxSpeed: 250,
+      position: [400, 0, 300],
+    },
+
+    parameters: {
+      type: "form",
+      position: [800 - 343, 0, 600],
+      groups: {
+        evade: {
+          title: "Evade",
+          fields: {
+            maxPrediction: {
+              label: "Max Prediction",
+              inputType: "number",
+              defaultValue: DEFAULT_MAX_PREDICTION,
+            },
+          },
+        },
+      },
+    },
+  },
+}

package/src/docs/ai/movement/dynamic/face.js

@@ -0,0 +1,90 @@
+import {
+  DEFAULT_SLOW_RADIUS,
+  DEFAULT_TARGET_RADIUS,
+  DEFAULT_TIME_TO_TARGET,
+} from "@inglorious/engine/ai/movement/dynamic/align.js"
+import face from "@inglorious/engine/ai/movement/dynamic/face.js"
+import { clampToBounds } from "@inglorious/game/bounds.js"
+import { enableCharacter } from "@inglorious/game/decorators/character.js"
+import { enableMouse } from "@inglorious/game/decorators/input/mouse.js"
+import { merge } from "@inglorious/utils/data-structures/objects.js"
+import { pi } from "@inglorious/utils/math/trigonometry.js"
+
+export default {
+  types: {
+    mouse: [enableMouse()],
+
+    character: [
+      enableCharacter(),
+      {
+        "game:update"(instance, event, { dt, instances }) {
+          const target = instances.mouse
+          const { fields } = instances.parameters.groups.face
+
+          merge(
+            instance,
+            face(instance, target, {
+              dt,
+              targetRadius: fields.targetRadius.value,
+              slowRadius: fields.slowRadius.value,
+              timeToTarget: fields.timeToTarget.value,
+            }),
+          )
+
+          clampToBounds(instance, instances.game.bounds)
+        },
+      },
+    ],
+
+    form: {
+      "field:change"(instance, event) {
+        const { id, value } = event.payload
+        instance.groups.face.fields[id].value = value
+      },
+    },
+  },
+
+  instances: {
+    mouse: {
+      type: "mouse",
+      position: [400, 0, 300],
+    },
+
+    character: {
+      type: "character",
+      maxAngularSpeed: pi() / 4,
+      maxAngularAcceleration: 1000,
+      position: [400, 0, 300],
+    },
+
+    parameters: {
+      type: "form",
+      position: [800 - 328, 0, 600],
+      groups: {
+        face: {
+          title: "Face",
+          fields: {
+            targetRadius: {
+              label: "Target Radius",
+              inputType: "number",
+              step: 0.1,
+              defaultValue: DEFAULT_TARGET_RADIUS,
+            },
+            slowRadius: {
+              label: "Slow Radius",
+              inputType: "number",
+              step: 0.1,
+              defaultValue: DEFAULT_SLOW_RADIUS,
+            },
+            timeToTarget: {
+              label: "Time To Target",
+              inputType: "number",
+              step: 0.1,
+              defaultValue: DEFAULT_TIME_TO_TARGET,
+            },
+          },
+        },
+      },
+    },
+  },
+}