Add optional Lua scripting module, examples, and validation

2026-09-18 11:28:50 +03:00
parent 06210aac23
commit 5a67735ff4
45 changed files with 3887 additions and 92 deletions
@@ -0,0 +1,55 @@
+# Lua module validation
+
+Local implementation checks, 2026-09-18. These results supplement, not replace,
+the earlier MVP acceptance record. Toolchain: Linux x86-64, GCC 13.3, CMake 4.4.3,
+Ninja 1.13.2; pinned Lua 5.4.9.
+
+## Observed results
+
+| Configuration | Result |
+|---|---|
+| Lua enabled, renderer/editor UI disabled | 20/20 CTest tests passed |
+| Lua disabled, renderer/editor UI disabled | 18/18 CTest tests passed |
+| AddressSanitizer + UndefinedBehaviorSanitizer, Lua suites | 3/3 tests passed |
+| Renderer-linked native Player and SchemaExporter | Built successfully; CPU Lua CLI contracts passed |
+| Lua-only project without project C++ files | Empty native adapter built; sample validated; exactly two Lua schemas exported |
+| Native Editor and Editor UI library | Compiled and linked; Editor `--help` ran |
+| Manual | MkDocs strict build passed |
+
+The Lua tests exercise lifecycle ordering, per-instance fields/state, VM ownership,
+stale/cross-world handles, deferred structural operations, native physics contacts,
+`require`, invalid schemas, CPU/memory limits and the shipped example scene. Additional
+safety cases cover deep/cyclic JSON, repeated-string/key expansion, structural queue
+limits, protected metatables, repeated OOM and reclamation of a failing instance.
+
+BuildService tests exercise source snapshots, fingerprints, changes during a build,
+Lua-only projects, export contents/notices, and switching back to Lua-free games.
+Their native build/export fixture is a stand-in, not a graphical Player execution.
+
+## Reproduce the CPU suite
+
+```sh
+cmake -S . -B build/lua-check -G Ninja -DCMAKE_BUILD_TYPE=Debug \
+  -DFASET_ENABLE_LUA=ON -DFASET_BUILD_RENDERER=OFF -DFASET_BUILD_EDITOR=OFF
+cmake --build build/lua-check --parallel
+ctest --test-dir build/lua-check --output-on-failure
+```
+
+Use a separate build directory with `-DFASET_ENABLE_LUA=OFF` for the optional-module
+check. For sanitizers, configure with `-DFASET_SANITIZERS=ON`, build the
+`faset_lua_tests`, `faset_lua_safety_tests`, and `faset_schema_exporter` targets, then
+run `ctest --test-dir <build> --output-on-failure -R '^lua_'`.
+
+## Not verified here
+
+- Windows compilation or execution of the new module.
+- Graphical/window interaction and real-time Lua reload in a running rendered game.
+  `lua_player_reload` is provided as a GPU-labelled integration test for an equipped host.
+- A complete real Release export launched on a separate machine.
+- LeakSanitizer: this execution environment uses tracing incompatible with its
+  process inspection, so sanitizer runs used `ASAN_OPTIONS=detect_leaks=0` and
+  `UBSAN_OPTIONS=halt_on_error=1`. Address/undefined-behavior checks stayed enabled.
+
+The renderer-linked CPU checks used the existing Vulkan loader, repo-pinned Vulkan
+headers and cached Slang, with SDL X11/Wayland disabled. No system graphics packages
+were installed. This proves linkage and CPU validation, not graphics compatibility.