Add Return Value Support for Script Functions (#3479)

* Add Return Value Support for Script Functions
* Removed address-of operator on instruction_pointer parameter, as sol is pass-by-value.
* Fixed reset_session_data & start_creator_script
* Added support for Vector3 and updated casting for bool type for proper conversion to Lua boolean
* Updated documentation for scr_function
* Added get_int method and updated param names for script functions
* Fix #3497 graceful landing not saved.
* Added a check in view_lsc to see if the vehicle can accept clan logos first.
* Fixed vehicle clan logo SP bypass not working properly.
* Fixed COPY VEHICLE not giving persist_car_service::spawn_vehicle_json the target's ped so it can copy their clan logo and not ours.
Fixed spawn_vehicle_json calling add_clan_logo_to_vehicle with our logo and not the ped parameter's logo.
* Added Clone Player Car.
* Fixed has_clan_logo check in view_lsc being given the wrong parameter.

---------

Co-authored-by: gir489 <100792176+gir489returns@users.noreply.github.com>

docs/lua/classes/pointer.md

@@ -63,6 +63,18 @@ Rips the current memory address and returns a new pointer object.
 pointer = pointer:rip(offset)
 ```
 
+### `get_int()`
+
+Retrieves the value stored at the memory address as the specified type.
+
+- **Returns:**
+  - `number`: the value stored at the memory address as the specified type.
+
+**Example Usage:**
+```lua
+number = pointer:get_int()
+```
+
 ### `get_byte()`
 
 Retrieves the value stored at the memory address as the specified type.
@@ -123,6 +135,18 @@ Retrieves the value stored at the memory address as the specified type.
 number = pointer:get_qword()
 ```
 
+### `set_int(value)`
+
+Sets the value at the memory address to the specified value of the given type.
+
+- **Parameters:**
+  - `value` (number): new value.
+
+**Example Usage:**
+```lua
+pointer:set_int(value)
+```
+
 ### `set_byte(value)`
 
 Sets the value at the memory address to the specified value of the given type.

docs/lua/tables/scr_function.md

@@ -0,0 +1,43 @@
+# Table: scr_function
+
+Table for calling GTA script functions. Needs to be called in the fiber pool or a GTA script. Only call the function when necessary.
+
+## Functions (2)
+
+### `call_script_function(script_name, function_name, pattern, return_type_string, args_)`
+
+Calls a script function with the given arguments. Returns the return value as the given type.
+
+- **Parameters:**
+  - `script_name` (string): Name of the script.
+  - `function_name` (string): Name of the function. This parameter needs to be unique.
+  - `pattern` (string): Pattern to scan for within the script.
+  - `return_type_string` (string): Return type of the function. Supported types are **"int"**, **"bool"**, **"const char\*/string"**, **"ptr/pointer/*"**, **"float"**, and **"vector3"**. Anything different will be rejected.
+  - `_args` (table): Arguments to pass to the function. Supported types are the same as return types.
+
+**Example Usage:**
+```lua
+local value = scr_function.call_script_function("freemode", "wear_sunglasses_at_night", "69 42 06 66", "bool", {
+  { "int", 69 },
+  { "float", 4.20 },
+  { "int", 666 }
+})
+```
+
+### `call_script_function(script_name, instruction_pointer, return_type_string, args_)`
+
+Calls a script function directly using the function position with the given arguments. Returns the return value as the given type.
+
+- **Parameters:**
+  - `script_name` (string): Name of the script.
+  - `function_name` (string): Name of the function.
+  - `instruction_pointer` (integer): Position of the function within the script.
+  - `return_type_string` (string): Return type of the function. Supported types are **"int"**, **"bool"**, **"const char\*/string"**, **"ptr/pointer/*"**, **"float"**, and **"vector3"**. Anything different will be rejected.
+  - `_args` (table): Arguments to pass to the function. Supported types are the same as return types.
+
+**Example Usage:**
+```lua
+local value = scr_function.call_script_function("freemode", 0xE792, "string", {
+  { "int", 191 }
+})
+```

docs/lua/tables/script.md

@@ -106,22 +106,6 @@ Adds a patch for the specified script.
 script.add_patch("fm_content_xmas_truck", "Flickering Fix", "56 ? ? 4F ? ? 40 ? 5D ? ? ? 74", 0, {0x2B, 0x00, 0x00})
 ```
 
-### `call_function(name, script_name, pattern, offset, _args)`
-
-Calls a function from the specified script.
-
-- **Parameters:**
-  - `name` (string): The name of the script function.
-  - `script_name` (string): The name of the script.
-  - `pattern` (string): The pattern to scan for within the script.
-  - `offset` (integer): The position within the pattern.
-  - `_args` (table): The arguments to pass to the script function.
-
-**Example Usage:**
-```lua
-script.call_function("Collect Collectible", "freemode", "2D 05 33 00 00", 0, {17, 0, 1, 1, 0})
-```
-
 ### `start_launcher_script(script_name)`
 
 Tries to start a launcher script. Needs to be called in the fiber pool or a loop.