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.
:searchable()	A new result without the deprecated assets, the ones a search or a picker offers.
: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.