API Reference

Complete reference for all bitECS 0.4 functions.

World

createWorld

createWorld(context?, entityIndex?) → World

Creates a new world. Optionally accepts a context object and/or shared entity index.

Parameters

  • context object? - Custom context object to attach to the world
  • entityIndex EntityIndex? - Shared entity index for multiple worlds

Returns

World - The created world object

resetWorld

resetWorld(world) → World

Resets a world to its initial state, removing all entities and components.

Parameters

  • world World - The world to reset

Returns

World - The reset world

deleteWorld

deleteWorld(world) → void

Deletes a world and cleans up its internal data.

Parameters

  • world World - The world to delete

getWorldComponents

getWorldComponents(world) → ComponentRef[]

Returns all components registered to a world.

Parameters

  • world World - The world object

Returns

ComponentRef[] - Array of registered components

getAllEntities

getAllEntities(world) → number[]

Returns all existing entities in a world.

Parameters

  • world World - The world object

Returns

number[] - Array of entity IDs

Entity

addEntity

addEntity(world) → number

Adds a new entity to the world.

Parameters

  • world World - The world object

Returns

number - The new entity ID

removeEntity

removeEntity(world, eid) → void

Removes an entity from the world.

Parameters

  • world World - The world object
  • eid number - Entity ID to remove

entityExists

entityExists(world, eid) → boolean

Checks if an entity exists in the world.

Parameters

  • world World - The world object
  • eid number - Entity ID to check

Returns

boolean - True if entity exists

getEntityComponents

getEntityComponents(world, eid) → ComponentRef[]

Returns all components an entity has.

Parameters

  • world World - The world object
  • eid number - Entity ID

Returns

ComponentRef[] - Array of components

addPrefab

addPrefab(world) → number

Creates a new prefab entity. Prefabs are excluded from normal queries.

Parameters

  • world World - The world object

Returns

number - The prefab entity ID

createEntityIndex

createEntityIndex(options?) → EntityIndex

Creates a standalone entity index for sharing across worlds.

Parameters

  • options object? - Configuration from withVersioning()

Returns

EntityIndex - The entity index

withVersioning

withVersioning(versionBits?) → object

Creates configuration for entity ID recycling with versioning.

Parameters

  • versionBits number? - Bits for version (default: 8)

Returns

object - Configuration object

Component

registerComponent

registerComponent(world, component) → ComponentData

Explicitly registers a component with a world.

Parameters

  • world World - The world object
  • component ComponentRef - Component to register

Returns

ComponentData - Registered component data

registerComponents

registerComponents(world, components) → void

Registers multiple components at once.

Parameters

  • world World - The world object
  • components ComponentRef[] - Components to register

addComponent

addComponent(world, eid, component) → boolean

Adds a component to an entity.

Parameters

  • world World - The world object
  • eid number - Entity ID
  • component ComponentRef | ComponentSetter - Component or set(component, data)

Returns

boolean - True if added, false if already existed

addComponents

addComponents(world, eid, ...components) → void

Adds multiple components to an entity.

Parameters

  • world World - The world object
  • eid number - Entity ID
  • components ...ComponentRef - Components to add

removeComponent

removeComponent(world, eid, ...components) → void

Removes one or more components from an entity.

Parameters

  • world World - The world object
  • eid number - Entity ID
  • components ...ComponentRef - Components to remove

hasComponent

hasComponent(world, eid, component) → boolean

Checks if an entity has a component.

Parameters

  • world World - The world object
  • eid number - Entity ID
  • component ComponentRef - Component to check

Returns

boolean - True if entity has component

getComponent

getComponent(world, eid, component) → any

Gets component data (triggers onGet observers).

Parameters

  • world World - The world object
  • eid number - Entity ID
  • component ComponentRef - Component to get

Returns

any - Component data or undefined

setComponent

setComponent(world, eid, component, data) → void

Sets component data (triggers onSet observers).

Parameters

  • world World - The world object
  • eid number - Entity ID
  • component ComponentRef - Component to set
  • data any - Data to set

set

set(component, data) → ComponentSetter

Helper to set component data when adding.

Parameters

  • component ComponentRef - The component
  • data any - Initial data

Returns

ComponentSetter - Object for use with addComponent

Query

query

query(world, terms, ...modifiers) → QueryResult

Queries entities matching component patterns.

Parameters

  • world World - The world object
  • terms QueryTerm[] - Components and operators
  • modifiers ...QueryModifier - asBuffer, isNested, etc.

Returns

QueryResult - Array of matching entity IDs

And / All

And(...components) → OpReturnType

Matches entities with ALL specified components (default behavior).

Parameters

  • components ...ComponentRef - Components to match

Returns

OpReturnType - Query operator

Or / Any

Or(...components) → OpReturnType

Matches entities with ANY of the specified components.

Parameters

  • components ...ComponentRef - Components to match

Returns

OpReturnType - Query operator

Not / None

Not(...components) → OpReturnType

Excludes entities with the specified components.

Parameters

  • components ...ComponentRef - Components to exclude

Returns

OpReturnType - Query operator

commitRemovals

commitRemovals(world) → void

Commits all pending entity removals for queries.

Parameters

  • world World - The world object

Query Modifiers

  • asBuffer - Return Uint32Array instead of number[]
  • isNested / noCommit - Skip committing removals (safe for nested queries)

Observer

observe

observe(world, hook, callback) → () => void

Subscribes to component changes.

Parameters

  • world World - The world object
  • hook ObservableHook - onAdd, onRemove, onSet, or onGet
  • callback function - Handler function

Returns

function - Unsubscribe function

onAdd

onAdd(...components) → ObservableHook

Triggers when entity gains all specified components.

Parameters

  • components ...ComponentRef - Components to observe

Returns

ObservableHook - Hook for observe()

onRemove

onRemove(...components) → ObservableHook

Triggers when entity loses any specified component.

Parameters

  • components ...ComponentRef - Components to observe

Returns

ObservableHook - Hook for observe()

onSet

onSet(component) → ObservableHook

Triggers when component data is set. Callback receives (eid, params).

Parameters

  • component ComponentRef - Component to observe

Returns

ObservableHook - Hook for observe()

onGet

onGet(component) → ObservableHook

Triggers when component data is retrieved. Callback returns data.

Parameters

  • component ComponentRef - Component to observe

Returns

ObservableHook - Hook for observe()

Relation

createRelation

createRelation(...modifiers) → Relation

Creates a new relation with optional modifiers.

Parameters

  • modifiers ...function - withStore, makeExclusive, etc.

Returns

Relation - The created relation

withStore

withStore(createStore) → (Relation) => Relation

Adds a data store to a relation.

Parameters

  • createStore () => T - Function returning store object

Returns

function - Relation modifier

makeExclusive

makeExclusive(relation) → Relation

Makes a relation exclusive (one target per subject).

Parameters

  • relation Relation - The relation to modify

Returns

Relation - Modified relation

withAutoRemoveSubject

withAutoRemoveSubject(relation) → Relation

Removes subject when target is removed.

Parameters

  • relation Relation - The relation to modify

Returns

Relation - Modified relation

withOnTargetRemoved

withOnTargetRemoved(callback) → (Relation) => Relation

Adds callback when a target is removed.

Parameters

  • callback (world, subject, target) => void - Handler

Returns

function - Relation modifier

getRelationTargets

getRelationTargets(world, eid, relation) → number[]

Gets all targets for an entity's relation.

Parameters

  • world World - The world object
  • eid number - Subject entity ID
  • relation Relation - The relation

Returns

number[] - Array of target entity IDs

Wildcard

Wildcard

Matches any target in relation queries.

IsA

IsA

Built-in relation for prefab inheritance.

Hierarchy

Hierarchy / Cascade

Hierarchy(relation, depth?) → HierarchyTerm

Creates hierarchy query term for topological ordering.

Parameters

  • relation ComponentRef - The relation (e.g., ChildOf)
  • depth number? - Optional depth limit

Returns

HierarchyTerm - Hierarchy term for queries

getHierarchyDepth

getHierarchyDepth(world, eid, relation) → number

Gets the hierarchy depth of an entity.

Parameters

  • world World - The world object
  • eid number - Entity ID
  • relation ComponentRef - The relation

Returns

number - Depth (0 = root)

getMaxHierarchyDepth

getMaxHierarchyDepth(world, relation) → number

Gets the maximum depth in a hierarchy.

Parameters

  • world World - The world object
  • relation ComponentRef - The relation

Returns

number - Maximum depth

Serialization

Import from bitecs/serialization

SoA Serialization

createSoASerializer

createSoASerializer(components, options?) → (eids) => ArrayBuffer

Creates a serializer for Structure of Arrays components.

Parameters

  • components ComponentRef[] - Components to serialize
  • options object? - diff, buffer, epsilon

Returns

function - Serializer function

createSoADeserializer

createSoADeserializer(components, options?) → (buffer, idMap?) => void

Creates a deserializer for SoA data.

Parameters

  • components ComponentRef[] - Components to deserialize
  • options object? - diff

Returns

function - Deserializer function

AoS Serialization

createAoSSerializer

createAoSSerializer(components, options?) → (eids) => ArrayBuffer

Creates a serializer for Array of Structures components.

Parameters

  • components ComponentRef[] - Components to serialize
  • options object? - diff, buffer, epsilon

Returns

function - Serializer function

createAoSDeserializer

createAoSDeserializer(components, options?) → (buffer, idMap?) => void

Creates a deserializer for AoS data.

Parameters

  • components ComponentRef[] - Components to deserialize
  • options object? - diff

Returns

function - Deserializer function

Observer Serialization

createObserverSerializer

createObserverSerializer(world, networkTag, components, options?) → () => ArrayBuffer

Creates a serializer that tracks entity/component additions and removals.

Parameters

  • world World - The world object
  • networkTag ComponentRef - Tag for networked entities
  • components ComponentRef[] - Components to track
  • options object? - buffer

Returns

function - Serializer function

createObserverDeserializer

createObserverDeserializer(world, networkTag, components, options?) → (buffer, idMap?) => void

Creates a deserializer for observer data.

Parameters

  • world World - The world object
  • networkTag ComponentRef - Tag for networked entities
  • components ComponentRef[] - Components to track
  • options object? - idMap

Returns

function - Deserializer function

Snapshot Serialization

createSnapshotSerializer

createSnapshotSerializer(world, components, buffer?) → () => ArrayBuffer

Creates a serializer for full world state.

Parameters

  • world World - The world object
  • components ComponentRef[] - Components to serialize
  • buffer ArrayBuffer? - Backing buffer

Returns

function - Serializer function

createSnapshotDeserializer

createSnapshotDeserializer(world, components) → (buffer, idMap?) => void

Creates a deserializer for snapshot data.

Parameters

  • world World - The world object
  • components ComponentRef[] - Components to deserialize

Returns

function - Deserializer function

Type Tags

  • u8(), i8() - 8-bit integers
  • u16(), i16() - 16-bit integers
  • u32(), i32() - 32-bit integers
  • f32() - 32-bit floats
  • f64() - 64-bit floats (default)
  • str() - UTF-8 strings
  • array(type) - Arrays of type