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

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. The filtering is done at the archetype level, and so it is faster than manually skipping entities. 

for id in world:query(Target):without(Model) do
	-- Do something
end

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}.

view​

</>
QueryResult:view() → View

Creates a View of the query and does all of the iterator tasks at once at an amortized cost. This is used for many repeated random access to an entity. If you only need to iterate, just use a query. 

local inflicting = world:query(Damage, Hitting, Player):view()
for _, source in world:query(DamagedBy) do
	local damage = inflicting:get(source.from)
end

for _ in world:query(Damage):view() do end -- You can still iterate views if you want!
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```\n\n\t",
            "params": [],
            "returns": [
                {
                    "desc": "Entity ID",
                    "lua_type": "id"
                },
                {
                    "desc": "The requested component values",
                    "lua_type": "...ComponentInstance"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 741,
                "path": "lib/World.luau"
            }
        },
        {
            "name": "without",
            "desc": "Returns an iterator that will skip any entities that also have the given components.\nThe filtering is done at the archetype level, and so it is faster than manually skipping entities.\n\n\n```lua\nfor id in world:query(Target):without(Model) do\n\t-- Do something\nend\n```\n\t",
            "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": 827,
                "path": "lib/World.luau"
            }
        },
        {
            "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}`.\n\n\t",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{{entityId: number, component: ComponentInstance, component: ComponentInstance, component: ComponentInstance, ...}}"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 907,
                "path": "lib/World.luau"
            }
        },
        {
            "name": "view",
            "desc": "Creates a View of the query and does all of the iterator tasks at once at an amortized cost.\nThis is used for many repeated random access to an entity. If you only need to iterate, just use a query.\n\n```lua\nlocal inflicting = world:query(Damage, Hitting, Player):view()\nfor _, source in world:query(DamagedBy) do\n\tlocal damage = inflicting:get(source.from)\nend\n\nfor _ in world:query(Damage):view() do end -- You can still iterate views if you want!\n```\n\n\t",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "View"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 953,
                "path": "lib/World.luau"
            }
        }
    ],
    "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": 644,
        "path": "lib/World.luau"
    }
}