Merge remote-tracking branch 'origin/main' into docs-validator

README.md

@@ -181,6 +181,7 @@ The binaries will be in `build/bin/Release/`. You can also try the scripts in `.
 
 ```
 --launch_game [path]    launch ../Spel2.exe, path/Spel2.exe, or a specific exe, and load OL with Detours
+--oldflip               launch the game with -oldflip, may improve performance with external windows
 --console               keep console open to debug scripts etc
 --inject                use the old injection method instead of Detours with --launch_game
 --info_dump             output a bunch of game data to 'Spelunky 2/game_data'

docs/examples/io.lua

@@ -0,0 +1,15 @@
+-- Write a data file
+-- Data will be written to Mods/Data/[scriptname.lua or Mod Name]/timestamp.txt
+local f = io.open_data(tostring(os.time()) .. ".txt", "w")
+if f then
+    f:write("hello world at " .. os.date())
+    f:close()
+end
+
+-- List all files in data dir and read them out
+for _, v in pairs(list_data_dir()) do
+    local f = io.open_data(v)
+    if f then
+        print(v .. ": " .. f:read("a"))
+    end
+end

docs/generate.py

@@ -203,8 +203,45 @@ def print_lf(lf):
 print(
     "The following Lua libraries and their functions are available. You can read more about them in the [Lua documentation](https://www.lua.org/manual/5.4/manual.html#6). We're using Lua 5.4 with the [Sol C++ binding](https://sol2.readthedocs.io/en/latest/)."
 )
+
+print("\n## io")
+include_example("io")
+print(
+    """
+`meta.unsafe` exposes all [standard library functions](https://www.lua.org/manual/5.4/manual.html#6.8) and removes basedir restrictions from the custom functions.
+
+In safe mode (default) the following standard and custom functions are available:
+
+- `io.type`
+- `io.open_data`: like `io.open` but restricted to base directory `Mods/Data/modname`
+- `io.open_mod`: like `io.open` but restricted to the mod directory
+
+Safely opened files can be used normally through the `file:` handle. Files and folders opened in write mode are automatically created.
+
+Also see [list_dir](#list_dir) and [list_data_dir](#list_data_dir).
+"""
+)
+
+print("\n## os")
+include_example("os")
+print(
+    """
+`meta.unsafe` exposes all [standard library functions](https://www.lua.org/manual/5.4/manual.html#6.9) and removes basedir restrictions from the custom functions.
+
+In safe mode (default) the following standard and custom functions are available:
+
+- `os.clock`
+- `os.date`
+- `os.difftime`
+- `os.time`
+- `os.remove_data`: like `os.remove` but restricted to base directory `Mods/Data/modname`
+- `os.remove_mod`: like `os.remove` but restricted to the mod directory
+"""
+)
+
 for lib in ps.lualibs:
     print("\n## " + lib + "")
+
 print("\n## json")
 include_example("json")
 print(
@@ -276,7 +313,7 @@ def print_lf(lf):
 
 print("\n# Unsafe mode")
 print(
-    "Setting `meta.unsafe = true` enables the rest of the standard Lua libraries like `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` 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."
 )
 
 print("\n# Modules")

docs/generate_emmylua.py

@@ -184,7 +184,9 @@ def main():
     gu.setup_stdout("game_data/spel2.lua")
 
     print(
-        """---@diagnostic disable: unused-function,lowercase-global,missing-return,duplicate-doc-alias,duplicate-set-field
+        """---@meta
+---@diagnostic disable: duplicate-doc-alias
+
 ---@class Meta
 ---@field name string
 ---@field version string