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
public sealed class LuauVm : IDisposable, IScriptEnvironments
Inheritance¶
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¶
ConnectionCount¶
The signal connections scripts hold that are still live.
public int ConnectionCount { get; }
Property Value¶
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¶
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¶
NativeCodeEnabled¶
public bool NativeCodeEnabled { get; }
Property Value¶
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¶
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 (
public ScriptEnvironment Create()
Returns¶
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¶
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
public IReadOnlyList<Value> Execute(ScriptOwner owner, string chunkName, string source)
Parameters¶
owner ScriptOwner
chunkName string
source string
Returns¶
IsModuleLoaded(string)¶
public bool IsModuleLoaded(string path)
Parameters¶
path string
Returns¶
MemoryUsed()¶
Bytes the VM has allocated, all owners together.
public long MemoryUsed()
Returns¶
NotifyDefsChanged()¶
Calls the functions scripts gave to defs.on_change. The host does this after it set
public void NotifyDefsChanged()
ProcessPending()¶
Destroys the objects scripts made and let go of, and releases function references that were dropped. Called after every
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¶
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?