This page introduces bitECS as an Entity Component System (ECS) library for TypeScript and JavaScript. It covers the library's design philosophy, key features, module organization, and high-level architecture. For installation and first steps, see Getting Started. For detailed explanations of ECS concepts, see Core Concepts. For advanced capabilities, see Advanced Features.
Sources: README.md1-26 docs/Intro.md1-13
bitECS is a flexible, minimal, data-oriented Entity Component System library for TypeScript and JavaScript. Unlike prescriptive ECS frameworks, bitECS provides low-level primitives that developers compose into custom architectures. The library achieves high performance through data-oriented design principles while maintaining a small footprint (~5kb minzipped).
The library implements the ECS architectural pattern where:
EntityIndexSources: README.md24-26 package.json4 docs/Intro.md3-8
bitECS embraces data-oriented design by separating data layout from API design. Component stores can be any JavaScript reference, allowing developers to optimize memory layout per use case. The library recommends Structure of Arrays (SoA) format for cache-friendly iteration but does not enforce it.
The library provides only essential operations: createWorld, addEntity, addComponent, removeComponent, query. Higher-level abstractions like component definitions and system registration are left to user code. This minimalism keeps the library lightweight and prevents framework lock-in.
bitECS avoids imposing architectural decisions. There is no formal concept of "systems"—only queries and user functions. Component stores live wherever developers choose. Multiple worlds can share or isolate data. This flexibility enables integration into existing codebases and supports diverse use cases from games to simulations.
Sources: docs/Intro.md3-13 README.md30-38
| Feature | Description |
|---|---|
| Simple API | Declarative functions for entities, components, and queries |
| Lightweight | ~5kb minzipped with zero runtime dependencies |
| Powerful Querying | Bitmask-based filtering with And, Or, Not operators and hierarchy support |
| Relational Modeling | Entity relationships via Pair components with wildcard querying |
| Serialization | Multiple strategies (SoA, AoS, Snapshot, Observer) for network sync and persistence |
| Thread-Friendly | SharedArrayBuffer support for concurrent access |
| TypeScript Support | Full type definitions with generic World types |
Sources: README.md30-38 package.json1-78
Module Structure Explained
bitECS distributes functionality across three independent modules:
Core Module (bitecs): The main ECS implementation exported from dist/core/index containing all fundamental operations. This module has no external dependencies and provides the complete ECS foundation.
Serialization Module (bitecs/serialization): Optional serialization strategies for network synchronization and persistence, exported from dist/serialization/index Depends on the core module but can be excluded if serialization is not needed.
Legacy Module (bitecs/legacy): Backward-compatible API from earlier versions, exported from dist/legacy/index Provides higher-level abstractions like defineComponent that wrap core functionality with Observer and SoA serialization.
Sources: package.json10-35 package.json48-72
Architecture Explained
The World object serves as the central coordinator, internally maintaining:
Entity operations (addEntity, removeEntity) modify the EntityIndex and update all active queries. Component operations (addComponent, removeComponent) update entity masks via bitwise OR/AND operations, triggering query re-evaluation. The query function performs bitwise operations on entity masks to filter matching entities in O(1) time per entity.
Relations extend the component system by creating Pair components with metadata symbols ($relation, $pairTarget). The hierarchy system tracks entity depths in typed arrays for topological query ordering.
Sources: src/core/World.ts src/core/EntityIndex.ts src/core/Component.ts src/core/Query.ts
Data Flow Explained
addEntity allocates an ID from the EntityIndex sparse set and registers it in the world's entityComponents mapaddComponent registers the component (if new), assigns a bitflag, and updates the entity's bitmask via bitwise ORquery retrieves or compiles a cached query with bitmasks, then iterates entity masks performing bitwise AND/OR/NOT operationsqueryCheckEntity re-evaluates affected queries and updates their result sets via queryAddEntity or queryRemoveEntityThis architecture achieves O(1) query evaluation per entity through bitmask operations, with query results cached in SparseSet structures for fast iteration.
Sources: src/core/Entity.ts src/core/Component.ts src/core/Query.ts
Integration Points
Pair components with metadata. See Relations and HierarchySources: src/core/index.ts src/serialization/index.ts src/legacy/index.ts
| Operation | Complexity | Implementation |
|---|---|---|
addEntity | O(1) | Sparse set allocation from EntityIndex.dense |
removeEntity | O(1) | Sparse set swap-remove from EntityIndex.dense |
addComponent | O(Q) | Bitwise OR on mask, re-evaluate Q active queries |
removeComponent | O(Q) | Bitwise AND NOT on mask, re-evaluate Q queries |
hasComponent | O(1) | Check entityComponents Set membership |
query (cached) | O(N) | Iterate N entities, bitwise AND/OR/NOT per entity |
query (compilation) | O(C) | Hash C components, generate bitmasks |
| Entity iteration | O(N) | Dense array iteration, cache-friendly |
Performance Notes:
Sources: src/core/EntityIndex.ts src/core/Query.ts src/core/Component.ts
bitECS supports concurrent access patterns through:
SharedArrayBuffer-backed TypedArrays for lock-free readsEntityIndex enable parallel processingFor multithreading details, see Multithreading.
Sources: README.md37
The library provides full TypeScript definitions with generic types:
World<T> preserves custom context types passed to createWorld$u8, $f32, etc.) for type safetyFor TypeScript usage patterns, see TypeScript Support.
Sources: package.json12 dist/core/index.d.ts
Ideal Use Cases:
Considerations:
Production Usage:
Sources: README.md156-161
Refresh this wiki