arancini
An object-based entity component system for JavaScript.
> npm i arancini
- 👾 Manage game or simulation entities with the Entity Component System pattern
- 🛹 Strikes a balance between ease of use and performance
- 🍱 Entities are regular objects, components are properties on objects
- 🧩 Framework agnostic, plug arancini into anything
- 💙 TypeScript friendly
- ⚛️ Easy integration with React
Introduction
Arancini is an implementation of the Entity Component System pattern for JavaScript. An Entity Component System is a data-oriented approach for structuring applications.
Arancini has a few key features/differentiators:
- Entities are regular objects, and components are properties on objects.
- Queries update reactively as components are added and removed from entities.
- The core library has no concept of "Systems", it's easy to plug arancini into your existing gameloop.
- Strong TypeScript support for queries
- A silly name that doesn't contain "ecs"
To learn more about the different types of Entity Component Systems, see: https://github.com/SanderMertens/ecs-faq
Overview
🌎 Creating a World
A world is a container for entities. It provides methods for managing entities, and methods for querying entities based on their components.
import { World } from "arancini";
type Entity = {
position?: { x: number; y: number };
health?: number;
velocity?: { x: number; y: number };
inventory?: { items: string[] };
};
const world = new World<Entity>();
🍱 Creating Entities
You can use world.create
to create an entity from any object.
const playerEntity = { position: { x: 0, y: 0 } };
world.create(playerEntity);
📦 Adding and Removing Components
To add and remove components from an entity, you can use world.add
, world.remove
.
world.add(playerEntity, "health", 100);
world.remove(playerEntity, "health");
You can also use world.update
to add and remove multiple components at once.
world.update(playerEntity, {
velocity: { x: 1, y: 0 },
poisioned: undefined,
});
world.update(playerEntity, (e) => {
e.velocity = { x: 1, y: 0 };
delete e.poisioned;
});
Warning: Avoid adding/removing properties without using world.add
, world.remove
, or world.update
. These methods ensure that queries are updated correctly.
🔎 Querying Entities
You can query entities based on their components with world.query
. Queries are reactive, they will update as components are added and removed from components.
const monsters = world.query((e) => e.all("health", "position", "velocity"));
Note: Arancini dedupes queries with the same conditions, so you can create multiple of the same query without performance penalty!
🧠 Iterating over Query results
You can use a for...of
loop to iterate over queries in reverse order. This prevents problems that can occur when removing entities from queries within a loop.
const moving = world.query((e) => e.all("position", "velocity"));
const alive = world.query((e) => e.all("health"));
const movementSystem = () => {
for (const entity of moving) {
const position = entity.position;
const velocity = entity.velocity;
position.x += velocity.x;
position.y += velocity.y;
}
};
const healthSystem = () => {
for (const entity of alive) {
if (entity.health <= 0) {
world.destroy(entity);
}
}
};
You can also use query.entities
directly.
const moving = world.query((e) => e.all("position", "velocity"));
console.log(moving.entities);
⍰ Query Conditions
Query functions support all
, any
, and none
conditions. The query builder also has some no-op grammar and aliases to make queries easier to read.
const monsters = world.query((e) =>
e.all("health", "position").any("skeleton", "zombie").none("dead"),
);
const monsters = world.query((entities) =>
entities
.with("health", "position")
.and.any("skeleton", "zombie")
.but.not("dead"),
);
🗑 Destroying Entities
world.destroy
removes an entity from the world and from all queries.
world.destroy(playerEntity);
Destroying an entity doesn't remove any properties from the entity object.
📡 Query Events
Queries emit events when entities are added or removed.
const query = world.query((e) => e.has("position"));
query.onEntityAdded.add((entity) => {
console.log("added!", entity);
});
query.onEntityRemoved.add((entity) => {
console.log("removed!", entity);
});
🔦 Ad-hoc Queries
You can use world.filter
and world.find
to get ad-hoc query results.
const monsters = world.filter((e) => e.has("health", "position", "velocity"));
const player = world.find((e) => e.has("player"));
This is useful for cases where you want to get results infrequently, without the cost of evaluating a reactive query as the world changes.
If there is an existing query with the same conditions, the query results will be reused.
🧠 Systems
The core library (@arancini/core
) does not have a built-in concept of systems.
A "System" can be anything that operates on the world. You can write simple functions and call them however you like, e.g. inside setInterval, requestAnimationFrame, or in your existing game loop.
If you're not sure where to start, some optional utilities for organising logic are provided in the arancini/systems
package.
See the @arancini/systems README for more information.
Packages
You can install all of arancini with the umbrella arancini
package, or you can install individual packages under the @arancini/*
scope.
Note: In order to use entrypoints with typescript, you must use a moduleResolution
option that supports entrypoints, for example bundler
or NodeNext
.
Note: Bundles are ECMAScript modules, there are no CommonJS bundles right now.
The umbrella package for arancini
.
> npm install arancini
import { World } from "arancini";
import { Executor, System } from "arancini/systems";
import { createReactAPI } from "arancini/react";
The core library!
> npm install @arancini/core
import { World } from "@arancini/core";
Systems for arancini.
> npm install @arancini/systems
import { Executor, System } from "@arancini/systems";
See the @arancini/systems README for docs.
React glue for arancini.
See the @arancini/react README for docs.
> npm install @arancini/react
import { createReactAPI } from "@arancini/react";
Eventing utilities.
> npm install @arancini/events
import { Topic } from "@arancini/events";
const inventoryEvents = new Topic<[item: string, quantity: number]>();
const unsubscribe = topic.inventoryEvents((item, quantity) => {
console.log(item, quantity);
});
inventoryEvents.emit("apple", 1);
inventoryEvents.clear();