Skip to content

Execution and lifecycle

Context isolation

Create one DreamContext per independent script environment. Contexts own separate VMs and global environments; operations within one context are serialized because the VM is not thread-safe.

await using var runtime = new DreamRuntime(new NuLuaBackend());
await using var first = runtime.CreateContext();
await using var second = runtime.CreateContext();

first.SetGlobal("score", 10);
using var value = second.GetGlobal("score");
Console.WriteLine(value.Kind); // Nil

Execute source and files

using var result = await context.ExecuteStringAsync(source, "player-script.luau", cancellationToken);

var values = await context.CallFunctionAsync("onStart", ["level-1"], cancellationToken);
foreach (var value in values)
    value.Dispose();

ExecuteFileAsync reads a UTF-8 script file when AllowFileExecution is enabled. File execution is enabled by default. Returned DreamResult and backend composite values should be disposed. DreamResult.Dispose() disposes all values it contains.

GetGlobal returns an IDreamValue; dispose returned tables and functions when finished. Primitive wrappers also implement IDisposable and can be disposed safely.

Errors and cancellation

Script failures are wrapped in DreamRuntimeException, which includes the script name and inner exception. OperationCanceledException is passed through.

Cancellation is cooperative around async resume points. It can stop waiting for a context or be observed at a backend resume boundary. It cannot interrupt a pure Luau infinite loop already running inside NuLua. Do not treat cancellation as an execution timeout.

Cleanup

Contexts dispose their VM, scheduler work, and tracked resources. Context-owned signal subscriptions are removed automatically. Disposing a runtime disposes every context it created.

Prefer await using for runtime and contexts. Explicit resource ownership is also available through context.OwnResource(resource).