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";

// (optional) define a type for entities in the world
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.

/* add a component */
world.add(playerEntity, "health", 100);

/* remove a component */
world.remove(playerEntity, "health");

You can also use world.update to add and remove multiple components at once.

/* add and remove multiple components with a partial entity */
world.update(playerEntity, {
  // add a component
  velocity: { x: 1, y: 0 },
  // remove a component
  poisioned: undefined,
});

/* add and remove multiple components with an update callback */
world.update(playerEntity, (e) => {
  // add a component
  e.velocity = { x: 1, y: 0 };

  // remove a component
  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.

arancini

The umbrella package for arancini.

> npm install arancini

import { World } from "arancini";
import { Executor, System } from "arancini/systems";
import { createReactAPI } from "arancini/react";

@arancini/core

The core library!

> npm install @arancini/core

import { World } from "@arancini/core";

@arancini/systems

Systems for arancini.

> npm install @arancini/systems

import { Executor, System } from "@arancini/systems";

See the @arancini/systems README for docs.

@arancini/react

React glue for arancini.

See the @arancini/react README for docs.

> npm install @arancini/react

import { createReactAPI } from "@arancini/react";

@arancini/events

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();