From 5df01eac59c4e73819f3f45e0a1a06517c8a8640 Mon Sep 17 00:00:00 2001 From: Dregu Date: Sun, 15 Oct 2023 11:33:48 +0300 Subject: [PATCH] docs --- docs/game_data/spel2.lua | 7 ++++++- docs/generate.py | 11 +++++++++-- docs/src/includes/_globals.md | 11 ++++++++++- docs/src/includes/_home.md | 2 +- src/game_api/script/lua_vm.cpp | 9 +++++---- 5 files changed, 31 insertions(+), 9 deletions(-) diff --git a/docs/game_data/spel2.lua b/docs/game_data/spel2.lua index ffa664047..4ddeecfaa 100644 --- a/docs/game_data/spel2.lua +++ b/docs/game_data/spel2.lua @@ -53,7 +53,7 @@ function lua_print() end ---@param message string ---@return nil function print(message) end ----Print a log message to ingame console. +---Print a log message to ingame console with a comment identifying the script that sent it. ---@param message string ---@return nil function console_print(message) end @@ -73,6 +73,11 @@ function prinspect(...) end ---@vararg any ---@return nil function messpect(...) end +---Dump the object (table, container, class) as a recursive table, for pretty printing in console. Don't use this for anything except debug printing. Unsafe. +---@param any any +---@param depth integer? +---@return table +function dump(object, depth) end ---Adds a command that can be used in the console. ---@param name string ---@param cmd function diff --git a/docs/generate.py b/docs/generate.py index 339d7945c..e44df546a 100644 --- a/docs/generate.py +++ b/docs/generate.py @@ -306,7 +306,7 @@ def print_lf(lf): print("\n# Unsafe mode") print( - "Setting `meta.unsafe = true` enables the rest of the standard Lua libraries like unrestricted `io` and `os`, loading dlls with require and `package.loadlib`. Using unsafe scripts requires users to enable the option in the overlunky.ini file which is found in the Spelunky 2 installation directory." + "Setting `meta.unsafe = true` enables the rest of the standard Lua libraries like unrestricted `io`, `os`, `ffi` and `debug`, loading dlls with require, `package.loadlib`, the [network functions](#Network-functions) and some [debug functions](#Debug-functions). Using unsafe scripts requires users to enable the option in the overlunky.ini file which is found in the Spelunky 2 installation directory." ) print("\n# Modules") @@ -393,7 +393,14 @@ def print_lf(lf): cat = "Message functions" elif any( subs in func["name"] - for subs in ["get_rva", "get_virtual_rva", "raise", "dump_network"] + for subs in [ + "get_rva", + "get_virtual_rva", + "raise", + "dump_network", + "dump", + "dump_string", + ] ): cat = "Debug functions" elif any(subs in func["name"] for subs in ["_option"]): diff --git a/docs/src/includes/_globals.md b/docs/src/includes/_globals.md index 138da2c7c..30c12d1c7 100644 --- a/docs/src/includes/_globals.md +++ b/docs/src/includes/_globals.md @@ -342,6 +342,15 @@ If you set such a callback and then play the same sound yourself you have to wai ## Debug functions +### dump + + +> Search script examples for [dump](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=dump) + +#### table dump(object object, optional depth) + +Dump the object (table, container, class) as a recursive table, for pretty printing in console. Don't use this for anything except debug printing. Unsafe. + ### dump_network @@ -1983,7 +1992,7 @@ Prinspect to ingame console. #### nil console_print(string message) -Print a log message to ingame console. +Print a log message to ingame console with a comment identifying the script that sent it. ### log_print diff --git a/docs/src/includes/_home.md b/docs/src/includes/_home.md index c08dce91a..4efbe5a83 100644 --- a/docs/src/includes/_home.md +++ b/docs/src/includes/_home.md @@ -140,7 +140,7 @@ end ``` # Unsafe mode -Setting `meta.unsafe = true` enables the rest of the standard Lua libraries like unrestricted `io` and `os`, loading dlls with require and `package.loadlib`. Using unsafe scripts requires users to enable the option in the overlunky.ini file which is found in the Spelunky 2 installation directory. +Setting `meta.unsafe = true` enables the rest of the standard Lua libraries like unrestricted `io`, `os`, `ffi` and `debug`, loading dlls with require, `package.loadlib`, the [network functions](#Network-functions) and some [debug functions](#Debug-functions). Using unsafe scripts requires users to enable the option in the overlunky.ini file which is found in the Spelunky 2 installation directory. # Modules You can load modules with `require "mymod"` or `require "mydir.mymod"`, just put `mymod.lua` in the same directory the script is, or in `mydir/` to keep things organized. diff --git a/src/game_api/script/lua_vm.cpp b/src/game_api/script/lua_vm.cpp index b7e681085..5ebd92de4 100644 --- a/src/game_api/script/lua_vm.cpp +++ b/src/game_api/script/lua_vm.cpp @@ -413,6 +413,7 @@ end /// Same as `print` lua["message"] = [&lua](std::string message) -> void { lua["print"](message); }; + /// Prints any type of object by first funneling it through `inspect`, no need for a manual `tostring` or `inspect`. lua["prinspect"] = [&lua](sol::variadic_args objects) -> void { @@ -430,10 +431,14 @@ end lua["print"](std::move(message)); } }; + /// Same as `prinspect` lua["messpect"] = [&lua](sol::variadic_args objects) -> void { lua["prinspect"](objects); }; + /// Dump the object (table, container, class) as a recursive table, for pretty printing in console. Don't use this for anything except debug printing. Unsafe. + // lua["dump"] = [](object object, optional depth) -> table + /// Adds a command that can be used in the console. lua["register_console_command"] = [](std::string name, sol::function cmd) { @@ -2780,7 +2785,6 @@ void add_partial_safe_libraries(sol::environment& env) std::string fullpath = datadir + "/" + filename; std::string dirpath = std::filesystem::path(fullpath).parent_path().string(); auto is_based = check_safe_io_path(fullpath, datadir); - DEBUG("io.open_data: safe:{} pack:{} based:{} mode:{} {}", is_safe, is_pack, is_based, mode.value_or("r"), fullpath); if (is_safe && !is_based) { luaL_error(global_vm, "Attempted to open data file outside data directory"); @@ -2799,7 +2803,6 @@ void add_partial_safe_libraries(sol::environment& env) std::string fullpath = std::string(backend->get_root()) + "/" + filename; auto is_based = check_safe_io_path(fullpath, backend->get_root()); std::string dirpath = std::filesystem::path(fullpath).parent_path().string(); - DEBUG("io.open_mod: safe:{} pack:{} based:{} mode:{} {}", is_safe, is_pack, is_based, mode.value_or("r"), fullpath); if (is_safe) { if (!is_based) @@ -2829,7 +2832,6 @@ void add_partial_safe_libraries(sol::environment& env) std::string fullpath = datadir + "/" + filename; std::string dirpath = std::filesystem::path(fullpath).parent_path().string(); auto is_based = check_safe_io_path(fullpath, datadir); - DEBUG("os.remove_data: safe:{} pack:{} based:{} {}", is_safe, is_pack, is_based, fullpath); if (is_safe && !is_based) { luaL_error(global_vm, "Attempted to remove data file outside data directory"); @@ -2846,7 +2848,6 @@ void add_partial_safe_libraries(sol::environment& env) std::string fullpath = std::string(backend->get_root()) + "/" + filename; auto is_based = check_safe_io_path(fullpath, backend->get_root()); std::string dirpath = std::filesystem::path(fullpath).parent_path().string(); - DEBUG("os.remove_mod: safe:{} pack:{} based:{} {}", is_safe, is_pack, is_based, fullpath); if (is_safe) { if (!is_based)