jecs/docs/api/world.md

World

A World contains entities which have components. The World is queryable and can be used to get entities with a specific set of components.

Functions

new()

function World.new(): World

Creates a new world.

Example: ::: code-group

local world = jecs.World.new()

import { World } from "@rbxts/jecs";

const world = new World();

:::

entity()

function World:entity(): Entity -- The new entit.

Creates a new entity.

Example: ::: code-group

local entity = world:entity()

const entity = world.entity();

:::

component()

function World:component<T>(): Entity<T> -- The new componen.

Creates a new component.

Example: ::: code-group

local Health = world:component() :: jecs.Entity<number>

const Health = world.component<number>();

:::

::: info You should use this when creating components.

For example, a Health type should be created using this. :::

get()

function World:get<T>(
    entity: Entity, -- The entity
    id: Entity<T> -- The component ID to fetch
): T

Returns the data for the component data the corresponding entity, nil if entity does not have the ID or was a tag.

has()

function World:has(
    entity: Entity, -- The entity
    id: Entity<T> -- The component ID to check
): boolean

Returns whether the entity has the ID.

:::

add()

function World:add(
    entity: Entity, -- The entity
    id: Entity<T> -- The component ID to add
): ()

Adds a component ID to the entity.

This operation adds a single (component) id to an entity.

::: info This function is idempotent, meaning if the entity already has the id, this operation will have no side effects. :::

set()

function World:set(
    entity: Entity, -- The entity
    id: Entity<T>, -- The component ID to set
    data: T -- The data of the component's type
): ()

Adds or changes the entity's component.

query()

function World:query(
    ...: Entity -- The IDs to query with
): Query

Creates a query with the given IDs. Entities that satisfies the conditions of the query will be returned and their corresponding data.

Example: ::: code-group

for id, position, velocity in world:query(Position, Velocity) do
	-- Do something
end

for (const [id, position, velocity] of world.query(Position, Velocity) {
    // Do something
}

:::

:::info Queries are uncached by default, this is generally very cheap unless you have high fragmentation from e.g. relationships.

:::

target()

function World:target(
    entity: Entity, -- The entity
    relation: Entity, -- The relationship between the entity and the target
    nth: number, -- The index
): Entity? -- The target for the relationship at the specified index.

Get the target of a relationship.

This will return a target (second element of a pair) of the entity for the specified relationship. The index allows for iterating through the targets, if a single entity has multiple targets for the same relationship.

If the index is larger than the total number of instances the entity has for the relationship or if there is no pair with the specified relationship on the entity, the operation will return nil.

parent()

function World:parent(
    child: Entity -- The child ID to find the parent of
): Entity? -- Returns the parent of the child

Get parent (target of ChildOf relationship) for entity. If there is no ChildOf relationship pair, it will return nil.

This operation is the same as calling:

world:target(entity, jecs.ChildOf, 0)