Skip to main content

QueryResult

A result from the World:query function.

Calling the table or the next method allows iteration over the results. Once all results have been returned, the QueryResult is exhausted and is no longer useful. 

for id, enemy, charge, model in world:query(Enemy, Charge, Model) do
	-- Do something
end

Functions​

next​

</>
QueryResult:next() → (
id,--

Entity ID

...ComponentInstance--

The requested component values

)

Returns the next set of values from the query result. Once all results have been returned, the QueryResult is exhausted and is no longer useful.

info

This function is equivalent to calling the QueryResult as a function. When used in a for loop, this is implicitly done by the language itself. 

-- Using world:query in this position will make Lua invoke the table as a function. This is conventional.
for id, enemy, charge, model in world:query(Enemy, Charge, Model) do
	-- Do something
end

If you wanted to iterate over the QueryResult without a for loop, it's recommended that you call next directly instead of calling the QueryResult as a function. 

local id, enemy, charge, model = world:query(Enemy, Charge, Model):next()
local id, enemy, charge, model = world:query(Enemy, Charge, Model)() -- Possible, but unconventional

snapshot​

</>
QueryResult:snapshot() → {{
entityId: number,
component: ComponentInstance,
component: ComponentInstance,
component: ComponentInstance,
...
}}

Creates a "snapshot" of this query, draining this QueryResult and returning a list containing all of its results.

By default, iterating over a QueryResult happens in "real time": it iterates over the actual data in the ECS, so changes that occur during the iteration will affect future results.

By contrast, QueryResult:snapshot() creates a list of all of the results of this query at the moment it is called, so changes made while iterating over the result of QueryResult:snapshot do not affect future results of the iteration.

Of course, this comes with a cost: we must allocate a new list and iterate over everything returned from the QueryResult in advance, so using this method is slower than iterating over a QueryResult directly.

The table returned from this method has a custom __iter method, which lets you use it as you would use QueryResult directly: 

	for entityId, health, player in world:query(Health, Player):snapshot() do

	end

However, the table itself is just a list of sub-tables structured like {entityId, component1, component2, ...etc}.

without​

</>
QueryResult:without(
...: Component--

The component types to filter against.

) → () → (
id,
...ComponentInstance
)--

Iterator of entity ID followed by the requested component values

Returns an iterator that will skip any entities that also have the given components.

tip

This is essentially equivalent to querying normally, using World:get to check if a component is present, and using Lua's continue keyword to skip this iteration (though, using :without is faster).

This means that you should avoid queries that return a very large amount of results only to filter them down to a few with :without. If you can, always prefer adding components and making your query more specific. 

for id in world:query(Target):without(Model) do
	-- Do something
end
Show raw api
{
    "functions": [
        {
            "name": "next",
            "desc": "Returns the next set of values from the query result. Once all results have been returned, the\nQueryResult is exhausted and is no longer useful.\n\n:::info\nThis function is equivalent to calling the QueryResult as a function. When used in a for loop, this is implicitly\ndone by the language itself.\n:::\n\n```lua\n-- Using world:query in this position will make Lua invoke the table as a function. This is conventional.\nfor id, enemy, charge, model in world:query(Enemy, Charge, Model) do\n\t-- Do something\nend\n```\n\nIf you wanted to iterate over the QueryResult without a for loop, it's recommended that you call `next` directly\ninstead of calling the QueryResult as a function.\n```lua\nlocal id, enemy, charge, model = world:query(Enemy, Charge, Model):next()\nlocal id, enemy, charge, model = world:query(Enemy, Charge, Model)() -- Possible, but unconventional\n```",
            "params": [],
            "returns": [
                {
                    "desc": "Entity ID",
                    "lua_type": "id"
                },
                {
                    "desc": "The requested component values",
                    "lua_type": "...ComponentInstance"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 426,
                "path": "lib/World.lua"
            }
        },
        {
            "name": "snapshot",
            "desc": "Creates a \"snapshot\" of this query, draining this QueryResult and returning a list containing all of its results.\n\nBy default, iterating over a QueryResult happens in \"real time\": it iterates over the actual data in the ECS, so\nchanges that occur during the iteration will affect future results.\n\nBy contrast, `QueryResult:snapshot()` creates a list of all of the results of this query at the moment it is called,\nso changes made while iterating over the result of `QueryResult:snapshot` do not affect future results of the\niteration.\n\nOf course, this comes with a cost: we must allocate a new list and iterate over everything returned from the\nQueryResult in advance, so using this method is slower than iterating over a QueryResult directly.\n\nThe table returned from this method has a custom `__iter` method, which lets you use it as you would use QueryResult\ndirectly:\n\n```lua\n\tfor entityId, health, player in world:query(Health, Player):snapshot() do\n\n\tend\n```\n\nHowever, the table itself is just a list of sub-tables structured like `{entityId, component1, component2, ...etc}`.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{{entityId: number, component: ComponentInstance, component: ComponentInstance, component: ComponentInstance, ...}}"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 472,
                "path": "lib/World.lua"
            }
        },
        {
            "name": "without",
            "desc": "Returns an iterator that will skip any entities that also have the given components.\n\n:::tip\nThis is essentially equivalent to querying normally, using `World:get` to check if a component is present,\nand using Lua's `continue` keyword to skip this iteration (though, using `:without` is faster).\n\nThis means that you should avoid queries that return a very large amount of results only to filter them down\nto a few with `:without`. If you can, always prefer adding components and making your query more specific.\n:::\n\n\n```lua\nfor id in world:query(Target):without(Model) do\n\t-- Do something\nend\n```",
            "params": [
                {
                    "name": "...",
                    "desc": "The component types to filter against.",
                    "lua_type": "Component"
                }
            ],
            "returns": [
                {
                    "desc": "Iterator of entity ID followed by the requested component values",
                    "lua_type": "() -> (id, ...ComponentInstance)"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 508,
                "path": "lib/World.lua"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "QueryResult",
    "desc": "A result from the [`World:query`](/api/World#query) function.\n\nCalling the table or the `next` method allows iteration over the results. Once all results have been returned, the\nQueryResult is exhausted and is no longer useful.\n\n```lua\nfor id, enemy, charge, model in world:query(Enemy, Charge, Model) do\n\t-- Do something\nend\n```",
    "source": {
        "line": 387,
        "path": "lib/World.lua"
    }
}