Environment · Function

filtergc

Search Luau garbage-collected objects using structured filters.

function filtergc(filterType: "function" | "table", filterOptions: table, returnOne?: boolean): any

Synopsis

How it works

Scans the Luau garbage collectorGarbage collectorLuau uses an incremental tri-color mark-and-sweep GC. Objects are white (unreached), gray (reached, children not scanned), or black (fully scanned). The GC runs incrementally across frames to avoid pauses.’s object list and returns objects matching the specified filter. For "function" type, you can filter by name, upvalueUpvalueA variable captured from an enclosing scope. When a function references a local variable from an outer function, that variable becomes an upvalue — stored in an UpVal struct that persists even after the outer function returns. count, constant values, etc. For "table" type, you can filter by keys or values. This is more targeted than getgc() — the filtering happens in C before building the result array.

Performance

Because filtering is done at the C level during GC traversal, filtergc is significantly faster than calling getgc() and looping in Lua. Use the returnOne parameter to stop scanning after the first match when you only need a single object. Common filters:

{ Name = "functionName" } — match by debug name
{ UpvalueCount = 3 } — match by upvalueUpvalueA variable captured from an enclosing scope. When a function references a local variable from an outer function, that variable becomes an upvalue — stored in an UpVal struct that persists even after the outer function returns. count
{ Constants = { "string" } } — match closures containing a specific constant

Usage

Find a function by its string constant

local target = filtergc("function", {
    Constants = { "SuperSecretKey" }
}, true)

if target then
    print("Found target function:", target)
end

Find all tables with a specific key

local results = filtergc("table", { Keys = { "PlayerData" } })
for _, tbl in ipairs(results) do
    print("Found table with PlayerData key:", tbl)
end

Parameters

filterType "function" | "table"

The type of GC object to search for.

filterOptions table

Filter criteria. Fields depend on filterType — see FunctionFilterOptions or TableFilterOptions.

returnOne boolean optional

If true, returns the first match directly. If false or omitted, returns a table of all matches.

Returns

any A table of matches, or a single object if returnOne is true. Returns nil if no match when returnOne=true.

Function filters

For functions: Name (string), Hash (SHA-384 hex), Constants (array of values), Upvalues (array of values).

Table filters

For tables: Keys (array), Values (array), Metatable (table reference).

C closures

Filters like Constants and Hash do not apply to C closures and will never match them.