From 739bbc1b4397a457518d5b742e0c22c4b31f915d Mon Sep 17 00:00:00 2001
From: GigabiteStudios <gigabitestudios@noreply.localhost>
Date: Sat, 25 Jan 2025 04:59:59 +0000
Subject: [PATCH] Update README.md
---
README.md | 274 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 272 insertions(+), 2 deletions(-)
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