Skip to main content

World

A world holds entities and the components, tags and pairs on them. mErCS.world creates one.

Every component, tag and pair keeps a bitset of the entities that have it, and the values of a component sit in pages indexed by the entity slot: adding or removing an id sets a bit and a value and never moves the entity.

Functions​

entity​

</>
World:entity(
id: Id?--

an id to make alive

) → Entity

A new entity. With id, makes that id alive and returns it (the entity of its slot, if it has another generation, is deleted).

component​

</>
World:component() → Component<T>

A new entity with the mErCS.Component trait: it can hold data. The first 256 are the ids 1..256, then any entity id (there is no limit).

set​

</>
World:set(
entity: Id,
id: Id<T>,--

a component or a pair that holds data

value: T
) → ()

Adds id with a value, or replaces the value; mErCS.OnAdd or mErCS.OnChange runs. Only ids with the mErCS.Component trait hold data: setting a value on a tag raises an error.

add​

</>
World:add(
entity: Id,
id: Id
) → ()

Adds id without a value: a tag, or a component whose value stays nil. Any entity can be a tag: local Frozen = world:entity().

get​

</>
World:get(
entity: Id,
...: Id--

up to 8 ids

) → ...any--

the values, nil for a tag or a missing id

The values of up to 8 ids; World:get_list takes any number.

get_list​

</>
World:get_list(
entity: Id,
ids: {Id},
out: {any}?--

the table to fill; a new one when nil

) → {any}

The values of any number of ids.

has​

</>
World:has(
entity: Id,
...: Id--

up to 8 ids

) → boolean

Whether the entity has all of up to 8 ids; World:has_all takes any number.

has_all​

</>
World:has_all(
entity: Id,
ids: {Id}
) → boolean

Whether the entity has all of any number of ids.

remove​

</>
World:remove(
entity: Id,
id: Id--

a wildcard pair removes every matching pair

) → ()

Removes id from the entity; mErCS.OnRemove runs first.

delete​

</>
World:delete(entity: Id) → ()

Removes every id of the entity (their mErCS.OnRemove hooks run first), applies the cleanup policies of the entity used as an id or a target, and frees the slot. Cascades of any depth work (past 100 nested levels the rest is queued).

clear​

</>
World:clear(entity: Id) → ()

Removes every id of the entity; the entity stays alive.

contains​

</>
World:contains(entity: Id) → boolean

Whether the entity is alive. An old handle of a reused slot is not.

exists​

</>
World:exists(entity: Id) → boolean

Whether the slot of the entity was ever used, also after the delete.

target​

</>
World:target(
entity: Id,
relation: Id,
index: number?--

from 0; the targets are ordered by entity slot

) → Entity?

The index-th target of the relation on the entity.

targets​

</>
World:targets(
entity: Id,
relation: Id
) → () → Entity?--

an iterator

Iterates the targets of the relation on the entity.

parent​

</>
World:parent(entity: Id) → Entity?

The target of mErCS.ChildOf on the entity.

children​

</>
World:children(parent: Id) → () → Entity?--

an iterator

Iterates the entities that have (ChildOf, parent).

each​

</>
World:each(id: Id) → () → Entity?--

an iterator

Iterates the entities that have id.

remove_all​

</>
World:remove_all(id: Id) → ()

Removes id from every entity that has it. Without mErCS.OnRemove hooks it takes about 20 ns per entity.

query​

</>
World:query(
...: Id--

the ids whose values the query returns

) → Query

A query over the entities that have all of the given ids (any number; more than 8 go through a table). See Query.

added​

</>
World:added(
id: Id<T>,
listener: (
entity: Entity,
id: Id<T>,
value: T
) → ()
) → () → ()--

disconnects the listener

Connects a listener that runs when id is added to an entity. A listener may connect or disconnect listeners, itself included, while it runs: the change applies from the next event.

changed​

</>
World:changed(
id: Id<T>,
listener: (
entity: Entity,
id: Id<T>,
value: T
) → ()
) → () → ()--

disconnects the listener

Connects a listener that runs when the value of id is set again on an entity.

removed​

</>
World:removed(
id: Id<T>,
listener: (
entity: Entity,
id: Id<T>,
deleting: boolean?
) → ()
) → () → ()--

disconnects the listener

Connects a listener that runs before id is removed from an entity; deleting is true when the entity itself is being deleted.

track​

</>
World:track(id: Id) → ()

Starts recording additions, value changes and removals of id per tick, for the change filters Query:added, Query:changed and Query:removed. Untracked ids cost nothing; a tracked id costs a call per add, change or remove.

tick​

</>
World:tick() → number--

the new tick

Advances the tick: the changes recorded so far become visible to change filters. Call it once per frame.

range​

</>
World:range(
first: number,
last: number?
) → ()

The entity ids of this world start at first and stay below last (networked worlds).

column​

</>
World:column(id: Id) → {{any}}--

the value pages

The value pages of a component, for the fast path of [Query:spans]: the value of a slot is column[slot // PAGE_SIZE + 1][slot % PAGE_SIZE + 1].

alive_table​

</>
World:alive_table() → {number}

The entity of every slot, for the fast path: alive_table()[slot]. A free slot holds a negative number.

ids​

</>
World:ids(entity: Id) → {Id}

Every id of the entity (components, tags, pairs), sorted ascending.

Show raw api
{
    "functions": [
        {
            "name": "entity",
            "desc": "A new entity. With `id`, makes that id alive and returns it (the entity of its slot, if\nit has another generation, is deleted).",
            "params": [
                {
                    "name": "id",
                    "desc": "an id to make alive",
                    "lua_type": "Id?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Entity"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 631,
                "path": "src/init.luau"
            }
        },
        {
            "name": "component",
            "desc": "A new entity with the [mErCS.Component] trait: it can hold data. The first 256 are the\nids 1..256, then any entity id (there is no limit).",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Component<T>"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 639,
                "path": "src/init.luau"
            }
        },
        {
            "name": "set",
            "desc": "Adds `id` with a value, or replaces the value; [mErCS.OnAdd] or [mErCS.OnChange] runs.\nOnly ids with the [mErCS.Component] trait hold data: setting a value on a tag raises an\nerror.",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                },
                {
                    "name": "id",
                    "desc": "a component or a pair that holds data",
                    "lua_type": "Id<T>"
                },
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "T"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 650,
                "path": "src/init.luau"
            }
        },
        {
            "name": "add",
            "desc": "Adds `id` without a value: a tag, or a component whose value stays nil. Any entity can be\na tag: `local Frozen = world:entity()`.",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                },
                {
                    "name": "id",
                    "desc": "",
                    "lua_type": "Id"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 659,
                "path": "src/init.luau"
            }
        },
        {
            "name": "get",
            "desc": "The values of up to 8 ids; [World:get_list] takes any number.",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                },
                {
                    "name": "...",
                    "desc": "up to 8 ids",
                    "lua_type": "Id"
                }
            ],
            "returns": [
                {
                    "desc": "the values, nil for a tag or a missing id",
                    "lua_type": "...any"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 668,
                "path": "src/init.luau"
            }
        },
        {
            "name": "get_list",
            "desc": "The values of any number of ids.",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                },
                {
                    "name": "ids",
                    "desc": "",
                    "lua_type": "{ Id }"
                },
                {
                    "name": "out",
                    "desc": "the table to fill; a new one when nil",
                    "lua_type": "{ any }?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ any }"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 678,
                "path": "src/init.luau"
            }
        },
        {
            "name": "has",
            "desc": "Whether the entity has all of up to 8 ids; [World:has_all] takes any number.",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                },
                {
                    "name": "...",
                    "desc": "up to 8 ids",
                    "lua_type": "Id"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 687,
                "path": "src/init.luau"
            }
        },
        {
            "name": "has_all",
            "desc": "Whether the entity has all of any number of ids.",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                },
                {
                    "name": "ids",
                    "desc": "",
                    "lua_type": "{ Id }"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 696,
                "path": "src/init.luau"
            }
        },
        {
            "name": "remove",
            "desc": "Removes `id` from the entity; [mErCS.OnRemove] runs first.",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                },
                {
                    "name": "id",
                    "desc": "a wildcard pair removes every matching pair",
                    "lua_type": "Id"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 704,
                "path": "src/init.luau"
            }
        },
        {
            "name": "delete",
            "desc": "Removes every id of the entity (their [mErCS.OnRemove] hooks run first), applies the\ncleanup policies of the entity used as an id or a target, and frees the slot. Cascades\nof any depth work (past 100 nested levels the rest is queued).",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 713,
                "path": "src/init.luau"
            }
        },
        {
            "name": "clear",
            "desc": "Removes every id of the entity; the entity stays alive.",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 720,
                "path": "src/init.luau"
            }
        },
        {
            "name": "contains",
            "desc": "Whether the entity is alive. An old handle of a reused slot is not.",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 728,
                "path": "src/init.luau"
            }
        },
        {
            "name": "exists",
            "desc": "Whether the slot of the entity was ever used, also after the delete.",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 736,
                "path": "src/init.luau"
            }
        },
        {
            "name": "target",
            "desc": "The `index`-th target of the relation on the entity.",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                },
                {
                    "name": "relation",
                    "desc": "",
                    "lua_type": "Id"
                },
                {
                    "name": "index",
                    "desc": "from 0; the targets are ordered by entity slot",
                    "lua_type": "number?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Entity?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 746,
                "path": "src/init.luau"
            }
        },
        {
            "name": "targets",
            "desc": "Iterates the targets of the relation on the entity.",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                },
                {
                    "name": "relation",
                    "desc": "",
                    "lua_type": "Id"
                }
            ],
            "returns": [
                {
                    "desc": "an iterator",
                    "lua_type": "() -> Entity?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 755,
                "path": "src/init.luau"
            }
        },
        {
            "name": "parent",
            "desc": "The target of [mErCS.ChildOf] on the entity.",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Entity?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 763,
                "path": "src/init.luau"
            }
        },
        {
            "name": "children",
            "desc": "Iterates the entities that have `(ChildOf, parent)`.",
            "params": [
                {
                    "name": "parent",
                    "desc": "",
                    "lua_type": "Id"
                }
            ],
            "returns": [
                {
                    "desc": "an iterator",
                    "lua_type": "() -> Entity?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 771,
                "path": "src/init.luau"
            }
        },
        {
            "name": "each",
            "desc": "Iterates the entities that have `id`.",
            "params": [
                {
                    "name": "id",
                    "desc": "",
                    "lua_type": "Id"
                }
            ],
            "returns": [
                {
                    "desc": "an iterator",
                    "lua_type": "() -> Entity?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 779,
                "path": "src/init.luau"
            }
        },
        {
            "name": "remove_all",
            "desc": "Removes `id` from every entity that has it. Without [mErCS.OnRemove] hooks it takes\nabout 20 ns per entity.",
            "params": [
                {
                    "name": "id",
                    "desc": "",
                    "lua_type": "Id"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 787,
                "path": "src/init.luau"
            }
        },
        {
            "name": "query",
            "desc": "A query over the entities that have all of the given ids (any number; more than 8 go\nthrough a table). See [Query].",
            "params": [
                {
                    "name": "...",
                    "desc": "the ids whose values the query returns",
                    "lua_type": "Id"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Query"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 796,
                "path": "src/init.luau"
            }
        },
        {
            "name": "added",
            "desc": "Connects a listener that runs when `id` is added to an entity. A listener may connect or\ndisconnect listeners, itself included, while it runs: the change applies from the next\nevent.",
            "params": [
                {
                    "name": "id",
                    "desc": "",
                    "lua_type": "Id<T>"
                },
                {
                    "name": "listener",
                    "desc": "",
                    "lua_type": "(entity: Entity, id: Id<T>, value: T) -> ()"
                }
            ],
            "returns": [
                {
                    "desc": "disconnects the listener",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 807,
                "path": "src/init.luau"
            }
        },
        {
            "name": "changed",
            "desc": "Connects a listener that runs when the value of `id` is set again on an entity.",
            "params": [
                {
                    "name": "id",
                    "desc": "",
                    "lua_type": "Id<T>"
                },
                {
                    "name": "listener",
                    "desc": "",
                    "lua_type": "(entity: Entity, id: Id<T>, value: T) -> ()"
                }
            ],
            "returns": [
                {
                    "desc": "disconnects the listener",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 816,
                "path": "src/init.luau"
            }
        },
        {
            "name": "removed",
            "desc": "Connects a listener that runs before `id` is removed from an entity; `deleting` is true\nwhen the entity itself is being deleted.",
            "params": [
                {
                    "name": "id",
                    "desc": "",
                    "lua_type": "Id<T>"
                },
                {
                    "name": "listener",
                    "desc": "",
                    "lua_type": "(entity: Entity, id: Id<T>, deleting: boolean?) -> ()"
                }
            ],
            "returns": [
                {
                    "desc": "disconnects the listener",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 826,
                "path": "src/init.luau"
            }
        },
        {
            "name": "track",
            "desc": "Starts recording additions, value changes and removals of `id` per tick, for the change\nfilters [Query:added], [Query:changed] and [Query:removed]. Untracked ids cost nothing; a\ntracked id costs a call per add, change or remove.",
            "params": [
                {
                    "name": "id",
                    "desc": "",
                    "lua_type": "Id"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 835,
                "path": "src/init.luau"
            }
        },
        {
            "name": "tick",
            "desc": "Advances the tick: the changes recorded so far become visible to change filters. Call it\nonce per frame.",
            "params": [],
            "returns": [
                {
                    "desc": "the new tick",
                    "lua_type": "number"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 843,
                "path": "src/init.luau"
            }
        },
        {
            "name": "range",
            "desc": "The entity ids of this world start at `first` and stay below `last` (networked worlds).",
            "params": [
                {
                    "name": "first",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "last",
                    "desc": "",
                    "lua_type": "number?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 851,
                "path": "src/init.luau"
            }
        },
        {
            "name": "column",
            "desc": "The value pages of a component, for the fast path of [Query:spans]: the value of a slot\nis `column[slot // PAGE_SIZE + 1][slot % PAGE_SIZE + 1]`.",
            "params": [
                {
                    "name": "id",
                    "desc": "",
                    "lua_type": "Id"
                }
            ],
            "returns": [
                {
                    "desc": "the value pages",
                    "lua_type": "{ { any } }"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 860,
                "path": "src/init.luau"
            }
        },
        {
            "name": "alive_table",
            "desc": "The entity of every slot, for the fast path: `alive_table()[slot]`. A free slot holds a\nnegative number.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ number }"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 868,
                "path": "src/init.luau"
            }
        },
        {
            "name": "ids",
            "desc": "Every id of the entity (components, tags, pairs), sorted ascending.",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ Id }"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 876,
                "path": "src/init.luau"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "World",
    "desc": "A world holds entities and the components, tags and pairs on them. [mErCS.world]\ncreates one.\n\nEvery component, tag and pair keeps a bitset of the entities that have it, and the\nvalues of a component sit in pages indexed by the entity slot: adding or removing an id\nsets a bit and a value and never moves the entity.",
    "source": {
        "line": 622,
        "path": "src/init.luau"
    }
}