Add experimental static Luau runtime support

Compile source scripts into per-state bytecode, adapt module loading and userdata lifetimes, and preserve plain-data persistence across Lua runtimes. Add standalone tests, live smoke fixtures, CI and compatibility documentation.

Author: NixAJ

.github/workflows/luau-runtime.yml

@@ -0,0 +1,22 @@
+name: Luau runtime
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  runtime:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04, windows-2022]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+      - name: Configure
+        run: cmake -S tests -B TestBuilds/Runtime-luau -DLUA_VERSION=luau -DLUA_STATIC=ON -DCMAKE_BUILD_TYPE=Debug
+      - name: Build
+        run: cmake --build TestBuilds/Runtime-luau --config Debug --target eluna-runtime-tests --parallel 4
+      - name: Test
+        run: ctest --test-dir TestBuilds/Runtime-luau -C Debug --output-on-failure

BindingMap.h

@@ -12,11 +12,7 @@
 #include "ElunaUtility.h"
 #include <type_traits>
 
-extern "C"
-{
-#include "lua.h"
-#include "lauxlib.h"
-};
+#include "ElunaCompat.h"
 
 class BaseBindingMap
 {

CMakeLists.txt

@@ -1,6 +1,6 @@
 set(CUSTOM_METHODS_HEADER "${CMAKE_CURRENT_SOURCE_DIR}/methods/Custom/CustomMethods.h")
 if(EXISTS "${CUSTOM_METHODS_HEADER}")
-  if(NOT ${LUA_VERSION} MATCHES "luajit")
+  if(NOT LUA_VERSION MATCHES "^(luajit|luau)$")
     target_compile_definitions(lualib PUBLIC ELUNA_USE_CUSTOM_METHODS)
   else()
     target_compile_definitions(lualib INTERFACE ELUNA_USE_CUSTOM_METHODS)
@@ -17,7 +17,7 @@ elseif(WIN32)
 endif()
 
 # Add Lua compatibility definition
-if(NOT ${LUA_VERSION} MATCHES "luajit")
+if(NOT LUA_VERSION MATCHES "^(luajit|luau)$")
   target_compile_definitions(lualib PUBLIC LUA_COMPAT_MODULE) 
 endif()
 
@@ -36,6 +36,9 @@ foreach(dir ${modules_list})
 
     # Add module target and properties
     if(sources_module)
+      if(LUA_VERSION STREQUAL "luau")
+        message(FATAL_ERROR "Native Lua module ${dir} is not supported by experimental Luau; use CustomMethods.h for C++ bindings")
+      endif()
       add_library(${module_name} MODULE ${sources_module})
       target_include_directories(${module_name} INTERFACE ${PUBLIC_INCLUDES})
       target_link_libraries(${module_name} PUBLIC lualib)
@@ -88,3 +91,7 @@ foreach(target ${all_targets})
     remove_module_sources(${target})
   endif()
 endforeach()
+
+if(BUILD_TESTING)
+  add_subdirectory(tests)
+endif()

ElunaCompat.cpp

@@ -6,7 +6,7 @@
 
 #include "ElunaCompat.h"
 
-#if LUA_VERSION_NUM == 501
+#if !defined ELUNA_LUAU && LUA_VERSION_NUM == 501
 const char* luaL_tolstring(lua_State* L, int idx, size_t* len) {
     if (!luaL_callmeta(L, idx, "__tostring")) {
         int t = lua_type(L, idx), tt = 0;
@@ -41,6 +41,14 @@ const char* luaL_tolstring(lua_State* L, int idx, size_t* len) {
     return lua_tolstring(L, -1, len);
 }
 
+int lua_absindex(lua_State* L, int i) {
+    if (i < 0 && i > LUA_REGISTRYINDEX)
+        i += lua_gettop(L) + 1;
+    return i;
+}
+#endif
+
+#if defined ELUNA_LUAU || LUA_VERSION_NUM == 501
 int luaL_getsubtable(lua_State* L, int i, const char* name) {
     int abs_i = lua_absindex(L, i);
     luaL_checkstack(L, 3, "not enough stack slots");
@@ -56,12 +64,6 @@ int luaL_getsubtable(lua_State* L, int i, const char* name) {
     return 0;
 }
 
-int lua_absindex(lua_State* L, int i) {
-    if (i < 0 && i > LUA_REGISTRYINDEX)
-        i += lua_gettop(L) + 1;
-    return i;
-}
-
 #if !defined LUAJIT_VERSION
 void* luaL_testudata(lua_State* L, int index, const char* tname) {
     void* ud = lua_touserdata(L, index);
@@ -86,3 +88,36 @@ void luaL_setmetatable(lua_State* L, const char* tname) {
 }
 #endif
 #endif
+
+#if defined ELUNA_LUAU
+int luaL_ref(lua_State* L, int table)
+{
+    if (table != LUA_REGISTRYINDEX)
+        return luaL_error(L, "Eluna's Luau references require the registry");
+    int ref = lua_ref(L, -1);
+    lua_pop(L, 1); // lua_ref itself does not consume the referenced value.
+    return ref;
+}
+
+void luaL_unref(lua_State* L, int table, int ref)
+{
+    if (table != LUA_REGISTRYINDEX)
+        luaL_error(L, "Eluna's Luau references require the registry");
+    lua_unref(L, ref);
+}
+#endif
+
+#if defined ELUNA_LUAU || (LUA_VERSION_NUM == 501 && !defined LUAJIT_VERSION)
+void luaL_setfuncs(lua_State* L, const luaL_Reg* functions, int upvalues)
+{
+    luaL_checkstack(L, upvalues + 1, "too many upvalues");
+    for (; functions->name; ++functions)
+    {
+        for (int i = 0; i < upvalues; ++i)
+            lua_pushvalue(L, -upvalues);
+        lua_pushcclosure(L, functions->func, upvalues);
+        lua_setfield(L, -(upvalues + 2), functions->name);
+    }
+    lua_pop(L, upvalues);
+}
+#endif

ElunaCompat.h

@@ -7,18 +7,53 @@
 #ifndef ELUNACOMPAT_H
 #define ELUNACOMPAT_H
 
+#if defined ELUNA_LUAU
+// Luau uses C++ linkage and exceptions. Do not wrap these headers in extern C.
+#include "lua.h"
+#include "lualib.h"
+#else
 extern "C"
 {
 #include "lua.h"
+#include "lualib.h"
 #include "lauxlib.h"
 #if __has_include(<luajit.h>)
 #include <luajit.h>
 #endif
 };
+#endif
 
-/* Compatibility layer for compiling with Lua 5.1 or LuaJIT */
-#if LUA_VERSION_NUM == 501
+#if defined ELUNA_LUAU
+    #define lua_pushglobaltable(L) lua_pushvalue((L), LUA_GLOBALSINDEX)
+    #define lua_rawlen(L, idx) lua_objlen((L), (idx))
+
+    #undef lua_pushcfunction
+    #undef lua_pushcclosure
+    #define lua_pushcfunction(L, fn) lua_pushcclosurek((L), (fn), nullptr, 0, nullptr)
+    #define lua_pushcclosure(L, fn, nup) lua_pushcclosurek((L), (fn), nullptr, (nup), nullptr)
+
+    // Preserve Lua's expression-style error API used by existing bindings.
+    #undef luaL_error
+    #undef luaL_argerror
+    #define luaL_error(...) (luaL_errorL(__VA_ARGS__), 0)
+    #define luaL_argerror(L, arg, msg) (luaL_argerrorL((L), (arg), (msg)), 0)
+    #define lua_error(L) (lua_error(L), 0)
+
+    int luaL_ref(lua_State* L, int table);
+    void luaL_unref(lua_State* L, int table, int ref);
+#endif
+
+#if defined ELUNA_LUAU || LUA_VERSION_NUM == 501
     int luaL_getsubtable(lua_State* L, int i, const char* name);
+#if !defined LUAJIT_VERSION
+    void luaL_setfuncs(lua_State* L, const luaL_Reg* functions, int upvalues);
+    void* luaL_testudata(lua_State* L, int index, const char* tname);
+    void luaL_setmetatable(lua_State* L, const char* tname);
+#endif
+#endif
+
+/* Compatibility layer for compiling with Lua 5.1 or LuaJIT */
+#if !defined ELUNA_LUAU && LUA_VERSION_NUM == 501
     const char* luaL_tolstring(lua_State* L, int idx, size_t* len);
     int lua_absindex(lua_State* L, int i);
     #define lua_pushglobaltable(L) \
@@ -30,14 +65,9 @@ extern "C"
     #define lua_load(L, buf_read, dec_buf, str, NULL) \
         lua_load(L, buf_read, dec_buf, str)
 
-#if !defined LUAJIT_VERSION
-    void* luaL_testudata(lua_State* L, int index, const char* tname);
-    void luaL_setmetatable(lua_State* L, const char* tname);
-    #define luaL_setfuncs(L, l, n) luaL_register(L, NULL, l)
-#endif
 #endif
 
-#if LUA_VERSION_NUM > 502
+#if !defined ELUNA_LUAU && LUA_VERSION_NUM > 502
     #define lua_dump(L, writer, data) \
         lua_dump(L, writer, data, 0)
     #define lua_pushunsigned(L, u) \

ElunaEventMgr.cpp

@@ -12,11 +12,7 @@
 #include "Entities/Object.h"
 #endif
 
-extern "C"
-{
-#include "lua.h"
-#include "lauxlib.h"
-};
+#include "ElunaCompat.h"
 
 ElunaEventProcessor::~ElunaEventProcessor()
 {

ElunaLoader.cpp

@@ -9,6 +9,7 @@
 #include "ElunaConfig.h"
 #include "ElunaLoader.h"
 #include "ElunaUtility.h"
+#include "ElunaLuaRuntime.h"
 #include <fstream>
 #include <sstream>
 #include <thread>
@@ -32,11 +33,7 @@ namespace fs = std::filesystem;
 #include "Maps/MapManager.h"
 #endif
 
-extern "C" {
-#include <lua.h>
-#include <lualib.h>
-#include <lauxlib.h>
-}
+#include "ElunaCompat.h"
 
 #if defined ELUNA_TRINITY
 void ElunaUpdateListener::handleFileAction(efsw::WatchID /*watchid*/, std::string const& dir, std::string const& filename, efsw::Action /*action*/, std::string /*oldFilename*/)
@@ -48,7 +45,11 @@ void ElunaUpdateListener::handleFileAction(efsw::WatchID /*watchid*/, std::strin
     std::string ext = path.extension().string();
     std::transform(ext.begin(), ext.end(), ext.begin(), [](unsigned char c) { return std::tolower(c); });
 
-    if (ext != ".lua" && ext != ".ext")
+    if (ext != ".lua" && ext != ".ext"
+#if defined ELUNA_LUAU
+        && ext != ".luau"
+#endif
+        )
         return;
 
     sElunaLoader->ReloadElunaForMap(RELOAD_ALL_STATES);
@@ -183,9 +184,14 @@ void ElunaLoader::ReadFiles(lua_State* L, std::string path)
     if (fs::exists(someDir) && fs::is_directory(someDir) && !fs::is_empty(someDir))
     {
         m_requirePath +=
+#if defined ELUNA_LUAU
+            path + "/?.luau;" +
+#endif
             path + "/?.lua;" +
-            path + "/?.ext;" +
-            path + "/?.moon;";
+            path + "/?.ext;";
+#if !defined ELUNA_LUAU
+        m_requirePath += path + "/?.moon;";
+#endif
 
         m_requirecPath +=
             path + "/?.dll;" +
@@ -239,6 +245,37 @@ void ElunaLoader::ReadFiles(lua_State* L, std::string path)
 
 bool ElunaLoader::CompileScript(lua_State* L, LuaScript& script)
 {
+#if defined ELUNA_LUAU
+    if (script.fileext == ".moon")
+    {
+        ELUNA_LOG_ERROR("[Eluna]: MoonScript is not supported by Luau: `%s`", script.filepath.c_str());
+        return false;
+    }
+    std::ifstream file(script.filepath, std::ios::binary);
+    if (!file)
+    {
+        ELUNA_LOG_ERROR("[Eluna]: Cannot read Luau script `%s`", script.filepath.c_str());
+        return false;
+    }
+    std::string source((std::istreambuf_iterator<char>(file)), std::istreambuf_iterator<char>());
+    if (file.bad())
+    {
+        ELUNA_LOG_ERROR("[Eluna]: Failed reading Luau script `%s`", script.filepath.c_str());
+        return false;
+    }
+    std::string bytecode = ElunaLua::Compile(source.data(), source.size());
+    // Luau's compiler encodes syntax errors in its output. Loading validates
+    // that output and places a useful diagnostic on the temporary state's stack.
+    if (luau_load(L, ("@" + script.filepath).c_str(), bytecode.data(), bytecode.size(), 0))
+    {
+        ELUNA_LOG_ERROR("[Eluna]: Failed compiling Luau script `%s`", script.filepath.c_str());
+        Eluna::Report(L);
+        return false;
+    }
+    lua_pop(L, 1);
+    script.bytecode.assign(bytecode.begin(), bytecode.end());
+    return true;
+#else
     // Attempt to load the file
     int err = 0;
     if (script.fileext == ".moon")
@@ -270,6 +307,7 @@ bool ElunaLoader::CompileScript(lua_State* L, LuaScript& script)
     // pop the loaded function from the stack
     lua_pop(L, 1);
     return true;
+#endif
 }
 
 void ElunaLoader::ProcessScript(lua_State* L, std::string filename, const size_t& filesize, const std::string& fullpath, int32 mapId)
@@ -284,7 +322,11 @@ void ElunaLoader::ProcessScript(lua_State* L, std::string filename, const size_t
     filename = filename.substr(0, extDot);
 
     // check extension and add path to scripts to load
-    if (ext != ".lua" && ext != ".ext" && ext != ".moon")
+    if (ext != ".lua" && ext != ".ext" && ext != ".moon"
+#if defined ELUNA_LUAU
+        && ext != ".luau"
+#endif
+        )
         return;
     bool extension = ext == ".ext";
 

ElunaLoader.h

@@ -14,10 +14,7 @@
 #include <efsw/efsw.hpp>
 #endif
 
-extern "C"
-{
-#include "lua.h"
-};
+#include "ElunaCompat.h"
 
 enum ElunaReloadActions
 {