---

@nrbx/luau-vm

A loadstring-like LuaU VM for Roblox-TS projects, allowing you to execute Luau code from strings in-game and by code instead of using Roblox's loadstring() function.

The code which makes up this VM is constructed from my own typings, and the code from other authors who've made Fiu, the Compiler and the Base64 modules.

It ships a full Luau compiler and an interpreter ("Fiu"), so you can compile and run arbitrary Luau at runtime — no loadstring required.

Installation

yarn add @nrbx/luau-vm
npm install @nrbx/luau-vm
pnpm add @nrbx/luau-vm

Then add the following to your Rojo project file, under your node_modules configuration.

"node_modules": {
  "$className": "Folder",
  "@rbxts": {
    "$path": "node_modules/@rbxts"
  },
  "@nrbx": {
    "$path": "node_modules/@nrbx"
  }
}

And this to your tsconfig.json

"typeRoots": ["node_modules/@rbxts", "node_modules/@nrbx"],

Quick Start

Require the VM and call it with a Luau source string. The returned function is the loaded chunk — call it to execute:

import VM from "@nrbx/luau-vm";

const code = 'Instance.new("Part", game.Workspace)';

// Compile and load, then run
VM(code)();

Usage

The module is a callable table: it can be invoked directly to compile and load code, and exposes compile to produce base64-encoded bytecode ahead of time.

import VM from "@nrbx/luau-vm";
const Payload = 'Instance.new("Part", game.Workspace)';

// Compile + run in one go
VM(Payload)()
VM(Payload, false)() // or for explicitly stating it's not a compiled string

Pre-compiling for later use

import VM from "@nrbx/luau-vm";
const Payload = 'Instance.new("Part", game.Workspace)';

// Compile the source into base64-encoded bytecode once...
const Compiled = VM.compile(Payload);

// ...then load and run it whenever you need (no recompilation)
VM(Compiled, true)()

The true second argument tells the VM the string is already compiled base64 bytecode, so it skips the compiler and goes straight to loading.

API

compile(source)

Compiles Luau source code to bytecode and returns it as a base64-encoded string. Useful for caching/transporting compiled code so it only has to be compiled once.

const bytecode = VM.compile('print("hi")');

Argument	Type	Description
source	string	The Luau source code to compile

Returns string — base64-encoded bytecode.

VM(source, isPureBytecode?)

Compiles (or decodes) and loads the code into a function. It does not run it — call the returned function to execute.

// From raw source
VM('print("hello")')();

// From pre-compiled base64 bytecode
const bytecode = VM.compile('print("hello")');
VM(bytecode, true)();

Argument	Type	Default	Description
source	string	—	Luau source, or base64-encoded bytecode when isPureBytecode is true
isPureBytecode	boolean?	false	Whether source is already compiled bytecode

Returns () => () — the loaded function. Call it to execute the code.

Development

# Install dependencies
yarn install

# Compile with roblox-ts
yarn build

# Watch mode
yarn watch

# Lint + format with Biome
yarn biome

License

MIT

---