filtergc

filtergc(kind: "function" | "table", options: table, returnOne: boolean?) -> any | { any }
filtergc(predicate: (object) -> boolean, options: table?, returnOne: boolean?) -> any | { any }

Searches the objects the garbage collector is tracking and returns those that match. Matching happens during the collector walk, so filtergc builds far less garbage than iterating getgc yourself and is the right tool whenever you are looking for something specific. Athena accepts two forms: a kind + options filter, or a predicate function you supply.

Parameters

"function" | "table"

The category to search. "function" walks closures; "table" walks tables. Replace this with a predicate function to match with your own logic.

(object) -> boolean

Alternative to kind. Called with each candidate object; return true to keep it. When a predicate is used, every collectable object is offered to it.

table

The match criteria. The accepted keys depend on kind (see below). With a predicate, options is ignored and may be omitted.

boolean

default:"false"

When true, returns the first match instead of an array. When no object matches, returns nil.

Returns

any | table

With returnOne set, the first matching object or nil. Otherwise a fresh array of every match.

Used when kind is "function".

Option	Type	Matches when
`Name`	`string`	The function’s name equals this. For anonymous functions, matched against its `function: 0x…` address text.
`Source`	`string`	The function’s short source name equals this.
`StartLine`	`number`	The function’s defined line equals this. C functions report `-1`.
`Environment`	`table`	The function’s global environment is exactly this table.
`UpvalueCount`	`number`	The function has exactly this many upvalues.
`ConstantCount`	`number`	The function has exactly this many visible constants (Luau functions only).
`Constants`	`table`	Every value listed appears among the function’s visible constants.
`Upvalues`	`table`	Every value listed appears among the function’s upvalue values.
`Hash`	`string`	The function’s bytecode hash equals this (see `getfunctionhash`).
`IgnoreExecutor`	`boolean`	Default `true`. When `true`, functions Athena created are excluded from results.

Constants, Upvalues, ConstantCount, and Hash only apply to Luau closures. A C closure can never match them, so requesting any of them quietly excludes every C function from the results. Used when kind is "table".

Option	Type	Matches when
`Keys`	`table`	Every listed key exists in the table.
`Values`	`table`	Every listed value appears in the table.
`KeyValuePairs`	`table`	Every listed key maps to the listed value.
`Metatable`	`table`	The table’s metatable is exactly this table.

Behavior

Snapshot then match. filtergc snapshots the matching category under a GC hold, then tests each candidate. The result array is never included in itself.
All criteria must hold. Within one call, every option you set must match (logical AND). To match alternatives, make separate calls.
IgnoreExecutor defaults on. By default your own functions are filtered out, so you find the game’s code rather than your own. Set it to false when you specifically want to inspect Athena-created functions.
Predicate form. When the first argument is a function, it is called for every live collectable object and decides matches itself. An error thrown inside the predicate is treated as “no match” for that object rather than aborting the search.

Example

Find a module cache by the fields it holds, the kind of lookup you’d use to hook into a game’s own code:

local cache = filtergc("table", {
    Keys = { "NetworkClient", "ScreenCull" },
}, true)

if cache then
    print("found the module table:", cache)
end

Errors

Message	Condition
`Expected type 'function' or 'table'`	The first argument was neither a predicate function nor one of the strings `"function"` / `"table"`.

getgc: the unfiltered snapshot filtergc searches.
getfunctionhash: produce the value Hash matches against.

Getting Started

Environment

Closures

Scripts

Reflection

Metatable

Instances

Cache

Signals

Signal

Actors

LuaStateProxy

Console

Input

Drawing

Filesystem

Encoding

Crypt

HTTP

WebSocket

RakNet

Miscellaneous

oth

Parameters

Returns

Behavior

Example

Errors

​Parameters

​Returns

​Function filter options

​Table filter options

​Behavior

​Example

​Errors

​Related

Parameters

Returns

Function filter options

Table filter options

Behavior

Example

Errors

Related