refactor: Introduce script engine and related services for enhanced scripting capabilities

AGENTS.md

@@ -0,0 +1,12 @@
+# AGENTS.md
+
+## Code Style
+- Use Java / Spring conventions: explicit names, clear structure, and standard patterns.
+- Prefer readability over cleverness.
+- Avoid complex template tricks unless required for correctness.
+
+## C++ Guidelines
+- Minimise use of macros; only use them when there is no clear alternative.
+- Prefer `constexpr`, `inline`, and scoped enums over macros.
+- Keep APIs explicit and predictable; avoid implicit conversions.
+

CMakeLists.txt

@@ -125,6 +125,13 @@ if(BUILD_SDL3_APP)
             src/events/event_bus.cpp
             src/services/impl/json_config_service.cpp
             src/services/impl/logger_service.cpp
+            src/services/impl/script_engine_service.cpp
+            src/services/impl/scene_script_service.cpp
+            src/services/impl/shader_script_service.cpp
+            src/services/impl/gui_script_service.cpp
+            src/services/impl/audio_command_service.cpp
+            src/services/impl/physics_bridge_service.cpp
+            src/services/impl/mesh_service.cpp
             src/services/impl/sdl_window_service.cpp
             src/services/impl/sdl_input_service.cpp
             src/services/impl/vulkan_device_service.cpp

src/app/service_based_app.cpp

@@ -11,7 +11,14 @@
 #include "services/impl/buffer_service.hpp"
 #include "services/impl/render_command_service.hpp"
 #include "services/impl/graphics_service.hpp"
+#include "services/impl/script_engine_service.hpp"
 #include "services/impl/lua_script_service.hpp"
+#include "services/impl/scene_script_service.hpp"
+#include "services/impl/shader_script_service.hpp"
+#include "services/impl/gui_script_service.hpp"
+#include "services/impl/audio_command_service.hpp"
+#include "services/impl/physics_bridge_service.hpp"
+#include "services/impl/mesh_service.hpp"
 #include "services/impl/scene_service.hpp"
 #include "services/impl/sdl_audio_service.hpp"
 #include "services/impl/vulkan_gui_service.hpp"
@@ -239,9 +246,30 @@ void ServiceBasedApp::RegisterServices() {
         registry_.GetService<services::IRenderCommandService>(),
         registry_.GetService<services::IWindowService>());
 
-    // Script service
+    // Script engine service (shared Lua runtime)
+    registry_.RegisterService<services::IScriptEngineService, services::impl::ScriptEngineService>(
+        scriptPath_,
+        registry_.GetService<services::ILogger>(),
+        runtimeConfig.luaDebug);
+
+    // Script-facing services
+    registry_.RegisterService<services::ISceneScriptService, services::impl::SceneScriptService>(
+        registry_.GetService<services::IScriptEngineService>());
+    registry_.RegisterService<services::IShaderScriptService, services::impl::ShaderScriptService>(
+        registry_.GetService<services::IScriptEngineService>());
+    registry_.RegisterService<services::IGuiScriptService, services::impl::GuiScriptService>(
+        registry_.GetService<services::IScriptEngineService>());
+    registry_.RegisterService<services::IAudioCommandService, services::impl::AudioCommandService>(
+        registry_.GetService<services::IScriptEngineService>());
+    registry_.RegisterService<services::IPhysicsBridgeService, services::impl::PhysicsBridgeService>(
+        registry_.GetService<services::IScriptEngineService>());
+    registry_.RegisterService<services::IMeshService, services::impl::MeshService>(
+        registry_.GetService<services::IScriptEngineService>());
+
+    // Script service (facade)
     registry_.RegisterService<services::IScriptService, services::impl::LuaScriptService>(
-        scriptPath_, registry_.GetService<services::ILogger>());
+        registry_.GetService<services::IScriptEngineService>(),
+        registry_.GetService<services::ILogger>());
 
     // Connect input service to script service for GUI input processing
     auto inputService = registry_.GetService<services::IInputService>();
@@ -252,7 +280,7 @@ void ServiceBasedApp::RegisterServices() {
 
     // Scene service
     registry_.RegisterService<services::ISceneService, services::impl::SceneService>(
-        registry_.GetService<services::IScriptService>(),
+        registry_.GetService<services::ISceneScriptService>(),
         registry_.GetService<services::ILogger>());
 
     // Audio service
@@ -270,4 +298,4 @@ void ServiceBasedApp::RegisterServices() {
     logger_->Trace("ServiceBasedApp", "RegisterServices", "", "Exiting");
 }
 
-}  // namespace sdl3cpp::app
+}  // namespace sdl3cpp::app

src/controllers/render_controller.cpp

@@ -1,7 +1,8 @@
 #include "render_controller.hpp"
 #include "../services/interfaces/i_logger.hpp"
 #include "../services/interfaces/i_graphics_service.hpp"
-#include "../services/interfaces/i_script_service.hpp"
+#include "../services/interfaces/i_scene_script_service.hpp"
+#include "../services/interfaces/i_gui_script_service.hpp"
 #include "../services/interfaces/i_gui_service.hpp"
 #include "../services/interfaces/i_scene_service.hpp"
 
@@ -21,7 +22,8 @@ void RenderController::RenderFrame(float time) {
 
     // Get required services
     auto graphicsService = registry_.GetService<services::IGraphicsService>();
-    auto scriptService = registry_.GetService<services::IScriptService>();
+    auto sceneScriptService = registry_.GetService<services::ISceneScriptService>();
+    auto guiScriptService = registry_.GetService<services::IGuiScriptService>();
     auto guiService = registry_.GetService<services::IGuiService>();
     auto sceneService = registry_.GetService<services::ISceneService>();
 
@@ -35,9 +37,9 @@ void RenderController::RenderFrame(float time) {
     graphicsService->BeginFrame();
 
     // Load scene and render
-    if (scriptService && sceneService) {
+    if (sceneScriptService && sceneService) {
         // Load scene objects from script
-        auto sceneObjects = scriptService->LoadSceneObjects();
+        auto sceneObjects = sceneScriptService->LoadSceneObjects();
         sceneService->LoadScene(sceneObjects);
         
         // Get render commands from scene service
@@ -45,15 +47,15 @@ void RenderController::RenderFrame(float time) {
 
         // Get view-projection matrix
         float aspect = 1920.0f / 1080.0f;  // TODO: Get from window service
-        auto viewProj = scriptService->GetViewProjectionMatrix(aspect);
+        auto viewProj = sceneScriptService->GetViewProjectionMatrix(aspect);
 
         // Render scene
         graphicsService->RenderScene(renderCommands, viewProj);
     }
 
     // Render GUI overlay
-    if (guiService && scriptService && scriptService->HasGuiCommands()) {
-        auto guiCommands = scriptService->LoadGuiCommands();
+    if (guiService && guiScriptService && guiScriptService->HasGuiCommands()) {
+        auto guiCommands = guiScriptService->LoadGuiCommands();
         // guiService->PrepareFrame(guiCommands, width, height);
         // guiService->RenderToSwapchain(commandBuffer, swapchainImage);
     }

src/services/impl/audio_command_service.cpp

@@ -0,0 +1,17 @@
+#include "audio_command_service.hpp"
+#include <utility>
+
+namespace sdl3cpp::services::impl {
+
+AudioCommandService::AudioCommandService(std::shared_ptr<IScriptEngineService> engineService)
+    : engineService_(std::move(engineService)) {
+}
+
+bool AudioCommandService::QueueAudioCommand(script::AudioManager::AudioCommandType type,
+                                            const std::string& path,
+                                            bool loop,
+                                            std::string& error) {
+    return engineService_->GetEngine().QueueAudioCommand(type, path, loop, error);
+}
+
+}  // namespace sdl3cpp::services::impl

src/services/impl/audio_command_service.hpp

@@ -0,0 +1,25 @@
+#pragma once
+
+#include "../interfaces/i_audio_command_service.hpp"
+#include "../interfaces/i_script_engine_service.hpp"
+#include <memory>
+
+namespace sdl3cpp::services::impl {
+
+/**
+ * @brief Script-facing audio command service implementation.
+ */
+class AudioCommandService : public IAudioCommandService {
+public:
+    explicit AudioCommandService(std::shared_ptr<IScriptEngineService> engineService);
+
+    bool QueueAudioCommand(script::AudioManager::AudioCommandType type,
+                           const std::string& path,
+                           bool loop,
+                           std::string& error) override;
+
+private:
+    std::shared_ptr<IScriptEngineService> engineService_;
+};
+
+}  // namespace sdl3cpp::services::impl

src/services/impl/gui_script_service.cpp

@@ -0,0 +1,22 @@
+#include "gui_script_service.hpp"
+#include <utility>
+
+namespace sdl3cpp::services::impl {
+
+GuiScriptService::GuiScriptService(std::shared_ptr<IScriptEngineService> engineService)
+    : engineService_(std::move(engineService)) {
+}
+
+std::vector<script::GuiCommand> GuiScriptService::LoadGuiCommands() {
+    return engineService_->GetEngine().LoadGuiCommands();
+}
+
+void GuiScriptService::UpdateGuiInput(const script::GuiInputSnapshot& input) {
+    engineService_->GetEngine().UpdateGuiInput(input);
+}
+
+bool GuiScriptService::HasGuiCommands() const {
+    return engineService_->GetEngine().HasGuiCommands();
+}
+
+}  // namespace sdl3cpp::services::impl

src/services/impl/gui_script_service.hpp

@@ -0,0 +1,24 @@
+#pragma once
+
+#include "../interfaces/i_gui_script_service.hpp"
+#include "../interfaces/i_script_engine_service.hpp"
+#include <memory>
+
+namespace sdl3cpp::services::impl {
+
+/**
+ * @brief Script-facing GUI service implementation.
+ */
+class GuiScriptService : public IGuiScriptService {
+public:
+    explicit GuiScriptService(std::shared_ptr<IScriptEngineService> engineService);
+
+    std::vector<script::GuiCommand> LoadGuiCommands() override;
+    void UpdateGuiInput(const script::GuiInputSnapshot& input) override;
+    bool HasGuiCommands() const override;
+
+private:
+    std::shared_ptr<IScriptEngineService> engineService_;
+};
+
+}  // namespace sdl3cpp::services::impl

src/services/impl/lua_script_service.cpp

@@ -1,10 +1,11 @@
 #include "lua_script_service.hpp"
 #include <stdexcept>
+#include <utility>
 
 namespace sdl3cpp::services::impl {
 
-LuaScriptService::LuaScriptService(const std::filesystem::path& scriptPath, std::shared_ptr<ILogger> logger, bool debugEnabled)
-    : scriptPath_(scriptPath), logger_(logger), debugEnabled_(debugEnabled) {
+LuaScriptService::LuaScriptService(std::shared_ptr<IScriptEngineService> engineService, std::shared_ptr<ILogger> logger)
+    : engineService_(std::move(engineService)), logger_(std::move(logger)) {
 }
 
 LuaScriptService::~LuaScriptService() {
@@ -20,7 +21,10 @@ void LuaScriptService::Initialize() {
         return;
     }
 
-    engine_ = std::make_unique<script::ScriptEngine>(scriptPath_, debugEnabled_);
+    if (!engineService_ || !engineService_->IsInitialized()) {
+        throw std::runtime_error("Script engine service not initialized");
+    }
+
     initialized_ = true;
 
     logger_->Info("Script service initialized");
@@ -33,7 +37,6 @@ void LuaScriptService::Shutdown() noexcept {
         return;
     }
 
-    engine_.reset();
     initialized_ = false;
 
     logger_->Info("Script service shutdown");
@@ -42,69 +45,69 @@ void LuaScriptService::Shutdown() noexcept {
 std::vector<script::SceneManager::SceneObject> LuaScriptService::LoadSceneObjects() {
     logger_->TraceFunction(__func__);
 
-    if (!engine_) {
+    if (!engineService_ || !engineService_->IsInitialized()) {
         throw std::runtime_error("Script service not initialized");
     }
 
-    return engine_->LoadSceneObjects();
+    return engineService_->GetEngine().LoadSceneObjects();
 }
 
 std::array<float, 16> LuaScriptService::ComputeModelMatrix(int functionRef, float time) {
-    if (!engine_) {
+    if (!engineService_ || !engineService_->IsInitialized()) {
         throw std::runtime_error("Script service not initialized");
     }
 
-    return engine_->ComputeModelMatrix(functionRef, time);
+    return engineService_->GetEngine().ComputeModelMatrix(functionRef, time);
 }
 
 std::array<float, 16> LuaScriptService::GetViewProjectionMatrix(float aspect) {
-    if (!engine_) {
+    if (!engineService_ || !engineService_->IsInitialized()) {
         throw std::runtime_error("Script service not initialized");
     }
 
-    return engine_->GetViewProjectionMatrix(aspect);
+    return engineService_->GetEngine().GetViewProjectionMatrix(aspect);
 }
 
 std::unordered_map<std::string, sdl3cpp::services::ShaderPaths> LuaScriptService::LoadShaderPathsMap() {
     logger_->TraceFunction(__func__);
 
-    if (!engine_) {
+    if (!engineService_ || !engineService_->IsInitialized()) {
         throw std::runtime_error("Script service not initialized");
     }
 
-    return engine_->LoadShaderPathsMap();
+    return engineService_->GetEngine().LoadShaderPathsMap();
 }
 
 std::vector<script::GuiCommand> LuaScriptService::LoadGuiCommands() {
-    if (!engine_) {
+    if (!engineService_ || !engineService_->IsInitialized()) {
         return {};
     }
 
-    return engine_->LoadGuiCommands();
+    return engineService_->GetEngine().LoadGuiCommands();
 }
 
 void LuaScriptService::UpdateGuiInput(const script::GuiInputSnapshot& input) {
-    if (!engine_) {
+    if (!engineService_ || !engineService_->IsInitialized()) {
         return;
     }
 
-    engine_->UpdateGuiInput(input);
+    engineService_->GetEngine().UpdateGuiInput(input);
 }
 
 bool LuaScriptService::HasGuiCommands() const {
-    if (!engine_) {
+    if (!engineService_ || !engineService_->IsInitialized()) {
         return false;
     }
 
-    return engine_->HasGuiCommands();
+    return engineService_->GetEngine().HasGuiCommands();
 }
 
 script::PhysicsBridge& LuaScriptService::GetPhysicsBridge() {
-    if (!engine_) {
+    if (!engineService_ || !engineService_->IsInitialized()) {
         throw std::runtime_error("Script service not initialized");
     }
 
-    return engine_->GetPhysicsBridge();
+    return engineService_->GetEngine().GetPhysicsBridge();
 }
 
 void LuaScriptService::SetAudioPlayer(app::AudioPlayer* audioPlayer) {
@@ -113,19 +116,19 @@ void LuaScriptService::SetAudioPlayer(app::AudioPlayer* audioPlayer) {
 }
 
 std::filesystem::path LuaScriptService::GetScriptDirectory() const {
-    if (!engine_) {
+    if (!engineService_ || !engineService_->IsInitialized()) {
         return {};
     }
 
-    return engine_->GetScriptDirectory();
+    return engineService_->GetEngine().GetScriptDirectory();
 }
 
 std::string LuaScriptService::GetLuaError() {
-    if (!engine_) {
+    if (!engineService_ || !engineService_->IsInitialized()) {
         return "Script service not initialized";
     }
 
-    return engine_->GetLuaError();
+    return engineService_->GetEngine().GetLuaError();
 }
 
 }  // namespace sdl3cpp::services::impl

src/services/impl/lua_script_service.hpp

@@ -1,8 +1,8 @@
 #pragma once
 
 #include "../interfaces/i_script_service.hpp"
+#include "../interfaces/i_script_engine_service.hpp"
 #include "../interfaces/i_logger.hpp"
-#include "../../script/script_engine.hpp"
 #include "../../di/lifecycle.hpp"
 #include <memory>
 #include <filesystem>
@@ -19,7 +19,7 @@ class LuaScriptService : public IScriptService,
                          public di::IInitializable,
                          public di::IShutdownable {
 public:
-    explicit LuaScriptService(const std::filesystem::path& scriptPath, std::shared_ptr<ILogger> logger, bool debugEnabled = false);
+    explicit LuaScriptService(std::shared_ptr<IScriptEngineService> engineService, std::shared_ptr<ILogger> logger);
     ~LuaScriptService() override;
 
     // Lifecycle
@@ -45,10 +45,8 @@ public:
     std::string GetLuaError() override;
 
 private:
+    std::shared_ptr<IScriptEngineService> engineService_;
     std::shared_ptr<ILogger> logger_;
-    std::unique_ptr<script::ScriptEngine> engine_;
-    std::filesystem::path scriptPath_;
-    bool debugEnabled_ = false;
     bool initialized_ = false;
 };
 

src/services/impl/mesh_service.cpp

@@ -0,0 +1,25 @@
+#include "mesh_service.hpp"
+#include <utility>
+
+#include "../../script/mesh_loader.hpp"
+
+namespace sdl3cpp::services::impl {
+
+MeshService::MeshService(std::shared_ptr<IScriptEngineService> engineService)
+    : engineService_(std::move(engineService)) {
+}
+
+bool MeshService::LoadFromFile(const std::string& requestedPath,
+                               script::MeshPayload& outPayload,
+                               std::string& outError) {
+    return script::MeshLoader::LoadFromFile(engineService_->GetScriptDirectory(),
+                                            requestedPath,
+                                            outPayload,
+                                            outError);
+}
+
+void MeshService::PushMeshToLua(lua_State* L, const script::MeshPayload& payload) {
+    script::MeshLoader::PushMeshToLua(L, payload);
+}
+
+}  // namespace sdl3cpp::services::impl

src/services/impl/mesh_service.hpp

@@ -0,0 +1,25 @@
+#pragma once
+
+#include "../interfaces/i_mesh_service.hpp"
+#include "../interfaces/i_script_engine_service.hpp"
+#include <memory>
+
+namespace sdl3cpp::services::impl {
+
+/**
+ * @brief Script-facing mesh loading service implementation.
+ */
+class MeshService : public IMeshService {
+public:
+    explicit MeshService(std::shared_ptr<IScriptEngineService> engineService);
+
+    bool LoadFromFile(const std::string& requestedPath,
+                      script::MeshPayload& outPayload,
+                      std::string& outError) override;
+    void PushMeshToLua(lua_State* L, const script::MeshPayload& payload) override;
+
+private:
+    std::shared_ptr<IScriptEngineService> engineService_;
+};
+
+}  // namespace sdl3cpp::services::impl

src/services/impl/physics_bridge_service.cpp

@@ -0,0 +1,28 @@
+#include "physics_bridge_service.hpp"
+#include <utility>
+
+namespace sdl3cpp::services::impl {
+
+PhysicsBridgeService::PhysicsBridgeService(std::shared_ptr<IScriptEngineService> engineService)
+    : engineService_(std::move(engineService)) {
+}
+
+bool PhysicsBridgeService::AddBoxRigidBody(const std::string& name,
+                                           const btVector3& halfExtents,
+                                           float mass,
+                                           const btTransform& transform,
+                                           std::string& error) {
+    return engineService_->GetEngine().GetPhysicsBridge().addBoxRigidBody(name, halfExtents, mass, transform, error);
+}
+
+int PhysicsBridgeService::StepSimulation(float deltaTime) {
+    return engineService_->GetEngine().GetPhysicsBridge().stepSimulation(deltaTime);
+}
+
+bool PhysicsBridgeService::GetRigidBodyTransform(const std::string& name,
+                                                 btTransform& outTransform,
+                                                 std::string& error) const {
+    return engineService_->GetEngine().GetPhysicsBridge().getRigidBodyTransform(name, outTransform, error);
+}
+
+}  // namespace sdl3cpp::services::impl

src/services/impl/physics_bridge_service.hpp

@@ -0,0 +1,30 @@
+#pragma once
+
+#include "../interfaces/i_physics_bridge_service.hpp"
+#include "../interfaces/i_script_engine_service.hpp"
+#include <memory>
+
+namespace sdl3cpp::services::impl {
+
+/**
+ * @brief Script-facing physics bridge service implementation.
+ */
+class PhysicsBridgeService : public IPhysicsBridgeService {
+public:
+    explicit PhysicsBridgeService(std::shared_ptr<IScriptEngineService> engineService);
+
+    bool AddBoxRigidBody(const std::string& name,
+                         const btVector3& halfExtents,
+                         float mass,
+                         const btTransform& transform,
+                         std::string& error) override;
+    int StepSimulation(float deltaTime) override;
+    bool GetRigidBodyTransform(const std::string& name,
+                               btTransform& outTransform,
+                               std::string& error) const override;
+
+private:
+    std::shared_ptr<IScriptEngineService> engineService_;
+};
+
+}  // namespace sdl3cpp::services::impl

src/services/impl/scene_script_service.cpp

@@ -0,0 +1,22 @@
+#include "scene_script_service.hpp"
+#include <utility>
+
+namespace sdl3cpp::services::impl {
+
+SceneScriptService::SceneScriptService(std::shared_ptr<IScriptEngineService> engineService)
+    : engineService_(std::move(engineService)) {
+}
+
+std::vector<script::SceneManager::SceneObject> SceneScriptService::LoadSceneObjects() {
+    return engineService_->GetEngine().LoadSceneObjects();
+}
+
+std::array<float, 16> SceneScriptService::ComputeModelMatrix(int functionRef, float time) {
+    return engineService_->GetEngine().ComputeModelMatrix(functionRef, time);
+}
+
+std::array<float, 16> SceneScriptService::GetViewProjectionMatrix(float aspect) {
+    return engineService_->GetEngine().GetViewProjectionMatrix(aspect);
+}
+
+}  // namespace sdl3cpp::services::impl

src/services/impl/scene_script_service.hpp

@@ -0,0 +1,24 @@
+#pragma once
+
+#include "../interfaces/i_scene_script_service.hpp"
+#include "../interfaces/i_script_engine_service.hpp"
+#include <memory>
+
+namespace sdl3cpp::services::impl {
+
+/**
+ * @brief Script-facing scene service implementation.
+ */
+class SceneScriptService : public ISceneScriptService {
+public:
+    explicit SceneScriptService(std::shared_ptr<IScriptEngineService> engineService);
+
+    std::vector<script::SceneManager::SceneObject> LoadSceneObjects() override;
+    std::array<float, 16> ComputeModelMatrix(int functionRef, float time) override;
+    std::array<float, 16> GetViewProjectionMatrix(float aspect) override;
+
+private:
+    std::shared_ptr<IScriptEngineService> engineService_;
+};
+
+}  // namespace sdl3cpp::services::impl

src/services/impl/scene_service.cpp

@@ -3,12 +3,12 @@
 
 namespace sdl3cpp::services::impl {
 
-SceneService::SceneService(std::shared_ptr<IScriptService> scriptService, std::shared_ptr<ILogger> logger)
+SceneService::SceneService(std::shared_ptr<ISceneScriptService> scriptService, std::shared_ptr<ILogger> logger)
     : scriptService_(scriptService), logger_(logger) {
     logger_->TraceFunction(__func__);
 
     if (!scriptService_) {
-        throw std::invalid_argument("Script service cannot be null");
+        throw std::invalid_argument("Scene script service cannot be null");
     }
 }
 
@@ -76,4 +76,4 @@ void SceneService::Shutdown() noexcept {
     Clear();
 }
 
-}  // namespace sdl3cpp::services::impl
+}  // namespace sdl3cpp::services::impl

src/services/impl/scene_service.hpp

@@ -1,7 +1,7 @@
 #pragma once
 
 #include "../interfaces/i_scene_service.hpp"
-#include "../interfaces/i_script_service.hpp"
+#include "../interfaces/i_scene_script_service.hpp"
 #include "../interfaces/i_logger.hpp"
 #include "../../di/lifecycle.hpp"
 #include <vector>
@@ -18,7 +18,7 @@ namespace sdl3cpp::services::impl {
 class SceneService : public ISceneService,
                      public di::IShutdownable {
 public:
-    explicit SceneService(std::shared_ptr<IScriptService> scriptService, std::shared_ptr<ILogger> logger);
+    explicit SceneService(std::shared_ptr<ISceneScriptService> scriptService, std::shared_ptr<ILogger> logger);
     ~SceneService() override;
 
     // ISceneService interface
@@ -32,10 +32,10 @@ public:
     void Shutdown() noexcept override;
 
 private:
-    std::shared_ptr<IScriptService> scriptService_;
+    std::shared_ptr<ISceneScriptService> scriptService_;
     std::shared_ptr<ILogger> logger_;
     std::vector<SceneObject> sceneObjects_;
     bool initialized_ = false;
 };
 
-}  // namespace sdl3cpp::services::impl
+}  // namespace sdl3cpp::services::impl

src/services/impl/script_engine_service.cpp

@@ -0,0 +1,61 @@
+#include "script_engine_service.hpp"
+
+#include "../../script/script_engine.hpp"
+#include <stdexcept>
+#include <utility>
+
+namespace sdl3cpp::services::impl {
+
+ScriptEngineService::ScriptEngineService(const std::filesystem::path& scriptPath,
+                                         std::shared_ptr<ILogger> logger,
+                                         bool debugEnabled)
+    : logger_(std::move(logger)),
+      scriptPath_(scriptPath),
+      debugEnabled_(debugEnabled) {
+}
+
+ScriptEngineService::~ScriptEngineService() {
+    if (initialized_) {
+        Shutdown();
+    }
+}
+
+void ScriptEngineService::Initialize() {
+    if (initialized_) {
+        return;
+    }
+    logger_->TraceFunction(__func__);
+
+    engine_ = std::make_unique<script::ScriptEngine>(scriptPath_, debugEnabled_);
+    initialized_ = true;
+
+    logger_->Info("Script engine service initialized");
+}
+
+void ScriptEngineService::Shutdown() noexcept {
+    if (!initialized_) {
+        return;
+    }
+    logger_->TraceFunction(__func__);
+
+    engine_.reset();
+    initialized_ = false;
+
+    logger_->Info("Script engine service shutdown");
+}
+
+script::ScriptEngine& ScriptEngineService::GetEngine() {
+    if (!engine_) {
+        throw std::runtime_error("Script engine service not initialized");
+    }
+    return *engine_;
+}
+
+std::filesystem::path ScriptEngineService::GetScriptDirectory() const {
+    if (!engine_) {
+        throw std::runtime_error("Script engine service not initialized");
+    }
+    return engine_->GetScriptDirectory();
+}
+
+}  // namespace sdl3cpp::services::impl

src/services/impl/script_engine_service.hpp

@@ -0,0 +1,40 @@
+#pragma once
+
+#include "../interfaces/i_script_engine_service.hpp"
+#include "../interfaces/i_logger.hpp"
+#include "../../di/lifecycle.hpp"
+#include <filesystem>
+#include <memory>
+
+namespace sdl3cpp::services::impl {
+
+/**
+ * @brief Service wrapper around ScriptEngine.
+ */
+class ScriptEngineService : public IScriptEngineService,
+                            public di::IInitializable,
+                            public di::IShutdownable {
+public:
+    ScriptEngineService(const std::filesystem::path& scriptPath,
+                        std::shared_ptr<ILogger> logger,
+                        bool debugEnabled = false);
+    ~ScriptEngineService() override;
+
+    // Lifecycle
+    void Initialize() override;
+    void Shutdown() noexcept override;
+
+    // IScriptEngineService interface
+    script::ScriptEngine& GetEngine() override;
+    std::filesystem::path GetScriptDirectory() const override;
+    bool IsInitialized() const override { return initialized_; }
+
+private:
+    std::shared_ptr<ILogger> logger_;
+    std::filesystem::path scriptPath_;
+    bool debugEnabled_ = false;
+    bool initialized_ = false;
+    std::unique_ptr<script::ScriptEngine> engine_;
+};
+
+}  // namespace sdl3cpp::services::impl

src/services/impl/shader_script_service.cpp

@@ -0,0 +1,14 @@
+#include "shader_script_service.hpp"
+#include <utility>
+
+namespace sdl3cpp::services::impl {
+
+ShaderScriptService::ShaderScriptService(std::shared_ptr<IScriptEngineService> engineService)
+    : engineService_(std::move(engineService)) {
+}
+
+std::unordered_map<std::string, ShaderPaths> ShaderScriptService::LoadShaderPathsMap() {
+    return engineService_->GetEngine().LoadShaderPathsMap();
+}
+
+}  // namespace sdl3cpp::services::impl

src/services/impl/shader_script_service.hpp

@@ -0,0 +1,22 @@
+#pragma once
+
+#include "../interfaces/i_shader_script_service.hpp"
+#include "../interfaces/i_script_engine_service.hpp"
+#include <memory>
+
+namespace sdl3cpp::services::impl {
+
+/**
+ * @brief Script-facing shader service implementation.
+ */
+class ShaderScriptService : public IShaderScriptService {
+public:
+    explicit ShaderScriptService(std::shared_ptr<IScriptEngineService> engineService);
+
+    std::unordered_map<std::string, ShaderPaths> LoadShaderPathsMap() override;
+
+private:
+    std::shared_ptr<IScriptEngineService> engineService_;
+};
+
+}  // namespace sdl3cpp::services::impl

src/services/interfaces/i_audio_command_service.hpp

@@ -0,0 +1,21 @@
+#pragma once
+
+#include "../../script/audio_manager.hpp"
+#include <string>
+
+namespace sdl3cpp::services {
+
+/**
+ * @brief Script-facing audio command service interface.
+ */
+class IAudioCommandService {
+public:
+    virtual ~IAudioCommandService() = default;
+
+    virtual bool QueueAudioCommand(script::AudioManager::AudioCommandType type,
+                                   const std::string& path,
+                                   bool loop,
+                                   std::string& error) = 0;
+};
+
+}  // namespace sdl3cpp::services

src/services/interfaces/i_gui_script_service.hpp

@@ -0,0 +1,20 @@
+#pragma once
+
+#include "../../script/gui_types.hpp"
+#include <vector>
+
+namespace sdl3cpp::services {
+
+/**
+ * @brief Script-facing GUI command service interface.
+ */
+class IGuiScriptService {
+public:
+    virtual ~IGuiScriptService() = default;
+
+    virtual std::vector<script::GuiCommand> LoadGuiCommands() = 0;
+    virtual void UpdateGuiInput(const script::GuiInputSnapshot& input) = 0;
+    virtual bool HasGuiCommands() const = 0;
+};
+
+}  // namespace sdl3cpp::services

src/services/interfaces/i_mesh_service.hpp

@@ -0,0 +1,21 @@
+#pragma once
+
+#include "../../script/mesh_loader.hpp"
+#include <string>
+
+namespace sdl3cpp::services {
+
+/**
+ * @brief Script-facing mesh loading service interface.
+ */
+class IMeshService {
+public:
+    virtual ~IMeshService() = default;
+
+    virtual bool LoadFromFile(const std::string& requestedPath,
+                              script::MeshPayload& outPayload,
+                              std::string& outError) = 0;
+    virtual void PushMeshToLua(lua_State* L, const script::MeshPayload& payload) = 0;
+};
+
+}  // namespace sdl3cpp::services

src/services/interfaces/i_physics_bridge_service.hpp

@@ -0,0 +1,26 @@
+#pragma once
+
+#include "../../script/physics_bridge.hpp"
+#include <string>
+
+namespace sdl3cpp::services {
+
+/**
+ * @brief Script-facing physics bridge service interface.
+ */
+class IPhysicsBridgeService {
+public:
+    virtual ~IPhysicsBridgeService() = default;
+
+    virtual bool AddBoxRigidBody(const std::string& name,
+                                 const btVector3& halfExtents,
+                                 float mass,
+                                 const btTransform& transform,
+                                 std::string& error) = 0;
+    virtual int StepSimulation(float deltaTime) = 0;
+    virtual bool GetRigidBodyTransform(const std::string& name,
+                                       btTransform& outTransform,
+                                       std::string& error) const = 0;
+};
+
+}  // namespace sdl3cpp::services

src/services/interfaces/i_scene_script_service.hpp

@@ -0,0 +1,21 @@
+#pragma once
+
+#include "../../script/scene_manager.hpp"
+#include <array>
+#include <vector>
+
+namespace sdl3cpp::services {
+
+/**
+ * @brief Script-facing scene service interface.
+ */
+class ISceneScriptService {
+public:
+    virtual ~ISceneScriptService() = default;
+
+    virtual std::vector<script::SceneManager::SceneObject> LoadSceneObjects() = 0;
+    virtual std::array<float, 16> ComputeModelMatrix(int functionRef, float time) = 0;
+    virtual std::array<float, 16> GetViewProjectionMatrix(float aspect) = 0;
+};
+
+}  // namespace sdl3cpp::services

src/services/interfaces/i_script_engine_service.hpp

@@ -0,0 +1,23 @@
+#pragma once
+
+#include <filesystem>
+
+namespace sdl3cpp::script {
+class ScriptEngine;
+}
+
+namespace sdl3cpp::services {
+
+/**
+ * @brief Service for owning and exposing the Lua script engine.
+ */
+class IScriptEngineService {
+public:
+    virtual ~IScriptEngineService() = default;
+
+    virtual script::ScriptEngine& GetEngine() = 0;
+    virtual std::filesystem::path GetScriptDirectory() const = 0;
+    virtual bool IsInitialized() const = 0;
+};
+
+}  // namespace sdl3cpp::services

src/services/interfaces/i_shader_script_service.hpp

@@ -0,0 +1,19 @@
+#pragma once
+
+#include "graphics_types.hpp"
+#include <string>
+#include <unordered_map>
+
+namespace sdl3cpp::services {
+
+/**
+ * @brief Script-facing shader lookup service interface.
+ */
+class IShaderScriptService {
+public:
+    virtual ~IShaderScriptService() = default;
+
+    virtual std::unordered_map<std::string, ShaderPaths> LoadShaderPathsMap() = 0;
+};
+
+}  // namespace sdl3cpp::services