Skip to content

Class LuauVm

Namespace: Apogee.Scripting
Assembly: Apogee.Scripting.dll

One Luau VM for the game and its mods. Every script runs in a thread of its own with its own globals over the read-only ones (luaL_sandbox), and belongs to a : the owner's memory category counts what it allocates, and its time budget limits each call. Not thread safe: use it from the thread that made it.

public sealed class LuauVm : IDisposable, IScriptEnvironments

Inheritance

object ← LuauVm

Implements

IDisposable, IScriptEnvironments

Inherited Members

object.Equals(object?), object.Equals(object?, object?), object.GetHashCode(), object.GetType(), object.ReferenceEquals(object?, object?), object.ToString()

Constructors

LuauVm(LuauVmOptions?)

public LuauVm(LuauVmOptions? options = null)

Parameters

options LuauVmOptions?

Properties

BaseOwner

The engine's and the base game's own scripts.

public ScriptOwner BaseOwner { get; }

Property Value

ScriptOwner

ConnectionCount

The signal connections scripts hold that are still live.

public int ConnectionCount { get; }

Property Value

int

Defs

The definitions scripts read through the defs library. Null (the default): the library is there and finds nothing. Setting it again (a reload) makes scripts see the new definitions from their next call; tables they already hold stay as they were.

public DefDatabase? Defs { get; set; }

Property Value

DefDatabase?

EngineModules

The engine's own Luau modules (@engine/test…): name and source, from the library's embedded resources.

public static IReadOnlyList<(string Name, string Source)> EngineModules { get; }

Property Value

IReadOnlyList<(string Name, string Source)>

LoadedModules

The modules require has loaded from files, by path.

public IReadOnlyCollection<string> LoadedModules { get; }

Property Value

IReadOnlyCollection<string>

NativeCodeEnabled

public bool NativeCodeEnabled { get; }

Property Value

bool

Scheduler

The tasks scripts started with the task library (sleeping, deferred and running) and the tweens of the tween library.

public ScriptScheduler Scheduler { get; }

Property Value

ScriptScheduler

Methods

AddAlias(string, string)

Makes require("@name/x") mean path plus /x for every script (a package's id for its folder, mod://cool).

public void AddAlias(string name, string path)

Parameters

name string

path string

AddEmbeddedModule(string, string)

Adds a module of the engine, required as @engine/name.

public void AddEmbeddedModule(string name, string source)

Parameters

name string

source string

AddRoot(string)

Lets require load files below directory; nothing outside the roots can be required.

public void AddRoot(string directory)

Parameters

directory string

AdvanceTime(double, double)

Moves the game clock by gameSeconds and the real clock by realSeconds (the game's time scale makes them differ), resumes the tasks that are due, steps the tweens, and then runs the deferred tasks (which includes the ones whose Tween:wait just ended). There is no clock inside the VM: this is how time passes for scripts, so a test calls it with a fake one.

public void AdvanceTime(double gameSeconds, double realSeconds)

Parameters

gameSeconds double

realSeconds double

CollectGarbage()

Runs a full collection: what no script can reach any more is freed, and the owners' counts drop.

public void CollectGarbage()

Create()

A new environment for the script that is calling the engine (); the base game's when none is.

public ScriptEnvironment Create()

Returns

ScriptEnvironment

CreateOwner(string, bool, long, int)

Makes an owner (a mod) with its own memory category: up to 255 in one VM.

public ScriptOwner CreateOwner(string id, bool isMod, long memoryLimit = 0, int timeBudgetMilliseconds = 0)

Parameters

id string

isMod bool

memoryLimit long

timeBudgetMilliseconds int

Returns

ScriptOwner

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Execute(ScriptOwner, string, string)

Compiles and runs a chunk as owner and returns what it returns. A chunk name that starts with @ is a path (relative requires start from its folder); =name is a name for messages only. Failures are s.

public IReadOnlyList<Value> Execute(ScriptOwner owner, string chunkName, string source)

Parameters

owner ScriptOwner

chunkName string

source string

Returns

IReadOnlyList<Value>

IsModuleLoaded(string)

public bool IsModuleLoaded(string path)

Parameters

path string

Returns

bool

MemoryUsed()

Bytes the VM has allocated, all owners together.

public long MemoryUsed()

Returns

long

NotifyDefsChanged()

Calls the functions scripts gave to defs.on_change. The host does this after it set again; a listener that fails is logged and the others still run.

public void NotifyDefsChanged()

ProcessPending()

Destroys the objects scripts made and let go of, and releases function references that were dropped. Called after every ; a game loop can call it too.

public void ProcessPending()

ReloadModule(string)

Runs a loaded module again from its file and updates it where it is: the module's table that every script that required it holds gets the new fields (and loses the ones the new code does not have), so they see the new functions without being reloaded themselves. What the module registered when it first loaded (functions that draw, signal connections, systems, defs.on_change listeners) is taken back and registered again by the new run. If the new code fails (a syntax error, a runtime error, a timeout) nothing changes: the old module and its registrations stay. A module may have a function on_reload(new, old), called before the update, to take state from the old table. A function a script copied into a local (local f = module.f) stays the old one; a module that returns something other than a table is replaced in the cache only.

public ModuleReload ReloadModule(string path)

Parameters

path string

Returns

ModuleReload

RunDeferred()

Runs the tasks that were deferred (task.defer) since the last time they ran: what the end of a frame does for the ones that GUI functions, UI handlers and signals deferred after the frame's step.

public void RunDeferred()

SetGlobal(string, EngineObject?)

Makes value a global of every script (read-only for them), such as world. Null removes it.

public void SetGlobal(string name, EngineObject? value)

Parameters

name string

value EngineObject?