diff --git a/README.md b/README.md index 4843df6..2ca5a92 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,273 @@ -# ProtoHook-LuaDocs +# Lua API Documentation -The Lua API docs for protohook \ No newline at end of file +This document describes the **Lua** functions, tables, and callbacks exposed by the C++ code. You can use these in your Lua scripts to interact with the engine, draw on the screen, or retrieve player data. + +--- + +## Table of Contents + +1. [Global Functions](#global-functions) + 1. [GetPlayers()](#getplayers) +2. [Engine Table](#engine-table) + 1. [Engine.LogDebug(message)](#enginelogdebugmessage) + 2. [Engine.LogError(message)](#enginelogerrormessage) + 3. [Engine.WorldToScreen(x, y, z)](#engineworldtoscreenx-y-z) +3. [Renderer Table](#renderer-table) + 1. [Renderer.DrawBox(x, y, w, h, r, g, b, a)](#rendererdrawboxx-y-w-h-r-g-b-a) + 2. [Renderer.DrawCircle(x, y, radius, r, g, b, a)](#rendererdrawcirclex-y-radius-r-g-b-a) + 3. [Renderer.DrawLine(x1, y1, x2, y2, r, g, b, a)](#rendererdrawlinex1-y1-x2-y2-r-g-b-a) + 4. [Renderer.DrawText(x, y, text, r, g, b, a)](#rendererdrawtextx-y-text-r-g-b-a) +4. [Lua Script Lifecycle](#lua-script-lifecycle) + 1. [onInit()](#oninit) + 2. [onTick()](#ontick) +5. [Player Table Structure](#player-table-structure) +6. [Example Lua Script](#example-lua-script) + +--- + +## Global Functions + +### GetPlayers() + +```lua +players = GetPlayers() +``` + +- **Description**: Returns a table (array) of player objects. +- **Return Value**: A **table** where each element is a player’s sub-table containing: + - `name` (string) + - `ping` (integer) + - `health` (integer) + - `armor` (integer) + - `team` (integer) + - `distance` (number/float) + - `hasDefuser` (boolean) + - `hasHelmet` (boolean) + - `position` (table) with `x`, `y`, `z` (floats) + +**Usage**: + +```lua +local allPlayers = GetPlayers() +for i, player in ipairs(allPlayers) do + print("Player "..i.." name:", player.name) + print("Position x:", player.position.x, "y:", player.position.y, "z:", player.position.z) +end +``` + +--- + +## Engine Table + +The `Engine` table exposes general engine-level functionalities. + +### Engine.LogDebug(message) + +```lua +Engine.LogDebug("Some debug message") +``` + +- **Description**: Logs a debug-level message to the console or in-game logger. +- **Parameters**: + - `message` (string): The message to log. + +### Engine.LogError(message) + +```lua +Engine.LogError("Something went wrong!") +``` + +- **Description**: Logs an error-level message. +- **Parameters**: + - `message` (string): The error message to log. + +### Engine.WorldToScreen(x, y, z) + +```lua +local success, sx, sy = Engine.WorldToScreen(worldX, worldY, worldZ) +if success then + print("Screen coordinates:", sx, sy) +else + print("Failed to project to screen.") +end +``` + +- **Description**: Converts 3D world coordinates (x, y, z) to 2D screen coordinates. +- **Parameters**: + - `x`, `y`, `z` (numbers/floats): The 3D position. +- **Return Values**: + 1. `success` (boolean): `true` if the 3D point is visible on screen, `false` otherwise. + 2. `sx`, `sy` (numbers/floats): The 2D screen coordinates if `success` is `true`. + +--- + +## Renderer Table + +The `Renderer` table provides drawing functions that use [ImGui](https://github.com/ocornut/imgui) behind the scenes. These functions are typically called during your script’s `onTick()` callback, and are rendered each frame. + +### Renderer.DrawBox(x, y, w, h, r, g, b, a) + +```lua +Renderer.DrawBox(100, 100, 200, 50, 1.0, 0.0, 0.0, 1.0) +``` + +- **Description**: Draws a filled rectangle at screen coordinates `(x, y)`. +- **Parameters**: + - `x`, `y`: Upper-left screen coordinates. + - `w`, `h`: Width and height. + - `r`, `g`, `b`, `a`: Color, in the range [0.0, 1.0]. + +### Renderer.DrawCircle(x, y, radius, r, g, b, a) + +```lua +Renderer.DrawCircle(300, 300, 50, 0.0, 1.0, 0.0, 1.0) +``` + +- **Description**: Draws a filled circle at screen coordinates `(x, y)`. +- **Parameters**: + - `x`, `y`: Center screen coordinates. + - `radius`: Radius of the circle. + - `r`, `g`, `b`, `a`: Color, in the range [0.0, 1.0]. + +### Renderer.DrawLine(x1, y1, x2, y2, r, g, b, a) + +```lua +Renderer.DrawLine(50, 50, 150, 150, 0.5, 0.5, 1.0, 1.0) +``` + +- **Description**: Draws a line from `(x1, y1)` to `(x2, y2)`. +- **Parameters**: + - `x1`, `y1`: Starting screen coordinate. + - `x2`, `y2`: Ending screen coordinate. + - `r`, `g`, `b`, `a`: Color, in the range [0.0, 1.0]. + +### Renderer.DrawText(x, y, text, r, g, b, a) + +```lua +Renderer.DrawText(100, 200, "Hello, world!", 1.0, 1.0, 1.0, 1.0) +``` + +- **Description**: Draws text at screen coordinates `(x, y)`. +- **Parameters**: + - `x`, `y`: Position of the text. + - `text`: String to be displayed. + - `r`, `g`, `b`, `a`: Color, in the range [0.0, 1.0]. + +--- + +## Lua Script Lifecycle + +When you load a Lua script in this system, the following callbacks are recognized: + +### onInit() + +- **Optional** function in your Lua script. +- Called **once** right before the first `onTick`. +- Typically used to initialize state or print a welcome message. + +### onTick() + +- **Required** if you want continuous updates. +- Called every frame or game update cycle. +- Useful for drawing, logic updates, or retrieving game data (e.g., players). + +--- + +## Player Table Structure + +`GetPlayers()` returns an array (1-based) of **player tables**, each containing: + +- `name` (string): Player’s name +- `ping` (integer): Network ping +- `health` (integer): Health points +- `armor` (integer): Armor value +- `team` (integer): Team identifier +- `distance` (float): Distance from the local player or some reference point +- `hasDefuser` (boolean): Whether the player has a defuser kit +- `hasHelmet` (boolean): Whether the player has a helmet +- `position` (table): Sub-table with: + - `x` (float) + - `y` (float) + - `z` (float) + +**Example**: + +```lua +local players = GetPlayers() +for i, p in ipairs(players) do + print("---- Player "..i.." ----") + print("Name:", p.name) + print("Ping:", p.ping) + print("Health:", p.health) + print("Armor:", p.armor) + print("Team:", p.team) + print("Distance:", p.distance) + print("Has Defuser?:", p.hasDefuser) + print("Has Helmet?:", p.hasHelmet) + print("Position X:", p.position.x, "Y:", p.position.y, "Z:", p.position.z) +end +``` + +--- + +## Example Lua Script + +Below is a minimal Lua script demonstrating how to use the exposed functions/tables: + +```lua +-- ExampleScript.lua + +-- Called once on script load +function onInit() + Engine.LogDebug("ExampleScript.lua: onInit() called!") +end + +-- Called every game tick / frame update +function onTick() + -- 1) Retrieve players + local players = GetPlayers() + + -- 2) Loop over players, draw name + for i, p in ipairs(players) do + -- Convert world position to screen + local success, sx, sy = Engine.WorldToScreen(p.position.x, p.position.y, p.position.z) + + if success then + -- Draw the player's name in white + Renderer.DrawText(sx, sy, p.name, 1.0, 1.0, 1.0, 1.0) + + -- Draw a circle around their position + Renderer.DrawCircle(sx, sy, 10, 1.0, 0.0, 0.0, 1.0) + end + end + + -- 3) Draw some HUD elements + Renderer.DrawBox(10, 10, 200, 40, 0.0, 0.0, 0.0, 0.5) + Renderer.DrawText(20, 20, "HUD Title", 1.0, 1.0, 1.0, 1.0) +end +``` + +In this example: + +1. `onInit()` logs a debug message. +2. `onTick()` retrieves all players, converts each player's 3D position to screen coordinates, and draws the player's name/circle at that position. +3. Draws a semi-transparent box (HUD) at the top-left of the screen with a title. + +--- + +### Quick Reference + +| **Function** | **Usage** | +|-------------------------------------|---------------------------------------------------------------------| +| **`GetPlayers()`** | Returns a list of player tables. | +| **`Engine.LogDebug(msg)`** | Logs a debug message. | +| **`Engine.LogError(msg)`** | Logs an error message. | +| **`Engine.WorldToScreen(x,y,z)`** | Converts world coords to screen coords. Returns `bool, sx, sy`. | +| **`Renderer.DrawBox(...)`** | Draws a filled rectangle (box). | +| **`Renderer.DrawCircle(...)`** | Draws a filled circle. | +| **`Renderer.DrawLine(...)`** | Draws a line between two points. | +| **`Renderer.DrawText(...)`** | Draws text on screen. | +| **`onInit()`** (Lua callback) | Called once when the script is loaded. | +| **`onTick()`** (Lua callback) | Called every frame or update cycle. | + +Use these APIs in your Lua scripts to create overlays, debug messages, or build interactive features. \ No newline at end of file