bitecs

👾 bitECS 👾

Functional, minimal, data-oriented, ultra-high performance ECS library written using JavaScript TypedArrays.

Features

🔮 Simple, declarative API	🔥 Blazing fast iteration
🔍 Powerful & performant queries	💾 Swift serialization
🍃 Zero dependencies	🌐 Node or browser
🤏 ~5kb gzipped	🚀 Unparalleled performance benchmarks

Benchmarks

noctjs/ecs-benchmark	ddmills/js-ecs-benchmarks

In Development

🧵 Multithreading

Install

npm i bitecs

Overview

This is the entire API:

import {

  createWorld,
  addEntity,
  removeEntity,

  defineComponent,
  addComponent,
  removeComponent,
  hasComponent,
  
  defineQuery,
  Changed,
  Not,
  enterQuery,
  exitQuery,
  
  defineSystem,
  
  defineSerializer,
  defineDeserializer,

  pipe,

} from 'bitecs'

World

A world represents a set of entities and the components that they each possess.

Worlds do not store actual component data, only the relationships with entities (archetypes).

Any number of worlds can be created. An empty object is returned which you can use as a context.

const world = createWorld()

world.name = 'MyWorld'

Entity

An entity is an integer, technically a pointer, which components can be associated with. Entities are accessed via queries, components of whom are mutated with systems.

Add entities to the world:

const eid = addEntity(world)
const eid2 = addEntity(world)

Remove entities from the world:

removeEntity(world, eid2)

Component

Components are pure data and added to entities to give them state.

The object returned from defineComponent is a SoA (Structure of Arrays). This is what actually stores the component data.

Define component stores:

const Vector3 = { x: Types.f32, y: Types.f32, z: Types.f32 }
const Position = defineComponent(Vector3)
const Velocity = defineComponent(Vector3)

Add components to an entity in a world:

addComponent(world, Position, eid)
addComponent(world, Velocity, eid)

Component data accessed directly via eid, there are no getters or setters:

• This is how high performance iteration is achieved

Velocity.x[eid] = 1
Velocity.y[eid] = 1

Query

A query is defined with components and is used to obtain a specific set of entities from a world.

Define a query:

const movementQuery = defineQuery([Position, Velocity])

Use the query on a world to obtain an array of entities with those components:

const ents = movementQuery(world)

Wrapping a component with the Not modifier defines a query which returns entities who explicitly do not have the component:

const positionWithoutVelocityQuery = defineQuery([ Position, Not(Velocity) ])

Wrapping a component with the Change modifier creates a query which returns entities whose component's state has changed since last call of the function:

const changedPositionQuery = defineQuery([ Changed(Position) ])

let ents = changedPositionQuery(world)
console.log(ents) // => []

Position.x[eid]++

ents = changedPositionQuery(world)
console.log(ents) // => [0]

The enter-query hook is called when an entity's components match the query:

enterQuery(world, movementQuery, eid => {})

The exit-query hook is called when an entity's components no longer match the query:

exitQuery(world, movementQuery, eid => {})

System

Systems are functions and are run against a world to update componenet state of entities, or anything else.

Queries are used inside of systems to obtain a relevant set of entities and perform operations on their component data.

While not required, it is greatly encouraged that you keep all component data mutations inside of systems, and all system-dependent state on the world.

Define a system that moves entity positions based on their velocity:

const movementSystem = defineSystem(world => {
  const ents = movementQuery(world)
  for (let i = 0; i < ents.length; i++) {
    const eid = ents[i];
    Position.x[eid] += Velocity.x[eid]
    Position.y[eid] += Velocity.y[eid]
  }
})

Define a system which tracks time:

world.time = { 
  delta: 0, 
  elapsed: 0,
  then: performance.now()
}
const timeSystem = defineSystem(world => {
  const now = performance.now()
  const delta = now - world.time.then
  world.time.delta = delta
  world.time.elapsed += delta
  world.time.then = now
})

Systems are used to update entities of a world:

movementSystem(world)

Pipelines of systems should be created with the pipe function:

const pipeline = pipe(
  movementSystem,
  timeSystem
)

pipeline(world)

Serialization

Performant and highly customizable serialization is built-in. Any subset of data can be targeted and serialized/deserialized with great efficiency and ease.

Serializers and deserializers need the same configs in order to work properly. Any combination of components and component properties may be used as configs.

Serialization can take a whole world as a config and will serialize all component stores in that world:

const serialize = createSerializer(world)
const deserialize = createDeserializer(world)

Serialize all of the world's entities and thier component data:

const packet = serialize(world)

Use the deserializer to apply state onto the same or any other world:

• Note: serialized entities and components are automatically (re)created if they do not exist in the target world

deserialize(world, packet)

Serialize a more specific set of entities using queries:

const ents = movementQuery(world)
const packet = serialize(ents)
deserialize(world, packet)

Serialization for any mixture of components and component properties:

const serializePositions = createSerializer([Position, Velocity.x])
const deserializePositions = createDeserializer([Position, Velocity.x])

Serialize Position data for entities matching the movementQuery, defined with pipe:

const serializeMovementQueryPositions = pipe(movementQuery, serializePositions)
const packet = serializeMovementQueryPositions(world)
deserializePositions(world, packet)

Serialization which targets select component stores of entities whose component state has changed since the last call of the function:

const serializeOnlyChangedPositions = createSerializer([Changed(Position)])

const serializeChangedMovementQuery = pipe(movementQuery, serializeOnlyChangedPositions)
let packet = serializeChangedMovementQuery(world)
console.log(packet) // => undefined

Position.x[eid]++

packet = serializeChangedMovementQuery(world)
console.log(packet.byteLength) // => 13