add lua api: script.execute_as_script (#2824)

Co-authored-by: xiaoxiao921 <xiaoxiao921@hotmail.fr>

docs/lua/tables/script.md

@@ -2,7 +2,7 @@
 
 Table containing helper functions related to gta scripts.
 
-## Functions (2)
+## Functions (3)
 
 ### `register_looped(name, func)`
 
@@ -75,4 +75,15 @@ end)
 script.run_in_fiber(func)
 ```
 
+### `execute_as_script(script_name, func)`
+
+- **Parameters:**
+  - `script_name` (string): target script thread.
+  - `func` (function): function that will be executed once in the script thread.
+
+**Example Usage:**
+```lua
+script.execute_as_script(script_name, func)
+```
+
 

src/lua/bindings/script.cpp

@@ -3,6 +3,7 @@
 
 #include "lua/lua_manager.hpp"
 #include "script_mgr.hpp"
+#include "gta_util.hpp"
 
 namespace lua::script
 {
@@ -151,15 +152,26 @@ namespace lua::script
 		module->m_registered_scripts.push_back(std::move(lua_script));
 	}
 
+	// Lua API: function
+	// Table: script
+	// Name: execute_as_script
+	// Param: script_name: string: target script thread.
+	// Param: func: function: function that will be executed once in the script thread.
+	static void execute_as_script(const std::string& script_name, sol::protected_function func)
+	{
+		big::gta_util::execute_as_script(rage::joaat(script_name), func);
+	}
+
 	void bind(sol::state& state)
 	{
 		auto ns               = state["script"].get_or_create<sol::table>();
 		ns["register_looped"] = register_looped;
 		ns["run_in_fiber"]    = run_in_fiber;
+		ns["execute_as_script"] = execute_as_script;
 
 		auto usertype = state.new_usertype<script_util>("script_util");
 
 		usertype["yield"] = sol::yielding(&script_util::yield);
 		usertype["sleep"] = sol::yielding(&script_util::sleep);
 	}
-}
+}