Add optional Lua scripting module, examples, and validation

include/faset/scripting/LuaModule.hpp

@@ -0,0 +1,37 @@
+#pragma once
+
+#include <cstddef>
+#include <faset/runtime/Runtime.hpp>
+#include <faset/scripting/project.hpp>
+#include <memory>
+#include <string>
+#include <vector>
+
+namespace faset::scripting {
+
+struct LuaLimits {
+    std::size_t memoryBytes{16 * 1024 * 1024};
+    unsigned instructions{1'000'000};
+};
+
+// One sandboxed VM per module, isolated instance tables per entity/component.
+// Behavior callbacks retain shared ownership of the VM until Runtime is destroyed.
+class LuaModule {
+  public:
+    explicit LuaModule(const LuaProject& project, LuaLimits limits = {});
+    ~LuaModule();
+    LuaModule(const LuaModule&) = delete;
+    LuaModule& operator=(const LuaModule&) = delete;
+    nlohmann::json schema() const;
+    // Validates Lua component configuration without creating instances or running callbacks.
+    // Pair with runtime::validate_scene_schemas for cross-language IDs and versions.
+    void validateScene(const nlohmann::json& scene) const;
+    void registerBehaviors(runtime::Runtime& runtime);
+    std::vector<std::string> takeLogs();
+
+  private:
+    struct Impl;
+    std::shared_ptr<Impl> impl_;
+};
+
+} // namespace faset::scripting

include/faset/scripting/project.hpp

@@ -0,0 +1,28 @@
+#pragma once
+
+#include <filesystem>
+#include <map>
+#include <string>
+#include <vector>
+
+namespace faset::scripting {
+
+// Immutable source snapshot. Keys and entries are project-relative UTF-8 paths.
+// Only Lua files below Scripts are accepted; loading never follows symlinks.
+struct LuaProject {
+    std::vector<std::string> scripts;
+    std::map<std::string, std::string> sources;
+    std::string fingerprint;
+    bool enabled() const noexcept {
+        return !scripts.empty();
+    }
+};
+
+// project.faset.json: scripting.lua.scripts = ["Scripts/player.lua", ...].
+// An absent Lua declaration is a C++-only project.
+LuaProject loadLuaProject(const std::filesystem::path& projectRoot);
+
+// Writes the captured sources, not live files. The caller owns the target manifest.
+void writeLuaSources(const LuaProject& project, const std::filesystem::path& targetRoot);
+
+} // namespace faset::scripting