bitECS Documentation

bitECS is a minimal, data-oriented Entity Component System (ECS) library for TypeScript. It supports both Structure of Arrays (SoA) and Array of Structures (AoS) patterns for component storage, making it highly flexible for different performance and modeling needs.

Key features include:

• Simple, declarative API
• Lightweight (~5kb minzipped)
• Powerful querying
• Relational entity modeling
• Thread-friendly (suitable for multithreading)
• Built-in serialization

import {
  createWorld,
  query,
  addEntity,
  removeEntity,
  addComponent,
} from 'bitecs'

// 1. Define components (SoA or AoS)
const Health = [] as number[]

const world = createWorld({
  components: {
    // SoA: Structure of Arrays
    Position: { x: [], y: [] },
    Velocity: { x: new Float32Array(1e5), y: new Float32Array(1e5) },
    // AoS: Array of Structures
    Player: [] as { level: number; experience: number; name: string }[]
  },
  time: {
    delta: 0, 
    elapsed: 0, 
    then: performance.now()
  }
})

const { Position, Velocity, Player } = world.components

// 2. Create and configure an entity
const eid = addEntity(world)
addComponent(world, eid, Position)
addComponent(world, eid, Velocity)
addComponent(world, eid, Player)
addComponent(world, eid, Health)

// 3. Access data
Position.x[eid] = 0
Player[eid] = { level: 1, experience: 0, name: "Hero" }

// 4. Define and run systems using query()
const movementSystem = (world) => {
  const { Position, Velocity } = world.components
  for (const eid of query(world, [Position, Velocity])) {
    Position.x[eid] += Velocity.x[eid] * world.time.delta
    Position.y[eid] += Velocity.y[eid] * world.time.delta
  }
}

const update = (world) => {
  movementSystem(world)
  // ... other systems
}

// 5. Run the loop
requestAnimationFrame(function animate() {
  update(world)
  requestAnimationFrame(animate)
})

To prevent issues with recycled IDs (where an old system might accidentally reference a new entity that reused an old ID), you can enable versioning via createEntityIndex(withVersioning(bits)).

Each ID carries a version number that increments upon recycling. This allows you to distinguish between different lifetimes of the same ID.

Configuration:

• Pass withVersioning(n) where n is the number of bits.
• Default is 12 bits (4096 recycles).
• 8 bits: 16M entities / 256 recycles
• 10 bits: 4M entities / 1K recycles
• 12 bits: 1M entities / 4K recycles
• 14 bits: 262K entities / 16K recycles
• 16 bits: 65K entities / 65K recycles

⚠️ Caution with TypedArrays: Versioning changes the entity ID by large amounts. If using the eid as an index into a sparse TypedArray, ensure the array is large enough to prevent out-of-bounds access, as JavaScript does not throw on out-of-bounds index access.

const entityIndex = createEntityIndex(withVersioning(8))
const world = createWorld(entityIndex)

const eid1 = addEntityId(entityIndex)
const eid2 = addEntityId(entityIndex)
removeEntityId(entityIndex, eid1)
const eid3 = addEntityId(entityIndex)

assert(eid1 !== eid3) // With versioning, eid1 and eid3 will not be the same

Snapshot serialization captures the complete state of entities and components at a specific point in time. This is ideal for full state synchronization, save game systems, or debugging/replay functionality.

Unlike the Observer serializer, the Snapshot serializer does not track changes over time but rather takes a 'picture' of the current world state for the specified components.

import { createWorld, addEntity, addComponent, removeEntity, hasComponent } from 'bitecs'
import { createSnapshotSerializer, createSnapshotDeserializer, f32, u8 } from 'bitecs/serialization'

// Example using Snapshot serializer for full state capture
const world = createWorld()
const eid = addEntity(world)

// Define components with tagged SoA data storage
const Position = { x: f32([]), y: f32([]) }
const Health = u8([])

// Create serializers
const serialize = createSnapshotSerializer(world, [Position, Health])
const deserialize = createSnapshotDeserializer(world, [Position, Health])

// Set up initial state
addComponent(world, eid, Position)
Position.x[eid] = 10
Position.y[eid] = 20

addComponent(world, eid, Health)
Health[eid] = 100

// Serialize full state
const buffer = serialize()

// Clear world state
removeEntity(world, eid)
Position.x[eid] = 0
Position.y[eid] = 0
Health[eid] = 0

// Deserialize state back
deserialize(buffer)

// Verify state was restored
console.assert(hasComponent(world, eid, Position))
console.assert(hasComponent(world, eid, Health))
console.assert(Position.x[eid] === 10)
console.assert(Position.y[eid] === 20)
console.assert(Health[eid] === 100)

The enterQuery and exitQuery functions from 0.3.x are replaced by a pattern using Observers and Queues attached to the world object.

1. Create arrays on your world object to act as queues (e.g., world.enteredMovers = []).
2. Use observe with onAdd and onRemove to push entity IDs into these queues.
3. In your systems, consume the queues using .splice(0) to retrieve and clear the accumulated entities.

// 1. Setup queues on the world
world.enteredMovers = []
world.exitedMovers = []

// 2. Set up observers once
observe(world, onAdd(Position, Velocity), (eid) => world.enteredMovers.push(eid))
observe(world, onRemove(Position, Velocity), (eid) => world.exitedMovers.push(eid))

// 3. In your system, consume and clear the queues
const entered = world.enteredMovers.splice(0)
const exited = world.exitedMovers.splice(0)

for (const eid of entered) {
  console.log(`Entity ${eid} started moving`)
}

The Observer serializer tracks the addition and removal of entities and components. It is designed to work in tandem with an SoA (Structure of Arrays) serializer for efficient network synchronization: the Observer serializer handles the presence/absence of entities and components, while the SoA serializer handles the actual component data.

To use it, you must provide a networkTag component. Only entities possessing this tag will be tracked and included in the serialization process. The components array specifies which components' additions and removals should be monitored.

import { addComponent, removeComponent, hasComponent, addEntity, createWorld } from 'bitecs'
import { createObserverSerializer, createObserverDeserializer } from 'bitecs/serialization'

const world = createWorld()
const eid = addEntity(world)

const Position = { x: [] as number[], y: [] as number[] }
const Health = [] as number[]
const Networked = {}

// Create serializers
const serializer = createObserverSerializer(world, Networked, [Position, Health])
const deserializer = createObserverDeserializer(world, Networked, [Position, Health])

// Add some components
addComponent(world, eid, Networked)
addComponent(world, eid, Position)
addComponent(world, eid, Health)

// Serialize changes
const buffer = serializer()

// Reset the state
removeComponent(world, eid, Position)
removeComponent(world, eid, Health)

// Deserialize changes back
deserializer(buffer)

// Verify components were restored
console.assert(hasComponent(world, eid, Position))
console.assert(hasComponent(world, eid, Health))