LuauToolkit

A collection of various Luau-related libraries.

[!WARNING] LuauToolkit is deeply unstable and is far from production ready.

Structure

Modules

The library is split into the following:

Binaries

Some modules also have command line applications, accessible under the bin/ directory.

Examples

A series of examples can be found under the examples/ directory.

You can run an example with:

lune run examples/<path_to_example> [args]

# eg:
lune run examples/bytecode/strip chunk.luauc stripped.luauc

Documentation

Documentation can be found here.

Installation

To install luau_toolkit, copy the lib/ directory to wherever you'd like to install the library, and rename it to luau_toolkit.

Optionally, create an @luau_toolkit alias in your .luaurc file to make the library accessible with require("@luau_toolkit/<module>"):

{
    //...
    "aliases": {
        "luau_toolkit": "./path/to/library"
    }
    //...
}

Modules

Parts

• Bytecode Module

Bytecode Module

Introduction

The bytecode module provides functionality for generating and manipulating Luau bytecode.

Testing

LuauToolkit comes with a test suite.

lune run tests          # Run all tests
lune run tests bytecode # Run all bytecode tests
lune run tests --werror # Run all tests and treat warnings as errors

Dependencies and Tools

Luau Internals

This section contains information about the Luau language internals.

Parts

• Bytecode Format

Bytecode Format

1. Introduction

This chapter attempts to describe the Luau bytecode format up to version 6.

2. Definitions

2.1. Terms

2.1. Type Notation

Any types not defined above will be defined in Section 3.

3. Structure

The encapsulating data structure, called the chunk, the contains metadata, strings, function definitions, constants, instructions and type/debug information required to execute the compiled program.

3.1. Chunk

The top level Chunk encodes the entire bytecode chunk, and is a struct with the following fields:

3.2. UserdataTypes

The UserdataTypes encodes tagged userdata type names, and is encoded as a null-terminated array of type name definitions.

The first value is a u8 of the userdata tag it defines, incremented by 1. The second value is a StringRef containing the type name.

3.3. Proto

A Proto encodes a function, and is a struct with the following fields:

3.4. ProtoId

A ProtoId is a varint that points to a Proto in the chunk proto table.

3.5. ProtoFlags

A ProtoFlags is a bitfield containing the following fields:

3.6. StringRef

A StringRef is a varint that points to a string in the chunk string table. StringRefs are one-indexed to allow 0 to act as a 'null' variant. The actual index of a string would be string_ref - 1.

3.7. ProtoTypeInfo

A ProtoTypeInfo encodes type information for a Proto, and begins with a header struct with the following fields:

After the header, an array of ASCII characters function_length bytes long contains the functions type.

After the function type, an array upvalue_count items long contains the upvalue types, encoded as a BytecodeType.

After the upvalue types, an array local_count items long contains the local types, encoded as:

3.8. BytecodeType

A BytecodeType is a byte containing type information.

The first 7 bits of the BytecodeType are an enum of possible types. The last bit indicates whether the type is optional.

The list of types are:

3.9. Constant

A Constant encodes a constant value.

The first byte of a constant encodes the constant type as an enum of:

The rest of the Constant depends on the constant type:

3.10. TableShape

A TableShape encodes the shape of a constant table as a length-prefixed array of key-value pairs, where each element points to another constant table entry.

3.11. ImportId

An ImportId is a u32 that encodes an import path (e.g. string.format or _G.hello.world), as a series of constant IDs pointing to constant strings.

ImportIds are encoded as:

3.12. ProtoLineInfo

A ProtoLineInfo encodes the line information of a Protos instructions.

This is implementation defined.

3.13. ProtoDebugInfo

A ProtoDebugInfo encodes debugging information for a Proto, and contains the following fields:

where Local is:

and Upvalue is:

4. Instructions Structure

An instruction buffer encodes instructions as a series of 32-bit words.

4.1. Instruction Word Structure

The first byte of an instruction contains the opcode.

The rest of the instruction contains its operands, which can be encoded in one of the following modes:

Some instructions have additional operands encoded in a follow up 'auxiliary' instruction.

Other instructions, like BREAK and NOP have no operands at all. Internally, LuauToolkit treats operand-less instructions as abc for simplicity's sake.

4.2. List of Instructions