jecs

jecs is a high-performance Entity Component System (ECS) designed for Luau. Key features include:

• Entity Relationships: Supported as first-class citizens.
• High Performance: Capable of iterating 800,000 entities at 60 FPS.
• Type-Safety: Provides a type-safe Luau API.
• Optimized Storage: Uses an archetype/SoA (Structure of Arrays) approach optimized for column-major operations and cache friendliness.
• Zero-dependency: The package has no external dependencies.

To use Jecs, you must first create a World instance. This instance acts as the container for all entities, components, and relationships. You can optionally pass a DEBUG boolean to the constructor.

import { world } from 'jecs';

const world = world(); // or world(true) for debug mode

To begin using jecs, it is recommended to explore the provided subfolders in the repository to understand the design and implementation patterns:

• how_to/: Provides a step-by-step introduction to the ECS mechanics and the design reasoning.
• modules/: Contains regularly used modules that can be used to accelerate development.
• examples/: Contains larger programs demonstrating real-world use cases and how the different parts of the ECS integrate.

If you are working within Roblox Studio, you can import a model file containing the documentation directly from the provided nightly link.

https://nightly.link/Ukendio/jecs/workflows/build-studio-docs.yaml/main/studio_docs.zip

A cached query is an optimized version of a standard query. It works by:

1. Archetype Tracking: It pre-calculates which archetypes match the query.
2. Observer Pattern: It registers observers on the world.observable for EcsOnArchetypeCreate and EcsOnArchetypeDelete. When an archetype is created or destroyed, the cached query updates its internal list of compatible archetypes.
3. Fast Iteration: The iterator uses the pre-calculated archetype list to jump directly to relevant data.

Lifecycle Management: Because cached queries register observers on the world, they must be manually cleaned up using query:fini() to avoid memory leaks and stale observers.

Use jecs.world() to create a new ECS world instance. You can pass an optional boolean to configure the world during creation.

local jecs = require(path.to.jecs)
local world = jecs.world()

Jecs distinguishes between standard entities and components.

• Entities: Use world.entity() to create a basic entity (a Tag with no data).
• Components: Use world.component<TData>() to create a component that holds data of type TData. Components are typically created in the first 256 IDs for fast access.
• Tags: Use tag() or world.entity() to create a Tag, which is an entity used as a component with no associated data.

import { world, tag } from 'jecs';

const world = world();

// Create a basic entity (Tag)
const myEntity = world.entity();

// Create a component with data type
interface Position { x: number; y: number }
const Position = world.component<Position>();

// Create a tag specifically
const MyTag = tag();

You can install hooks on components to react to changes in the world:

• OnAdd: Triggered when a component is added to an entity.
• OnRemove: Triggered when a component is removed.
• OnChange: Triggered when a component's value is updated.
• OnDelete: Triggered when an entity is deleted.

Use world.set(component, hook, callback) to register these. Note that OnAdd and OnChange provide the new data, while OnRemove can optionally provide a deleted flag.

const pos = world.component<{x: number}>();

world.set(pos, OnAdd, (entity, id, data) => {
  console.log("Component added to", entity);
});

world.set(pos, OnChange, (entity, id, data) => {
  console.log("Position changed to", data.x);
});

For performance-critical updates, use bulk operations to modify multiple components on an entity at once:

• bulk_insert(world, entity, ids, values): Inserts multiple components/relationships with provided values.
• bulk_remove(world, entity, ids): Removes multiple components/relationships from an entity.

import { bulk_insert, bulk_remove } from 'jecs';

// bulk_insert(world, entity, [id1, id2], [val1, val2])
bulk_insert(world, entity, [pos, vel], [{x: 0}, {v: 1}]);

bulk_remove(world, entity, [pos, vel]);