Lua-CSharp Documentation

Lua-CSharp provides the ILuaModuleLoader interface to control how require resolves modules. This mechanism runs before the standard Lua package.searchers.

• LuaState.ModuleLoader: Set this property to provide a custom loader.
• FileModuleLoader: The default implementation that loads modules from Lua files.
• CompositeModuleLoader.Create(loader1, loader2, ...): Allows combining multiple loaders into a single search chain.
• LuaState.LoadedModules: Provides access to the package.loaded table for cached modules.

public interface ILuaModuleLoader
{
    bool Exists(string moduleName);
    ValueTask<LuaModule> LoadAsync(string moduleName, CancellationToken cancellationToken = default);
}

// Usage example
state.ModuleLoader = CompositeModuleLoader.Create(
    new CustomModuleLoader1(),
    new CustomModuleLoader2()
);

Since LuaFunction is asynchronous, you can define C# functions that perform asynchronous work (like Task.Delay) and await them within a Lua script. This is particularly useful for game scripting where you need to pause execution without blocking the main thread.

// Define a function that waits for a given number of seconds
state.Environment["wait"] = new LuaFunction(async (context, ct) =>
{
    var sec = context.GetArgument<double>(0);
    await Task.Delay(TimeSpan.FromSeconds(sec));
    return context.Return();
});

// Lua script can now use: wait(1.0)
await state.DoFileAsync("sample.lua");

Because Lua-CSharp is implemented in .NET, it behaves differently than standard C Lua in two key areas:

1. Character Encoding (UTF-16) Lua-CSharp uses UTF-16. Standard Lua assumes single-byte encoding. Consequently, string length functions like string.len() will return the number of UTF-16 code units rather than bytes. For example, string.len("あいうえお") will return 5 in Lua-CSharp, whereas standard Lua would return 15.

2. Garbage Collection Lua-CSharp relies on the .NET Garbage Collector. While collectgarbage() is available, it is a wrapper for .NET GC methods and may not behave identically to the deterministic behavior of the C Lua garbage collector.

Because Lua-CSharp is implemented in C#, it differs from standard C Lua implementations in two key areas:

1. UTF-16 Character Encoding: Strings are handled as UTF-16. Functions in the string library operate on UTF-16 code units. For example, string.len("あいうえお") will return 5 instead of the byte length expected in standard Lua.
2. Garbage Collection: Memory management relies on the .NET GC. Calling collectgarbage() is equivalent to GC.Collect() and its arguments are ignored. Weak tables (week tables) are not supported.

The Lua.Unity package introduces LuaAsset, allowing .lua files to be treated as assets in the Unity Editor, similar to TextAsset. You can load them via Resources.Load and execute them using DoStringAsync.

var asset = Resources.Load<LuaAsset>("example");
await state.DoStringAsync(asset.Text, ct);

When using Lua-CSharp in Unity, use the provided UnityStandardIO and UnityApplicationOsEnvironment to ensure Lua commands map correctly to Unity behavior:

• UnityStandardIO: Redirects print to Debug.Log().
• UnityApplicationOsEnvironment: Maps environment variables to a Dictionary and makes os.exit() call Application.Quit().

Additionally, use ResourcesModuleLoader or AddressablesModuleLoader to allow Lua's require to find Unity assets.

var platform = new LuaPlatform(
    FileSystem: new FileSystem(),
    OsEnvironment: new UnityApplicationOsEnvironment(),
    StandardIO: new UnityStandardIO(),
    TimeProvider: TimeProvider.System);

var state = LuaState.Create(platform);

// To load assets via Unity's systems:
state.ModuleLoader = new ResourcesModuleLoader(); // or new AddressablesModuleLoader();

Lua-CSharp requires .NET Standard 2.1 or higher. You can install it via NuGet using the .NET CLI or the Package Manager.

# .NET CLI
dotnet add package LuaCSharp

# Package Manager
Install-Package LuaCSharp

The LuaState class is the entry point for the interpreter. You can create a state and execute Lua code using DoStringAsync or DoFileAsync.

WARNING

LuaState is not thread-safe. Do not access it from multiple threads simultaneously.

using Lua;

// Create a LuaState
var state = LuaState.Create();

// Execute a Lua script string with DoStringAsync
var results = await state.DoStringAsync("return 1 + 1");

// 2
Console.WriteLine(results[0]);

Lua-CSharp supports Unity (both Mono and IL2CPP) with Unity 2021.3 or higher. Follow these steps:

1. Install NugetForUnity.
2. Open the NuGet window via NuGet > Manage NuGet Packages.
3. Search for and install the LuaCSharp package.
4. Open the Package Manager (Window > Package Manager).
5. Click [+] > Add package from git URL and enter: https://github.com/nuskey8/Lua-CSharp.git?path=src/Lua.Unity/Assets/Lua.Unity

Runtime errors in Lua scripts throw exceptions that inherit from LuaException. You should catch these to prevent application crashes and handle errors gracefully.

Common exception types:

• LuaCompileException: Thrown during script parsing.
• LuaRuntimeException: Thrown during script execution.
• OperationCanceledException / LuaCanceledException: Thrown when a task is canceled, allowing you to identify the cancellation point within Lua.

try
{
    await state.DoFileAsync("filename.lua");
}
catch (LuaCompileException)
{
    // Handle parsing errors
}
catch (LuaRuntimeException)
{
    // Handle runtime exceptions
}

To use Lua-CSharp in your .NET project, you must use .NET Standard 2.1 or higher. You can install it using the .NET CLI or the Visual Studio Package Manager.

# .NET CLI
dotnet add package LuaCSharp

# Package Manager
Install-Package LuaCSharp