luau Documentation

Technical Documentation: luau-lang/luau

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Luau [](https://codecov.io/gh/luau-lang/luau)

Luau (lowercase u, /ˈlu.aʊ/) is a fast, small, safe, gradually typed embeddable scripting language derived from Lua.

It is designed to be backwards compatible with Lua 5.1, as well as incorporating some features from future Lua releases, but also expands the feature set (most notably with type annotations and a state-of-the-art type inference system). Luau is largely implemented from scratch, with the language runtime being a very heavily modified version of Lua 5.1 runtime, with completely rewritten interpreter and other performance innovations. The runtime mostly preserves Lua 5.1 API, so existing bindings should be more or less compatible with a few caveats.

Luau is used by Roblox game developers to write game code, and by Roblox engineers to implement large parts of the user-facing application code as well as portions of the editor (Roblox Studio) as plugins. Roblox chose to open-source Luau to foster collaboration within the Roblox community as well as to allow other companies and communities to benefit from the ongoing language and runtime innovation. More recently, Luau has seen adoption in games like Alan Wake 2, Farming Simulator 2025, Second Life, and Warframe.

This repository hosts source code for the language implementation and associated tooling. Documentation for the language is available at https://luau.org/ and accepts contributions via site repository; the language is evolved through RFCs that are located in rfcs repository.

Usage

Luau is an embeddable programming language, but it also comes with two command-line tools by default, luau and luau-analyze.

luau is a command-line REPL and can also run input files. Note that REPL runs in a sandboxed environment and as such doesn't have access to the underlying file system except for ability to require modules.

luau-analyze is a command-line type checker and linter; given a set of input files, it produces errors/warnings according to the file configuration, which can be customized by using --! comments in the files or .luaurc files. For details, please refer to our type checking and linting documentation. Our community maintains a language server frontend for luau-analyze called luau-lsp for use with text editors.

Installation

You can install and run Luau by downloading the compiled binaries from a recent release; note that luau and luau-analyze binaries from the archives will need to be added to PATH or copied to a directory like /usr/local/bin on Linux/macOS.

Alternatively, you can use one of the packaged distributions (note that these are not maintained by Luau development team):

• macOS: Install Homebrew and run brew install luau
• Arch Linux: Luau has been added to the official Arch Linux packages repository under the extras repository (see luau), simply install using pacman: pacman -Syu luau
• Alpine Linux: Enable community repositories and run apk add luau
• Gentoo Linux: Luau is officially packaged by Gentoo and can be installed using emerge dev-lang/luau. You may have to unmask the package first before installing it (which can be done by including the --autounmask=y option in the emerge command).

After installing, you will want to validate the installation was successful by running the test case here.

Building Copy Chapter

On all platforms, you can use CMake to run the following commands to build Luau binaries from source:

mkdir cmake && cd cmake
cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build . --target Luau.Repl.CLI --config RelWithDebInfo
cmake --build . --target Luau.Analyze.CLI --config RelWithDebInfo

Alternatively, on Linux and macOS, you can also use make:

make config=release luau luau-analyze

To integrate Luau into your CMake application projects as a library, at the minimum, you'll need to depend on Luau.Compiler and Luau.VM projects. From there you need to create a new Luau state (using Lua 5.x API such as lua_newstate), compile source to bytecode and load it into the VM like this:

// needs lua.h and luacode.h
size_t bytecodeSize = 0;
char* bytecode = luau_compile(source, strlen(source), NULL, &bytecodeSize);
int result = luau_load(L, chunkname, bytecode, bytecodeSize, 0);
free(bytecode);

if (result == 0)
    return 1; /* return chunk main function */

For more details about the use of the host API, see the C API documentation.
Much of it is similar to the Lua 5.x API, but Luau has a few deviations, such as the need to compile source separately (which is important to be able to deploy VM without a compiler), and the lack of __gc support (use lua_newuserdatadtor instead).

To gain advantage of many performance improvements, it's highly recommended to use the safeenv feature, which sandboxes individual scripts' global tables from each other, and protects builtin libraries from monkey-patching. For this to work, you must call luaL_sandbox on the global state and luaL_sandboxthread for each new script's execution thread.

Testing

Luau has an internal test suite; in CMake builds, it is split into two targets, Luau.UnitTest (for the bytecode compiler and type checker/linter tests) and Luau.Conformance (for the VM tests). The unit tests are written in C++, whereas the conformance tests are largely written in Luau (see tests/conformance).

Makefile builds combine both into a single target that can be run via make test.

Dependencies

Luau uses C++ as its implementation language. The runtime requires C++11, while the compiler and analysis components require C++17. It should build without issues using Microsoft Visual Studio 2017 or later, or gcc-7 or clang-7 or later.

Other than the STL/CRT, Luau library components don't have external dependencies. The test suite depends on the doctest testing framework, and the REPL command-line depends on isocline.

License

Luau implementation is distributed under the terms of MIT License. It is based on the Lua 5.x implementation, also under the MIT License.

When Luau is integrated into external projects, we ask that you honor the license agreement and include Luau attribution into the user-facing product documentation. Attribution making use of the Luau logo is also encouraged when reasonable.

Overview (`extern/isocline/readme.md`) Copy Section

Isocline: a portable readline alternative.

Isocline is a pure C library that can be used as an alternative to the GNU readline library (latest release v1.0.9, 2022-01-15).

• Small: less than 8k lines and can be compiled as a single C file without
  any dependencies or configuration (e.g. gcc -c src/isocline.c).

• Portable: works on Unix, Windows, and macOS, and uses a minimal
  subset of ANSI escape sequences.

• Features: extensive multi-line editing mode (shift-tab), (24-bit) color, history, completion, unicode,
  undo/redo, incremental history search, inline hints, syntax highlighting, brace matching,
  closing brace insertion, auto indentation, graceful fallback, support for custom allocators, etc.

• License: MIT.

• Comes with a Haskell binding (System.Console.Isocline.

Enjoy,
Daan

Demo

Shows in order: unicode, syntax highlighting, brace matching, jump to matching brace, auto indent, multiline editing, 24-bit colors, inline hinting, filename completion, and incremental history search.
_{(screen capture was made with termtosvg by Nicolas Bedos)}

Usage

Include the isocline header in your C or C++ source:

#include <include/isocline.h>

and call ic_readline to get user input with rich editing abilities:

char* input;
while( (input = ic_readline("prompt")) != NULL ) { // ctrl+d/c or errors return NULL
  printf("you typed:\n%s\n", input); // use the input
  free(input);  
}

See the example for a full example with completion, syntax highligting, history, etc.

Run the Example

You can compile and run the example as:

$ gcc -o example -Iinclude test/example.c src/isocline.c
$ ./example

or, the Haskell example:

$ ghc -ihaskell test/Example.hs src/isocline.c
$ ./test/Example

Editing with Isocline

Isocline tries to be as compatible as possible with standard GNU Readline key bindings.

Overview: Copy Section

home/ctrl-a       cursor     end/ctrl-e
         ┌─────────────────┼───────────────┐    (navigate)
         │     ctrl-left   │  ctrl-right   │
         │         ┌───────┼──────┐        │    ctrl-r   : search history
         ▼         ▼       ▼      ▼        ▼    tab      : complete word
  prompt> it is the quintessential language     shift-tab: insert new line
         ▲         ▲              ▲        ▲    esc      : delete input, done
         │         └──────────────┘        │    ctrl-z   : undo
         │    alt-backsp        alt-d      │
         └─────────────────────────────────┘    (delete)
       ctrl-u                          ctrl-k

_{Note: on macOS, the meta (alt) key is not directly available in most terminals.
Terminal/iTerm2 users can activate the meta key through
Terminal → Preferences → Settings → Use option as meta key.}

Key Bindings Copy Section

These are also shown when pressing F1 on a Isocline prompt. We use ^ as a shorthand for ctrl-:

Build the Library

Build as a Single Source Copy Section

Copy the sources (in include and src) into your project, or add the library as a submodule:

$ git submodule add https://github.com/daanx/isocline

and add isocline/src/isocline.c to your build rules -- no configuration is needed.

Build with CMake Copy Section

Clone the repository and run cmake to build a static library (.a/.lib):

$ git clone https://github.com/daanx/isocline
$ cd isocline
$ mkdir -p build/release
$ cd build/release
$ cmake ../..
$ cmake --build .

This builds a static library libisocline.a (or isocline.lib on Windows)
and the example program:

$ ./example

Build the Haskell Library Copy Section

See the Haskell readme for instructions to build and use the Haskell library.

API Reference

• See the C API reference and the example for example usage of history, completion, etc.

• See the Haskell API reference on Hackage and the Haskell example.

Motivation

Isocline was created for use in the Koka interactive compiler.
This required: pure C (no dependency on a C++ runtime or other libraries),
portable (across Linux, macOS, and Windows), unicode support,
a BSD-style license, and good functionality for completion and multi-line editing.

Some other excellent libraries that we considered:
GNU readline,
editline,
linenoise,
replxx, and
Haskeline.

Formatted Output

Isocline also exposes functions for rich terminal output
as ic_print (and ic_println and ic_printf).
Inspired by the (Python) Rich library,
this supports a form of bbcode's to format the output:

ic_println( "[b]bold [red]and red[/red][/b]" );

Each print automatically closes any open tags that were
not yet closed. Also, you can use a general close
tag as [/] to close the innermost tag, so the
following print is equivalent to the earlier one:

ic_println( "[b]bold [red]and red[/]" );

There can be multiple styles in one tag
(where the first name is used for the closing tag):

ic_println( "[u #FFD700]underlined gold[/]" );

Sometimes, you need to display arbitrary messages
that may contain sequences that you would not like
to be interpreted as bbcode tags. One way to do
this is the [!tag] which ignores formatting
up to a close tag of the form [/tag].

ic_printf( "[red]red? [!pre]%s[/pre].\n", "[blue]not blue!" );

Predefined styles include b (bold),
u (underline), i (italic), and r (reverse video), but
you can (re)define any style yourself as:

ic_style_def("warning", "crimson u");

and use them like any builtin style or property:

ic_println( "[warning]this is a warning![/]" );

which is great for adding themes to your application.

Each ic_print function always closes any unclosed tags automatically.
To open a style persistently, use ic_style_open with a matching
ic_style_close which scopes over any ic_print statements in between.

ic_style_open("warning");
ic_println("[b]crimson underlined and bold[/]");
ic_style_close();

Advanced

BBCode Format Copy Chapter

An open tag can have multiple white space separated
entries that are
either a style name, or a primitive property[=value].

Styles Copy Section

Isocline provides the following builtin styles as property shorthands:
b (bold), u (underline), i (italic), r (reverse video),
and some builtin styles for syntax highlighting:
keyword, control (control-flow keywords), string,
comment, number, type, constant.

Predefined styles used by Isocline itself are:

• ic-prompt: prompt style, e.g. ic_style_def("ic-prompt", "yellow on blue").
• ic-info: information (like the numbers in a completion menu).
• ic-diminish: dim text (used for example in history search).
• ic-emphasis: emphasized text (also used in history search).
• ic-hint: color of an inline hint.
• ic-error: error color (like an unmatched brace).
• ic-bracematch: color of matching parenthesis.

Properties Copy Section

Boolean properties are by default on:

• bold [=(on|off)]
• italic [=(on|off)]
• underline [=(on|off)]
• reverse [=(on|off)]

Color properties can be assigned a color:

• color=color
• bgcolor=color
• color: equivalent to color=color.
• on color: equivalent to bgcolor=color.

A color value can be specified in many ways:

• any standard HTML color name.
• any of the 16 standard ANSI color names by prefixing ansi-
  (like ansi-black or ansi-maroon).
  The actual color value of these depend on the a terminal theme.
• #rrggbb or #rgb for a specific 24-bit color.
• ansi-color=idx: where 0 <= idx <= 256 specifies an entry in the
  standard ANSI 256 color palette, where 256 is used for the ANSI
  default color.

Environment Variables Copy Chapter

• NO_COLOR: if present no colors are displayed.
• CLICOLOR=1: if set, the LSCOLORS or LS_COLORS environment variables are used to colorize
  filename completions.
• COLORTERM=(truecolor|256color|16color|8color|monochrome): enable a certain color palette, see the next section.
• TERM: used on some systems to determine the color

Colors Copy Chapter

Isocline supports 24-bit colors and any RGB colors are automatically
mapped to a reduced palette on older terminals if these do not
support true color. Detection of full color support
is not always possible to do automatically and you can
set the COLORTERM environment variable expicitly to force Isocline to use
a specific palette:

• COLORTERM=truecolor: use 24-bit colors.

• COLORTERM=256color: use the ANSI 256 color palette.

• COLORTERM=16color : use the regular ANSI 16 color
  palette (8 normal and 8 bright colors).

• COLORTERM=8color: use bold for bright colors.

• COLORTERM=monochrome: use no color.

The above screenshots are made with the
test_colors.c program. You can test your own
terminal as:

$ gcc -o test_colors -Iinclude test/test_colors.c src/isocline.c
$ ./test_colors
$ COLORTERM=truecolor ./test_colors
$ COLORTERM=16color ./test_colors

ANSI Escape Sequences Copy Chapter

Isocline uses just few ANSI escape sequences that are widely
supported:

• ESC[nA, ESC[nB, ESC[nC, and ESC[nD,
  for moving the cursor n places up, down, right, and left.
• ESC[K to clear the line from the cursor.
• ESC[nm for colors, with n one of: 0 (reset), 1,22 (bold), 3,23 (italic),
  4,24 (underline), 7,27 (reverse), 30-37,40-47,90-97,100-107 (color),
  and 39,49 (select default color).
• ESC[38;5;nm, ESC[48;5;nm, ESC[38;2;r;g;bm, ESC[48;2;r;g;bm:
  on terminals that support it, select
  entry n from the
  256 color ANSI palette (used with XTERM=xterm-256color for example), or directly specify
  any 24-bit rgb color (used with COLORTERM=truecolor) for the foreground or background.

On Windows the above functionality is implemented using the Windows console API
(except if running in the new Windows Terminal which supports these escape
sequences natively).

Async and Threads Copy Chapter

Isocline is not thread-safe and ic_readlinexxx and ic_printxxx should
be used from one thread only.

The best way to use ic_readline asynchronously is
to run it in a (blocking) dedicated thread and deliver
results from there to the async event loop. Isocline has the

bool ic_async_stop(void)

function that is thread-safe and can deliver an
asynchronous event to Isocline that unblocks a current
ic_readline and makes it behave as if the user pressed
ctrl-c (which returns NULL from the read line call).

Color Mapping Copy Chapter

To map full RGB colors to an ANSI 256 or 16-color palette
Isocline finds a palette color with the minimal "color distance" to
the original color. There are various
ways of calculating this: one way is to take the euclidean distance
in the sRGB space (simple-rgb), a slightly better way is to
take a weighted distance where the weight distribution is adjusted
according to how big the red component is (redmean,
denoted as delta-rgb in the figure),
this is used by Isocline),
and finally, we can first translate into a perceptually uniform color space
(CIElab) and calculate the distance there using the CIEDE2000
algorithm (ciede2000). Here are these three methods compared on
some colors:

Each top row is the true 24-bit RGB color. Surprisingly,
the sophisticated CIEDE2000 distance seems less good here compared to the
simpler methods (as in the upper left block for example)
(perhaps because this algorithm was created to find close
perceptual colors in images where lightness differences may be given
less weight?). CIEDE2000 also leads to more "outliers", for example as seen
in column 5. Given these results, Isocline uses redmean for
color mapping. We also add a gray correction that makes it less
likely to substitute a color for a gray value (and the other way
around).

Possible Future Extensions Copy Chapter

• Vi key bindings.
• kill buffer.
• make the ic_printxxx functions thread-safe.
• extended low-level terminal functions.
• status and progress bars.
• prompt variants: confirm, etc.
• ...

Contact me if you are interested in doing any of these :-)

Releases

• 2022-01-15: v1.0.9: fix missing ic_completion_arg (issue #6),
  fix null ptr check in ic_print (issue #7), fix crash when using /dev/null as both input and output.
• 2021-09-05: v1.0.5: use our own wcwidth for consistency;
  thanks to Hans-Georg Breunig for helping with testing on NetBSD.
• 2021-08-28: v1.0.4: fix color query on Ubuntu/Gnome
• 2021-08-27: v1.0.3: fix duplicates in completions
• 2021-08-23: v1.0.2: fix windows eol wrapping
• 2021-08-21: v1.0.1: fix line-buffering
• 2021-08-20: v1.0.0: initial release

Overview (`tests/golden/analysis/README.md`) Copy Section

Type inference analysis goldens

These folders contain CLI-observable ports of the C++ TypeInfer.*.test.cpp,
TypeFunction.test.cpp, and TypeFunction.user.test.cpp suites. Folder names
are normalized to kebab-case from the source category name; for example,
TypeInfer.intersectionTypes.test.cpp maps to intersection-types/, the
uncategorized TypeInfer.test.cpp maps to general/, and the two type function
suites map to type-functions/ and user-defined-type-functions/.

Each entry is an independently runnable golden test. Its adjacent
flags-on/flags-off strict and nonstrict .output files encode complete
combined process output, so the suite detects changed diagnostics, changed
locations, unexpected warnings, and unexpected output from successful
analysis.

Only behavior visible through luau-analyze and safely runnable through
luau belongs here. Tests remain C++-only when they depend on fixture-provided
definition files or extern classes, hidden types such as Not<T>, direct
TypeId/arena/unifier inspection, autocomplete state, custom fast-flag
combinations outside the golden matrix, old-solver behavior, or crash-only
internal invariants. This currently excludes the definitions, externTypes,
classes, negations, provisional, and tryUnify categories except where a
portable equivalent is added later.

Overview (`tests/golden/meta/README.md`) Copy Section

Golden harness meta tests

The tests in this directory exercise the golden test framework itself rather
than serving as regression tests for Luau language behavior.

They cover configuration-specific status resolution; strict, nonstrict, and
runtime failures; global and scoped regex assertions; exact-output files; empty
outputs; and multifile test discovery. New language behavior tests should
normally live elsewhere under tests/golden/.

Overview (`tests/require/config_tests/README.md`) Copy Section

The with_config and with_config_luau directories should be identical, apart from the configuration file type they use.

Overview (`bench/tests/vibemark67/charonvg-dir/README.md`) Copy Section

CharonVG

CharonVG is a standalone 2D vector graphics library for Luau, based on PlutoVG. It provides the same rendering capabilities — anti-aliased path filling and stroking, gradients, compositing, transforms, and SVG parsing — reimplemented in pure Luau with an idiomatic method-call API.

Features Copy Chapter

• Path Filling, Stroking and Dashing
• Solid, Linear Gradient and Radial Gradient Paints
• All 12 Porter-Duff Compositing Operators
• Anti-Aliased Rendering (exact-coverage scanline rasterizer)
• Clipping
• Affine Transformations
• SVG Parsing and Rendering
• CSS Custom Properties (var(--name, fallback))
• BMP Output

Example Copy Chapter

local cvg = require("./main")

local surface = cvg.Surface.create(150, 150)
surface:clear(cvg.Color.WHITE)
local canvas = cvg.Canvas.create(surface)

-- Yellow face
canvas:arc(75, 75, 70, 0, math.pi * 2, false)
canvas:setRgb(1, 1, 0)
canvas:fillPreserve()
canvas:setRgb(0, 0, 0)
canvas:setLineWidth(5)
canvas:stroke()

-- Eyes
canvas:circle(50, 55, 10)
canvas:circle(100, 55, 10)
canvas:setRgb(0, 0, 0)
canvas:fill()

-- Mouth
canvas:arc(75, 75, 50, 0, math.pi, false)
canvas:setRgb(0, 0, 0)
canvas:setLineWidth(5)
canvas:stroke()

cvg.Bmp.write(surface, "smiley.bmp")

SVG Rendering Copy Chapter

local cvg = require("./main")

local doc = cvg.Svg.parse(svgString)
local surface = doc:renderToSurface(800, 600)
cvg.Bmp.write(surface, "output.bmp")

SVG custom properties can be themed at render time:

local surface = doc:renderToSurface(800, 600, {
    bg = "#1a1a2e",
    primary = "#e94560",
})

Attribution Copy Chapter

CharonVG is a Luau port of PlutoVG by Samuel Ugochukwu. The rendering algorithms — including the exact-coverage scanline rasterizer, path stroker, and gradient interpolation — are derived from PlutoVG's C implementation, adapted for Luau's idioms (method syntax, garbage collection, buffer type).

The SVG parser is based on PlutoSVG by the same author.

License Copy Chapter

MIT — see LICENSE for details.

Overview (`bench/tests/vibemark67/charonvg/README.md`) Copy Section

CharonVG

CharonVG is a standalone 2D vector graphics library for Luau, based on PlutoVG. It provides the same rendering capabilities — anti-aliased path filling and stroking, gradients, compositing, transforms, and SVG parsing — reimplemented in pure Luau with an idiomatic method-call API.

Features Copy Chapter

• Path Filling, Stroking and Dashing
• Solid, Linear Gradient and Radial Gradient Paints
• All 12 Porter-Duff Compositing Operators
• Anti-Aliased Rendering (exact-coverage scanline rasterizer)
• Clipping
• Affine Transformations
• SVG Parsing and Rendering
• CSS Custom Properties (var(--name, fallback))
• BMP Output

Example Copy Chapter

local cvg = require("./main")

local surface = cvg.Surface.create(150, 150)
surface:clear(cvg.Color.WHITE)
local canvas = cvg.Canvas.create(surface)

-- Yellow face
canvas:arc(75, 75, 70, 0, math.pi * 2, false)
canvas:setRgb(1, 1, 0)
canvas:fillPreserve()
canvas:setRgb(0, 0, 0)
canvas:setLineWidth(5)
canvas:stroke()

-- Eyes
canvas:circle(50, 55, 10)
canvas:circle(100, 55, 10)
canvas:setRgb(0, 0, 0)
canvas:fill()

-- Mouth
canvas:arc(75, 75, 50, 0, math.pi, false)
canvas:setRgb(0, 0, 0)
canvas:setLineWidth(5)
canvas:stroke()

cvg.Bmp.write(surface, "smiley.bmp")

SVG Rendering Copy Chapter

local cvg = require("./main")

local doc = cvg.Svg.parse(svgString)
local surface = doc:renderToSurface(800, 600)
cvg.Bmp.write(surface, "output.bmp")

SVG custom properties can be themed at render time:

local surface = doc:renderToSurface(800, 600, {
    bg = "#1a1a2e",
    primary = "#e94560",
})

Attribution Copy Chapter

CharonVG is a Luau port of PlutoVG by Samuel Ugochukwu. The rendering algorithms — including the exact-coverage scanline rasterizer, path stroker, and gradient interpolation — are derived from PlutoVG's C implementation, adapted for Luau's idioms (method syntax, garbage collection, buffer type).

The SVG parser is based on PlutoSVG by the same author.

License Copy Chapter

MIT — see LICENSE for details.

--- METRICS ---

• Files Extracted: 7
• Estimated Token Budget: ~7756 tokens
• Canonical Reference: https://codewiki.google/github.com/luau-lang/luau