From 4c71be41428131a4ad9ea421f33e1fa18281eda9 Mon Sep 17 00:00:00 2001 From: Quentin Date: Sun, 2 Jul 2023 00:59:02 +0200 Subject: [PATCH] Lua doc (#1552) --- docs/lua/classes/base_text_element.md | 27 + docs/lua/classes/button.md | 6 + docs/lua/classes/checkbox.md | 29 + docs/lua/classes/input_float.md | 29 + docs/lua/classes/input_int.md | 29 + docs/lua/classes/input_string.md | 29 + docs/lua/classes/lua_patch.md | 25 + docs/lua/classes/pointer.md | 322 ++++++++++ docs/lua/classes/sameline.md | 4 + docs/lua/classes/separator.md | 4 + docs/lua/classes/tab.md | 119 ++++ docs/lua/classes/text.md | 19 + docs/lua/classes/vec3.md | 40 ++ docs/lua/doc_gen.py | 556 ++++++++++++++++++ docs/lua/tables/Global Table.md | 20 + docs/lua/tables/command.md | 34 ++ docs/lua/tables/event.md | 20 + docs/lua/tables/globals.md | 106 ++++ docs/lua/tables/gui.md | 69 +++ docs/lua/tables/locals.md | 73 +++ docs/lua/tables/log.md | 43 ++ docs/lua/tables/memory.md | 71 +++ docs/lua/tables/menu_event.md | 81 +++ docs/lua/tables/network.md | 132 +++++ docs/lua/tables/script.md | 53 ++ docs/lua/tables/tunables.md | 79 +++ src/core/data/menu_event.hpp | 11 + .../assign_physical_index.cpp | 4 +- .../player_management/network_player_mgr.cpp | 5 +- src/hooks/protections/receive_net_message.cpp | 2 +- .../protections/script_event_handler.cpp | 2 +- src/lua/bindings/command.hpp | 27 +- src/lua/bindings/event.hpp | 104 +++- src/lua/bindings/global_table.hpp | 20 + src/lua/bindings/globals.hpp | 46 ++ src/lua/bindings/gui.hpp | 80 +++ src/lua/bindings/gui/base_text_element.hpp | 13 + src/lua/bindings/gui/button.hpp | 4 + src/lua/bindings/gui/checkbox.hpp | 13 + src/lua/bindings/gui/input_float.hpp | 13 + src/lua/bindings/gui/input_int.hpp | 13 + src/lua/bindings/gui/input_string.hpp | 13 + src/lua/bindings/gui/sameline.hpp | 3 + src/lua/bindings/gui/separator.hpp | 3 + src/lua/bindings/gui/text.hpp | 9 + src/lua/bindings/locals.hpp | 36 +- src/lua/bindings/log.hpp | 20 + src/lua/bindings/memory.hpp | 184 ++++++ src/lua/bindings/network.hpp | 69 +++ src/lua/bindings/script.hpp | 24 + src/lua/bindings/tunables.hpp | 40 ++ src/lua/bindings/vector.hpp | 26 + src/lua/lua_manager.hpp | 7 +- src/lua/lua_module.cpp | 3 +- src/lua/lua_module.hpp | 3 +- src/lua/lua_patch.hpp | 12 + 56 files changed, 2804 insertions(+), 24 deletions(-) create mode 100644 docs/lua/classes/base_text_element.md create mode 100644 docs/lua/classes/button.md create mode 100644 docs/lua/classes/checkbox.md create mode 100644 docs/lua/classes/input_float.md create mode 100644 docs/lua/classes/input_int.md create mode 100644 docs/lua/classes/input_string.md create mode 100644 docs/lua/classes/lua_patch.md create mode 100644 docs/lua/classes/pointer.md create mode 100644 docs/lua/classes/sameline.md create mode 100644 docs/lua/classes/separator.md create mode 100644 docs/lua/classes/tab.md create mode 100644 docs/lua/classes/text.md create mode 100644 docs/lua/classes/vec3.md create mode 100644 docs/lua/doc_gen.py create mode 100644 docs/lua/tables/Global Table.md create mode 100644 docs/lua/tables/command.md create mode 100644 docs/lua/tables/event.md create mode 100644 docs/lua/tables/globals.md create mode 100644 docs/lua/tables/gui.md create mode 100644 docs/lua/tables/locals.md create mode 100644 docs/lua/tables/log.md create mode 100644 docs/lua/tables/memory.md create mode 100644 docs/lua/tables/menu_event.md create mode 100644 docs/lua/tables/network.md create mode 100644 docs/lua/tables/script.md create mode 100644 docs/lua/tables/tunables.md create mode 100644 src/core/data/menu_event.hpp create mode 100644 src/lua/bindings/global_table.hpp diff --git a/docs/lua/classes/base_text_element.md b/docs/lua/classes/base_text_element.md new file mode 100644 index 00000000..c2a856e0 --- /dev/null +++ b/docs/lua/classes/base_text_element.md @@ -0,0 +1,27 @@ +# Class: base_text_element + +Class representing a gui text element. + +## Functions (2) + +### `set_text(new_text)` + +- **Parameters:** + - `new_text` (string): The new text for that gui text element. + +**Exemple Usage:** +```lua +base_text_element:set_text(new_text) +``` + +### `get_text()` + +- **Returns:** + - `string`: Returns the current text for that gui text element. + +**Exemple Usage:** +```lua +string = base_text_element:get_text() +``` + + diff --git a/docs/lua/classes/button.md b/docs/lua/classes/button.md new file mode 100644 index 00000000..81854cd1 --- /dev/null +++ b/docs/lua/classes/button.md @@ -0,0 +1,6 @@ +# Class: button + +## Inherit from 1 class: base_text_element + +Class representing a gui button. + diff --git a/docs/lua/classes/checkbox.md b/docs/lua/classes/checkbox.md new file mode 100644 index 00000000..cf7f63de --- /dev/null +++ b/docs/lua/classes/checkbox.md @@ -0,0 +1,29 @@ +# Class: checkbox + +## Inherit from 1 class: base_text_element + +Class representing a gui checkbox. + +## Functions (2) + +### `is_enabled()` + +- **Returns:** + - `boolean`: Is the checkbox checked? + +**Exemple Usage:** +```lua +boolean = checkbox:is_enabled() +``` + +### `set_enabled(enabled)` + +- **Parameters:** + - `enabled` (boolean): The desired enabled state of the checkbox. + +**Exemple Usage:** +```lua +checkbox:set_enabled(enabled) +``` + + diff --git a/docs/lua/classes/input_float.md b/docs/lua/classes/input_float.md new file mode 100644 index 00000000..a97635d4 --- /dev/null +++ b/docs/lua/classes/input_float.md @@ -0,0 +1,29 @@ +# Class: input_float + +## Inherit from 1 class: base_text_element + +Class for representing an input field for editing a float value within the GUI. + +## Functions (2) + +### `get_value()` + +- **Returns:** + - `float`: Get the value currently written inside the input field. + +**Exemple Usage:** +```lua +float = input_float:get_value() +``` + +### `set_value(val)` + +- **Parameters:** + - `val` (float): Set the value currently written inside the input field. + +**Exemple Usage:** +```lua +input_float:set_value(val) +``` + + diff --git a/docs/lua/classes/input_int.md b/docs/lua/classes/input_int.md new file mode 100644 index 00000000..63bab2ca --- /dev/null +++ b/docs/lua/classes/input_int.md @@ -0,0 +1,29 @@ +# Class: input_int + +## Inherit from 1 class: base_text_element + +Class for representing an input field for editing an integer value within the GUI. + +## Functions (2) + +### `get_value()` + +- **Returns:** + - `integer`: Get the value currently written inside the input field. + +**Exemple Usage:** +```lua +integer = input_int:get_value() +``` + +### `set_value(val)` + +- **Parameters:** + - `val` (integer): Set the value currently written inside the input field. + +**Exemple Usage:** +```lua +input_int:set_value(val) +``` + + diff --git a/docs/lua/classes/input_string.md b/docs/lua/classes/input_string.md new file mode 100644 index 00000000..3a1d599f --- /dev/null +++ b/docs/lua/classes/input_string.md @@ -0,0 +1,29 @@ +# Class: input_string + +## Inherit from 1 class: base_text_element + +Class for representing an input field for editing a string value within the GUI. + +## Functions (2) + +### `get_value()` + +- **Returns:** + - `string`: Get the value currently written inside the input field. + +**Exemple Usage:** +```lua +string = input_string:get_value() +``` + +### `set_value(val)` + +- **Parameters:** + - `val` (string): Set the value currently written inside the input field. + +**Exemple Usage:** +```lua +input_string:set_value(val) +``` + + diff --git a/docs/lua/classes/lua_patch.md b/docs/lua/classes/lua_patch.md new file mode 100644 index 00000000..a188e681 --- /dev/null +++ b/docs/lua/classes/lua_patch.md @@ -0,0 +1,25 @@ +# Class: lua_patch + +Class representing a in-memory patch. + +## Functions (2) + +### `apply()` + +Apply the modified value. + +**Exemple Usage:** +```lua +lua_patch:apply() +``` + +### `restore()` + +Restore the original value. + +**Exemple Usage:** +```lua +lua_patch:restore() +``` + + diff --git a/docs/lua/classes/pointer.md b/docs/lua/classes/pointer.md new file mode 100644 index 00000000..b67b8b3e --- /dev/null +++ b/docs/lua/classes/pointer.md @@ -0,0 +1,322 @@ +# Class: pointer + +Class representing a 64-bit memory address. + +## Constructors (1) + +### `new(address)` + +Returns a memory instance, with the given address. + +- **Parameters:** + - `address` (integer): Address + +**Exemple Usage:** +```lua +myInstance = pointer:new(address) +``` + +## Functions (23) + +### `add(offset)` + +Adds an offset to the current memory address and returns a new pointer object. + +- **Parameters:** + - `offset` (integer): offset + +- **Returns:** + - `pointer`: new pointer object. + +**Exemple Usage:** +```lua +pointer = pointer:add(offset) +``` + +### `sub(offset)` + +Subs an offset to the current memory address and returns a new pointer object. + +- **Parameters:** + - `offset` (integer): offset + +- **Returns:** + - `pointer`: new pointer object. + +**Exemple Usage:** +```lua +pointer = pointer:sub(offset) +``` + +### `rip(offset)` + +Rips the current memory address and returns a new pointer object. + +- **Parameters:** + - `offset` (integer): offset + +- **Returns:** + - `pointer`: new pointer object. + +**Exemple Usage:** +```lua +pointer = pointer:rip(offset) +``` + +### `get_byte()` + +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. + +**Exemple Usage:** +```lua +number = pointer:get_byte() +``` + +### `get_word()` + +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. + +**Exemple Usage:** +```lua +number = pointer:get_word() +``` + +### `get_dword()` + +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. + +**Exemple Usage:** +```lua +number = pointer:get_dword() +``` + +### `get_float()` + +Retrieves the value stored at the memory address as the specified type. + +- **Returns:** + - `float`: the value stored at the memory address as the specified type. + +**Exemple Usage:** +```lua +float = pointer:get_float() +``` + +### `get_qword()` + +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. + +**Exemple Usage:** +```lua +number = pointer:get_qword() +``` + +### `set_byte(value)` + +Sets the value at the memory address to the specified value of the given type. + +- **Parameters:** + - `value` (number): new value. + +**Exemple Usage:** +```lua +pointer:set_byte(value) +``` + +### `set_word(value)` + +Sets the value at the memory address to the specified value of the given type. + +- **Parameters:** + - `value` (number): new value. + +**Exemple Usage:** +```lua +pointer:set_word(value) +``` + +### `set_dword(value)` + +Sets the value at the memory address to the specified value of the given type. + +- **Parameters:** + - `value` (number): new value. + +**Exemple Usage:** +```lua +pointer:set_dword(value) +``` + +### `set_float(value)` + +Sets the value at the memory address to the specified value of the given type. + +- **Parameters:** + - `value` (float): new value. + +**Exemple Usage:** +```lua +pointer:set_float(value) +``` + +### `set_qword(value)` + +Sets the value at the memory address to the specified value of the given type. + +- **Parameters:** + - `value` (number): new value. + +**Exemple Usage:** +```lua +pointer:set_qword(value) +``` + +### `get_string()` + +Retrieves the value stored at the memory address as the specified type. + +- **Returns:** + - `string`: the value stored at the memory address as the specified type. + +**Exemple Usage:** +```lua +string = pointer:get_string() +``` + +### `set_string(value)` + +Sets the value at the memory address to the specified value of the given type. + +- **Parameters:** + - `value` (string): new value. + +**Exemple Usage:** +```lua +pointer:set_string(value) +``` + +### `patch_byte(value)` + +Creates a memory patch for modifying the value at the memory address with the specified value. +The modified value is applied when you call the apply function on the lua_patch object. +The original value is restored when you call the restore function on the lua_patch object. + +- **Parameters:** + - `value` (number): new value. + +- **Returns:** + - `lua_patch`: memory patch instance for modifying the value at the memory address with the specified value. Can call apply / restore on the object. + +**Exemple Usage:** +```lua +lua_patch = pointer:patch_byte(value) +``` + +### `patch_word(value)` + +Creates a memory patch for modifying the value at the memory address with the specified value. +The modified value is applied when you call the apply function on the lua_patch object. +The original value is restored when you call the restore function on the lua_patch object. + +- **Parameters:** + - `value` (number): new value. + +- **Returns:** + - `lua_patch`: memory patch instance for modifying the value at the memory address with the specified value. Can call apply / restore on the object. + +**Exemple Usage:** +```lua +lua_patch = pointer:patch_word(value) +``` + +### `patch_dword(value)` + +Creates a memory patch for modifying the value at the memory address with the specified value. +The modified value is applied when you call the apply function on the lua_patch object. +The original value is restored when you call the restore function on the lua_patch object. + +- **Parameters:** + - `value` (number): new value. + +- **Returns:** + - `lua_patch`: memory patch instance for modifying the value at the memory address with the specified value. Can call apply / restore on the object. + +**Exemple Usage:** +```lua +lua_patch = pointer:patch_dword(value) +``` + +### `patch_qword(value)` + +Creates a memory patch for modifying the value at the memory address with the specified value. +The modified value is applied when you call the apply function on the lua_patch object. +The original value is restored when you call the restore function on the lua_patch object. + +- **Parameters:** + - `value` (number): new value. + +- **Returns:** + - `lua_patch`: memory patch instance for modifying the value at the memory address with the specified value. Can call apply / restore on the object. + +**Exemple Usage:** +```lua +lua_patch = pointer:patch_qword(value) +``` + +### `is_null()` + +- **Returns:** + - `boolean`: Returns true if the address is null. + +**Exemple Usage:** +```lua +boolean = pointer:is_null() +``` + +### `is_valid()` + +- **Returns:** + - `boolean`: Returns true if the address is not null. + +**Exemple Usage:** +```lua +boolean = pointer:is_valid() +``` + +### `deref()` + +Dereferences the memory address and returns a new pointer object pointing to the value at that address. + +- **Returns:** + - `pointer`: A new pointer object pointing to the value at that address. + +**Exemple Usage:** +```lua +pointer = pointer:deref() +``` + +### `get_address()` + +Retrieves the memory address stored in the pointer object. + +- **Returns:** + - `number`: The memory address stored in the pointer object as a number. + +**Exemple Usage:** +```lua +number = pointer:get_address() +``` + + diff --git a/docs/lua/classes/sameline.md b/docs/lua/classes/sameline.md new file mode 100644 index 00000000..561c0c66 --- /dev/null +++ b/docs/lua/classes/sameline.md @@ -0,0 +1,4 @@ +# Class: sameline + +Class for ImGui::SameLine() - Puts a sameline between widgets or groups to layout them horizontally. + diff --git a/docs/lua/classes/separator.md b/docs/lua/classes/separator.md new file mode 100644 index 00000000..2f24475e --- /dev/null +++ b/docs/lua/classes/separator.md @@ -0,0 +1,4 @@ +# Class: separator + +Class for ImGui::Separator() - separator, generally horizontal. Inside a menu bar or in horizontal layout mode, this becomes a vertical separator. + diff --git a/docs/lua/classes/tab.md b/docs/lua/classes/tab.md new file mode 100644 index 00000000..01721ec9 --- /dev/null +++ b/docs/lua/classes/tab.md @@ -0,0 +1,119 @@ +# Class: tab + +Class for representing a tab within the GUI. + +## Functions (8) + +### `add_button(name, callback)` + +Add a button to the gui tab. + +- **Parameters:** + - `name` (string): Text written inside the button. + - `callback` (function): function that will be called when the button is clicked. + +**Exemple Usage:** +```lua +tab:add_button(name, callback) +``` + +### `add_text(name)` + +Add text to the gui tab. + +- **Parameters:** + - `name` (string): Text that will be written. + +- **Returns:** + - `text`: The text object instance. + +**Exemple Usage:** +```lua +text = tab:add_text(name) +``` + +### `add_checkbox(name)` + +Add a checkbox widget to the gui tab. + +- **Parameters:** + - `name` (string): Text that will be written next to the checkbox. + +- **Returns:** + - `checkbox`: The checkbox object instance. + +**Exemple Usage:** +```lua +checkbox = tab:add_checkbox(name) +``` + +### `add_sameline()` + +Add a ImGui::SameLine. + +- **Returns:** + - `sameline`: The sameline object instance. + +**Exemple Usage:** +```lua +sameline = tab:add_sameline() +``` + +### `add_separator()` + +Add a ImGui::Separator. + +- **Returns:** + - `separator`: The separator object instance. + +**Exemple Usage:** +```lua +separator = tab:add_separator() +``` + +### `add_input_int(name)` + +Add a ImGui::InputInt. + +- **Parameters:** + - `name` (string): Text that will be written next to the input field. + +- **Returns:** + - `input_int`: The input_int object instance. + +**Exemple Usage:** +```lua +input_int = tab:add_input_int(name) +``` + +### `add_input_float(name)` + +Add a ImGui::InputFloat. + +- **Parameters:** + - `name` (string): Text that will be written next to the input field. + +- **Returns:** + - `input_float`: The input_float object instance. + +**Exemple Usage:** +```lua +input_float = tab:add_input_float(name) +``` + +### `add_input_string(name)` + +Add a ImGui::InputText. + +- **Parameters:** + - `name` (string): Text that will be written next to the input field. + +- **Returns:** + - `input_string`: The input_string object instance. + +**Exemple Usage:** +```lua +input_string = tab:add_input_string(name) +``` + + diff --git a/docs/lua/classes/text.md b/docs/lua/classes/text.md new file mode 100644 index 00000000..bfe49723 --- /dev/null +++ b/docs/lua/classes/text.md @@ -0,0 +1,19 @@ +# Class: text + +## Inherit from 1 class: base_text_element + +Class representing an imgui text element. + +## Functions (1) + +### `set_font(font)` + +- **Parameters:** + - `font` (string): The new font name for that imgui text element. + +**Exemple Usage:** +```lua +text:set_font(font) +``` + + diff --git a/docs/lua/classes/vec3.md b/docs/lua/classes/vec3.md new file mode 100644 index 00000000..dd2f51b8 --- /dev/null +++ b/docs/lua/classes/vec3.md @@ -0,0 +1,40 @@ +# Class: vec3 + +Class representing a 3D vector. + +## Fields (3) + +### `x` + +x component of the vector. + +- Type: `float` + +### `y` + +y component of the vector. + +- Type: `float` + +### `z` + +z component of the vector. + +- Type: `float` + +## Constructors (1) + +### `new(x, y, z)` + +Returns a vector that contains the x, y, and z values. + +- **Parameters:** + - `x` (float): x component of the vector. + - `y` (float): y component of the vector. + - `z` (float): z component of the vector. + +**Exemple Usage:** +```lua +myInstance = vec3:new(x, y, z) +``` + diff --git a/docs/lua/doc_gen.py b/docs/lua/doc_gen.py new file mode 100644 index 00000000..84793599 --- /dev/null +++ b/docs/lua/doc_gen.py @@ -0,0 +1,556 @@ +import os +from enum import Enum + +src_folder = "../../src/" + +lua_api_comment_identifier = "lua api" +lua_api_comment_separator = ":" + +tables = {} +classes = {} +functions = {} + + +class DocKind(Enum): + Table = "table" + Class = "class" + Field = "field" + Constructor = "constructor" + Function = "function" + + +class Table: + def __init__(self, name, fields, functions, description): + self.name = name.strip() + self.fields = fields + self.functions = functions + self.description = description + + def __str__(self): + s = f"# Table: {self.name}\n" + s += "\n" + + if len(self.description) > 0: + s += f"{self.description}\n" + s += "\n" + + if len(self.fields) > 0: + s += f"## Fields ({len(self.fields)})\n" + s += "\n" + + self.check_for_duplicate_fields_names() + + for field in self.fields: + s += field.print_markdown() + + if len(self.functions) > 0: + s += f"## Functions ({len(self.functions)})\n" + s += "\n" + + self.check_for_duplicate_function_names() + + for func in self.functions: + s += func.print_markdown(f"{self.name}.") + + s += "\n" + + return s + + def check_for_duplicate_fields_names(self): + seen = set() + duplicates = [x for x in self.fields if x.name in seen or seen.add(x.name)] + if len(duplicates) > 0: + print("Error while building lua doc. Duplicate field names:") + for dup in duplicates: + print(dup) + exit(1) + + def check_for_duplicate_function_names(self): + seen = set() + duplicates = [x for x in self.functions if x.name in seen or seen.add(x.name)] + if len(duplicates) > 0: + print("Error while building lua doc. Duplicate function names:") + for dup in duplicates: + print(dup) + exit(1) + + +class Class: + def __init__(self, name, inheritance, fields, constructors, functions, description): + self.name = name.strip() + self.inheritance = inheritance + self.fields = fields + self.constructors = constructors + self.functions = functions + self.description = description + + def __str__(self): + s = f"# Class: {self.name}\n" + s += "\n" + + if len(self.inheritance) > 0: + inherited_class_names = ", ".join(self.inheritance) + s += f"## Inherit from {len(self.inheritance)} class: {inherited_class_names}\n" + s += "\n" + + if len(self.description) > 0: + s += f"{self.description}\n" + s += "\n" + + if len(self.fields) > 0: + s += f"## Fields ({len(self.fields)})\n" + s += "\n" + + self.check_for_duplicate_fields_names() + + for field in self.fields: + s += field.print_markdown() + + if len(self.constructors) > 0: + s += f"## Constructors ({len(self.constructors)})\n" + s += "\n" + + for ctor in self.constructors: + s += ctor.print_markdown() + + if len(self.functions) > 0: + s += f"## Functions ({len(self.functions)})\n" + s += "\n" + + self.check_for_duplicate_function_names() + + for func in self.functions: + s += func.print_markdown(f"{self.name}:") + + s += "\n" + + return s + + def check_for_duplicate_fields_names(self): + seen = set() + duplicates = [x for x in self.fields if x.name in seen or seen.add(x.name)] + if len(duplicates) > 0: + print("Error while building lua doc. Duplicate field names:") + for dup in duplicates: + print(dup) + exit(1) + + def check_for_duplicate_function_names(self): + seen = set() + duplicates = [x for x in self.functions if x.name in seen or seen.add(x.name)] + if len(duplicates) > 0: + print("Error while building lua doc. Duplicate function names:") + for dup in duplicates: + print(dup) + exit(1) + + +class Field: + def __init__(self, name, type_, description): + self.name = name.strip() + self.type_ = type_.strip() + self.description = description + + def __str__(self): + s = f"Field: {self.name}\n" + s += f"Type: {self.type_}\n" + s += f"Description: {self.description.strip()}\n" + return s + + def print_markdown(self): + s = "" + + s += f"### `{self.name}`\n" + s += "\n" + + if len(self.description) > 0: + s += f"{self.description}\n" + s += "\n" + + if self.type_ is not None and len(self.type_) > 0: + s += f"- Type: `{self.type_}`\n" + + s += "\n" + + return s + + +class Constructor: + def __init__(self, parent, parameters, description): + self.parent = parent + self.parameters = parameters + self.description = description + + def print_markdown(self): + s = "" + + parameters_str = ", ".join(p.name for p in self.parameters) + + s += f"### `new({parameters_str})`\n" + s += "\n" + + if len(self.description) > 0: + s += f"{self.description}\n" + s += "\n" + + if len(self.parameters) > 0: + s += f"- **Parameters:**\n" + for param in self.parameters: + s += f" - `{param.name}` ({param.type_})" + if len(param.description) > 0: + s += f": {param.description}\n" + else: + s += f"\n" + s += "\n" + + s += f"**Exemple Usage:**\n" + s += "```lua\n" + + s += f"myInstance = {self.parent.name}:new({parameters_str})\n" + + s += "```\n" + s += "\n" + + return s + + +class Parameter: + def __init__(self, name, type_, description): + self.name = name.strip() + self.type_ = type_.strip() + self.description = description + + def __str__(self): + s = f"Parameter: {self.name}\n" + s += f"Type: {self.type_}\n" + s += f"Description: {self.description.strip()}\n" + return s + + +class Function: + def __init__( + self, name, parent, parameters, return_type, return_description, description + ): + self.name = name.strip() + self.parent = parent + self.parameters = parameters + self.return_type = return_type + self.return_description = return_description + self.description = description + + def __str__(self): + s = f"Function: {self.name}\n" + + type_name = str(type(self.parent)).split(".")[1][:-2] + s += f"Parent: {self.parent.name} ({type_name})\n" + + s += f"Parameters: {len(self.parameters)}\n" + i = 1 + for param in self.parameters: + s += f"Parameter {i}\n" + s += str(param) + "\n" + i += 1 + + s += f"Return Type: {self.return_type}\n" + s += f"Return Description: {self.return_description}\n" + + s += f"Description: {self.description}\n" + return s + + def print_markdown(self, prefix): + s = "" + + parameters_str = ", ".join(p.name for p in self.parameters) + + s += f"### `{self.name}({parameters_str})`\n" + s += "\n" + + if len(self.description) > 0: + s += f"{self.description}\n" + s += "\n" + + if len(self.parameters) > 0: + s += f"- **Parameters:**\n" + for param in self.parameters: + s += f" - `{param.name}` ({param.type_})" + if len(param.description) > 0: + s += f": {param.description}\n" + else: + s += f"\n" + s += "\n" + + if self.return_type is not None and len(self.return_type) > 0: + s += f"- **Returns:**\n" + s += f" - `{self.return_type}`: {self.return_description}\n" + + s += "\n" + + s += f"**Exemple Usage:**\n" + s += "```lua\n" + if self.return_type is not None and len(self.return_type) > 0: + s += self.return_type + " = " + + if "Global Table" in prefix: + prefix = "" + s += f"{prefix}{self.name}({parameters_str})\n" + + s += "```\n" + s += "\n" + + return s + + +def make_table(table_name): + if table_name not in tables: + tables[table_name] = Table(table_name, [], [], "") + cur_table = tables[table_name] + return cur_table + + +def make_class(class_name): + if class_name not in classes: + classes[class_name] = Class(class_name, [], [], [], [], "") + cur_class = classes[class_name] + return cur_class + + +def is_comment_a_lua_api_doc_comment(text_lower): + return ( + lua_api_comment_identifier in text_lower + and lua_api_comment_separator in text_lower + and "//" in text_lower + ) + + +def parse_lua_api_doc(folder_path): + for root, dirs, files in os.walk(folder_path): + for file_name in files: + if os.path.splitext(file_name)[1].startswith((".c", ".h")): + file_path = os.path.join(root, file_name) + with open(file_path, "r") as file: + doc_kind = None + cur_table = None + cur_class = None + cur_function = None + cur_field = None + cur_constructor = None + + for line in file: + line = line.strip() + line_lower = line.lower() + if is_comment_a_lua_api_doc_comment(line_lower): + doc_kind = DocKind( + line.split(lua_api_comment_separator, 1)[1] + .strip() + .lower() + ) + + continue + + if doc_kind is not None and "//" in line: + match doc_kind: + case DocKind.Table: + cur_table = parse_table_doc( + cur_table, line, line_lower + ) + case DocKind.Class: + cur_class = parse_class_doc( + cur_class, line, line_lower + ) + case DocKind.Function: + ( + cur_function, + cur_table, + cur_class, + ) = parse_function_doc( + cur_function, + cur_table, + cur_class, + line, + line_lower, + ) + case DocKind.Field: + (cur_field, cur_table, cur_class) = parse_field_doc( + cur_field, + cur_table, + cur_class, + line, + line_lower, + ) + case DocKind.Constructor: + ( + cur_constructor, + cur_class, + ) = parse_constructor_doc( + cur_constructor, + cur_class, + line, + line_lower, + ) + case _: + # print("unsupported doc kind: " + str(doc_kind)) + pass + else: + doc_kind = None + + +def parse_table_doc(cur_table, line, line_lower): + if is_lua_doc_comment_startswith(line_lower, "name"): + table_name = line.split(lua_api_comment_separator, 1)[1].strip() + cur_table = make_table(table_name) + else: + if len(cur_table.description) != 0: + cur_table.description += "\n" + cur_table.description += sanitize_description(line) + + return cur_table + +def parse_class_doc(cur_class, line, line_lower): + if is_lua_doc_comment_startswith(line_lower, "name"): + class_name = line.split(lua_api_comment_separator, 1)[1].strip() + cur_class = make_class(class_name) + elif is_lua_doc_comment_startswith(line_lower, "inherit"): + inherited_class_name = line.split(lua_api_comment_separator, 1)[1].strip() + cur_class.inheritance.append(inherited_class_name) + else: + if len(cur_class.description) != 0: + cur_class.description += "\n" + cur_class.description += sanitize_description(line) + + return cur_class + + +def parse_function_doc(cur_function, cur_table, cur_class, line, line_lower): + if is_lua_doc_comment_startswith(line_lower, "table") and lua_api_comment_separator in line_lower: + table_name = line.split(lua_api_comment_separator, 1)[1].strip() + cur_table = make_table(table_name) + + cur_function = Function("Didnt get name yet", cur_table, [], None, "", "") + cur_table.functions.append(cur_function) + elif is_lua_doc_comment_startswith(line_lower, "class") and lua_api_comment_separator in line_lower: + class_name = line.split(lua_api_comment_separator, 1)[1].strip() + cur_class = make_class(class_name) + + cur_function = Function("Didnt get name yet", cur_class, [], None, "", "") + cur_class.functions.append(cur_function) + elif is_lua_doc_comment_startswith(line_lower, "name") and lua_api_comment_separator in line_lower: + function_name = line.split(lua_api_comment_separator, 1)[1].strip() + cur_function.name = function_name + + if function_name not in functions: + functions[function_name] = cur_function + elif is_lua_doc_comment_startswith(line_lower, "param") and lua_api_comment_separator in line_lower: + parameter = make_parameter_from_doc_line(line) + cur_function.parameters.append(parameter) + elif is_lua_doc_comment_startswith(line_lower, "return") and lua_api_comment_separator in line_lower: + return_info = line.split(lua_api_comment_separator, 2) + try: + cur_function.return_type = return_info[1].strip() + cur_function.return_description = return_info[2].strip() + except IndexError: + pass + else: + if len(cur_function.description) != 0: + cur_function.description += "\n" + cur_function.description += sanitize_description(line) + + return cur_function, cur_table, cur_class + + +def parse_field_doc(cur_field, cur_table, cur_class, line, line_lower): + if is_lua_doc_comment_startswith(line_lower, "table") and lua_api_comment_separator in line_lower: + table_name = line.split(lua_api_comment_separator, 1)[1].strip() + cur_table = make_table(table_name) + + cur_field = Field("Didnt get name yet", "", "") + cur_table.fields.append(cur_field) + elif is_lua_doc_comment_startswith(line_lower, "class") and lua_api_comment_separator in line_lower: + class_name = line.split(lua_api_comment_separator, 1)[1].strip() + cur_class = make_class(class_name) + + cur_field = Field("Didnt get name yet", "", "") + cur_class.fields.append(cur_field) + elif is_lua_doc_comment_startswith(line_lower, "field") and lua_api_comment_separator in line_lower: + field_info = line.split(lua_api_comment_separator, 2) + cur_field.name = field_info[1].strip() + cur_field.type_ = field_info[2].strip() + else: + if len(cur_field.description) != 0: + cur_field.description += "\n" + + if line.startswith("// "): + line = line[3:] + cur_field.description += sanitize_description(line) + + return cur_field, cur_table, cur_class + + +def parse_constructor_doc(cur_constructor, cur_class, line, line_lower): + if is_lua_doc_comment_startswith(line_lower, "class") and lua_api_comment_separator in line_lower: + class_name = line.split(lua_api_comment_separator, 1)[1].strip() + cur_class = make_class(class_name) + + cur_constructor = Constructor(cur_class, [], "") + cur_class.constructors.append(cur_constructor) + elif is_lua_doc_comment_startswith(line_lower, "param") and lua_api_comment_separator in line_lower: + parameter = make_parameter_from_doc_line(line) + cur_constructor.parameters.append(parameter) + else: + if len(cur_constructor.description) != 0: + cur_constructor.description += "\n" + cur_constructor.description += sanitize_description(line) + + return cur_constructor, cur_class + + +def make_parameter_from_doc_line(line): + param_info = line.split(lua_api_comment_separator, 3)[1:] + param_name = param_type = param_desc = "" + + try: + param_name = param_info[0].strip() + param_type = param_info[1].strip() + param_desc = param_info[2].strip() + except IndexError: + pass + + return Parameter(param_name, param_type, param_desc) + +def sanitize_description(line): + if line.startswith("// ") and line[3] != ' ': + line = line[3:] + if line.startswith("//"): + line = line[2:] + return line.rstrip() + +def is_lua_doc_comment_startswith(line_lower, starts_with_text): + return line_lower.replace("//", "").strip().startswith(starts_with_text) + + +parse_lua_api_doc(src_folder) + +try: + os.makedirs("./tables/") +except: + pass + +for table_name, table in tables.items(): + file_name = f"./tables/{table_name}.md" + if os.path.exists(file_name): + os.remove(file_name) + f = open(file_name, "a") + f.write(str(table)) + f.close() + +try: + os.makedirs("./classes/") +except: + pass + +for class_name, class_ in classes.items(): + file_name = f"./classes/{class_name}.md" + if os.path.exists(file_name): + os.remove(file_name) + f = open(file_name, "a") + f.write(str(class_)) + f.close() diff --git a/docs/lua/tables/Global Table.md b/docs/lua/tables/Global Table.md new file mode 100644 index 00000000..0b6eb1a6 --- /dev/null +++ b/docs/lua/tables/Global Table.md @@ -0,0 +1,20 @@ +# Table: Global Table + +Custom fields, functions, etc added to The Lua [Global Table](https://www.lua.org/pil/15.4.html). + +## Functions (1) + +### `joaat(str)` + +- **Parameters:** + - `str` (string): The string that needs to be joaat hashed. + +- **Returns:** + - `integer`: The joaat hashed input string. + +**Exemple Usage:** +```lua +integer = joaat(str) +``` + + diff --git a/docs/lua/tables/command.md b/docs/lua/tables/command.md new file mode 100644 index 00000000..32709bbd --- /dev/null +++ b/docs/lua/tables/command.md @@ -0,0 +1,34 @@ +# Table: command + +Table for calling menu commands. + +## Functions (2) + +### `call(command_name, _args)` + +Call a menu command. + +- **Parameters:** + - `command_name` (string): The name of the command that will be called. + - `_args` (table): Optional. List of arguments for the command. + +**Exemple Usage:** +```lua +command.call(command_name, _args) +``` + +### `call_player(player_idx, command_name, _args)` + +Call a menu command on a given player. + +- **Parameters:** + - `player_idx` (integer): Index of the player on which the menu command will be executed. + - `command_name` (string): The name of the command that will be called. + - `_args` (table): Optional. List of arguments for the command. + +**Exemple Usage:** +```lua +command.call_player(player_idx, command_name, _args) +``` + + diff --git a/docs/lua/tables/event.md b/docs/lua/tables/event.md new file mode 100644 index 00000000..6fc3c812 --- /dev/null +++ b/docs/lua/tables/event.md @@ -0,0 +1,20 @@ +# Table: event + +Table for responding to various events. The list of events is available in the menu_event table. + +## Functions (1) + +### `register_handler(menu_event, func)` + +Register a function that will be called each time the corresponding menu_event is triggered. + +- **Parameters:** + - `menu_event` (menu_event): The menu_event that we want to respond to. + - `func` (function): The function that will be called. + +**Exemple Usage:** +```lua +event.register_handler(menu_event, func) +``` + + diff --git a/docs/lua/tables/globals.md b/docs/lua/tables/globals.md new file mode 100644 index 00000000..76845171 --- /dev/null +++ b/docs/lua/tables/globals.md @@ -0,0 +1,106 @@ +# Table: globals + +Table containing functions for manipulating gta script globals. + +## Functions (7) + +### `get_int(global)` + +Retrieves an int global value. + +- **Parameters:** + - `global` (integer): index of the global + +- **Returns:** + - `integer`: value of the global + +**Exemple Usage:** +```lua +integer = globals.get_int(global) +``` + +### `get_float(global)` + +Retrieves a float global value. + +- **Parameters:** + - `global` (integer): index of the global + +- **Returns:** + - `float`: value of the global + +**Exemple Usage:** +```lua +float = globals.get_float(global) +``` + +### `get_string(global)` + +Retrieves a string global value. + +- **Parameters:** + - `global` (integer): index of the global + +- **Returns:** + - `string`: value of the global + +**Exemple Usage:** +```lua +string = globals.get_string(global) +``` + +### `set_int(global, val)` + +Sets an int global value. + +- **Parameters:** + - `global` (integer): index of the global + - `val` (integer): new value for the global + +**Exemple Usage:** +```lua +globals.set_int(global, val) +``` + +### `set_float(global, val)` + +Sets a float global value. + +- **Parameters:** + - `global` (integer): index of the global + - `val` (float): new value for the global + +**Exemple Usage:** +```lua +globals.set_float(global, val) +``` + +### `set_string(global, str)` + +Sets a string global value. + +- **Parameters:** + - `global` (integer): index of the global + - `str` (string): new value for the global + +**Exemple Usage:** +```lua +globals.set_string(global, str) +``` + +### `get_pointer(global)` + +Retrieves a pointer global. + +- **Parameters:** + - `global` (integer): index of the global + +- **Returns:** + - `pointer`: value of the global + +**Exemple Usage:** +```lua +pointer = globals.get_pointer(global) +``` + + diff --git a/docs/lua/tables/gui.md b/docs/lua/tables/gui.md new file mode 100644 index 00000000..21833781 --- /dev/null +++ b/docs/lua/tables/gui.md @@ -0,0 +1,69 @@ +# Table: gui + +Table containing functions for modifying the menu GUI. + +## Functions (5) + +### `get_tab(tab_name)` + +- **Parameters:** + - `tab_name` (string): Name of the tab to get. + +- **Returns:** + - `tab`: A tab instance which corresponds to the tab in the GUI. + +**Exemple Usage:** +```lua +tab = gui.get_tab(tab_name) +``` + +### `show_message(title, message)` + +Shows a message to the user with the given title and message. + +- **Parameters:** + - `title` (string) + - `message` (string) + +**Exemple Usage:** +```lua +gui.show_message(title, message) +``` + +### `show_warning(title, message)` + +Shows a warning to the user with the given title and message. + +- **Parameters:** + - `title` (string) + - `message` (string) + +**Exemple Usage:** +```lua +gui.show_warning(title, message) +``` + +### `show_error(title, message)` + +Shows an error to the user with the given title and message. + +- **Parameters:** + - `title` (string) + - `message` (string) + +**Exemple Usage:** +```lua +gui.show_error(title, message) +``` + +### `is_open()` + +- **Returns:** + - `bool`: Returns true if the GUI is open. + +**Exemple Usage:** +```lua +bool = gui.is_open() +``` + + diff --git a/docs/lua/tables/locals.md b/docs/lua/tables/locals.md new file mode 100644 index 00000000..6ec1f303 --- /dev/null +++ b/docs/lua/tables/locals.md @@ -0,0 +1,73 @@ +# Table: locals + +Table for manipulating GTA scripts locals. + +## Functions (5) + +### `get_int(script, index)` + +- **Parameters:** + - `script` (string): The name of the script + - `index` (index): Index of the script local. + +- **Returns:** + - `integer`: The value of the given local. + +**Exemple Usage:** +```lua +integer = locals.get_int(script, index) +``` + +### `get_float(script, index)` + +- **Parameters:** + - `script` (string): The name of the script + - `index` (index): Index of the script local. + +- **Returns:** + - `float`: The value of the given local. + +**Exemple Usage:** +```lua +float = locals.get_float(script, index) +``` + +### `set_int(script, index, val)` + +- **Parameters:** + - `script` (string): The name of the script + - `index` (index): Index of the script local. + - `val` (integer): The new value of the given local. + +**Exemple Usage:** +```lua +locals.set_int(script, index, val) +``` + +### `set_float(script, index, val)` + +- **Parameters:** + - `script` (string): The name of the script + - `index` (index): Index of the script local. + - `val` (float): The new value of the given local. + +**Exemple Usage:** +```lua +locals.set_float(script, index, val) +``` + +### `get_pointer(script, index)` + +- **Parameters:** + - `script` (string): The name of the script + - `index` (index): Index of the script local. + +- **Returns:** + - `pointer`: The pointer to the given local. + +**Exemple Usage:** +```lua +pointer = locals.get_pointer(script, index) +``` + + diff --git a/docs/lua/tables/log.md b/docs/lua/tables/log.md new file mode 100644 index 00000000..2ee10ede --- /dev/null +++ b/docs/lua/tables/log.md @@ -0,0 +1,43 @@ +# Table: log + +Table containing functions for printing to console / log file. + +## Functions (3) + +### `info(data)` + +Logs an informational message. + +- **Parameters:** + - `data` (string) + +**Exemple Usage:** +```lua +log.info(data) +``` + +### `warning(data)` + +Logs a warning message. + +- **Parameters:** + - `data` (string) + +**Exemple Usage:** +```lua +log.warning(data) +``` + +### `debug(data)` + +Logs a debug message. + +- **Parameters:** + - `data` (string) + +**Exemple Usage:** +```lua +log.debug(data) +``` + + diff --git a/docs/lua/tables/memory.md b/docs/lua/tables/memory.md new file mode 100644 index 00000000..035c8339 --- /dev/null +++ b/docs/lua/tables/memory.md @@ -0,0 +1,71 @@ +# Table: memory + +Table containing helper functions related to process memory. + +## Functions (5) + +### `scan_pattern(pattern)` + +Scans the specified memory pattern within the "GTA5.exe" module and returns a pointer to the found address. + +- **Parameters:** + - `pattern` (string): byte pattern (IDA format) + +- **Returns:** + - `pointer`: A pointer to the found address. + +**Exemple Usage:** +```lua +pointer = memory.scan_pattern(pattern) +``` + +### `handle_to_ptr(entity)` + +- **Parameters:** + - `entity` (number): script game entity handle + +- **Returns:** + - `pointer`: A rage::CDynamicEntity pointer to the script game entity handle + +**Exemple Usage:** +```lua +pointer = memory.handle_to_ptr(entity) +``` + +### `ptr_to_handle(mem_addr)` + +- **Parameters:** + - `mem_addr` (pointer): A rage::CDynamicEntity pointer. + +- **Returns:** + - `number`: The script game entity handle linked to the given rage::CDynamicEntity pointer. + +**Exemple Usage:** +```lua +number = memory.ptr_to_handle(mem_addr) +``` + +### `allocate(size)` + +- **Parameters:** + - `size` (integer): The number of bytes to allocate on the heap. + +- **Returns:** + - `pointer`: A pointer to the newly allocated memory. + +**Exemple Usage:** +```lua +pointer = memory.allocate(size) +``` + +### `free(ptr)` + +- **Parameters:** + - `ptr` (pointer): The pointer that must be freed. + +**Exemple Usage:** +```lua +memory.free(ptr) +``` + + diff --git a/docs/lua/tables/menu_event.md b/docs/lua/tables/menu_event.md new file mode 100644 index 00000000..08cde123 --- /dev/null +++ b/docs/lua/tables/menu_event.md @@ -0,0 +1,81 @@ +# Table: menu_event + +Table containing all possible events to which you can respond. + +## Fields (6) + +### `PlayerLeave` + +Event that is triggered when a player leave the game session. +**Exemple Usage:** +```lua +event.register_handler(menu_event.PlayerLeave, function (player_name) + log.info(player_name) +end) +``` + +- Type: `integer` + +### `PlayerJoin` + +Event that is triggered when a player join the game session. +**Exemple Usage:** +```lua +event.register_handler(menu_event.PlayerJoin, function (player_name, player_id) + log.info(player_name) + log.info(player_id) +end) +``` + +- Type: `integer` + +### `PlayerMgrInit` + +Event that is triggered when the player manager initialize. Usually called when we are joining a session. +**Exemple Usage:** +```lua +event.register_handler(menu_event.PlayerMgrInit, function () + log.info("Player manager inited, we just joined a session.") +end) +``` + +- Type: `integer` + +### `PlayerMgrShutdown` + +Event that is triggered when the player manager shutdown. Usually called when we are leaving a session. +**Exemple Usage:** +```lua +event.register_handler(menu_event.PlayerMgrShutdown, function () + log.info("Player manager inited, we just joined a session.") +end) +``` + +- Type: `integer` + +### `ChatMessageReceived` + +Event that is triggered when we receive a in-game chat message. +**Exemple Usage:** +```lua +event.register_handler(menu_event.ChatMessageReceived, function (player_id, chat_message) + log.info(player_id) + log.info(chat_message) +end) +``` + +- Type: `integer` + +### `ScriptedGameEventReceived` + +Event that is triggered when we receive a scripted game event. +**Exemple Usage:** +```lua +event.register_handler(menu_event.ScriptedGameEventReceived, function (player_id, script_event_args) + log.info(player_id) + log.info(script_event_args) +end) +``` + +- Type: `integer` + diff --git a/docs/lua/tables/network.md b/docs/lua/tables/network.md new file mode 100644 index 00000000..9fe160c5 --- /dev/null +++ b/docs/lua/tables/network.md @@ -0,0 +1,132 @@ +# Table: network + +Table containing helper functions for network related features. + +## Functions (10) + +### `trigger_script_event(bitset, _args)` + +Call trigger_script_event (TSE) + +- **Parameters:** + - `bitset` (integer) + - `_args` (table) + +**Exemple Usage:** +```lua +network.trigger_script_event(bitset, _args) +``` + +### `give_pickup_rewards(player, reward)` + +Give the given pickup reward to the given player. + +- **Parameters:** + - `player` (integer): Index of the player. + - `reward` (integer): Index of the reward pickup. + +**Exemple Usage:** +```lua +network.give_pickup_rewards(player, reward) +``` + +### `set_player_coords(player_idx, x, y, z)` + +Teleport the given player to the given position. + +- **Parameters:** + - `player_idx` (integer): Index of the player. + - `x` (float): New x position. + - `y` (float): New y position. + - `z` (float): New z position. + +**Exemple Usage:** +```lua +network.set_player_coords(player_idx, x, y, z) +``` + +### `set_all_player_coords(x, y, z)` + +Teleport all players to the given position. + +- **Parameters:** + - `x` (float): New x position. + - `y` (float): New y position. + - `z` (float): New z position. + +**Exemple Usage:** +```lua +network.set_all_player_coords(x, y, z) +``` + +### `get_selected_player()` + +- **Returns:** + - `integer`: Returns the index of the currently selected player in the GUI. + +**Exemple Usage:** +```lua +integer = network.get_selected_player() +``` + +### `get_selected_database_player_rockstar_id()` + +- **Returns:** + - `integer`: Returns the rockstar id of the currently selected player in the GUI. + +**Exemple Usage:** +```lua +integer = network.get_selected_database_player_rockstar_id() +``` + +### `flag_player_as_modder(player_idx)` + +Flags the given player as a modder in our local database. + +- **Parameters:** + - `player_idx` (integer): Index of the player. + +**Exemple Usage:** +```lua +network.flag_player_as_modder(player_idx) +``` + +### `is_player_flagged_as_modder(player_idx)` + +- **Parameters:** + - `player_idx` (integer): Index of the player. + +- **Returns:** + - `boolean`: Returns true if the given player is flagged as a modder. + +**Exemple Usage:** +```lua +boolean = network.is_player_flagged_as_modder(player_idx) +``` + +### `force_script_host(script_name)` + +Try to force ourself to be host for the given GTA Script. + +- **Parameters:** + - `script_name` (string): Name of the script + +**Exemple Usage:** +```lua +network.force_script_host(script_name) +``` + +### `send_chat_message(msg, team_only)` + +Sends a message to the in game chat. + +- **Parameters:** + - `msg` (string): Message to be sent. + - `team_only` (boolean): Should be true if the msg should only be sent to our team. + +**Exemple Usage:** +```lua +network.send_chat_message(msg, team_only) +``` + + diff --git a/docs/lua/tables/script.md b/docs/lua/tables/script.md new file mode 100644 index 00000000..7184c730 --- /dev/null +++ b/docs/lua/tables/script.md @@ -0,0 +1,53 @@ +# Table: script + +Table containing helper functions related to gta scripts. + +## Functions (4) + +### `register_looped(name, func)` + +Registers a function that will be looped as a gta script. + +- **Parameters:** + - `name` (string): name of your new looped script + - `func` (function): function that will be executed in a forever loop. + +**Exemple Usage:** +```lua +script.register_looped(name, func) +``` + +### `run_in_fiber(func)` + +Executes a function inside the fiber pool, you can call natives inside it. + +- **Parameters:** + - `func` (function): function that will be executed once in the fiber pool, you can call natives inside it. + +**Exemple Usage:** +```lua +script.run_in_fiber(func) +``` + +### `yield()` + +Yield execution. + +**Exemple Usage:** +```lua +script.yield() +``` + +### `sleep(ms)` + +Sleep for the given amount of time, time is in milliseconds. + +- **Parameters:** + - `ms` (integer): The amount of time in milliseconds that we will sleep for. + +**Exemple Usage:** +```lua +script.sleep(ms) +``` + + diff --git a/docs/lua/tables/tunables.md b/docs/lua/tables/tunables.md new file mode 100644 index 00000000..96a7b282 --- /dev/null +++ b/docs/lua/tables/tunables.md @@ -0,0 +1,79 @@ +# Table: tunables + +Table for manipulating gta tunables. + +## Functions (6) + +### `get_int(tunable_name)` + +- **Parameters:** + - `tunable_name` (string): The name of the tunable. + +- **Returns:** + - `integer`: The value of the given tunable. + +**Exemple Usage:** +```lua +integer = tunables.get_int(tunable_name) +``` + +### `get_float(tunable_name)` + +- **Parameters:** + - `tunable_name` (string): The name of the tunable. + +- **Returns:** + - `float`: The value of the given tunable. + +**Exemple Usage:** +```lua +float = tunables.get_float(tunable_name) +``` + +### `get_bool(tunable_name)` + +- **Parameters:** + - `tunable_name` (string): The name of the tunable. + +- **Returns:** + - `boolean`: The value of the given tunable. + +**Exemple Usage:** +```lua +boolean = tunables.get_bool(tunable_name) +``` + +### `set_int(tunable_name, val)` + +- **Parameters:** + - `tunable_name` (string): The name of the tunable. + - `val` (integer): The new value of the given tunable. + +**Exemple Usage:** +```lua +tunables.set_int(tunable_name, val) +``` + +### `set_float(tunable_name, val)` + +- **Parameters:** + - `tunable_name` (string): The name of the tunable. + - `val` (float): The new value of the given tunable. + +**Exemple Usage:** +```lua +tunables.set_float(tunable_name, val) +``` + +### `set_bool(tunable_name, val)` + +- **Parameters:** + - `tunable_name` (string): The name of the tunable. + - `val` (boolean): The new value of the given tunable. + +**Exemple Usage:** +```lua +tunables.set_bool(tunable_name, val) +``` + + diff --git a/src/core/data/menu_event.hpp b/src/core/data/menu_event.hpp new file mode 100644 index 00000000..9661a823 --- /dev/null +++ b/src/core/data/menu_event.hpp @@ -0,0 +1,11 @@ +#pragma once + +enum class menu_event +{ + PlayerLeave, + PlayerJoin, + PlayerMgrInit, + PlayerMgrShutdown, + ChatMessageReceived, + ScriptedGameEventReceived, +}; \ No newline at end of file diff --git a/src/hooks/player_management/assign_physical_index.cpp b/src/hooks/player_management/assign_physical_index.cpp index 8ec4591e..2b6d1605 100644 --- a/src/hooks/player_management/assign_physical_index.cpp +++ b/src/hooks/player_management/assign_physical_index.cpp @@ -26,7 +26,7 @@ namespace big if (net_player_data) { - g_lua_manager->trigger_event<"player_leave">(net_player_data->m_name); + g_lua_manager->trigger_event(net_player_data->m_name); if (g.notifications.player_leave.log) LOG(INFO) << "Player left '" << net_player_data->m_name << "' freeing slot #" << (int)player->m_player_id @@ -64,7 +64,7 @@ namespace big } } - g_lua_manager->trigger_event<"player_join">(net_player_data->m_name, player->m_player_id); + g_lua_manager->trigger_event(net_player_data->m_name, player->m_player_id); if (g.notifications.player_join.above_map && *g_pointers->m_gta.m_is_session_started) // prevent loading screen spam notify::player_joined(player); diff --git a/src/hooks/player_management/network_player_mgr.cpp b/src/hooks/player_management/network_player_mgr.cpp index d6865ec1..161eb9af 100644 --- a/src/hooks/player_management/network_player_mgr.cpp +++ b/src/hooks/player_management/network_player_mgr.cpp @@ -2,6 +2,7 @@ #include "lua/lua_manager.hpp" #include "pointers.hpp" #include "services/players/player_service.hpp" +#include "core/data/menu_event.hpp" #include @@ -17,7 +18,7 @@ namespace big g_hooking->get_original()(_this, a2, a3, a4); g_player_service->player_join(_this->m_local_net_player); - g_lua_manager->trigger_event<"player_mgr_init">(); + g_lua_manager->trigger_event(); } void hooks::network_player_mgr_shutdown(CNetworkPlayerMgr* _this) @@ -31,6 +32,6 @@ namespace big g_notification_service->push("NETWORK_PLAYER_MGR"_T.data(), "NETWORK_PLAYER_MGR_DESTROY"_T.data()); g_hooking->get_original()(_this); - g_lua_manager->trigger_event<"player_mgr_shutdown">(); + g_lua_manager->trigger_event(); } } diff --git a/src/hooks/protections/receive_net_message.cpp b/src/hooks/protections/receive_net_message.cpp index 43f37ec7..57c67cb6 100644 --- a/src/hooks/protections/receive_net_message.cpp +++ b/src/hooks/protections/receive_net_message.cpp @@ -134,7 +134,7 @@ namespace big if (g.session.chat_commands && message[0] == g.session.chat_command_prefix) command::process(std::string(message + 1), std::make_shared(player)); else - g_lua_manager->trigger_event<"chat_message_received">(player->id(), message); + g_lua_manager->trigger_event(player->id(), message); if (msgType == rage::eNetMessage::MsgTextMessage && g_pointers->m_gta.m_chat_data && player->get_net_data()) { diff --git a/src/hooks/protections/script_event_handler.cpp b/src/hooks/protections/script_event_handler.cpp index b4860de8..d84cad31 100644 --- a/src/hooks/protections/script_event_handler.cpp +++ b/src/hooks/protections/script_event_handler.cpp @@ -67,7 +67,7 @@ namespace big for (int i = 0; i < scripted_game_event->m_args_size; i++) script_event_args.push_back(args[i]); - auto event_ret = g_lua_manager->trigger_event<"script_event", bool>((int)player->m_player_id, script_event_args); + auto event_ret = g_lua_manager->trigger_event((int)player->m_player_id, script_event_args); if (event_ret.has_value()) return true; // don't care, block event if any bool is returned } diff --git a/src/lua/bindings/command.hpp b/src/lua/bindings/command.hpp index d970e080..f8c21277 100644 --- a/src/lua/bindings/command.hpp +++ b/src/lua/bindings/command.hpp @@ -5,25 +5,42 @@ namespace lua::command { + // Lua API: Table + // Name: command + // Table for calling menu commands. + + // Lua API: Function + // Table: command + // Name: call + // Param: command_name: string: The name of the command that will be called. + // Param: _args: table: Optional. List of arguments for the command. + // Call a menu command. static void call(const std::string& command_name, std::optional _args) { - auto args = convert_sequence(_args.value_or(sol::table())); + const auto args = convert_sequence(_args.value_or(sol::table())); - auto command = big::command::get(rage::joaat(command_name)); + const auto command = big::command::get(rage::joaat(command_name)); if (command) command->call(args, {}); } + // Lua API: Function + // Table: command + // Name: call_player + // Param: player_idx: integer: Index of the player on which the menu command will be executed. + // Param: command_name: string: The name of the command that will be called. + // Param: _args: table: Optional. List of arguments for the command. + // Call a menu command on a given player. static void call_player(int player_idx, const std::string& command_name, std::optional _args) { - auto args = convert_sequence(_args.value_or(sol::table())); + const auto args = convert_sequence(_args.value_or(sol::table())); - auto command = (big::player_command*)big::command::get(rage::joaat(command_name)); + const auto command = (big::player_command*)big::command::get(rage::joaat(command_name)); if (command) { - auto player = big::g_player_service->get_by_id(player_idx); + const auto player = big::g_player_service->get_by_id(player_idx); if (player) { diff --git a/src/lua/bindings/event.hpp b/src/lua/bindings/event.hpp index b3668e25..abdddd0a 100644 --- a/src/lua/bindings/event.hpp +++ b/src/lua/bindings/event.hpp @@ -5,17 +5,109 @@ namespace lua::event { - static void register_handler(const std::string& name, sol::function func, sol::this_state state) - { - auto module = sol::state_view(state)["!this"].get(); + // Lua API: Table + // Name: menu_event + // Table containing all possible events to which you can respond. - auto hash = rage::joaat(name); - module->m_event_callbacks.emplace(hash, std::vector()); - module->m_event_callbacks[hash].push_back(func); + // Lua API: Field + // Table: menu_event + // Field: PlayerLeave: integer + // Event that is triggered when a player leave the game session. + // **Exemple Usage:** + // ```lua + // event.register_handler(menu_event.PlayerLeave, function (player_name) + // log.info(player_name) + // end) + // ``` + + // Lua API: Field + // Table: menu_event + // Field: PlayerJoin: integer + // Event that is triggered when a player join the game session. + // **Exemple Usage:** + // ```lua + // event.register_handler(menu_event.PlayerJoin, function (player_name, player_id) + // log.info(player_name) + // log.info(player_id) + // end) + // ``` + + // Lua API: Field + // Table: menu_event + // Field: PlayerMgrInit: integer + // Event that is triggered when the player manager initialize. Usually called when we are joining a session. + // **Exemple Usage:** + // ```lua + // event.register_handler(menu_event.PlayerMgrInit, function () + // log.info("Player manager inited, we just joined a session.") + // end) + // ``` + + // Lua API: Field + // Table: menu_event + // Field: PlayerMgrShutdown: integer + // Event that is triggered when the player manager shutdown. Usually called when we are leaving a session. + // **Exemple Usage:** + // ```lua + // event.register_handler(menu_event.PlayerMgrShutdown, function () + // log.info("Player manager inited, we just joined a session.") + // end) + // ``` + + // Lua API: Field + // Table: menu_event + // Field: ChatMessageReceived: integer + // Event that is triggered when we receive a in-game chat message. + // **Exemple Usage:** + // ```lua + // event.register_handler(menu_event.ChatMessageReceived, function (player_id, chat_message) + // log.info(player_id) + // log.info(chat_message) + // end) + // ``` + + // Lua API: Field + // Table: menu_event + // Field: ScriptedGameEventReceived: integer + // Event that is triggered when we receive a scripted game event. + // **Exemple Usage:** + // ```lua + // event.register_handler(menu_event.ScriptedGameEventReceived, function (player_id, script_event_args) + // log.info(player_id) + // log.info(script_event_args) + // end) + // ``` + + // Lua API: Table + // Name: event + // Table for responding to various events. The list of events is available in the menu_event table. + + // Lua API: Function + // Table: event + // Name: register_handler + // Param: menu_event: menu_event: The menu_event that we want to respond to. + // Param: func: function: The function that will be called. + // Register a function that will be called each time the corresponding menu_event is triggered. + static void register_handler(const menu_event& menu_event, sol::function func, sol::this_state state) + { + const auto module = sol::state_view(state)["!this"].get(); + + module->m_event_callbacks[menu_event].push_back(func); } static void bind(sol::state& state) { + state.new_enum("menu_event", + { + {"PlayerLeave", menu_event::PlayerLeave}, + {"PlayerJoin", menu_event::PlayerJoin}, + {"PlayerMgrInit", menu_event::PlayerMgrInit}, + {"PlayerMgrShutdown", menu_event::PlayerMgrShutdown}, + {"ChatMessageReceived", menu_event::ChatMessageReceived}, + {"ScriptedGameEventReceived", menu_event::ScriptedGameEventReceived}, + }); + + auto ns = state["event"].get_or_create(); ns["register_handler"] = register_handler; // TODO: triggering events through script? diff --git a/src/lua/bindings/global_table.hpp b/src/lua/bindings/global_table.hpp new file mode 100644 index 00000000..471f7812 --- /dev/null +++ b/src/lua/bindings/global_table.hpp @@ -0,0 +1,20 @@ +#pragma once +#include "lua/sol.hpp" + +namespace lua::global_table +{ + // Lua API: Table + // Name: Global Table + // Custom fields, functions, etc added to The Lua [Global Table](https://www.lua.org/pil/15.4.html). + + // Lua API: Function + // Table: Global Table + // Name: joaat + // Param: str: string: The string that needs to be joaat hashed. + // Returns: integer: The joaat hashed input string. + + static void bind(sol::state& state) + { + state["joaat"] = rage::joaat; + } +} \ No newline at end of file diff --git a/src/lua/bindings/globals.hpp b/src/lua/bindings/globals.hpp index 77d53371..e0a2e889 100644 --- a/src/lua/bindings/globals.hpp +++ b/src/lua/bindings/globals.hpp @@ -4,36 +4,82 @@ namespace lua::globals { + // Lua API: Table + // Name: globals + // Table containing functions for manipulating gta script globals. + + // Lua API: Function + // Table: globals + // Name: get_int + // Param: global: integer: index of the global + // Returns: integer: value of the global + // Retrieves an int global value. static int get_int(int global) { return *big::script_global(global).as(); } + // Lua API: Function + // Table: globals + // Name: get_float + // Param: global: integer: index of the global + // Returns: float: value of the global + // Retrieves a float global value. static int get_float(int global) { return *big::script_global(global).as(); } + // Lua API: Function + // Table: globals + // Name: get_string + // Param: global: integer: index of the global + // Returns: string: value of the global + // Retrieves a string global value. static std::string get_string(int global) { return std::string(big::script_global(global).as()); } + // Lua API: Function + // Table: globals + // Name: set_int + // Param: global: integer: index of the global + // Param: val: integer: new value for the global + // Sets an int global value. static void set_int(int global, int val) { *big::script_global(global).as() = val; } + // Lua API: Function + // Table: globals + // Name: set_float + // Param: global: integer: index of the global + // Param: val: float: new value for the global + // Sets a float global value. static void set_float(int global, float val) { *big::script_global(global).as() = val; } + // Lua API: Function + // Table: globals + // Name: set_string + // Param: global: integer: index of the global + // Param: str: string: new value for the global + // Sets a string global value. static void set_string(int global, const std::string& str, int max_length) { strncpy(big::script_global(global).as(), str.data(), max_length); } + // Lua API: Function + // Table: globals + // Name: get_pointer + // Param: global: integer: index of the global + // Returns: pointer: value of the global + // Retrieves a pointer global. static memory::pointer get_pointer(int global) { return memory::pointer((uint64_t)big::script_global(global).as()); diff --git a/src/lua/bindings/gui.hpp b/src/lua/bindings/gui.hpp index 027d0c36..8bcaa272 100644 --- a/src/lua/bindings/gui.hpp +++ b/src/lua/bindings/gui.hpp @@ -22,6 +22,9 @@ namespace lua::gui module->m_gui[hash].push_back(std::move(element)); } + // Lua API: Class + // Name: tab + // Class for representing a tab within the GUI. class tab { rage::joaat_t m_tab_hash; @@ -32,6 +35,12 @@ namespace lua::gui { } + // Lua API: Function + // Class: tab + // Name: add_button + // Param: name: string: Text written inside the button. + // Param: callback: function: function that will be called when the button is clicked. + // Add a button to the gui tab. std::shared_ptr add_button(const std::string& name, sol::function callback, sol::this_state state) { auto element = std::make_shared(name, callback); @@ -39,6 +48,12 @@ namespace lua::gui return element; } + // Lua API: Function + // Class: tab + // Name: add_text + // Param: name: string: Text that will be written. + // Returns: text: The text object instance. + // Add text to the gui tab. std::shared_ptr add_text(const std::string& name, sol::this_state state) { auto element = std::make_shared(name); @@ -46,6 +61,12 @@ namespace lua::gui return element; } + // Lua API: Function + // Class: tab + // Name: add_checkbox + // Param: name: string: Text that will be written next to the checkbox. + // Returns: checkbox: The checkbox object instance. + // Add a checkbox widget to the gui tab. std::shared_ptr add_checkbox(const std::string& name, sol::this_state state) { auto element = std::make_shared(name); @@ -53,6 +74,11 @@ namespace lua::gui return element; } + // Lua API: Function + // Class: tab + // Name: add_sameline + // Returns: sameline: The sameline object instance. + // Add a ImGui::SameLine. std::shared_ptr add_sameline(sol::this_state state) { auto element = std::make_shared(); @@ -60,6 +86,11 @@ namespace lua::gui return element; } + // Lua API: Function + // Class: tab + // Name: add_separator + // Returns: separator: The separator object instance. + // Add a ImGui::Separator. std::shared_ptr add_separator(sol::this_state state) { auto element = std::make_shared(); @@ -67,6 +98,12 @@ namespace lua::gui return element; } + // Lua API: Function + // Class: tab + // Name: add_input_int + // Param: name: string: Text that will be written next to the input field. + // Returns: input_int: The input_int object instance. + // Add a ImGui::InputInt. std::shared_ptr add_input_int(const std::string& name, sol::this_state state) { auto element = std::make_shared(name); @@ -74,6 +111,12 @@ namespace lua::gui return element; } + // Lua API: Function + // Class: tab + // Name: add_input_float + // Param: name: string: Text that will be written next to the input field. + // Returns: input_float: The input_float object instance. + // Add a ImGui::InputFloat. std::shared_ptr add_input_float(const std::string& name, sol::this_state state) { auto element = std::make_shared(name); @@ -81,6 +124,12 @@ namespace lua::gui return element; } + // Lua API: Function + // Class: tab + // Name: add_input_string + // Param: name: string: Text that will be written next to the input field. + // Returns: input_string: The input_string object instance. + // Add a ImGui::InputText. std::shared_ptr add_input_string(const std::string& name, sol::this_state state) { auto element = std::make_shared(name); @@ -89,26 +138,57 @@ namespace lua::gui } }; + // Lua API: Table + // Name: gui + // Table containing functions for modifying the menu GUI. + + // Lua API: Function + // Table: gui + // Name: get_tab + // Param: tab_name: string: Name of the tab to get. + // Returns: tab: A tab instance which corresponds to the tab in the GUI. static tab get_tab(const std::string& tab_name) { return tab(rage::joaat(tab_name)); } + // Lua API: Function + // Table: gui + // Name: show_message + // Param: title: string + // Param: message: string + // Shows a message to the user with the given title and message. static void show_message(const std::string& title, const std::string& message) { big::g_notification_service->push(title, message); } + // Lua API: Function + // Table: gui + // Name: show_warning + // Param: title: string + // Param: message: string + // Shows a warning to the user with the given title and message. static void show_warning(const std::string& title, const std::string& message) { big::g_notification_service->push_warning(title, message); } + // Lua API: Function + // Table: gui + // Name: show_error + // Param: title: string + // Param: message: string + // Shows an error to the user with the given title and message. static void show_error(const std::string& title, const std::string& message) { big::g_notification_service->push_error(title, message); } + // Lua API: Function + // Table: gui + // Name: is_open + // Returns: bool: Returns true if the GUI is open. bool is_open(); static void bind(sol::state& state) diff --git a/src/lua/bindings/gui/base_text_element.hpp b/src/lua/bindings/gui/base_text_element.hpp index ec3290b1..94c8761c 100644 --- a/src/lua/bindings/gui/base_text_element.hpp +++ b/src/lua/bindings/gui/base_text_element.hpp @@ -3,6 +3,10 @@ namespace lua::gui { + // Lua API: Class + // Name: base_text_element + // Class representing a gui text element. + class base_text_element : public gui_element { protected: @@ -11,7 +15,16 @@ namespace lua::gui public: base_text_element(std::string text); + // Lua API: Function + // Class: base_text_element + // Name: set_text + // Param: new_text: string: The new text for that gui text element. void set_text(std::string new_text); + + // Lua API: Function + // Class: base_text_element + // Name: get_text + // Returns: string: Returns the current text for that gui text element. std::string get_text(); }; } \ No newline at end of file diff --git a/src/lua/bindings/gui/button.hpp b/src/lua/bindings/gui/button.hpp index 142b7c63..b61046f2 100644 --- a/src/lua/bindings/gui/button.hpp +++ b/src/lua/bindings/gui/button.hpp @@ -4,6 +4,10 @@ namespace lua::gui { + // Lua API: Class + // Name: button + // Inherit: base_text_element + // Class representing a gui button. class button : public base_text_element { sol::function m_callback; diff --git a/src/lua/bindings/gui/checkbox.hpp b/src/lua/bindings/gui/checkbox.hpp index c8d1d922..ac033620 100644 --- a/src/lua/bindings/gui/checkbox.hpp +++ b/src/lua/bindings/gui/checkbox.hpp @@ -3,6 +3,10 @@ namespace lua::gui { + // Lua API: Class + // Name: checkbox + // Inherit: base_text_element + // Class representing a gui checkbox. class checkbox : public base_text_element { bool m_enabled = false; @@ -12,7 +16,16 @@ namespace lua::gui void draw() override; + // Lua API: Function + // Class: checkbox + // Name: is_enabled + // Returns: boolean: Is the checkbox checked? bool is_enabled(); + + // Lua API: Function + // Class: checkbox + // Name: set_enabled + // Param: enabled: boolean: The desired enabled state of the checkbox. void set_enabled(bool enabled); }; } \ No newline at end of file diff --git a/src/lua/bindings/gui/input_float.hpp b/src/lua/bindings/gui/input_float.hpp index a026034c..5b60b9d8 100644 --- a/src/lua/bindings/gui/input_float.hpp +++ b/src/lua/bindings/gui/input_float.hpp @@ -3,6 +3,10 @@ namespace lua::gui { + // Lua API: Class + // Name: input_float + // Inherit: base_text_element + // Class for representing an input field for editing a float value within the GUI. class input_float : public base_text_element { bool m_enabled = false; @@ -13,7 +17,16 @@ namespace lua::gui void draw() override; + // Lua API: Function + // Class: input_float + // Name: get_value + // Returns: float: Get the value currently written inside the input field. int get_value(); + + // Lua API: Function + // Class: input_float + // Name: set_value + // Param: val: float: Set the value currently written inside the input field. void set_value(float val); }; } \ No newline at end of file diff --git a/src/lua/bindings/gui/input_int.hpp b/src/lua/bindings/gui/input_int.hpp index 1b0543fe..c6d783bb 100644 --- a/src/lua/bindings/gui/input_int.hpp +++ b/src/lua/bindings/gui/input_int.hpp @@ -3,6 +3,10 @@ namespace lua::gui { + // Lua API: Class + // Name: input_int + // Inherit: base_text_element + // Class for representing an input field for editing an integer value within the GUI. class input_int : public base_text_element { bool m_enabled = false; @@ -13,7 +17,16 @@ namespace lua::gui void draw() override; + // Lua API: Function + // Class: input_int + // Name: get_value + // Returns: integer: Get the value currently written inside the input field. int get_value(); + + // Lua API: Function + // Class: input_int + // Name: set_value + // Param: val: integer: Set the value currently written inside the input field. void set_value(int val); }; } \ No newline at end of file diff --git a/src/lua/bindings/gui/input_string.hpp b/src/lua/bindings/gui/input_string.hpp index d9cf1727..7f9dd023 100644 --- a/src/lua/bindings/gui/input_string.hpp +++ b/src/lua/bindings/gui/input_string.hpp @@ -3,6 +3,10 @@ namespace lua::gui { + // Lua API: Class + // Name: input_string + // Inherit: base_text_element + // Class for representing an input field for editing a string value within the GUI. class input_string : public base_text_element { bool m_enabled = false; @@ -13,7 +17,16 @@ namespace lua::gui void draw() override; + // Lua API: Function + // Class: input_string + // Name: get_value + // Returns: string: Get the value currently written inside the input field. std::string get_value(); + + // Lua API: Function + // Class: input_string + // Name: set_value + // Param: val: string: Set the value currently written inside the input field. void set_value(std::string val); }; } \ No newline at end of file diff --git a/src/lua/bindings/gui/sameline.hpp b/src/lua/bindings/gui/sameline.hpp index ea20b047..e396f3ea 100644 --- a/src/lua/bindings/gui/sameline.hpp +++ b/src/lua/bindings/gui/sameline.hpp @@ -3,6 +3,9 @@ namespace lua::gui { + // Lua API: Class + // Name: sameline + // Class for ImGui::SameLine() - Puts a sameline between widgets or groups to layout them horizontally. class sameline : public gui_element { public: diff --git a/src/lua/bindings/gui/separator.hpp b/src/lua/bindings/gui/separator.hpp index 5f5ead6a..f22becf8 100644 --- a/src/lua/bindings/gui/separator.hpp +++ b/src/lua/bindings/gui/separator.hpp @@ -3,6 +3,9 @@ namespace lua::gui { + // Lua API: Class + // Name: separator + // Class for ImGui::Separator() - separator, generally horizontal. Inside a menu bar or in horizontal layout mode, this becomes a vertical separator. class separator : public gui_element { public: diff --git a/src/lua/bindings/gui/text.hpp b/src/lua/bindings/gui/text.hpp index f097be3f..59407ab7 100644 --- a/src/lua/bindings/gui/text.hpp +++ b/src/lua/bindings/gui/text.hpp @@ -4,6 +4,10 @@ namespace lua::gui { + // Lua API: Class + // Name: text + // Inherit: base_text_element + // Class representing an imgui text element. class text : public base_text_element { ImFont* m_font = nullptr; @@ -12,6 +16,11 @@ namespace lua::gui text(std::string text); void draw() override; + + // Lua API: Function + // Class: text + // Name: set_font + // Param: font: string: The new font name for that imgui text element. void set_font(std::string font); }; } \ No newline at end of file diff --git a/src/lua/bindings/locals.hpp b/src/lua/bindings/locals.hpp index c768c2b9..4e14553f 100644 --- a/src/lua/bindings/locals.hpp +++ b/src/lua/bindings/locals.hpp @@ -5,6 +5,10 @@ namespace lua::locals { + // Lua API: Table + // Name: locals + // Table for manipulating GTA scripts locals. + template inline T get(const std::string& script, int index) { @@ -16,26 +20,56 @@ namespace lua::locals return &null; } + // Lua API: Function + // Table: locals + // Name: get_int + // Param: script: string: The name of the script + // Param: index: index: Index of the script local. + // Returns: integer: The value of the given local. static int get_int(const std::string& script, int index) { return *get(script, index); } + // Lua API: Function + // Table: locals + // Name: get_float + // Param: script: string: The name of the script + // Param: index: index: Index of the script local. + // Returns: float: The value of the given local. static int get_float(const std::string& script, int index) { return *get(script, index); } - + + // Lua API: Function + // Table: locals + // Name: set_int + // Param: script: string: The name of the script + // Param: index: index: Index of the script local. + // Param: val: integer: The new value of the given local. static void set_int(const std::string& script, int index, int val) { *get(script, index) = val; } + // Lua API: Function + // Table: locals + // Name: set_float + // Param: script: string: The name of the script + // Param: index: index: Index of the script local. + // Param: val: float: The new value of the given local. static void set_float(const std::string& script, int index, float val) { *get(script, index) = val; } + // Lua API: Function + // Table: locals + // Name: get_pointer + // Param: script: string: The name of the script + // Param: index: index: Index of the script local. + // Returns: pointer: The pointer to the given local. static memory::pointer get_pointer(const std::string& script, int index) { return memory::pointer((uint64_t)get(script, index)); diff --git a/src/lua/bindings/log.hpp b/src/lua/bindings/log.hpp index aeeb4917..ae1b1970 100644 --- a/src/lua/bindings/log.hpp +++ b/src/lua/bindings/log.hpp @@ -1,17 +1,37 @@ #pragma once +#include "lua/sol.hpp" namespace lua::log { + // Lua API: Table + // Name: log + // Table containing functions for printing to console / log file. + + // Lua API: Function + // Table: log + // Name: info + // Param: data: string + // Logs an informational message. static void info(const std::string& data, sol::this_state state) { LOG(INFO) << sol::state_view(state)["!module_name"].get() << ": " << data; } + // Lua API: Function + // Table: log + // Name: warning + // Param: data: string + // Logs a warning message. static void warning(const std::string& data, sol::this_state state) { LOG(WARNING) << sol::state_view(state)["!module_name"].get() << ": " << data; } + // Lua API: Function + // Table: log + // Name: debug + // Param: data: string + // Logs a debug message. static void debug(const std::string& data, sol::this_state state) { LOG(VERBOSE) << sol::state_view(state)["!module_name"].get() << ": " << data; diff --git a/src/lua/bindings/memory.hpp b/src/lua/bindings/memory.hpp index 397af19e..136a3c62 100644 --- a/src/lua/bindings/memory.hpp +++ b/src/lua/bindings/memory.hpp @@ -6,12 +6,21 @@ namespace lua::memory { + // Lua API: Class + // Name: pointer + // Class representing a 64-bit memory address. + struct pointer { private: std::uint64_t m_address; public: + + // Lua API: Constructor + // Class: pointer + // Param: address: integer: Address + // Returns a memory instance, with the given address. explicit pointer(std::uint64_t address) : m_address(address) { @@ -22,43 +31,167 @@ namespace lua::memory { } + // Lua API: Function + // Class: pointer + // Name: add + // Param: offset: integer: offset + // Returns: pointer: new pointer object. + // Adds an offset to the current memory address and returns a new pointer object. pointer add(uint64_t offset) { return pointer(m_address + offset); } + // Lua API: Function + // Class: pointer + // Name: sub + // Param: offset: integer: offset + // Returns: pointer: new pointer object. + // Subs an offset to the current memory address and returns a new pointer object. pointer sub(uint64_t offset) { return pointer(m_address - offset); } + // Lua API: Function + // Class: pointer + // Name: rip + // Param: offset: integer: offset + // Returns: pointer: new pointer object. + // Rips the current memory address and returns a new pointer object. pointer rip() { return add(*(std::int32_t*)m_address).add(4); } + // Lua API: Function + // Class: pointer + // Name: get_byte + // Returns: number: the value stored at the memory address as the specified type. + // Retrieves the value stored at the memory address as the specified type. + + // Lua API: Function + // Class: pointer + // Name: get_word + // Returns: number: the value stored at the memory address as the specified type. + // Retrieves the value stored at the memory address as the specified type. + + // Lua API: Function + // Class: pointer + // Name: get_dword + // Returns: number: the value stored at the memory address as the specified type. + // Retrieves the value stored at the memory address as the specified type. + + // Lua API: Function + // Class: pointer + // Name: get_float + // Returns: float: the value stored at the memory address as the specified type. + // Retrieves the value stored at the memory address as the specified type. + + // Lua API: Function + // Class: pointer + // Name: get_qword + // Returns: number: the value stored at the memory address as the specified type. + // Retrieves the value stored at the memory address as the specified type. + template T get() { return *(T*)m_address; } + // Lua API: Function + // Class: pointer + // Name: set_byte + // Param: value: number: new value. + // Sets the value at the memory address to the specified value of the given type. + + // Lua API: Function + // Class: pointer + // Name: set_word + // Param: value: number: new value. + // Sets the value at the memory address to the specified value of the given type. + + // Lua API: Function + // Class: pointer + // Name: set_dword + // Param: value: number: new value. + // Sets the value at the memory address to the specified value of the given type. + + // Lua API: Function + // Class: pointer + // Name: set_float + // Param: value: float: new value. + // Sets the value at the memory address to the specified value of the given type. + + // Lua API: Function + // Class: pointer + // Name: set_qword + // Param: value: number: new value. + // Sets the value at the memory address to the specified value of the given type. + template void set(T value) { *(T*)m_address = value; } + // Lua API: Function + // Class: pointer + // Name: get_string + // Returns: string: the value stored at the memory address as the specified type. + // Retrieves the value stored at the memory address as the specified type. std::string get_string() { return std::string((char*)m_address); } + // Lua API: Function + // Class: pointer + // Name: set_string + // Param: value: string: new value. + // Sets the value at the memory address to the specified value of the given type. void set_string(const std::string& string, int max_length) { strncpy((char*)m_address, string.data(), max_length); } + // Lua API: Function + // Class: pointer + // Name: patch_byte + // Param: value: number: new value. + // Returns: lua_patch: memory patch instance for modifying the value at the memory address with the specified value. Can call apply / restore on the object. + // Creates a memory patch for modifying the value at the memory address with the specified value. + // The modified value is applied when you call the apply function on the lua_patch object. + // The original value is restored when you call the restore function on the lua_patch object. + + // Lua API: Function + // Class: pointer + // Name: patch_word + // Param: value: number: new value. + // Returns: lua_patch: memory patch instance for modifying the value at the memory address with the specified value. Can call apply / restore on the object. + // Creates a memory patch for modifying the value at the memory address with the specified value. + // The modified value is applied when you call the apply function on the lua_patch object. + // The original value is restored when you call the restore function on the lua_patch object. + + // Lua API: Function + // Class: pointer + // Name: patch_dword + // Param: value: number: new value. + // Returns: lua_patch: memory patch instance for modifying the value at the memory address with the specified value. Can call apply / restore on the object. + // Creates a memory patch for modifying the value at the memory address with the specified value. + // The modified value is applied when you call the apply function on the lua_patch object. + // The original value is restored when you call the restore function on the lua_patch object. + + // Lua API: Function + // Class: pointer + // Name: patch_qword + // Param: value: number: new value. + // Returns: lua_patch: memory patch instance for modifying the value at the memory address with the specified value. Can call apply / restore on the object. + // Creates a memory patch for modifying the value at the memory address with the specified value. + // The modified value is applied when you call the apply function on the lua_patch object. + // The original value is restored when you call the restore function on the lua_patch object. + template big::lua_patch* patch(T value, sol::this_state state) { @@ -69,31 +202,82 @@ namespace lua::memory return raw; } + // Lua API: Function + // Class: pointer + // Name: is_null + // Returns: boolean: Returns true if the address is null. bool is_null() { return m_address == 0; } + // Lua API: Function + // Class: pointer + // Name: is_valid + // Returns: boolean: Returns true if the address is not null. bool is_valid() { return !is_null(); } + // Lua API: Function + // Class: pointer + // Name: deref + // Returns: pointer: A new pointer object pointing to the value at that address. + // Dereferences the memory address and returns a new pointer object pointing to the value at that address. pointer deref() { return pointer(*(uint64_t*)m_address); } + // Lua API: Function + // Class: pointer + // Name: get_address + // Returns: number: The memory address stored in the pointer object as a number. + // Retrieves the memory address stored in the pointer object. uint64_t get_address() const { return m_address; } }; + // Lua API: Table + // Name: memory + // Table containing helper functions related to process memory. + + // Lua API: Function + // Table: memory + // Name: scan_pattern + // Param: pattern: string: byte pattern (IDA format) + // Returns: pointer: A pointer to the found address. + // Scans the specified memory pattern within the "GTA5.exe" module and returns a pointer to the found address. pointer scan_pattern(const std::string& pattern); + + // Lua API: Function + // Table: memory + // Name: handle_to_ptr + // Param: entity: number: script game entity handle + // Returns: pointer: A rage::CDynamicEntity pointer to the script game entity handle pointer handle_to_ptr(int entity); + + // Lua API: Function + // Table: memory + // Name: ptr_to_handle + // Param: mem_addr: pointer: A rage::CDynamicEntity pointer. + // Returns: number: The script game entity handle linked to the given rage::CDynamicEntity pointer. int ptr_to_handle(pointer mem_addr); + + // Lua API: Function + // Table: memory + // Name: allocate + // Param: size: integer: The number of bytes to allocate on the heap. + // Returns: pointer: A pointer to the newly allocated memory. pointer allocate(int size, sol::this_state state); + + // Lua API: Function + // Table: memory + // Name: free + // Param: ptr: pointer: The pointer that must be freed. void free(pointer ptr, sol::this_state state); static void bind(sol::state& state) diff --git a/src/lua/bindings/network.hpp b/src/lua/bindings/network.hpp index 3ec43990..7144bb56 100644 --- a/src/lua/bindings/network.hpp +++ b/src/lua/bindings/network.hpp @@ -20,15 +20,84 @@ inline std::vector convert_sequence(sol::table t) namespace lua::network { + // Lua API: Table + // Name: network + // Table containing helper functions for network related features. + + // Lua API: Function + // Table: network + // Name: trigger_script_event + // Param: bitset: integer + // Param: _args: table + // Call trigger_script_event (TSE) void trigger_script_event(int bitset, sol::table _args); + + // Lua API: Function + // Table: network + // Name: give_pickup_rewards + // Param: player: integer: Index of the player. + // Param: reward: integer: Index of the reward pickup. + // Give the given pickup reward to the given player. void give_pickup_rewards(int player, int reward); + + // Lua API: Function + // Table: network + // Name: set_player_coords + // Param: player_idx: integer: Index of the player. + // Param: x: float: New x position. + // Param: y: float: New y position. + // Param: z: float: New z position. + // Teleport the given player to the given position. void set_player_coords(int player_idx, float x, float y, float z); + + // Lua API: Function + // Table: network + // Name: set_all_player_coords + // Param: x: float: New x position. + // Param: y: float: New y position. + // Param: z: float: New z position. + // Teleport all players to the given position. void set_all_player_coords(float x, float y, float z); + + // Lua API: Function + // Table: network + // Name: get_selected_player + // Returns: integer: Returns the index of the currently selected player in the GUI. int get_selected_player(); + + // Lua API: Function + // Table: network + // Name: get_selected_database_player_rockstar_id + // Returns: integer: Returns the rockstar id of the currently selected player in the GUI. int get_selected_database_player_rockstar_id(); + + // Lua API: Function + // Table: network + // Name: flag_player_as_modder + // Param: player_idx: integer: Index of the player. + // Flags the given player as a modder in our local database. void flag_player_as_modder(int player_idx); + + // Lua API: Function + // Table: network + // Name: is_player_flagged_as_modder + // Param: player_idx: integer: Index of the player. + // Returns: boolean: Returns true if the given player is flagged as a modder. bool is_player_flagged_as_modder(int player_idx); + + // Lua API: Function + // Table: network + // Name: force_script_host + // Param: script_name: string: Name of the script + // Try to force ourself to be host for the given GTA Script. void force_script_host(const std::string& script_name); + + // Lua API: Function + // Table: network + // Name: send_chat_message + // Param: msg: string: Message to be sent. + // Param: team_only: boolean: Should be true if the msg should only be sent to our team. + // Sends a message to the in game chat. void send_chat_message(const std::string& msg, bool team_only); static void bind(sol::state& state) diff --git a/src/lua/bindings/script.hpp b/src/lua/bindings/script.hpp index 592f630d..990d388c 100644 --- a/src/lua/bindings/script.hpp +++ b/src/lua/bindings/script.hpp @@ -6,6 +6,16 @@ namespace lua::script { + // Lua API: Table + // Name: script + // Table containing helper functions related to gta scripts. + + // Lua API: Function + // Table: script + // Name: register_looped + // Param: name: string: name of your new looped script + // Param: func: function: function that will be executed in a forever loop. + // Registers a function that will be looped as a gta script. static void register_looped(const std::string& name, sol::function func, sol::this_state state) { auto module = sol::state_view(state)["!this"].get(); @@ -24,6 +34,11 @@ namespace lua::script name))); } + // Lua API: Function + // Table: script + // Name: run_in_fiber + // Param: func: function: function that will be executed once in the fiber pool, you can call natives inside it. + // Executes a function inside the fiber pool, you can call natives inside it. static void run_in_fiber(sol::function func) { big::g_fiber_pool->queue_job([func] { @@ -33,11 +48,20 @@ namespace lua::script }); } + // Lua API: Function + // Table: script + // Name: yield + // Yield execution. static void yield() { big::script::get_current()->yield(); } + // Lua API: Function + // Table: script + // Name: sleep + // Param: ms: integer: The amount of time in milliseconds that we will sleep for. + // Sleep for the given amount of time, time is in milliseconds. static void sleep(int ms) { big::script::get_current()->yield(std::chrono::milliseconds(ms)); diff --git a/src/lua/bindings/tunables.hpp b/src/lua/bindings/tunables.hpp index 2f999129..0e4acfda 100644 --- a/src/lua/bindings/tunables.hpp +++ b/src/lua/bindings/tunables.hpp @@ -3,6 +3,28 @@ namespace lua::tunables { + // Lua API: Table + // Name: tunables + // Table for manipulating gta tunables. + + // Lua API: Function + // Table: tunables + // Name: get_int + // Param: tunable_name: string: The name of the tunable. + // Returns: integer: The value of the given tunable. + + // Lua API: Function + // Table: tunables + // Name: get_float + // Param: tunable_name: string: The name of the tunable. + // Returns: float: The value of the given tunable. + + // Lua API: Function + // Table: tunables + // Name: get_bool + // Param: tunable_name: string: The name of the tunable. + // Returns: boolean: The value of the given tunable. + template static T get(const std::string tunable_name) { @@ -12,6 +34,24 @@ namespace lua::tunables return T(); } + // Lua API: Function + // Table: tunables + // Name: set_int + // Param: tunable_name: string: The name of the tunable. + // Param: val: integer: The new value of the given tunable. + + // Lua API: Function + // Table: tunables + // Name: set_float + // Param: tunable_name: string: The name of the tunable. + // Param: val: float: The new value of the given tunable. + + // Lua API: Function + // Table: tunables + // Name: set_bool + // Param: tunable_name: string: The name of the tunable. + // Param: val: boolean: The new value of the given tunable. + template static void set(const std::string tunable_name, T val) { diff --git a/src/lua/bindings/vector.hpp b/src/lua/bindings/vector.hpp index d13c03c4..aa751d41 100644 --- a/src/lua/bindings/vector.hpp +++ b/src/lua/bindings/vector.hpp @@ -3,6 +3,32 @@ namespace lua::vector { + // Lua API: Class + // Name: vec3 + // Class representing a 3D vector. + + // Lua API: Constructor + // Class: vec3 + // Param: x: float: x component of the vector. + // Param: y: float: y component of the vector. + // Param: z: float: z component of the vector. + // Returns a vector that contains the x, y, and z values. + + // Lua API: Field + // Class: vec3 + // Field: x: float + // x component of the vector. + + // Lua API: Field + // Class: vec3 + // Field: y: float + // y component of the vector. + + // Lua API: Field + // Class: vec3 + // Field: z: float + // z component of the vector. + static void bind(sol::state& state) { //clang-format off diff --git a/src/lua/lua_manager.hpp b/src/lua/lua_manager.hpp index 278d6947..4523217b 100644 --- a/src/lua/lua_manager.hpp +++ b/src/lua/lua_manager.hpp @@ -1,5 +1,6 @@ #pragma once #include "lua_module.hpp" +#include "core/enums.hpp" namespace big { @@ -34,16 +35,14 @@ namespace big void handle_error(const sol::error& error, const sol::state_view& state); - template + template inline std::conditional_t, void, std::optional> trigger_event(Args&&... args) { - constexpr auto hash = rage::joaat(hash_str.value); - std::lock_guard guard(m_module_lock); for (auto& module : m_modules) { - if (auto vec = module->m_event_callbacks.find(hash); vec != module->m_event_callbacks.end()) + if (auto vec = module->m_event_callbacks.find(menu_event_); vec != module->m_event_callbacks.end()) { for (auto& cb : vec->second) { diff --git a/src/lua/lua_module.cpp b/src/lua/lua_module.cpp index 0d7f960c..1b0051c2 100644 --- a/src/lua/lua_module.cpp +++ b/src/lua/lua_module.cpp @@ -12,6 +12,7 @@ #include "bindings/script.hpp" #include "bindings/tunables.hpp" #include "bindings/vector.hpp" +#include "bindings/global_table.hpp" #include "file_manager.hpp" #include "script_mgr.hpp" @@ -120,6 +121,6 @@ namespace big lua::locals::bind(m_state); lua::event::bind(m_state); lua::vector::bind(m_state); - m_state["joaat"] = rage::joaat; + lua::global_table::bind(m_state); } } \ No newline at end of file diff --git a/src/lua/lua_module.hpp b/src/lua/lua_module.hpp index 30d2bdb4..8c2c19d9 100644 --- a/src/lua/lua_module.hpp +++ b/src/lua/lua_module.hpp @@ -2,6 +2,7 @@ #include "bindings/gui/gui_element.hpp" #include "lua_patch.hpp" #include "sol.hpp" +#include "core/data/menu_event.hpp" namespace big { @@ -17,7 +18,7 @@ namespace big std::vector m_registered_scripts; std::vector> m_registered_patches; std::unordered_map>> m_gui; - std::unordered_map> m_event_callbacks; + std::unordered_map> m_event_callbacks; std::vector m_allocated_memory; lua_module(std::string module_name); diff --git a/src/lua/lua_patch.hpp b/src/lua/lua_patch.hpp index 8d8866af..9be2f5f8 100644 --- a/src/lua/lua_patch.hpp +++ b/src/lua/lua_patch.hpp @@ -7,6 +7,9 @@ namespace memory namespace big { + // Lua API: Class + // Name: lua_patch + // Class representing a in-memory patch. class lua_patch { memory::byte_patch* m_byte_patch; @@ -15,7 +18,16 @@ namespace big lua_patch(memory::byte_patch* patch); ~lua_patch(); + // Lua API: Function + // Class: lua_patch + // Name: apply + // Apply the modified value. void apply(); + + // Lua API: Function + // Class: lua_patch + // Name: restore + // Restore the original value. void restore(); }; } \ No newline at end of file