World API

Complete API reference for the World class

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.

id · 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 · Id · required

The component or pair to set

value · T · 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 · Id · 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.

id · Id · 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()