A loaded native shared library (DLL).
Obtained via loadLibrary. The library remains loaded until the value is garbage-collected.
@eryx/_ffi Module
JSON
Foreign Function Interface for Luau.
Loads native shared libraries (DLLs) at runtime and invokes their exported C functions directly from Luau. Values are marshalled through typed ForeignValue wrappers to ensure correct ABI alignment.
Caution
This is a low-level API. Incorrect type declarations or pointer arithmetic will crash the process - there are no safety nets once you cross the FFI boundary.
local ffi = require("@eryx/_ffi")
local user32 = ffi.loadLibrary("user32.dll")
local msgBox = user32:getFunction(
"MessageBoxA",
ffi.i32,
{ ffi.u64, ffi.str:pointer(), ffi.str:pointer(), ffi.u32 }
)
local title = ffi.str("Hello from Luau!")
local body = ffi.str("It works!")
msgBox(ffi.u64(0), body:pointer(), title:pointer(), ffi.u32(0))
Summary
Classes
ForeignLibrary:getFunction(name: string | number, retType: ForeignType, argTypes: { ForeignType }) → ForeignFunction
Functions
API Reference
Classes
ForeignLibrary
Properties
ForeignLibrary:getFunction
Looks up an exported function by name or ordinal and returns a callable ForeignFunction.
ForeignLibrary:getFunction(name: string | number, retType: ForeignType, argTypes: { ForeignType }) → ForeignFunction
Parameters
name: string | number
The exported symbol name, or a numeric ordinal.
The return type of the function.
An array of argument types, in order.
Returns
A callable wrapper for the native function.
ForeignFunction
A resolved native function that can be called from Luau.
Calling the function with the correct number and types of arguments returns a ForeignValue containing the return value.
Properties
ForeignFunction:__call
Invokes the native function.
Arguments may be ForeignValue userdata or plain Luau values that are automatically converted according to the declared argument types.
Returns
The return value wrapped in a ForeignValue.
ForeignType
A C type descriptor (e.g. u32, str, i64).
Type objects are callable - invoking one creates a new ForeignValue of that type, optionally initialised with a value.
local n = ffi.u32(42) -- create a u32 with value 42
local s = ffi.str("hi") -- create a string value
Properties
ForeignType:pointer
Returns a new ForeignType representing a pointer to this type.
Can be chained: ffi.u32:pointer():pointer() yields u32**.
Returns
The pointer-to type.
ForeignType:__call
Creates a new ForeignValue of this type.
If initialValue is provided it is used to initialise the value;
otherwise the memory is zero-filled.
Parameters
initialValue: any?
An optional initial value.
Returns
The newly created value.
ForeignValue
A boxed C value that can be read, written, and passed across the FFI boundary.
Pointer values can be dereferenced with get() or turned into a pointer with pointer().
Properties
ForeignValue:get
Reads the value.
For scalar types this returns the corresponding Luau primitive (number or string). For pointer types this dereferences the pointer and returns a new ForeignValue one indirection level lower.
ForeignValue:get(dereference: boolean?) → any
Parameters
dereference: boolean?
For pointer values, pass false to get the raw numeric address instead of dereferencing. Defaults to true.
Returns
any
The Luau value, or a new ForeignValue for pointers.
ForeignValue:set
Overwrites the stored value.
Only valid for non-pointer scalar types. Returns self for
method chaining.
Parameters
value: any
The new value to store.
Returns
self.
ForeignValue:pointer
Returns a new ForeignValue that is a pointer to this value.
The returned pointer does not own the memory - the original value must be kept alive for the pointer to remain valid.
Returns
A pointer to this value.
Functions
_ffi.loadLibrary
Loads a native shared library (DLL) by file name or path.
The library is kept loaded until the returned ForeignLibrary is garbage-collected.
local kernel32 = _ffi.loadLibrary("kernel32.dll")
Parameters
path: string
The file name or full path of the library to load.
Returns
A handle to the loaded library.