EliCS Entity Component System

EliCS is a lightweight, flexible, and robust Entity-Component-System (ECS) framework for TypeScript and JavaScript. It is specifically designed for building dynamic and complex applications, such as 3D web applications and games.

Inspired by the architecture of the archived ECSY project, EliCS prioritizes developer ergonomics and type-safety over extreme low-level performance optimizations (like those found in BitECS), making it suitable for complex state management in 3D environments where rendering is typically the primary bottleneck.

EliCS is a lightweight Entity Component System (ECS) framework designed for complex 3D web applications. It focuses on three core pillars:

• Performance: Optimized for high-performance requirements in 3D environments.
• Ergonomics: Designed to be developer-friendly and easy to use.
• Flexibility: Supports various programming styles and architectural approaches.

For detailed implementation details, refer to the official documentation site.

An Entity is a core component of the EliCS ECS architecture, acting as a container for multiple components. It represents individual objects or actors within your application.

Key characteristics include:

• Component Management: Adding, accessing, and removing components.
• Lifecycle: Managing active states and destruction.
• Query Integration: Filtering and processing via queries.
• Vector Views: Optimized access to array-like component data.

Note on Creation: You should never instantiate an Entity directly. Instead, use the World.createEntity() method. The system uses an internal pooling mechanism via the EntityManager to reuse inactive entities, which minimizes garbage collection and improves performance.

import { World } from 'elics';

const world = new World();
const entity = world.createEntity();

Systems can use a schema to define configuration data that can be customized during registration. This data is accessed via the this.config property.

EliCS uses @preact/signals-core for configuration, meaning this.config properties are Signals. You can read their .value, subscribe to changes, or update them at runtime to trigger reactive logic.

// 1. Define schema
const schema = {
	healthRegen: { type: Types.Float32, default: 0.5 },
};

// 2. Register with overrides
world.registerSystem(EnemySystem, { configData: { healthRegen: 1.0 } });

// 3. Access in system
class EnemySystem extends createSystem(queries, schema) {
	update(delta: number): void {
		const rate = this.config.healthRegen.value;
	}
}

In EliCS, components are not instantiated per entity. Instead, a Component instance acts as a centralized manager for a specific data type. When a component is attached to an entity, the entity's unique index is used to look up or update its specific data within the component's internal optimized arrays.

This architecture provides:

• Memory Efficiency: Avoids creating thousands of small objects.
• Cache Locality: Data is stored in contiguous memory (e.g., Float32Array), making iteration extremely fast.
• Batch Operations: Allows for high-performance bulk data processing.

The World class is the central hub of the EliCS ECS architecture. It orchestrates the interaction between entities, components, queries, and systems.

Internally, the World manages three core components:

• ComponentManager: Handles component registration and optimized storage using typed arrays.
• EntityManager: Manages entity creation and recycling via a pooling mechanism to minimize garbage collection.
• QueryManager: Uses BitSet masks for fast entity filtering and supports deferred updates to batch processing.

Systems are executed based on their registration priority (lower-priority systems run first). This architecture is designed for high-performance, cache-friendly access and efficient memory management.

import { World } from 'elics';

const world = new World();
// The world is now ready to orchestrate components, entities, and systems.

EliCS follows the Entity Component System (ECS) pattern, which uses Data-Oriented Programming to favor composition over class hierarchies. The core abstractions are:

• Entities: Unique objects that act as containers for components.
• Components: Data structures representing facets of an entity (e.g., position, health).
• Systems: Logic that processes entities and modifies their components.
• Queries: Mechanisms used by systems to select specific entities based on their component composition.
• World: The central container that manages entities, components, systems, and queries.

To interact with component data on an entity:

1. Standard Data: Use entity.getValue(Component, 'key') to read and entity.setValue(Component, 'key', value) to write.
2. Vector/Color Data: For components using Types.Vec2, Types.Vec3, Types.Vec4, or Types.Color, you must use entity.getVectorView(Component, 'key').

Warning: Attempting to use getValue or setValue on vector/color fields will throw a runtime error to enforce proper mutation of these types.

// Correct way to mutate vector data
const position = entity.getVectorView(Position, 'value');
position[0] += velocity[0] * delta;

// Correct way to mutate standard data
entity.setValue(Unit, 'state', CombatState.Idle);