Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/isaac-mason/arancini
An object based Entity Component System
https://github.com/isaac-mason/arancini
ecs entity-component-system game-dev game-development typescript
Last synced: 14 days ago
JSON representation
An object based Entity Component System
- Host: GitHub
- URL: https://github.com/isaac-mason/arancini
- Owner: isaac-mason
- License: mit
- Created: 2022-07-04T08:12:07.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-15T14:58:34.000Z (29 days ago)
- Last Synced: 2024-10-16T23:31:00.666Z (27 days ago)
- Topics: ecs, entity-component-system, game-dev, game-development, typescript
- Language: TypeScript
- Homepage: https://arancini.isaacmason.com
- Size: 5.87 MB
- Stars: 72
- Watchers: 1
- Forks: 1
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/arancini)
[](https://www.npmjs.com/package/arancini)
[](https://bundlephobia.com/result?p=arancini)
# 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](https://github.com/isaac-mason/arancini/tree/main/packages/arancini-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.
```ts
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();
```
### 🍱 Creating Entities
You can use `world.create` to create an entity from any object.
```ts
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`.
```ts
/* 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.
```ts
/* 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.
```ts
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.
```ts
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.
```ts
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.
```ts
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.
```ts
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.
```ts
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.
```ts
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**](https://github.com/isaac-mason/arancini/tree/main/packages/arancini-systems) 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`**](https://github.com/isaac-mason/arancini/tree/main/packages/arancini)
[](https://www.npmjs.com/package/arancini)
The umbrella package for `arancini`.
```bash
> npm install arancini
```
```ts
import { World } from "arancini";
import { Executor, System } from "arancini/systems";
import { createReactAPI } from "arancini/react";
```
### [**`@arancini/core`**](https://github.com/isaac-mason/arancini/tree/main/packages/arancini-core)
[](https://www.npmjs.com/package/@arancini/core)
The core library!
```bash
> npm install @arancini/core
```
```ts
import { World } from "@arancini/core";
```
### [**`@arancini/systems`**](https://github.com/isaac-mason/arancini/tree/main/packages/arancini-systems)
[](https://www.npmjs.com/package/@arancini/systems)
Systems for arancini.
```bash
> npm install @arancini/systems
```
```ts
import { Executor, System } from "@arancini/systems";
```
See the [**@arancini/systems README**](https://github.com/isaac-mason/arancini/tree/main/packages/arancini-systems) for docs.
### [**`@arancini/react`**](https://github.com/isaac-mason/arancini/tree/main/packages/arancini-react)
[](https://www.npmjs.com/package/@arancini/react)
React glue for arancini.
See the [**@arancini/react README**](https://github.com/isaac-mason/arancini/tree/main/packages/arancini-react) for docs.
```bash
> npm install @arancini/react
```
```ts
import { createReactAPI } from "@arancini/react";
```
### [**`@arancini/events`**](https://github.com/isaac-mason/arancini/tree/main/packages/arancini-events)
[](https://www.npmjs.com/package/@arancini/events)
Eventing utilities.
```bash
> npm install @arancini/events
```
```ts
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();
```