273 lines
8.7 KiB
Markdown
273 lines
8.7 KiB
Markdown
# 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. |