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