From f3da9a4da625f3157f29e2727b8841463d742636 Mon Sep 17 00:00:00 2001
From: Dregu <dregu@dreg.us>
Date: Thu, 9 Nov 2023 20:10:53 +0200
Subject: [PATCH] add some lua libraries to spel2.lua

---
 docs/game_data/spel2.lua       | 28 ++++++++++++++++++++++++----
 docs/generate_emmylua.py       | 27 +++++++++++++++++++++++----
 docs/src/includes/_globals.md  |  2 +-
 src/game_api/script/lua_vm.cpp |  2 +-
 4 files changed, 49 insertions(+), 10 deletions(-)

diff --git a/docs/game_data/spel2.lua b/docs/game_data/spel2.lua
index 4668294e4..1c06048ca 100644
--- a/docs/game_data/spel2.lua
+++ b/docs/game_data/spel2.lua
@@ -25,14 +25,34 @@ options = nil
 ---@type PRNG
 prng = nil
 
+---Create a global `exports` table and put stuff in it,
+---and other scripts will be able to `import` your script like a library
+---@class Exports
+
+---@type Exports
+exports = nil
+
+---The json library converts tables to json and json to tables
+---Check https://github.com/rxi/json.lua for more information
+---@class Json
+---@field decode fun(str: string): table @Decode a json string into a table
+---@field encode fun(tbl: table): string @Encode a table into a json string
+---@type Json
+json = nil
+
+
 -- Functions
 
 
----Formatting function, use e.g. as f "my_var = {my_var}"
+---Return any type of object or multiple objects as a debug string.
+---@vararg any
+---@return string
+function inspect(...) end
+---Formatting function, use e.g. as f"my_var = {my_var}"
 ---@param f_string string
 ---@return string
 function f(f_string) end
----Formatting function, use e.g. as f "my_var = {my_var}"
+---Formatting function, use e.g. as F"my_var = {my_var}"
 ---@param f_string string
 ---@return string
 function F(f_string) end
@@ -129,8 +149,8 @@ function clear_callback(id) end
 ---- `false` if the script was not found but optional is set to true
 ---- an error if the script was not found and the optional argument was not set
 ---@param id string
----@param version string
----@param optional boolean
+---@param version string?
+---@param optional boolean?
 ---@return table
 function import(id, version, optional) end
 ---Check if another script is enabled by id "author/name". You should probably check this after all the other scripts have had a chance to load.
diff --git a/docs/generate_emmylua.py b/docs/generate_emmylua.py
index ac64ac002..16bebb248 100644
--- a/docs/generate_emmylua.py
+++ b/docs/generate_emmylua.py
@@ -211,17 +211,36 @@ def main():
 ---@type any
 options = nil
 ---@type PRNG
-prng = nil"""
-    )
+prng = nil
+
+---Create a global `exports` table and put stuff in it,
+---and other scripts will be able to `import` your script like a library
+---@class Exports
+
+---@type Exports
+exports = nil
+
+---The json library converts tables to json and json to tables
+---Check https://github.com/rxi/json.lua for more information
+---@class Json
+---@field decode fun(str: string): table @Decode a json string into a table
+---@field encode fun(tbl: table): string @Encode a table into a json string
+---@type Json
+json = nil
+""")
 
     print("\n-- Functions\n")
     print(
         """
----Formatting function, use e.g. as f "my_var = {my_var}"
+---Return any type of object or multiple objects as a debug string.
+---@vararg any
+---@return string
+function inspect(...) end
+---Formatting function, use e.g. as f"my_var = {my_var}"
 ---@param f_string string
 ---@return string
 function f(f_string) end
----Formatting function, use e.g. as f "my_var = {my_var}"
+---Formatting function, use e.g. as F"my_var = {my_var}"
 ---@param f_string string
 ---@return string
 function F(f_string) end
diff --git a/docs/src/includes/_globals.md b/docs/src/includes/_globals.md
index 7c8835208..cb5eda369 100644
--- a/docs/src/includes/_globals.md
+++ b/docs/src/includes/_globals.md
@@ -1572,7 +1572,7 @@ Grow vines from `GROWABLE_VINE` and `VINE_TREE_TOP` entities in a level, `area`
 
 > Search script examples for [import](https://github.com/spelunky-fyi/overlunky/search?l=Lua&q=import)
 
-#### table import(string id, string version = "", bool optional = false)
+#### table import(string id, optional<string> version, optional<bool> optional)
 
 Load another script by id "author/name" and import its `exports` table. Returns:
 
diff --git a/src/game_api/script/lua_vm.cpp b/src/game_api/script/lua_vm.cpp
index 55d1bb794..87fd2c8a9 100644
--- a/src/game_api/script/lua_vm.cpp
+++ b/src/game_api/script/lua_vm.cpp
@@ -555,7 +555,7 @@ end
     /// - `nil` if the script was found but has no exports
     /// - `false` if the script was not found but optional is set to true
     /// - an error if the script was not found and the optional argument was not set
-    // lua["import"] = [](string id, string version = "", bool optional = false) -> table
+    // lua["import"] = [](string id, optional<string> version, optional<bool> optional) -> table
     lua["import"] = sol::overload(
         [&lua](std::string id)
         {