World API - jecs

The World is the main container for all entities, components, and systems in jecs. It manages the ECS registry and provides methods for entity manipulation, querying, and lifecycle management.

Creating a World

world()

Creates a new World instance.

DEBUG

boolean

Enable debug mode for better error messages and assertions

Returns: World

local jecs = require("@jecs")
local world = jecs.world()

import { world } from "@jecs/core"
const myWorld = world()

Entity Management

entity()

Creates a new entity in the world.

Entity

Optional entity ID to create. If provided, creates an entity with that specific ID.

Returns: Entity (Tag if no ID provided)

local player = world:entity()

const player = world.entity()

component()

Creates a new component entity in the first 256 IDs for fast access. These are static components optimized for performance.

TData

type

The type of data this component will store

Returns: Entity<TData>

local Position = world:component()

const Position = world.component<{ x: number, y: number }>()

delete()

Completely removes an entity from the world, including all its components and relationships.

entity

Entity

required

The entity to delete

world:delete(player)

world.delete(player)

clear()

Removes all components and relationships from an entity, but keeps the entity alive in the world.

entity

Entity

required

The entity to clear

world:clear(entity)

world.clear(entity)

contains()

Checks if an entity exists in the world.

entity

Entity | number

required

The entity to check

Returns: boolean

if world:contains(player) then
    print("Player exists")
end

if (world.contains(player)) {
    console.log("Player exists")
}

exists()

Checks if an entity with the given ID is currently alive, ignoring its generation.

entity

Entity

required

The entity to verify

Returns: boolean

if world:exists(entity) then
    -- Entity ID exists
end

Component Operations

set()

Sets a component value on an entity, or installs a hook on a component.

Set Component Value

entity

Entity

required

The target entity

component

required

The component or pair to set

value

required

The value to store

world:set(player, Position, { x = 10, y = 20 })

world.set(player, Position, { x: 10, y: 20 })

Install Hook

component

Entity<T>

required

The component to hook

hook

OnAdd | OnChange | OnRemove

required

The hook type to install

callback

function

required

The callback function: (entity, id, value) => void

world:set(Position, jecs.OnAdd, function(entity, id, value)
    print("Position added to entity", entity)
end)

add()

Adds a tag component (with no value) to an entity.

entity

Entity

required

The target entity

component

Tag

required

The tag component to add

local Alive = world:component()
world:add(player, Alive)

const Alive = world.component()
world.add(player, Alive)

get()

Retrieves component values from an entity. Supports up to 4 components at once.

entity

Entity

required

The entity to query

components

Id[]

required

1-4 components to retrieve

Returns: Component value(s) or undefined if not present

local position = world:get(player, Position)
local pos, vel = world:get(player, Position, Velocity)

const position = world.get(player, Position)
const [pos, vel] = world.get(player, Position, Velocity)

has()

Checks if an entity has all specified components. Supports up to 4 components.

entity

Entity

required

The entity to check

components

Id[]

required

1-4 components to check for

Returns: boolean

if world:has(player, Position, Velocity) then
    -- Player has both components
end

if (world.has(player, Position, Velocity)) {
    // Player has both components
}

remove()

Removes a component from an entity.

entity

Entity

required

The target entity

component

required

The component to remove

world:remove(player, Position)

world.remove(player, Position)

Querying

query()

Creates a query to search for entities with specific components.

components

Id[]

required

Components to query for

Returns: Query<T> - See Query API

for entity, position, velocity in world:query(Position, Velocity) do
    position.x = position.x + velocity.x
end

for (const [entity, position, velocity] of world.query(Position, Velocity)) {
    position.x += velocity.x
}

each()

Iterates over all entities that have a specific component or relationship.

required

The component or relationship to search for

Returns: Iterator function yielding entities

for entity in world:each(Position) do
    print("Entity with Position:", entity)
end

Relationships

target()

Gets the target entity of a relationship. For example, with ChildOf(parent), this returns the parent entity.

entity

Entity

required

The entity with the relationship

relation

Entity

required

The relationship component (e.g., ChildOf)

index

number

default:"0"

Index if multiple targets exist

Returns: Entity | undefined

local parent = world:target(entity, jecs.ChildOf)

const parent = world.target(entity, ChildOf)

parent()

Gets the parent entity (target of ChildOf relationship).

entity

Entity

required

The entity to get the parent of

Returns: Entity | undefined

local parent = world:parent(child)

const parent = world.parent(child)

children()

Iterates over all child entities of a parent.

parent

Entity

required

The parent entity

Returns: Iterator function yielding child entities

for child in world:children(parent) do
    print("Child:", child)
end

Change Detection

added()

Registers a listener for when a component is added to any entity.

component

Entity<T>

required

The component to listen for

listener

function

required

Callback: (entity, id, value) => void

Returns: Cleanup function () => void

local disconnect = world:added(Position, function(entity, id, value)
    print("Position added:", value)
end)

-- Later: disconnect()

changed()

Registers a listener for when a component value changes.

component

Entity<T>

required

The component to listen for

listener

function

required

Callback: (entity, id, value) => void

Returns: Cleanup function () => void

world:changed(Health, function(entity, id, value)
    if value <= 0 then
        print("Entity died")
    end
end)

removed()

Registers a listener for when a component is removed from an entity.

component

Entity<T>

required

The component to listen for

listener

function

required

Callback: (entity, id, deleted?) => void

Returns: Cleanup function () => void

world:removed(Position, function(entity, id, deleted)
    print("Position removed, entity deleted:", deleted)
end)

Utility

range()

Enforces entity creation within a specific ID range.

range_begin

number

required

Starting ID for the range

range_end

number

Ending ID for the range (optional)

world:range(1000, 2000)
local entity = world:entity() -- Will be in range 1000-2000

cleanup()

Cleans up the world by removing empty archetypes and rebuilding archetype collections. Helps maintain memory efficiency.

world:cleanup()

world.cleanup()

API

Documentation Index

​Creating a World

​world()

​Entity Management

​entity()

​component()

​delete()

​clear()

​contains()

​exists()

​Component Operations

​set()

​Set Component Value

​Install Hook

​add()

​get()

​has()

​remove()

​Querying

​query()

​each()

​Relationships

​target()

​parent()

​children()

​Change Detection

​added()

​changed()

​removed()

​Utility

​range()

​cleanup()

Build docs developers (and LLMs) love

Creating a World

world()

Entity Management

entity()

component()

delete()

clear()

contains()

exists()

Component Operations

set()

Set Component Value

Install Hook

add()

get()

has()

remove()

Querying

query()

each()

Relationships

target()

parent()

children()

Change Detection

added()

changed()

removed()

Utility

range()

cleanup()