An embedded, sandboxed Luau virtual machine with a QVariant API.
More...
#include <PhosphorScripting/LuauEngine.h>
|
| | LuauEngine (std::shared_ptr< LuauWatchdog > watchdog=nullptr, std::size_t memoryCapBytes=DefaultMemoryCapBytes) |
| | watchdog may be shared across engines; nullptr disables the timeout safety net (useful for short, trusted scripts in tests).
|
| | ~LuauEngine () |
| | LuauEngine (const LuauEngine &)=delete |
| LuauEngine & | operator= (const LuauEngine &)=delete |
| bool | init (QString *error=nullptr) |
| | Create the VM, open the (restricted) standard libraries, and wire the interrupt callback.
|
| bool | runPrelude (const QString &chunkName, const QByteArray &source, QString *error=nullptr) |
| | Compile + run a chunk that installs host globals.
|
| void | sandbox () |
| | Freeze the global table and standard libraries.
|
| int | loadModule (const QString &chunkName, const QByteArray &source, QString *error=nullptr) |
| | Compile + load a module chunk and run it; the chunk is expected to return a table.
|
| void | releaseModule (int handle) |
| | Release a module handle from loadModule.
|
| QVariant | moduleField (int moduleHandle, const QString &key) const |
| | Read a (non-function) field from a loaded module as a QVariant.
|
| bool | hasFunction (int moduleHandle, const QString &name) const |
| | Whether the module exposes a callable field named name.
|
| CallOutcome | callModule (int moduleHandle, const QString &function, const QVariantList &args, int timeoutMs) |
| | Call module[function](args...) under the watchdog, returning a single result.
|
| bool | isValid () const noexcept |
| std::size_t | memoryUsedBytes () const noexcept |
| | Live heap bytes currently allocated by the VM (host accounting).
|
| std::size_t | peakMemoryBytes () const noexcept |
| | High-water mark of memoryUsedBytes over the engine's lifetime.
|
| std::size_t | memoryCapBytes () const noexcept |
| | The configured heap ceiling (0 = unlimited).
|
|
| static constexpr std::size_t | DefaultMemoryCapBytes = 64ull * 1024 * 1024 |
| | Default per-engine heap ceiling for untrusted script execution.
|
An embedded, sandboxed Luau virtual machine with a QVariant API.
Lifecycle: construct → init → runPrelude (zero or more, to install host globals such as a pluau standard library) → sandbox (freeze globals
The lua_State is private: the public surface is entirely QVariant-based so no Luau symbols cross the library boundary. Domain bindings marshal their params into nested QVariantMap/QVariantList and read results back the same way.
Not thread-safe — like the underlying VM, all calls must occur on the owning thread. Runaway scripts are bounded by the shared LuauWatchdog.
◆ CallStatus
| Enumerator |
|---|
| Ok | |
| TimedOut | |
| Error | |
◆ LuauEngine() [1/2]
watchdog may be shared across engines; nullptr disables the timeout safety net (useful for short, trusted scripts in tests).
memoryCapBytes caps heap allocated once the engine is sandboxed (0 = unlimited); the watchdog bounds CPU time, this bounds memory. See sandbox.
◆ ~LuauEngine()
| PhosphorScripting::LuauEngine::~LuauEngine |
( |
| ) |
|
◆ LuauEngine() [2/2]
| PhosphorScripting::LuauEngine::LuauEngine |
( |
const LuauEngine & | | ) |
|
|
delete |
◆ callModule()
| CallOutcome PhosphorScripting::LuauEngine::callModule |
( |
int | moduleHandle, |
|
|
const QString & | function, |
|
|
const QVariantList & | args, |
|
|
int | timeoutMs ) |
Call module[function](args...) under the watchdog, returning a single result.
timeoutMs <= 0 means no timeout. A result too large to convert (see Marshal::MaxNodes and Marshal::MaxBytes) is reported as CallStatus::Error, not as a nil.
◆ hasFunction()
| bool PhosphorScripting::LuauEngine::hasFunction |
( |
int | moduleHandle, |
|
|
const QString & | name ) const |
Whether the module exposes a callable field named name.
◆ init()
| bool PhosphorScripting::LuauEngine::init |
( |
QString * | error = nullptr | ) |
|
Create the VM, open the (restricted) standard libraries, and wire the interrupt callback.
Returns false (and sets error) on failure.
◆ isValid()
| bool PhosphorScripting::LuauEngine::isValid |
( |
| ) |
const |
|
inlinenoexcept |
◆ loadModule()
| int PhosphorScripting::LuauEngine::loadModule |
( |
const QString & | chunkName, |
|
|
const QByteArray & | source, |
|
|
QString * | error = nullptr ) |
Compile + load a module chunk and run it; the chunk is expected to return a table.
Returns a handle (>= 0) to that table, or -1 on error.
◆ memoryCapBytes()
| std::size_t PhosphorScripting::LuauEngine::memoryCapBytes |
( |
| ) |
const |
|
inlinenoexcept |
The configured heap ceiling (0 = unlimited).
◆ memoryUsedBytes()
| std::size_t PhosphorScripting::LuauEngine::memoryUsedBytes |
( |
| ) |
const |
|
inlinenoexcept |
Live heap bytes currently allocated by the VM (host accounting).
◆ moduleField()
| QVariant PhosphorScripting::LuauEngine::moduleField |
( |
int | moduleHandle, |
|
|
const QString & | key ) const |
Read a (non-function) field from a loaded module as a QVariant.
Returns an invalid QVariant if the handle/key is absent.
◆ operator=()
◆ peakMemoryBytes()
| std::size_t PhosphorScripting::LuauEngine::peakMemoryBytes |
( |
| ) |
const |
|
inlinenoexcept |
◆ releaseModule()
| void PhosphorScripting::LuauEngine::releaseModule |
( |
int | handle | ) |
|
◆ runPrelude()
| bool PhosphorScripting::LuauEngine::runPrelude |
( |
const QString & | chunkName, |
|
|
const QByteArray & | source, |
|
|
QString * | error = nullptr ) |
Compile + run a chunk that installs host globals.
Must be called BEFORE sandbox while the global table is still writable.
◆ sandbox()
| void PhosphorScripting::LuauEngine::sandbox |
( |
| ) |
|
Freeze the global table and standard libraries.
Call once, after all preludes and before loading untrusted modules.
◆ DefaultMemoryCapBytes
| std::size_t PhosphorScripting::LuauEngine::DefaultMemoryCapBytes = 64ull * 1024 * 1024 |
|
staticconstexpr |
Default per-engine heap ceiling for untrusted script execution.
Generous headroom over a tiling algorithm's real working set (which is well under 1 MiB beyond the ~1–2 MiB VM + stdlib baseline), while still bounding a runaway allocation long before it can exhaust the host.
The documentation for this class was generated from the following file: