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.

An error that a method raises for a mistake of its caller (a value set on a tag, a query without terms, an argument that a debug world refuses...) points at the line that called the library: in a hook or a listener, at the line of the hook.

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 first (and so is a new entity that the hooks of that delete make in the slot). An id made alive again has none of the components of its old life, nor their hooks; the signal listeners of the id hear it again. The next entity of the slot takes the generation after id, or after the newest generation of the slot when id is an older one: the ids of the newer generations stay dead.

pool​

World:pool() → Pool

A slot pool: Pool:entity creates entities whose slots come from blocks of 256 slots reserved for the pool, and a deleted entity of the pool gives its slot back to it. The entities of a pool stay together, so the bitsets and the value pages of what only they have stay dense, whatever other entities are created between them: a query over them reads a few words instead of a word per entity.

local npcs = world:pool()
local npc = npcs:entity() -- skills created with world:entity() do not scatter the NPCs

Worth it for a kind of entities that is created among many others (creatures among their skills and effects); each pool takes at least one block of 256 slots.

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 (the latter also with the value that it replaced). 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(). An id that is not alive is ignored (a debug world raises an error); a pair whose relation or target has a free slot raises an error.

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.

expect​

World:expect(
entity: Id,
id: Id<T>--

a component or a pair that holds data

) → T

The value of id on the entity, for an id that the entity must have: World:get of one id that raises an error instead of returning nil. The error names the entity and the id by their mErCS.Name, else by their number, and says what is missing:

entity "Goblin" (#4194561) has no Health
entity "Goblin" (#4194561) has Health without a value
entity "Goblin" (#4194561): Frozen is a tag, it has no value
entity "Goblin" (#4194561) has no #300 (the id is not alive)
entity #4194561 is not alive: an outdated handle or a deleted entity (expect Health)

A component added without a value (World:add, or set with nil) has none; a tag never has one. A wildcard pair reads as in [World:get]: the value of the pair with the lowest target slot for (R, *), with the lowest relation slot for (*, T). A read costs what World:get of one id costs; the message is made only for the error.

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. A removal of the same id from the same entity that the hooks of this removal start again, also by a delete or a clear of the entity, does nothing (this removal completes it): a relation kept in sync by its hooks, each side removing the pair of the other, runs the hook of each side once.

toggle​

World:toggle(
entity: Id,
id: Id--

a component, a tag or a pair (not a wildcard)

) → boolean--

true when the id was added

Adds id when the entity does not have it (as [World:add]: a component gets no value) and removes it when it does (as World:remove); the hooks, signals, monitors and change tracking of the id run as for those calls. A dead entity is ignored (false); a debug world raises an error for it.

delete​

World:delete(entity: Id) → ()

Removes every id of the entity (their mErCS.OnRemove hooks run first, once per id; an id that the hooks give the entity meanwhile goes without its hooks), applies the cleanup policies of the entity used as an id or a target (also to the uses that the hooks make meanwhile), and frees the slot. Cascades of any depth work (past 100 nested levels the rest is queued: the queued entities lose the deleted id at once, its mErCS.OnRemove runs for them with deleting = true, and they are deleted after the cascade).

clear​

World:clear(entity: Id) → ()

Removes every id of the entity; the entity stays alive. The mErCS.OnRemove hooks run first, once per id (an id that the hooks give the entity meanwhile goes without its hooks); a removal of an id whose hook has run already does nothing (the clear removes it).

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 (a slot skipped by World:range or an explicit id, or reserved by a World:pool, counts as used).

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), like World:each.

each​

World:each(id: Id) → () → Entity?--

an iterator

Iterates the entities that have id when the loop starts, in ascending slot order, whatever their number. They are collected into a buffer that the world reuses: a loop allocates only its iterator. Nothing that changes during the loop changes what it returns: an entity that gets the id is not visited, one that loses it is visited, and one deleted before the loop reaches it is returned as a dead id (a loop that deletes other entities checks world:contains).

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. A query must select entities through a required id, an OR term or a change filter: one with excluded ids alone raises an error when it is used.

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. id is a component, a tag or a relation (the listener runs for all its pairs); a pair raises an error.

changed​

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

disconnects the listener

Connects a listener that runs when the value of id is set again on an entity, with the new value and the value that it replaced (previous, nil when the entity had id without a value; a table changed in place and set again is the same value before and after). id is not a pair (see World:added).

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. id is not a pair (see World:added).

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. id is not a pair (see World:added). A query with a change filter of an id that is not tracked raises an error at every use (a loop, each, count, has, a batch operation).

track_created​

World:track_created() → ()

Starts recording the entities made from now on (World:entity, a Pool, World:entity with an id that makes a new id alive) per tick, for the change filter Query:created. A world that does not track creations pays a test per new entity; one that does pays a bit per new entity, and a deleted entity is gone from the filter. Without it, a query with the filter raises an error at every use.

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, between frames: outside hooks, listeners and loops. It also drops what an error raised by a hook or a listener left in the world (a removal, a clear or a cascade that did not finish) and deletes the entities that such a cascade had queued, so the frames after the error work again; a debug world reports it.

range​

World:range(
first: number,
last: number?
) → ()

The new entity ids of this world come after first (the first one is first + 1, as in jecs) and stay below last (networked worlds), also the ids of the pools made before. World:entity with an id makes any id alive, also outside the range (an id of another world); once deleted, its slot is not given to a new entity of this world.

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 it\nhas another generation, is deleted first (and so is a new entity that the hooks of that\ndelete make in the slot). An id made alive again has none of the components of its old\nlife, nor their hooks; the signal listeners of the id hear it again. The next entity of the\nslot takes the generation after `id`, or after the newest generation of the slot when `id`\nis an older one: the ids of the newer generations stay dead.",
            "params": [
                {
                    "name": "id",
                    "desc": "an id to make alive",
                    "lua_type": "Id?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Entity"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 822,
                "path": "src/init.luau"
            }
        },
        {
            "name": "pool",
            "desc": "A slot pool: [Pool:entity] creates entities whose slots come from blocks of 256 slots\nreserved for the pool, and a deleted entity of the pool gives its slot back to it. The\nentities of a pool stay together, so the bitsets and the value pages of what only they\nhave stay dense, whatever other entities are created between them: a query over them\nreads a few words instead of a word per entity.\n\n```lua\nlocal npcs = world:pool()\nlocal npc = npcs:entity() -- skills created with world:entity() do not scatter the NPCs\n```\n\nWorth it for a kind of entities that is created among many others (creatures among their\nskills and effects); each pool takes at least one block of 256 slots.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Pool"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 841,
                "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": 863,
                "path": "src/init.luau"
            }
        },
        {
            "name": "set",
            "desc": "Adds `id` with a value, or replaces the value; [mErCS.OnAdd] or [mErCS.OnChange] runs (the\nlatter also with the value that it replaced).\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": 875,
                "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()`. An `id` that is not alive is ignored (a debug world\nraises an error); a pair whose relation or target has a free slot raises an error.",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                },
                {
                    "name": "id",
                    "desc": "",
                    "lua_type": "Id"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 885,
                "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": 894,
                "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": 904,
                "path": "src/init.luau"
            }
        },
        {
            "name": "expect",
            "desc": "The value of `id` on the entity, for an id that the entity must have: [World:get] of one id\nthat raises an error instead of returning nil. The error names the entity and the id by\ntheir [mErCS.Name], else by their number, and says what is missing:\n\n```\nentity \"Goblin\" (#4194561) has no Health\nentity \"Goblin\" (#4194561) has Health without a value\nentity \"Goblin\" (#4194561): Frozen is a tag, it has no value\nentity \"Goblin\" (#4194561) has no #300 (the id is not alive)\nentity #4194561 is not alive: an outdated handle or a deleted entity (expect Health)\n```\n\nA component added without a value ([World:add], or `set` with nil) has none; a tag never\nhas one. A wildcard pair reads as in [World:get]: the value of the pair with the lowest\ntarget slot for `(R, *)`, with the lowest relation slot for `(*, T)`. A read costs what\n[World:get] of one id costs; the message is made only for the error.",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                },
                {
                    "name": "id",
                    "desc": "a component or a pair that holds data",
                    "lua_type": "Id<T>"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "T"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 928,
                "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": 937,
                "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": 946,
                "path": "src/init.luau"
            }
        },
        {
            "name": "remove",
            "desc": "Removes `id` from the entity; [mErCS.OnRemove] runs first. A removal of the same id from the\nsame entity that the hooks of this removal start again, also by a delete or a clear of the\nentity, does nothing (this removal completes it): a relation kept in sync by its hooks, each\nside removing the pair of the other, runs the hook of each side once.",
            "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": 957,
                "path": "src/init.luau"
            }
        },
        {
            "name": "toggle",
            "desc": "Adds `id` when the entity does not have it (as [World:add]: a component gets no value) and\nremoves it when it does (as [World:remove]); the hooks, signals, monitors and change\ntracking of the id run as for those calls. A dead entity is ignored (false); a debug world\nraises an error for it.",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                },
                {
                    "name": "id",
                    "desc": "a component, a tag or a pair (not a wildcard)",
                    "lua_type": "Id"
                }
            ],
            "returns": [
                {
                    "desc": "true when the id was added",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 969,
                "path": "src/init.luau"
            }
        },
        {
            "name": "delete",
            "desc": "Removes every id of the entity (their [mErCS.OnRemove] hooks run first, once per id; an id\nthat the hooks give the entity meanwhile goes without its hooks), applies the cleanup\npolicies of the entity used as an id or a target (also to the uses that the hooks make\nmeanwhile), and frees the slot. Cascades of any depth work (past 100 nested levels the rest is queued: the\nqueued entities lose the deleted id at once, its [mErCS.OnRemove] runs for them with\n`deleting = true`, and they are deleted after the cascade).",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 981,
                "path": "src/init.luau"
            }
        },
        {
            "name": "clear",
            "desc": "Removes every id of the entity; the entity stays alive. The [mErCS.OnRemove] hooks run\nfirst, once per id (an id that the hooks give the entity meanwhile goes without its hooks);\na removal of an id whose hook has run already does nothing (the clear removes it).",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 990,
                "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": 998,
                "path": "src/init.luau"
            }
        },
        {
            "name": "exists",
            "desc": "Whether the slot of the entity was ever used, also after the delete (a slot skipped by\n[World:range] or an explicit id, or reserved by a [World:pool], counts as used).",
            "params": [
                {
                    "name": "entity",
                    "desc": "",
                    "lua_type": "Id"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 1007,
                "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": 1017,
                "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": 1026,
                "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": 1034,
                "path": "src/init.luau"
            }
        },
        {
            "name": "children",
            "desc": "Iterates the entities that have `(ChildOf, parent)`, like [World:each].",
            "params": [
                {
                    "name": "parent",
                    "desc": "",
                    "lua_type": "Id"
                }
            ],
            "returns": [
                {
                    "desc": "an iterator",
                    "lua_type": "() -> Entity?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 1042,
                "path": "src/init.luau"
            }
        },
        {
            "name": "each",
            "desc": "Iterates the entities that have `id` when the loop starts, in ascending slot order,\nwhatever their number. They are collected into a buffer that the world reuses: a loop\nallocates only its iterator. Nothing that changes during the loop changes what it returns:\nan entity that gets the id is not visited, one that loses it is visited, and one deleted\nbefore the loop reaches it is returned as a dead id (a loop that deletes other entities\nchecks `world:contains`).",
            "params": [
                {
                    "name": "id",
                    "desc": "",
                    "lua_type": "Id"
                }
            ],
            "returns": [
                {
                    "desc": "an iterator",
                    "lua_type": "() -> Entity?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 1055,
                "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": 1063,
                "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]. A query must select entities through a required id, an OR\nterm or a change filter: one with excluded ids alone raises an error when it is used.",
            "params": [
                {
                    "name": "...",
                    "desc": "the ids whose values the query returns",
                    "lua_type": "Id"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Query"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 1073,
                "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. `id` is a component, a tag or a relation (the listener runs for all its pairs); a\npair raises an error.",
            "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": 1085,
                "path": "src/init.luau"
            }
        },
        {
            "name": "changed",
            "desc": "Connects a listener that runs when the value of `id` is set again on an entity, with the\nnew value and the value that it replaced (`previous`, nil when the entity had `id` without a\nvalue; a table changed in place and set again is the same value before and after). `id` is\nnot a pair (see [World:added]).",
            "params": [
                {
                    "name": "id",
                    "desc": "",
                    "lua_type": "Id<T>"
                },
                {
                    "name": "listener",
                    "desc": "",
                    "lua_type": "(entity: Entity, id: Id<T>, value: T, previous: T?) -> ()"
                }
            ],
            "returns": [
                {
                    "desc": "disconnects the listener",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 1097,
                "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. `id` is not a pair (see [World:added]).",
            "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": 1107,
                "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. `id` is not a pair (see [World:added]).\nA query with a change filter of an id that is not tracked raises an error at every use (a\nloop, `each`, `count`, `has`, a batch operation).",
            "params": [
                {
                    "name": "id",
                    "desc": "",
                    "lua_type": "Id"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 1118,
                "path": "src/init.luau"
            }
        },
        {
            "name": "track_created",
            "desc": "Starts recording the entities made from now on ([World:entity], a [Pool], [World:entity]\nwith an id that makes a new id alive) per tick, for the change filter [Query:created]. A\nworld that does not track creations pays a test per new entity; one that does pays a bit\nper new entity, and a deleted entity is gone from the filter. Without it, a query with the\nfilter raises an error at every use.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 1128,
                "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, between frames: outside hooks, listeners and loops. It also drops what an\nerror raised by a hook or a listener left in the world (a removal, a clear or a cascade that\ndid not finish) and deletes the entities that such a cascade had queued, so the frames\nafter the error work again; a debug world reports it.",
            "params": [],
            "returns": [
                {
                    "desc": "the new tick",
                    "lua_type": "number"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 1139,
                "path": "src/init.luau"
            }
        },
        {
            "name": "range",
            "desc": "The new entity ids of this world come after `first` (the first one is `first + 1`, as in\njecs) and stay below `last` (networked worlds), also the ids of the pools made before.\n[World:entity] with an id makes any id alive, also outside the range (an id of another\nworld); once deleted, its slot is not given to a new entity of this world.",
            "params": [
                {
                    "name": "first",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "last",
                    "desc": "",
                    "lua_type": "number?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 1150,
                "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": 1159,
                "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": 1167,
                "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": 1175,
                "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.\n\nAn error that a method raises for a mistake of its caller (a value set on a tag, a query\nwithout terms, an argument that a debug world refuses...) points at the line that called\nthe library: in a hook or a listener, at the line of the hook.",
    "source": {
        "line": 809,
        "path": "src/init.luau"
    }
}