result
The handle asset.list returns.
A query result is the array of matched AssetRef handles. Entry 1 is the
first match, #rows is the count, ipairs(rows) walks it, and anything that
accepts a list of refs accepts it unchanged. The handle adds methods on top of
that array through a metatable, so reading the result stays one expression.
local hero = asset.list({ type = "mesh", fields = { tags = "hero" } }):first()
local prop = asset.list({ type = "mesh", path = "/zero/source/props" }):random()
asset.list("material")
:filter(function(m) return m.name:find("rust") ~= nil end)
:each(function(m) print(m.identity) end)
Methods
| Method | Returns |
|---|---|
:first() / :last() | One entry, or nil when the query matched nothing. |
:random() | One entry chosen at random, or nil. |
:count() | How many entries matched. |
:isEmpty() | Whether nothing matched. |
:each(fn) | The same result, after calling fn(entry, index) in order. |
:map(fn) | A new result holding fn(entry, index) per entry. |
:filter(predicate) | A new result holding the entries kept. |
:sort(comparator?) | A new, ordered result; ordered by identity when the comparator is omitted. |
:toArray() | The entries as a plain table, without the handle. |
:map, :filter, and :sort return new results carrying the same methods, so
they chain. :sort leaves the result it was called on as it is.
Ordering
asset.list already returns its matches ordered — by identity unless the query
asks for another field with order — so :first() names the same asset on
every call. :sort is for orders the query cannot express, such as one computed
from an entry's fields.
What the handle does not change
The metatable carries __index alone. Length, ipairs, pairs, next,
table.*, and serialisation all read the array part, so a result behaves
exactly as a plain array everywhere those are used.
Scoped to this part · feeds back into the world's score.