WolfECS

The fastest Entity Component System library for the web.

NOTE: this shouldn't be used for games or applications, it exists solely to demonstrate the upper bound on speed in benchmarks

Features

• Written in Typescript for full, up to date type support.
• Zero dependencies.
• Advanced query operators.
• It's by far the fastest web ECS library that I know of. Benchmarks here and here.

Installation

Installing locally

npm i wolf-ecs

Alternatively, download the latest release here on GitHub.

Using a CDN

JSDelivr:

import { ECS, all, any, not, types } from "https://esm.run/wolf-ecs/wolf-ecs.js"

More on ECS

Entity–component–system (ECS) is an architectural pattern that is mostly used in game development. ECS follows the composition over inheritance principle that allows greater flexibility in defining entities where every object in a game's scene is an entity (e.g. enemies, bullets, vehicles, etc.). Every entity consists of one or more components which contains data or state.

- Wikipedia

This article is a good overview of what ECS is and why it is used.

Usage

First create an ECS instance:

const ecs = new ECS()

The ECS constructor takes two arguments:

• max: number = 1e4 which is the hard limit for the number of entities at a single time.
• defer: boolean = false which sets the value of ecs.DEFAULT_DEFER, which I'll get to later.

Use ecs.bind() to bind the value of this to the methods which allows omission of the ecs. prefix.

const ecs = new ECS()
const {
  defineComponent,
  createQuery,
  createEntity,
  etc.
} = ecs.bind()

Define components

Components are defined using ecs.defineComponent:

const myComponent = ecs.defineComponent(types.u8)
const position = ecs.defineComponent({
  x: types.f64,
  y: types.f64,
})

The object passed defines the shape of the component. Types are declared using the types constant.

Types available include all numeric types supported by TypedArrays:

types.
int8		i8	char
uint8		u8	uchar
int16		i16	short
uint16		u16	ushort
int32		i32	int
uint32		u32	uint
float32		f32	float
float64		f64	double
int64	bigint64	i64	long
uint64	biguint64	u64	ulong

For more flexibility, there is also the any type. custom is a TypeScript alternative to any which allows for - you guessed it - custom types.

const custom = ecs.defineComponent(types.custom<MyTypescriptType>())

Call ecs.defineComponent with no arguments to create a tag component, which is usually used as a flag for systems.

const tag = ecs.defineComponent()

Entities

An entity is simply a unique integer ID.

Create entities using ecs.createEntity:

const id = ecs.createEntity() // The entity ID is returned
doStuff(id)

Modify components

To modify the values of components, access the component array using the entity ID like so:

const position = ecs.defineComponent({
  x: types.f64,
  y: types.f64,
})
position.x[id]
position.y[id]

Add components using ecs.addComponent and remove them using ecs.removeComponent:

ecs.addComponent(id, component)
ecs.removeComponent(id, component)

The values of a component which has just been added are not defined, so it's a good idea to wrap the addition of a component in a custom function.

The third argument defaults to ecs.DEFAULT_DEFER. If set to true, defers the operation until the next ecs.updatePending call.

ecs.addComponent(id, component, true)
ecs.removeComponent(id, component, true)

doStuff()

ecs.updatePending() // Executes all pending add/remove calls

This is useful for avoiding double counting entities in queries, but is slower.

Queries

To define a query, use ecs.createQuery:

// Matches entities which have both component1 and component2
const query = ecs.createQuery(component1, component2)

There are helper functions for defining more complex queries: all, any and not.

const complexQuery = ecs.createQuery(A, B, any(C, D, E), any(F, not(C), all(G, H, I)))

Systems

A system is a function which can be called. This involves iterating over the entities matched by a query.

Using the builtin query.forEach function is the more convenient way:

function system() {
  query.forEach(id => {
    doStuff(id)
  })
}

However, this method has can sometimes have performance impacts due to whims of the JS engine.

The more performant method of iterating queries is using a manual for loop:

function system() {
  for(let i = 0; i < query.a.length; i++) {
    const arch = query.a[i].e
    for(let j = arch.length - 1; j >= 0; j--) { // Backward iteration helps prevent double counting entities
      const id = arch[j]
      doStuff(id)
    }
  }
}

Contributing

Small pull requests are welcome. For major changes, please open an issue first to discuss the changes you'd like to make.