ProtoHook-LuaDocs/README.md

# Lua API Documentation

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`.


### Engine.GetScreenSize()

```lua
local x, y = Engine.GetScreenSize()
```

- **Description**: Gets Screen Size
- **Parameters**:
  - None
- **Return Values**:
  1. `sx`, `sy` (numbers/floats): The Size of the active screen

---

## 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.