From 2060f3f153aedb39807c33faf10f731e45ecb550 Mon Sep 17 00:00:00 2001
From: MihailRis <mexaruc@gmail.com>
Date: Thu, 3 Sep 2026 22:25:58 +0300
Subject: [PATCH 1/2] add project arguments table passing in
 app.start_background_instance

---
 src/logic/scripting/lua/libs/libapp.cpp | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/src/logic/scripting/lua/libs/libapp.cpp b/src/logic/scripting/lua/libs/libapp.cpp
index b5a385bb9..0058fcada 100644
--- a/src/logic/scripting/lua/libs/libapp.cpp
+++ b/src/logic/scripting/lua/libs/libapp.cpp
@@ -405,6 +405,20 @@ static int l_start_background_instance(lua::State* L) {
 
     auto scriptPath = lua::require_lstring(L, 1);
     io::path outputPath = lua::isstring(L, 2) ? lua::require_lstring(L, 2) : "";
+
+    std::vector<std::pair<std::string, std::string>> projectArgs;
+    if (lua::istable(L, 3)) {
+        lua::pushnil(L);
+        while (lua::next(L, 3)) {
+            lua::pushvalue(L, -2);
+            auto key = lua::tolstring(L, -1);
+            auto value = lua::tolstring(L, -2);
+            projectArgs.emplace_back(key, value);
+            lua::pop(L, 2);
+        }
+        lua::pop(L);
+    }
+
     const auto& paths = engine->getPaths();
 
     std::vector<std::string> args {
@@ -419,6 +433,17 @@ static int l_start_background_instance(lua::State* L) {
     args.emplace_back("--project");
     args.emplace_back(io::resolve(engine->getProject().path).u8string());
 
+    if (!projectArgs.empty()) {
+        args.emplace_back("--");
+        for (const auto& [key, value] : projectArgs) {
+            if (key.empty()) {
+                throw std::runtime_error("empty project argument name passed");
+            }
+            args.emplace_back("--" + key);
+            args.emplace_back(value);
+        }
+    }
+
     int handle = -1;
     for (int i = 0; i < ::processes.size(); i++) {
         if (!::processes[i] || !::processes[i]->isActive()) {

From fb20db047d86042977341e68d68aa16e2a831eed Mon Sep 17 00:00:00 2001
From: MihailRis <mexaruc@gmail.com>
Date: Thu, 3 Sep 2026 22:31:28 +0300
Subject: [PATCH 2/2] update doc/*/scripting/builtins/libapp.md

---
 doc/en/scripting/builtins/libapp.md | 4 +++-
 doc/ru/scripting/builtins/libapp.md | 4 +++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/doc/en/scripting/builtins/libapp.md b/doc/en/scripting/builtins/libapp.md
index 06365fc99..f3d46238f 100644
--- a/doc/en/scripting/builtins/libapp.md
+++ b/doc/en/scripting/builtins/libapp.md
@@ -172,7 +172,9 @@ app.start_background_instance(
     -- script file
     app_script: string,
     -- log file
-    output_file: string | nil
+    output_file: string,
+    -- project parameters (can be read with vc.get_project_arg(name))
+    project_args: table<string, string> | nil
 ) -> int
 
 -- Checks if the engine sub-instance is alive.
diff --git a/doc/ru/scripting/builtins/libapp.md b/doc/ru/scripting/builtins/libapp.md
index 53a2224f2..71886a61f 100644
--- a/doc/ru/scripting/builtins/libapp.md
+++ b/doc/ru/scripting/builtins/libapp.md
@@ -162,7 +162,9 @@ app.start_background_instance(
     -- файл сценария
     app_script: string,
     -- файл лога
-    output_file: string | nil
+    output_file: string,
+    -- параметры проекта, что будут доступны через vc.get_project_arg(name)
+    project_args: table<string, string> | nil,
 ) -> int
 
 -- Проверяет, жив ли под-экземпляр движка.