Jecs API Reference

Jecs provides a simple but powerful API for entity component systems. This page documents the core API.

Core Types

World

jecs.World: World

The main container for all ECS data. See World API for details.

Entity

type Entity<T = unknown>

A unique identifier that can have components attached. The generic type T represents the data type of the entity when used as a component.

Id

type Id<T>

Represents either an Entity or a Pair that can be used to store component data of type T.

Core Functions

pair()

function jecs.pair(
    first: Entity, -- The first element of the pair (relationship)
    object: Entity -- The second element of the pair (target)
): number -- Returns the ID representing this relationship pair

Creates a relationship pair between two entities. Used for creating relationships like parent-child, ownership, etc.

::: info Note that while relationship pairs can be used as components (meaning you can add data with them as an ID), they cannot be used as entities. You cannot add components to a pair as the source of a binding. :::

Example:

local ChildOf = world:component()
local parent = world:entity()
local child = world:entity() 

-- Create parent-child relationship
world:add(child, pair(ChildOf, parent))

Constants

Wildcard

jecs.Wildcard: Entity

Special entity used for querying any entity in a relationship. See Relationships.

Component

jecs.Component: Entity

Built-in component type. Every component created with world:component() has this added to it.

ChildOf

jecs.ChildOf: Entity

Built-in relationship type for parent-child hierarchies.

Rest

jecs.Rest: Entity

Special component used in queries to match remaining components.

1.9 KiB Raw Blame History