Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

arancini

Package Overview
Dependencies
Maintainers
1
Versions
45
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

arancini

An object based Entity Component System

  • 6.6.1
  • latest
  • npm
  • Socket score

Version published
Weekly downloads
10
increased by42.86%
Maintainers
1
Weekly downloads
 
Created
Source

cover

Version GitHub Workflow Status (with event) Downloads Bundle Size

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

Version

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

Version

The core library!

> npm install @arancini/core
import { World } from "@arancini/core";

@arancini/systems

Version

Systems for arancini.

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

See the @arancini/systems README for docs.

@arancini/react

Version

React glue for arancini.

See the @arancini/react README for docs.

> npm install @arancini/react
import { createReactAPI } from "@arancini/react";

@arancini/events

Version

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

Keywords

FAQs

Package last updated on 01 May 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc