Use stb_image_write to save PNG screenshots

libs/ldump/.busted

@@ -0,0 +1,7 @@
+return {
+  default = {
+    ROOT = {"."},
+    pattern = "test_",
+    verbose = true,
+  },
+}

libs/ldump/.github/workflows/run_tests.yaml

@@ -0,0 +1,33 @@
+name: Run tests
+on: [push]
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        luaVersion: ["5.4", "5.3", "5.2", "5.1", "luajit-openresty"]
+
+    # would not test on windows, the leafo-gh-actions-lua bugs out even with presetup
+    runs-on: ubuntu-22.04
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+
+    - name: Setup Lua
+      uses: leafo/gh-actions-lua@v10
+      with:
+        luaVersion: ${{ matrix.luaVersion }}
+        buildCache: false
+
+    - name: Setup Luarocks
+      uses: leafo/gh-actions-luarocks@v4
+
+    - name: Setup busted
+      run: luarocks install busted
+
+    - name: Run Busted
+      run: busted -v
+
+    - name: Run Busted in safety mode
+      run: LDUMP_TEST_SAFETY=1 busted -v

libs/ldump/.gitignore

@@ -0,0 +1,4 @@
+luacov.stats.out
+luacov.report.out
+test.lua
+_deps

libs/ldump/LICENSE

@@ -0,0 +1,16 @@
+MIT No Attribution
+
+Copyright 2025 girvel a.k.a. Nikita Dobrynin
+
+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.
+
+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.

libs/ldump/README.md

@@ -0,0 +1,113 @@
+[API](/docs/api.md) | [Overloading serialization](/docs/overloading.md) | [Serializing modules](/docs/serializing_modules.md) | [Safety](/docs/safety.md) | [Development](/docs/development.md)
+
+# ldump — serialization library for any lua type
+
+`ldump` is a flexible serializer, able to serialize any data, starting with circular references, tables as keys, functions with upvalues, metatables and ending with coroutines, threads and userdata (by defining how they should be serialized). It outputs valid Lua code that recreates the original object, doing the deserialization through `load(data)()`. It aims for functionality and flexibility instead of speed and size, allowing full serialization of complex data, such as video game saves. The output is large, but can be drastically reduced with modern compression algorithms.
+
+Inspired by [`Ser`](https://github.com/gvx/Ser). Supports Lua 5.1, 5.2, 5.3, 5.4 and LuaJIT. Tested for edge cases, such as joined upvalues and _ENV redefinition. Fully annotated in compatibility with LuaLS.
+
+> [!WARNING]
+> `ldump`'s deserialization function is Lua's builtin `load`, which can load malicious code. Consider using JSON for untrusted data or use [safety measures](/docs/safety.md).
+
+| Type                                      | Support      |
+| ----------------------------------------- | ------------ |
+| nil, boolean, number, string              | full         |
+| function                                  | full         |
+| userdata                                  | user-defined |
+| thread                                    | user-defined |
+| table                                     | full         |
+| metatables[*](/docs/development.md#plans) | full         |
+
+
+## TL;DR show me the code
+
+```lua
+local ldump = require("ldump")
+
+local upvalue = 42
+local world = {
+  name = "New world",
+  get_answer = function() return upvalue end,
+}
+
+local serialized_data = ldump(world)  -- serialize to a string
+local loaded_world = load(serialized_data)()  -- deserialize the string
+
+assert.are_equal(world.name, loaded_world.name)
+assert.are_equal(world.get_answer(), loaded_world.get_answer())
+```
+
+See as a test at [/tests/test_use_case.lua:7](/tests/test_use_case.lua#L7)
+
+
+## The full power of ldump
+
+```lua
+local ldump = require("ldump")
+
+-- basic tables
+local game_state = {
+  player = {name = "Player"},
+  boss = {name = "Boss"},
+}
+
+-- circular references & tables as keys
+game_state.deleted_entities = {
+  [game_state.boss] = true,
+}
+
+-- functions even with upvalues
+local upvalue = 42
+game_state.get_answer = function() return upvalue end
+
+-- fundamentally non-serializable types if overridden
+local create_coroutine = function()
+  return coroutine.wrap(function()
+    coroutine.yield(1337)
+    coroutine.yield(420)
+  end)
+end
+
+-- override serialization
+game_state.coroutine = create_coroutine()
+ldump.serializer.handlers[game_state.coroutine] = create_coroutine
+
+local serialized_data = ldump(game_state)  -- serialize
+local loaded_game_state = load(serialized_data)()  -- deserialize
+
+-- assert
+assert.are_equal(game_state.get_answer(), loaded_game_state.get_answer())
+assert.are_equal(game_state.coroutine(), loaded_game_state.coroutine())
+assert.are_equal(game_state.coroutine(), loaded_game_state.coroutine())
+
+assert.are_same(game_state.player, loaded_game_state.player)
+assert.are_same(game_state.boss, loaded_game_state.boss)
+assert.are_same(
+  game_state.deleted_entities[game_state.boss],
+  loaded_game_state.deleted_entities[loaded_game_state.boss]
+)
+```
+
+See as a test at [/tests/test_use_case.lua:23](/tests/test_use_case.lua#L23)
+
+
+## Installation
+
+- *Traditional way:* copy the [raw contents of init.lua from the latest release](https://raw.githubusercontent.com/girvel/ldump/refs/tags/v1.4.0/init.lua) into your `<lib>/ldump.lua`
+- *Recommended way:* `git clone -b v1.4.0 https://github.com/girvel/ldump` inside the `<lib>/` — you still would be able to do `require("ldump")`, and it would allow version management through git
+
+## On module serialization
+
+In most cases, if you want to serialize code and don't want all the used modules within to be recursively serialized -- you can turn on `ldump.preserve_modules`. As long as your code does `local module_name = require("module_name")`, not `local module_function = require("module_name").f` (meaning upvalues hold modules themselves, not their contents), all references to modules will be deserialized through require.
+
+If you have a more complex case, where you need the references to the data inside the modules persisting between serialization, you can use branch `2.0-mark`. It provides `ldump.mark*` functions, that explain to `ldump.serializer` which part of the module is static and can be deserialized through require. It is a development branch, but thoroughly tested and actively used in my other project ([girvel/engine](https://github.com/girvel/engine)), so it's stable and ready to use.
+
+---
+
+## Credits
+
+- [paulstelian97](https://www.reddit.com/user/paulstelian97/) for providing a joined upvalue test case
+- [lambda_abstraction](https://www.reddit.com/user/lambda_abstraction/) for suggesting a way to join upvalues
+- [jhatemyjob](https://news.ycombinator.com/user?id=jhatemyjob) for the special characters test case
+- [lifthrasiir](https://news.ycombinator.com/user?id=lifthrasiir) for pointing out safety issues
+- [radioflash](https://github.com/radioflash) for suggesting a simpler module serialization logic and suggestions for publicity

libs/ldump/benchmark/run.lua

@@ -0,0 +1,125 @@
+package.path = package.path .. ";./benchmark/_deps/?.lua"
+local ldump = require("init")
+local binser = require("binser")
+local bitser = require("bitser")
+local inspect = require("inspect")
+local utils = require("benchmark.utils")
+math.randomseed(os.time())
+
+
+--[[
+  output should look like this:
+
+  iterations: 10
+
+  serializer               | serialization time | deserialization time | memory
+  ------------------------ | ------------------ | -------------------- | ------
+  binser                   | 1.32 s             | 2.22 s               | 1.3 KB
+  bitser                   | 1.31 s             | 2.01 s               | 1.3 KB
+  ldump raw                | 1.5 s              | 3 s                  | 200 KB
+  ldump with compression_1 | 1.6 s              | 3.3 s                | 2 KB
+  ldump with compression_2 | 1.7 s              | 3.8 s                | 2.5 KB
+
+  maybe binser/bitser should be attempted with compression too
+]]
+
+
+-- data --
+-- should include large array with gaps, containing entities with repeating fields
+local data = {
+  entities = {},
+}
+
+local field_names = {}
+
+local a_pos = string.byte("a")
+local random_letter = function()
+  return string.char(a_pos + math.random(0, 25))
+end
+
+local random_string = function(min_length, max_length)
+  local result = ""
+  for _ = 1, math.random(min_length, max_length) do
+    result = result .. random_letter()
+  end
+  return result
+end
+
+for _ = 0, 40 do
+  table.insert(field_names, random_string(3, 11))
+end
+
+local random_value
+random_value = function()
+  local r = math.random()
+
+  if r < .2 then
+    return math.random() < .4
+  elseif r < .5 then
+    return random_string(2, 20)
+  else
+    return math.random() * 65536
+  end
+end
+
+local random_table = function(min_fields_n, max_fields_n)
+  local result = {}
+  for _ = 1, math.random(min_fields_n, max_fields_n) do
+    result[field_names[math.random(#field_names)]] = random_value()
+  end
+  return result
+end
+
+for i = 1, 10000 do
+  if math.random() < 0.2 then
+    data.entities[i] = random_table(1, 20)
+  else
+    data.entities[i] = nil
+  end
+end
+
+
+-- logic --
+
+local serializers = {
+  {
+    name = "ldump",
+    serialize = ldump,
+    deserialize = function(data)
+      return load(data)()
+    end,
+  },
+  {
+    name = "binser",
+    serialize = binser.serialize,
+    deserialize = binser.deserialize,
+  },
+  {
+    name = "bitser",
+    serialize = bitser.dumps,
+    deserialize = bitser.loads,
+  }
+}
+
+local names = {}
+local serialize_ts = {}
+local deserialize_ts = {}
+local memory_usages = {}
+
+for i, serializer in ipairs(serializers) do
+  names[i] = serializer.name
+
+  local serialize_t = os.clock()
+  local serialized = serializer.serialize(data)
+  serialize_ts[i] = ("%.3f s"):format(os.clock() - serialize_t)
+
+  local deserialize_t = os.clock()
+  _ = serializer.deserialize(serialized)
+  deserialize_ts[i] = ("%.3f s"):format(os.clock() - deserialize_t)
+
+  memory_usages[i] = ("%.3f KB"):format(#serialized / 1024)
+end
+
+local headers = {"serializer", "serialize time", "deserialize time", "memory"}
+
+print(utils.render_table(headers, {names, serialize_ts, deserialize_ts, memory_usages}))

libs/ldump/benchmark/utils.lua

@@ -0,0 +1,36 @@
+local utils = {}
+
+utils.render_table = function(headers, columns)
+  local result = "| "
+  local column_sizes = {}
+  for i, header in ipairs(headers) do
+    column_sizes[i] = #header
+    for _, value in ipairs(columns[i]) do
+      column_sizes[i] = math.max(column_sizes[i], #value)
+    end
+
+    result = result .. header .. string.rep(" ", column_sizes[i] - #header) .. " | "
+  end
+
+  result = result .. "\n| "
+
+  for i, size in ipairs(column_sizes) do
+    result = result .. string.rep("-", size) .. " | "
+  end
+
+  result = result .. "\n| "
+
+  for i = 1, #columns[1] do
+    if i > 1 then
+      result = result .. "\n| "
+    end
+    for j = 1, #columns do
+      local v = columns[j][i]
+      result = result .. v .. string.rep(" ", column_sizes[j] - #v) .. " | "
+    end
+  end
+
+  return result
+end
+
+return utils