Skip to content

Namespace Apogee.Scripting

Classes

DefinitionOptions

What a host adds to or takes out of the definitions.

DefinitionWriter

Writes the engine's API as Luau type definitions (apogee.d.luau) for luau-lsp, from the registry: the classes, enums and script libraries the generator described, and the hand-written natives with the declarations they were registered with. The output depends only on the registry, in a fixed order.

Easing

The easing functions (Robert Penner's set, written from the formulas).

HostGlobal

A global that the host sets in its VMs (), which the definitions declare for the scripts that run there.

HotReloader

Reloads what changed on disk while the game runs (a development run, the editor). , called from the thread that owns the VM, takes the changes a has noticed and sorts them: a .luau file that a script has required is a module reload (: updated in place, the old one stays if the new one fails); a definition or schema in a package's content or schema folders makes the definitions be read again ( is replaced and defs.on_change listeners are called); an image or model is imported again (when the project has been imported: imported/index.xml) and says which; a .slang file raises , for the renderer to rebuild what uses it (the engine's renderers do not yet). A change that cannot be applied to a running game (a package's mod.xml, a script that only runs once) is listed in .

LuauTestRunner

Runs the *.test.luau files under a folder, each in a VM of its own (so one file's globals, modules and worlds cannot touch another's). A file's describe bodies run as it loads; its cases then run in order, one frame at a time, with @engine/test.

LuauVm

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.

LuauVmOptions

ModuleReload

What did.

PackageLoader

Runs the packages of a in a VM. Each package's scripts run in the order its manifest lists them, packages in load order; a package's base-game scripts run as the VM's base owner, a mod's as an owner of its own (its own memory category and limits), with:

  • @<id>/… as a require alias for each package, so that a mod can use a dependency's modules;
  • confinement: a mod may require files of its own package and of the packages it depends on (and res://), nothing else;
  • the fs library with the same rules: a mod reads res://, its own package, its dependencies', and user://moddata/<id>/, and writes only user://moddata/<id>/;
  • modules that run as the owner of the package they are in, whoever required them.

A script that fails stops its package (the error is logged and in the result), and what depends on it is not run; it never stops the game. Content the package brought stays loaded.

PackageLoaderOptions

PackageRunResult

What happened to a package's scripts.

PhysicalScriptFileSystem

Scripts from a folder of the real file system.

ReferenceWriter

Writes the engine's Luau API as Markdown pages for the Manual (--luau-docs), from the same registry as : one page per class (classes/Name.md), one per script library (libraries/name.md), one for all enums (enums.md) and reference.md, which lists everything with the host's globals. The output depends only on the registry, in a fixed order, with \n line ends.

ReloadReport

What one did.

ScriptException

A script failed. The message is the script's, with its traceback for a runtime error.

ScriptNatives

Methods of a class that are written by hand against the Luau stack because they take tables, functions or variable shapes that the registry cannot describe (the ECS calls on World). A native sees the stack as a method does: the object at index 1, then the arguments; it returns the number of results it pushed, and throws a for a script error. Each comes with its .d.luau declaration, so the definitions cannot lack one.

ScriptOwner

Whose code is running: the base game or one mod. Everything an owner's scripts allocate is counted in the owner's memory category of the VM, and its calls get the owner's time budget, so one mod cannot use up the memory or the frame of the others.

ScriptScheduler

The tasks of one VM (and its tweens, which it steps and cancels along with them): what task.spawn, task.defer, task.delay and task.every start, and what task.wait puts to sleep. A task is a Luau thread the scheduler resumes: at once (spawn), at the next drain (defer), when its time comes (delay, wait, every). There is no clock in here: says how much game time and real time passed, so a test drives it with a fake clock and the engine drives it with the frame. Every resume is a protected resume under the time budget of the task's owner, and the thread keeps the memory category of the script that started it. Not thread safe: use it from the thread that made the VM.

TestFailure

TestFileResult

TestRunResult

Tween

An animation that tween.value, tween.property and tween.field start: a number, a vector, a colour (a linear-RGB vector) or a rotation (slerped) moving from one value to another over some seconds, with an easing curve. It plays by itself, on the game clock (or the real clock with the unscaled option), stepped by . A playing tween stays alive when the script drops the handle. A tween on a property or a component field makes no Luau call per frame.

VfsScriptFiles

Scripts from the content file system: res://main.luau, mod://my_mod/ui.luau. Give it to and add the prefixes scripts may load from with .

Interfaces

IScriptFileSystem

Where scripts are read from. The VM only sees paths with / as the separator, plain ones or res://-style ones; reads them from the content file system.

Enums

Ease

The easing curves of tween: how the progress of a tween (0 to 1 in time) maps to the progress of its value. Scripts name them in snake_case (quad_in_out). The In curves start slowly, the Out ones end slowly and the InOut ones do both. Back, Elastic and Bounce go past the ends of the range on the way.

ScriptErrorKind