Cosmos.Executable.Lua 2.0.0

<h1 align="center">Cosmos Lua Interpreter 🚀</h1> <p> <a href="https://www.nuget.org/packages/Cosmos.Executable.Lua/" target="_blank"> <img alt="Version" src="https://img.shields.io/nuget/v/Cosmos.Executable.Lua.svg" /> </a> <a href="https://github.com/CosmosOS/Cosmos.Executable.Lua/blob/main/LICENSE.txt" target="_blank"> <img alt="License: BSD Clause 3 License" src="https://img.shields.io/badge/license-BSD License-yellow.svg" /> </a> </p>

Cosmos.Executable.Lua is a Lua 5.3 interpreter, based on UniLua, made in C# for the Cosmos operating system construction kit.

Usage

Add the package to your kernel .csproj:

<ItemGroup>
    <PackageReference Include="Cosmos.Executable.Lua" Version="2.0.0" />
</ItemGroup>

using System;
using Cosmos.Executable.Lua;

LuaInterpreter lua = new()
{
    WorkingDirectory = "/mnt", // where dofile, require and io.open start relative paths from
};

try
{
    lua.DoString("print('Hello from ' .. _VERSION)");
    lua.DoFile("script.lua", "first argument"); // as `lua script.lua first argument`
    lua.RunPrompt(); // the interactive prompt, until os.exit()
}
catch (LuaException e)
{
    // A syntax error, or a runtime error no pcall caught
    Console.WriteLine(e.Message);
    Console.WriteLine(e.LuaStackTrace);
}
catch (LuaExitException e)
{
    // The script called os.exit(e.ExitCode)
}

A C# function raises a Lua error with state.L_Error(...), or by throwing: a .NET exception becomes a Lua error that pcall catches.

Strings

Lua strings hold bytes, as in C Lua: on the ILuaState API a Lua string is a .NET string with one character, \0 to \xFF, per byte. LuaInterpreter takes and gives text, as UTF-8, and so do the console, file names and os.getenv; files give and take their bytes as they are, in text mode as in binary mode. So #"é" is 2, and the utf8 library reads the bytes of UTF-8 text. A C# function converts text with LuaText:

state.PushString(LuaText.Encode("héllo")); // the 6 bytes of "héllo"
string text = LuaText.Decode(state.ToString(-1)); // "héllo" again

Limitations

The standard libraries are those of Lua 5.3 built with LUA_COMPAT_5_2, as the reference one is, so bit32, math.pow and the others are there, except io.popen. There is no __gc and no weak tables, so close the files you open: a write reaches the file at once, unless file:setvbuf asks for a buffer. C calls and the parser nest 150 levels deep, not 200, for the small stacks of a kernel's threads. On a Cosmos kernel the local time is UTC and os.getenv returns nil.

The tests run the official Lua 5.3 test suite (lua-5.3.4-tests), but for gc.lua and main.lua, with the four lines these limitations break patched in LuaTestSuiteTests.cs.

Authors

👤 @xebecnan

👤 @valentinbreiz

🤝 Contributing

Contributions, issues and feature requests are welcome!

Feel free to check issues page.

📝 License

Copyright © 2026 CosmosOS.

This project is BSD Clause 3 licensed. It includes UniLua, Copyright © 2013 Sheng Lunan, and code ported from Lua 5.3, Copyright © 1994–2020 Lua.org, PUC-Rio, both under the MIT license: see THIRD-PARTY-NOTICES.txt.