Actors & threads

Enumerate live and deleted Actor states, run code and communicate between VMs.

13 functionssUNC 100%Lynx 0.0.0

Actor enumeration exposes actual Instances and threads, not a proxy userdata type. A destroyed Actor can leave a pooled VM state alive: getactors() includes its thread and getdeletedactors() selects only those orphan states. A deleted Actor object and a collected VM state are different lifetimes.

getactors

getactors(): {Actor | thread}

Enumerates readable actor-pool states. A pool entry with a live Actor returns that Actor Instance; an entry whose Actor expired returns its native thread. Ordering is the pool traversal order.

Also available as get_actors.

Returns

{Actor | thread}

Mixed snapshot of live Actor objects and deleted-Actor state threads.

Example

for i, actor in ipairs(getactors()) do
print(i, typeof(actor), actor)
end

getdeletedactors

getdeletedactors(): {thread}

Enumerates only actor-pool entries whose Actor weak reference has expired. Entries are retained VM-state threads; this does not resurrect destroyed Instances.

Also available as get_deleted_actors.

Returns

{thread}

Threads of deleted Actor states that still exist in the pool.

Example

for i, thread in ipairs(get_deleted_actors()) do
print(i, typeof(thread), thread)
end

getactorstates

getactorstates(): {thread}

Returns the state threads discovered by the native actor-state pool reader, without replacing live entries by Actor Instances.

Also available as getactorthreads.

Returns

{thread}

Actor VM-state thread snapshot.

Example

for _, thread in ipairs(getactorstates()) do print(thread) end

getallthreads

getallthreads(): {thread}

Walks the current shared-extra-space AllThreads chain and resolves its nodes against non-dead same-VM GC threads, including the current and main thread when present in that chain. It is not a process-wide inventory across every Actor VM.

Returns

{thread}

Resolvable threads belonging to the current shared list; empty when shared state is unavailable.

Example

for i, thread in ipairs(getallthreads()) do
print(i, typeof(thread), thread)
end

getgamestate

getgamestate(): thread?

Requests the native game state from the current script context using the ordinary script identity selector.

Also available as get_game_state.

Returns

thread?

Game-state thread, or nil when the state reader returns no state.

Example

local state = getgamestate()
print(typeof(state), state)

getluastate

getluastate(object: Instance? = nil): thread?

Without an argument, returns the calling thread. LocalScript and Script inputs resolve their native script state; Actor inputs resolve a known state or create a temporary child LocalScript to obtain one.

Other valid Instances return the calling thread. An Actor whose state remains unavailable raises Thread unavailable.

Also available as get_lua_State.

Parameters

objectInstance?
Optional.Optional Actor or script whose state is requested. Default nil.

Returns

thread?

Selected native thread; a null native script-state result becomes nil.

Example

local state = getluastate()
print(state == coroutine.running())

getactorfromthread

getactorfromthread(thread: thread? = coroutine.running()): Actor?

Reads the live Actor linked to a thread extra space. A thread with no extra space or an expired Actor reference returns nil; invalid state memory raises an argument error.

Also available as get_actor_from_thread.

Parameters

threadthread?
Optional.Thread to inspect. Default coroutine.running().

Returns

Actor?

Linked live Actor, or nil.

Example

print(getactorfromthread(coroutine.running()))

getcurrentactor

getcurrentactor(): Actor?

Reads the live Actor linked to the calling thread. It returns nil outside an Actor or after that Actor reference expires.

Also available as get_current_actor.

Returns

Actor?

Calling thread Actor, or nil.

Example

print(getcurrentactor())

isparallel

isparallel(): boolean?

Reads the active DataModel parallel-execution flag. If no ScriptContext or DataModel is available, the implementation returns no values.

Also available as is_parallel, check_parallel and checkparallel.

Returns

boolean?

Current parallel flag; nil when the native context is unavailable.

Example

print(isparallel())

runonactor

runonactor(actor: Actor | thread, source: string, ...: any): ()

Queues source in a new module-marked coroutine of the selected Actor state. Pass a live Actor Instance, or a deleted-state thread returned by getdeletedactors. A live-state thread input raises Actor still active; unknown or invalid state threads are rejected.

Also available as run_on_actor.

Parameters

actorActor | thread
Destination state selector.
sourcestring
Luau source to compile and schedule.
...any
Arguments received as varargs by the new source chunk.

Returns

()

No direct results; queued source runs through the target VM scheduler.

Example

local target = getactors()[1]
if target then
runonactor(target, [[
local message = ...
print(message, getcurrentactor())
]], "hello")
end

run_on_thread

run_on_thread(thread: thread, source: string, ...: any): ()

Queues source in a fresh module-marked coroutine belonging to the target thread VM. It does not resume or overwrite the supplied coroutine body.

Parameters

threadthread
Destination state selector.
sourcestring
Luau source to compile and schedule.
...any
Arguments received as varargs by the new source chunk.

Returns

()

No direct results; queued source runs through the target VM scheduler.

Example

local target = coroutine.running()
if target then
run_on_thread(target, [[
local message = ...
print(message, getcurrentactor())
]], "hello")
end

create_comm_channel

create_comm_channel(): (number, BindableEvent?)

Allocates a numbered communication channel backed by a native BindableEvent and stores it in the module channel map. If event creation fails, the second result is nil.

Returns

number, BindableEvent?

Channel identifier and backing BindableEvent.

Example

local id, channel = create_comm_channel()
if channel then
local connection = channel.Event:Connect(print)
channel:Fire("hello")
connection:Disconnect()
end

get_comm_channel

get_comm_channel(id: number): BindableEvent?

Looks up the BindableEvent associated with a module communication channel identifier. Unknown identifiers return nil.

Parameters

idnumber
Previously created integer channel identifier.

Returns

BindableEvent?

Existing channel event, or nil.

Example

local id, original = create_comm_channel()
print(get_comm_channel(id) == original)

State-created event

on_actor_state_created is a module Signal value. Its callback receives one live Actor Instance after that Actor state has been created and queued for delivery in the bound module VM. Reset/teleport invalidates older pending events; this is not an event for every new coroutine.

local connection = on_actor_state_created:Connect(function(actor)
print("Actor state ready:", actor)
end)
-- When no longer needed:
connection:Disconnect()

Written for Lynx 0.0.0

Something unclear? Tell us on Discord