Merge pull request #52 from gilzoide/feature/godot-package-searcher

Add support for local paths in package searchers, `loadfile` and `dofile`

Author: gilzoide

CHANGELOG.md

@@ -3,10 +3,15 @@
 ### Added
 - Editor plugin that registers the Lua REPL tab, where you can try Lua code using an empty `LuaState`
 - Support for calling Godot String methods using Lua strings
+- Optional support for `res://` and `user://` relative paths in package searchers, `loadfile` and `dofile`.
+  Open the `GODOT_LOCAL_PATHS` library to activate this behavior.
+- `LuaState.LoadMode` enum for specifying the Lua load mode: text, binary or any
+- `LuaState.do_buffer` and `LuaState.load_buffer` for loading Lua code from possibly binary chunks
 
 ### Changed
 - The GDExtension is now marked as reloadable
 - Renamed `LuaCoroutine::LuaCoroutineStatus` to `LuaCoroutine::Status`
+- `LuaState.load_file` and `LuaState.do_file` now receive the load mode instead of buffer size
 
 ### Removed
 - `VariantType::has_static_method` internal method

SConstruct

@@ -13,9 +13,11 @@ env.Command(
     [
         "src/generated/global_enums.hpp",
         "src/generated/utility_functions.hpp",
+        "src/generated/package_searcher.h",
     ],
     [
         "src/generate_code.py",
+        "src/luaopen/package_searcher.lua",
         "lib/godot-cpp/gdextension/extension_api.json",
         "lib/godot-cpp/gen/include/godot_cpp/variant/utility_functions.hpp",
     ],

src/LuaState.cpp

@@ -124,27 +124,38 @@ void LuaState::open_libraries(BitField<Library> libraries) {
 		if (libraries.has_flag(GODOT_ENUMS)) {
 			lua_state.require(module_names::enums, &luaopen_godot_enums, false);
 		}
+		if (libraries.has_flag(GODOT_LOCAL_PATHS)) {
+			lua_state.require(module_names::local_paths, &luaopen_godot_local_paths, false);
+		}
 	}
 }
 
 Ref<LuaTable> LuaState::create_table(const Dictionary& initial_values) {
 	return memnew(LuaTable(to_table(lua_state, initial_values)));
 }
 
+Variant LuaState::load_buffer(const PackedByteArray& chunk, const String& chunkname, LoadMode mode, LuaTable *env) {
+	return ::luagdextension::load_buffer(lua_state, chunk, chunkname, (sol::load_mode) mode, env);
+}
+
 Variant LuaState::load_string(const String& chunk, const String& chunkname, LuaTable *env) {
-	return ::luagdextension::load_string(lua_state, chunk, chunkname, env);
+	return ::luagdextension::load_buffer(lua_state, chunk.to_utf8_buffer(), chunkname, sol::load_mode::text, env);
 }
 
-Variant LuaState::load_file(const String& filename, int buffer_size, LuaTable *env) {
-	return ::luagdextension::load_file(lua_state, filename, buffer_size, env);
+Variant LuaState::load_file(const String& filename, LoadMode mode, LuaTable *env) {
+	return ::luagdextension::load_file(lua_state, filename, (sol::load_mode) mode, env);
+}
+
+Variant LuaState::do_buffer(const PackedByteArray& chunk, const String& chunkname, LoadMode mode, LuaTable *env) {
+	return ::luagdextension::do_buffer(lua_state, chunk, chunkname, (sol::load_mode) mode, env);
 }
 
 Variant LuaState::do_string(const String& chunk, const String& chunkname, LuaTable *env) {
-	return ::luagdextension::do_string(lua_state, chunk, chunkname, env);
+	return ::luagdextension::do_buffer(lua_state, chunk.to_utf8_buffer(), chunkname, sol::load_mode::text, env);
 }
 
-Variant LuaState::do_file(const String& filename, int buffer_size, LuaTable *env) {
-	return ::luagdextension::do_file(lua_state, filename, buffer_size, env);
+Variant LuaState::do_file(const String& filename, LoadMode mode, LuaTable *env) {
+	return ::luagdextension::do_file(lua_state, filename, (sol::load_mode) mode, env);
 }
 
 LuaTable *LuaState::get_globals() const {
@@ -187,17 +198,25 @@ void LuaState::_bind_methods() {
 	BIND_BITFIELD_FLAG(GODOT_SINGLETONS);
 	BIND_BITFIELD_FLAG(GODOT_CLASSES);
 	BIND_BITFIELD_FLAG(GODOT_ENUMS);
+	BIND_BITFIELD_FLAG(GODOT_LOCAL_PATHS);
 	BIND_BITFIELD_FLAG(GODOT_ALL_LIBS);
 
 	BIND_BITFIELD_FLAG(ALL_LIBS);
 
+	// LoadMode enum
+	BIND_ENUM_CONSTANT(LOAD_MODE_ANY);
+	BIND_ENUM_CONSTANT(LOAD_MODE_TEXT);
+	BIND_ENUM_CONSTANT(LOAD_MODE_BINARY);
+
 	// Methods
 	ClassDB::bind_method(D_METHOD("open_libraries", "libraries"), &LuaState::open_libraries, DEFVAL(BitField<Library>(ALL_LIBS)));
 	ClassDB::bind_method(D_METHOD("create_table", "initial_values"), &LuaState::create_table, DEFVAL(Dictionary()));
+	ClassDB::bind_method(D_METHOD("load_buffer", "chunk", "chunkname", "mode", "env"), &LuaState::load_buffer, DEFVAL(""), DEFVAL(LOAD_MODE_ANY), DEFVAL(nullptr));
 	ClassDB::bind_method(D_METHOD("load_string", "chunk", "chunkname", "env"), &LuaState::load_string, DEFVAL(""), DEFVAL(nullptr));
-	ClassDB::bind_method(D_METHOD("load_file", "filename", "buffer_size", "env"), &LuaState::load_file, DEFVAL(1024), DEFVAL(nullptr));
+	ClassDB::bind_method(D_METHOD("load_file", "filename", "mode", "env"), &LuaState::load_file, DEFVAL(LOAD_MODE_ANY), DEFVAL(nullptr));
+	ClassDB::bind_method(D_METHOD("do_buffer", "chunk", "chunkname", "mode", "env"), &LuaState::do_buffer, DEFVAL(""), DEFVAL(LOAD_MODE_ANY), DEFVAL(nullptr));
 	ClassDB::bind_method(D_METHOD("do_string", "chunk", "chunkname", "env"), &LuaState::do_string, DEFVAL(""), DEFVAL(nullptr));
-	ClassDB::bind_method(D_METHOD("do_file", "filename", "buffer_size", "env"), &LuaState::do_file, DEFVAL(1024), DEFVAL(nullptr));
+	ClassDB::bind_method(D_METHOD("do_file", "filename", "mode", "env"), &LuaState::do_file, DEFVAL(LOAD_MODE_ANY), DEFVAL(nullptr));
 	ClassDB::bind_method(D_METHOD("get_globals"), &LuaState::get_globals);
 	ClassDB::bind_method(D_METHOD("get_registry"), &LuaState::get_registry);
 

src/LuaState.hpp

@@ -70,18 +70,31 @@ class LuaState : public RefCounted {
 		LUA_ALL_LIBS = LUA_BASE | LUA_PACKAGE | LUA_COROUTINE | LUA_STRING | LUA_OS | LUA_MATH | LUA_TABLE | LUA_DEBUG | LUA_BIT32 | LUA_IO | LUA_FFI | LUA_JIT | LUA_UTF8,
 
 		// ----- Godot ----
+		// Variant types + String methods
 		GODOT_VARIANT = 1 << 13,
+		// utility functions, like "is_same" and "deg_to_rad". Also sets "print" to Godot's "printt"
 		GODOT_UTILITY_FUNCTIONS = 1 << 14,
+		// allows acessing singleton instances in _G
 		GODOT_SINGLETONS = 1 << 15,
+		// allows accessing classes by name in _G
 		GODOT_CLASSES = 1 << 16,
+		// global enums, like "KEY_A" and "PROPERTY_HINT_NONE"
 		GODOT_ENUMS = 1 << 17,
+		// add support for "res://" and "user://" paths in package searchers, "loadfile" and "dofile"
+		GODOT_LOCAL_PATHS = 1 << 18,
 
 		// all of the above
-		GODOT_ALL_LIBS = GODOT_VARIANT | GODOT_UTILITY_FUNCTIONS | GODOT_SINGLETONS | GODOT_CLASSES | GODOT_ENUMS,
+		GODOT_ALL_LIBS = GODOT_VARIANT | GODOT_UTILITY_FUNCTIONS | GODOT_SINGLETONS | GODOT_CLASSES | GODOT_ENUMS | GODOT_LOCAL_PATHS,
 
 		ALL_LIBS = LUA_ALL_LIBS | GODOT_ALL_LIBS,
 	};
 
+	enum LoadMode {
+		LOAD_MODE_ANY = (int) sol::load_mode::any,
+		LOAD_MODE_TEXT = (int) sol::load_mode::text,
+		LOAD_MODE_BINARY = (int) sol::load_mode::binary,
+	};
+
 	LuaState();
 	~LuaState();
 
@@ -90,10 +103,12 @@ class LuaState : public RefCounted {
 	void open_libraries(BitField<Library> libraries = ALL_LIBS);
 
 	Ref<LuaTable> create_table(const Dictionary& initial_values = {});
+	Variant load_buffer(const PackedByteArray& chunk, const String& chunkname = "", LoadMode mode = LOAD_MODE_ANY, LuaTable *env = nullptr);
 	Variant load_string(const String& chunk, const String& chunkname = "", LuaTable *env = nullptr);
-	Variant load_file(const String& filename, int buffer_size = 1024, LuaTable *env = nullptr);
+	Variant load_file(const String& filename, LoadMode mode = LOAD_MODE_ANY, LuaTable *env = nullptr);
+	Variant do_buffer(const PackedByteArray& chunk, const String& chunkname = "", LoadMode mode = LOAD_MODE_ANY, LuaTable *env = nullptr);
 	Variant do_string(const String& chunk, const String& chunkname = "", LuaTable *env = nullptr);
-	Variant do_file(const String& filename, int buffer_size = 1024, LuaTable *env = nullptr);
+	Variant do_file(const String& filename, LoadMode mode = LOAD_MODE_ANY, LuaTable *env = nullptr);
 
 	LuaTable *get_globals() const;
 	LuaTable *get_registry() const;
@@ -115,5 +130,6 @@ class LuaState : public RefCounted {
 
 }
 VARIANT_BITFIELD_CAST(luagdextension::LuaState::Library);
+VARIANT_ENUM_CAST(luagdextension::LuaState::LoadMode);
 
 #endif

src/generate_code.py

@@ -4,6 +4,7 @@
 SRC_DIR = os.path.dirname(__file__)
 DEST_DIR = os.path.join(SRC_DIR, "generated")
 API_JSON_PATH = os.path.join(SRC_DIR, "..", "lib", "godot-cpp", "gdextension", "extension_api.json")
+PACKAGE_SEARCHER_SRC = os.path.join(SRC_DIR, "luaopen", "package_searcher.lua")
 PRIMITIVE_VARIANTS = [
     "bool",
     "int",
@@ -18,7 +19,8 @@
 
 def generate_utility_functions(utility_functions):
     lines = [
-        "#undef register_utility_functions\n#define register_utility_functions(state)"
+        "// This file was automatically generated by generate_code.py",
+        "#undef register_utility_functions\n#define register_utility_functions(state)",
     ]
     for f in utility_functions:
         name = f["name"]
@@ -39,7 +41,8 @@ def generate_utility_functions(utility_functions):
 
 def generate_enums(global_enums):
     lines = [
-        "#undef register_global_enums\n#define register_global_enums(state)"
+        "// This file was automatically generated by generate_code.py",
+        "#undef register_global_enums\n#define register_global_enums(state)",
     ]
     for enum in global_enums:
         lines.append(f"\t/* {enum['name']} */")
@@ -48,6 +51,19 @@ def generate_enums(global_enums):
     return " \\\n".join(lines) + "\n"
 
 
+def generate_package_searcher():
+    lines = [
+        "// This file was automatically generated by generate_code.py",
+        "const char package_searcher_lua[] = ",
+    ]
+    with open(PACKAGE_SEARCHER_SRC, "r") as f:
+        for line in f:
+            line = line.replace("\\", "\\\\").replace('"', '\\"').rstrip("\r\n")
+            lines.append('"' + line + '\\n"')
+    lines.append(";")
+    return "\n".join(lines)
+
+
 def main():
     with open(API_JSON_PATH) as f:
         api = json.load(f)
@@ -60,6 +76,10 @@ def main():
     with open(os.path.join(DEST_DIR, "global_enums.hpp"), "w") as f:
         code = generate_enums(api["global_enums"])
         f.write(code)
+    
+    with open(os.path.join(DEST_DIR, "package_searcher.h"), "w") as f:
+        code = generate_package_searcher()
+        f.write(code)
 
 
 if __name__ == "__main__":

src/luaopen/enums.cpp

@@ -20,12 +20,9 @@
  * SOFTWARE.
  */
 #include "../generated/global_enums.hpp"
-#include "../utils/module_names.hpp"
 
 #include <sol/sol.hpp>
 
-using namespace luagdextension;
-
 extern "C" int luaopen_godot_enums(lua_State *L) {
 	sol::state_view state = L;
 

src/luaopen/godot.cpp

@@ -36,6 +36,7 @@ extern "C" int luaopen_godot(lua_State *L) {
 	state.require(module_names::singleton_access, &luaopen_godot_singleton_access, false);
 	state.require(module_names::classes, &luaopen_godot_classes, false);
 	state.require(module_names::enums, &luaopen_godot_enums, false);
+	state.require(module_names::local_paths, &luaopen_godot_local_paths, false);
 
 	return 0;
 }

src/luaopen/godot.hpp

@@ -32,6 +32,7 @@ int luaopen_godot_utility_functions(lua_State *L);
 int luaopen_godot_singleton_access(lua_State *L);
 int luaopen_godot_classes(lua_State *L);
 int luaopen_godot_enums(lua_State *L);
+int luaopen_godot_local_paths(lua_State *L);
 
 }
 

src/luaopen/local_paths.cpp

@@ -0,0 +1,124 @@
+/**
+ * Copyright (C) 2025 Gil Barbosa Reis.
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the “Software”), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+ * of the Software, and to permit persons to whom the Software is furnished to do
+ * so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+#include "../LuaTable.hpp"
+#include "../utils/convert_godot_lua.hpp"
+#include "../utils/load_fileaccess.hpp"
+#include "sol/forward.hpp"
+#include "sol/load_result.hpp"
+
+#include <godot_cpp/classes/engine.hpp>
+#include <godot_cpp/classes/file_access.hpp>
+#include <godot_cpp/classes/os.hpp>
+#include <godot_cpp/classes/project_settings.hpp>
+
+#include "../generated/package_searcher.h"
+
+using namespace luagdextension;
+
+static int l_searchpath(lua_State *L) {
+	String name = luaL_checkstring(L, 1);
+	String path = luaL_checkstring(L, 2);
+	String sep = luaL_optstring(L, 3, ".");
+	String rep = luaL_optstring(L, 4, "/");
+	if (!sep.is_empty()) {
+		name = name.replace(sep, rep);
+	}
+
+	String execdir_repl = Engine::get_singleton()->is_editor_hint()
+		? ProjectSettings::get_singleton()->globalize_path("res://")
+		: OS::get_singleton()->get_executable_path().get_base_dir();
+	
+	PackedStringArray path_list = path.split(";", false);
+	PackedStringArray not_found_list;
+	for (const String& path_template : path_list) {
+		String filename = path_template.replace("?", name).replace("!", execdir_repl);
+		if (FileAccess::file_exists(filename)) {
+			sol::stack::push(L, filename);
+			return 1;
+		}
+		else {
+			not_found_list.append(filename);
+		}
+	}
+
+	// path not found, return a formatted error message
+	String error_message;
+	for (const String& filename : not_found_list) {
+		error_message += String("\n\tno file \"%s\"") % filename;
+	}
+	sol::stack::push(L, sol::nil);
+	sol::stack::push(L, error_message);
+	return 2;
+}
+
+static int l_loadfile(lua_State *L) {
+	sol::state_view state(L);
+	String filename = luaL_optstring(L, 1, "");
+	String mode = luaL_optstring(L, 2, "bt");
+	Variant env = to_variant(sol::stack_object(L, 3));
+
+	sol::load_result result = load_fileaccess(state, filename, mode, Object::cast_to<LuaTable>(env));
+	if (result.valid()) {
+		result = sol::load_result();  // avoid popping result
+		return 1;
+	}
+	else {
+		lua_pushnil(L);
+		lua_rotate(L, result.stack_index(), 1);
+		result = sol::load_result();  // avoid popping error
+		return 2;
+	}
+}
+
+static int l_dofile(lua_State *L) {
+	sol::state_view state(L);
+	String filename = luaL_optstring(L, 1, "");
+	
+	int previous_top = lua_gettop(L);
+	sol::load_result result = load_fileaccess(state, filename);
+	if (result.valid()) {
+		result = sol::load_result();  // avoid over-popping function
+		lua_call(L, 0, LUA_MULTRET);
+		return lua_gettop(L) - previous_top;
+	}
+	else {
+		result = sol::load_result();  // avoid popping error
+		return lua_error(L);
+	}
+}
+
+extern "C" int luaopen_godot_local_paths(lua_State *L) {
+	sol::state_view state = L;
+
+	if (auto package = state.get<sol::optional<sol::table>>("package")) {
+		(*package)["searchpath"] = l_searchpath;
+		state.do_string(package_searcher_lua);
+	}
+
+	state["loadfile"] = l_loadfile;
+	state["dofile"] = l_dofile;
+
+	return 0;
+}
+ 
+