GooberDev/ProtoHook-LuaDocs
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
GigabiteStudios 2025-01-26 04:48:35 +00:00
parent 5fc4bf9651
commit f5e556f6a1
1 changed files with 696 additions and 216 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

912
README.md
View File

@ -1,286 +1,766 @@
# 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)
1. [Overview](#overview)
2. [Engine Table](#engine-table)
- [Engine.LogDebug](#enginelogdebug)
- [Engine.LogError](#enginelogerror)
- [Engine.WorldToScreen](#engineworldtoscreen)
- [Engine.GetScreenSize](#enginegetscreensize)
- [Engine.Settings.Set](#enginesettingsset)
3. [Renderer Table](#renderer-table)
- [Renderer.DrawBox](#rendererdrawbox)
- [Renderer.DrawCircle](#rendererdrawcircle)
- [Renderer.DrawLine](#rendererdrawline)
- [Renderer.DrawText](#rendererdrawtext)
- [Renderer.DrawEllipse](#rendererdrawellipse)
- [Renderer.DrawPolygon](#rendererdrawpolygon)
- [Renderer.DrawArc](#rendererdrawarc)
- [Renderer.DrawBezierCurve](#rendererdrawbeziercurve)
- [Renderer.DrawTriangle](#rendererdrawtriangle)
- [Renderer.DrawPolyline](#rendererdrawpolyline)
4. [Utility Functions](#utility-functions)
- [GetPlayers](#getplayers)
5. [Example Lua Scripts](#example-lua-scripts)
6. [Best Practices](#best-practices)
7. [Troubleshooting](#troubleshooting)
---
## Global Functions
## Overview
### GetPlayers()
This documentation outlines the Lua API exposed by your C++ application, allowing Lua scripts to interact with the engine's functionalities and perform rendering operations using ImGui. The API is organized into two primary tables:
```lua
players = GetPlayers()
```
- **Engine**: Provides utility functions related to logging, coordinate transformations, and settings management.
- **Renderer**: Offers a suite of drawing functions to render shapes, images, and text on the screen.
- **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
```
Additionally, utility functions like `GetPlayers` facilitate data retrieval from the C++ side to Lua.
---
## Engine Table
The `Engine` table exposes general engine-level functionalities.
The `Engine` table encapsulates functions related to debugging, coordinate transformations, screen information, and settings management. These functions are accessible in Lua as `Engine.<FunctionName>`.
### Engine.LogDebug(message)
### 1. Engine.LogDebug
**Description**: Logs a debug message to the engine's logging system.
**Usage**:
```lua
Engine.LogDebug("Some debug message")
Engine.LogDebug(message)
```
- **Description**: Logs a debug-level message to the console or in-game logger.
- **Parameters**:
- `message` (string): The message to log.
### Engine.LogError(message)
**Parameters**:
- `message` (`string`): The debug message to log.
**Example**:
```lua
Engine.LogError("Something went wrong!")
Engine.LogDebug("This is a debug message.")
```
- **Description**: Logs an error-level message.
- **Parameters**:
- `message` (string): The error message to log.
**Notes**:
- Primarily used for development and debugging purposes.
- Depending on your logging configuration, debug messages may be visible only in development builds.
### Engine.WorldToScreen(x, y, z)
---
### 2. Engine.LogError
**Description**: Logs an error message to the engine's logging system.
**Usage**:
```lua
local success, sx, sy = Engine.WorldToScreen(worldX, worldY, worldZ)
Engine.LogError(message)
```
**Parameters**:
- `message` (`string`): The error message to log.
**Example**:
```lua
Engine.LogError("An error has occurred in the script.")
```
**Notes**:
- Use this function to report errors that should be visible to users or developers.
- Errors are typically more prominent in logs and may trigger alerting mechanisms if implemented.
---
### 3. Engine.WorldToScreen
**Description**: Transforms world coordinates `(x, y, z)` to screen coordinates `(screenX, screenY)`.
**Usage**:
```lua
success, screenX, screenY = Engine.WorldToScreen(x, y, z)
```
**Parameters**:
- `x` (`number`): The X-coordinate in the world space.
- `y` (`number`): The Y-coordinate in the world space.
- `z` (`number`): The Z-coordinate in the world space.
**Returns**:
- `success` (`boolean`): `true` if the transformation was successful; `false` otherwise.
- `screenX` (`number`): The resulting X-coordinate on the screen (valid if `success` is `true`).
- `screenY` (`number`): The resulting Y-coordinate on the screen (valid if `success` is `true`).
**Example**:
```lua
local success, sx, sy = Engine.WorldToScreen(100.0, 200.0, 50.0)
if success then
print("Screen coordinates:", sx, sy)
Renderer.DrawCircle(sx, sy, 10, 255, 0, 0, 255) -- Draw a red circle at the screen position
else
print("Failed to project to screen.")
Engine.LogError("WorldToScreen transformation failed.")
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`.
**Notes**:
- Ensure that the provided world coordinates are valid and within the visible range.
- The function relies on an external view matrix (`g_ViewMatrix`) for the transformation.
---
### Engine.GetScreenSize()
### 4. Engine.GetScreenSize
**Description**: Retrieves the current screen's width and height.
**Usage**:
```lua
local x, y = Engine.GetScreenSize()
width, height = Engine.GetScreenSize()
```
- **Description**: Gets Screen Size
- **Parameters**:
- None
- **Return Values**:
1. `sx`, `sy` (numbers/floats): The Size of the active screen
**Returns**:
- `width` (`number`): The width of the screen in pixels.
- `height` (`number`): The height of the screen in pixels.
**Example**:
```lua
local screenWidth, screenHeight = Engine.GetScreenSize()
Renderer.DrawBox(screenWidth - 100, screenHeight - 50, 90, 40, 0, 255, 0, 255) -- Draw a green box near the bottom-right corner
```
**Notes**:
- Useful for positioning UI elements relative to the screen dimensions.
- Reflects the current display size; changes due to window resizing are updated accordingly.
---
### 5. Engine.Settings.Set
**Description**: Sets the value of a specified engine setting, particularly color configurations.
**Usage**:
```lua
Engine.Settings.Set(identifier, colorTable)
```
**Parameters**:
- `identifier` (`string`): The name of the color setting to modify (e.g., `"g_GlobalColor"`).
- `colorTable` (`table`): A table containing four numerical values representing RGBA components, each ranging from `0` to `255`.
**Color Identifiers**:
- `"g_GlobalColor"`
- `"g_RectangleColor"`
- `"g_SkeletonColor"`
- `"g_HealthColorLow"`
- `"g_HealthColorHigh"`
- `"g_GlowColor"`
- `"g_OffscreenArrowColor"`
- `"g_BombCircleColor"`
- `"g_CircleColor"`
- `"g_NameColor"`
- `"g_FlagsColor"`
**Example**:
```lua
-- Set the global color to blue with full opacity
Engine.Settings.Set("g_GlobalColor", {0, 0, 255, 255})
-- Set the health color low threshold to red with half opacity
Engine.Settings.Set("g_HealthColorLow", {255, 0, 0, 128})
```
**Notes**:
- The `colorTable` must contain exactly four numerical values corresponding to red (`r`), green (`g`), blue (`b`), and alpha (`a`) channels.
- Values must be within the range `[0, 255]`. Out-of-range values will result in an error.
- Changing these settings may immediately affect rendering elements that rely on these color configurations.
---
## 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.
The `Renderer` table provides a collection of functions to draw various shapes, images, and text on the screen. These functions leverage ImGui's drawing capabilities and are accessible in Lua as `Renderer.<FunctionName>`.
### Renderer.DrawBox(x, y, w, h, r, g, b, a)
### 1. Renderer.DrawBox
**Description**: Draws a filled rectangle (box) on the screen.
**Usage**:
```lua
Renderer.DrawBox(100, 100, 200, 50, 1.0, 0.0, 0.0, 1.0)
Renderer.DrawBox(x, y, width, height, r, g, b, a)
```
- **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)
**Parameters**:
- `x` (`number`): The X-coordinate of the top-left corner.
- `y` (`number`): The Y-coordinate of the top-left corner.
- `width` (`number`): The width of the box in pixels.
- `height` (`number`): The height of the box in pixels.
- `r` (`number`): Red component of the color (`0`-`255`).
- `g` (`number`): Green component of the color (`0`-`255`).
- `b` (`number`): Blue component of the color (`0`-`255`).
- `a` (`number`): Alpha (opacity) component of the color (`0`-`255`).
**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
-- Draw a semi-transparent blue box at (50, 50) with size 100x150
Renderer.DrawBox(50, 50, 100, 150, 0, 0, 255, 128)
```
**Notes**:
- The box is drawn relative to the screen's coordinate system.
- Alpha (`a`) controls the transparency; `0` is fully transparent, and `255` is fully opaque.
---
## Example Lua Script
### 2. Renderer.DrawCircle
Below is a minimal Lua script demonstrating how to use the exposed functions/tables:
**Description**: Draws a filled circle on the screen.
**Usage**:
```lua
Renderer.DrawCircle(x, y, radius, r, g, b, a)
```
**Parameters**:
- `x` (`number`): The X-coordinate of the circle's center.
- `y` (`number`): The Y-coordinate of the circle's center.
- `radius` (`number`): The radius of the circle in pixels.
- `r` (`number`): Red component of the color (`0`-`255`).
- `g` (`number`): Green component of the color (`0`-`255`).
- `b` (`number`): Blue component of the color (`0`-`255`).
- `a` (`number`): Alpha (opacity) component of the color (`0`-`255`).
**Example**:
```lua
-- Draw a solid red circle at (200, 200) with a radius of 50
Renderer.DrawCircle(200, 200, 50, 255, 0, 0, 255)
```
**Notes**:
- The circle is filled with the specified color and opacity.
- The number of segments (`24` in the C++ code) determines the smoothness of the circle.
---
### 3. Renderer.DrawLine
**Description**: Draws a straight line between two points on the screen.
**Usage**:
```lua
Renderer.DrawLine(x1, y1, x2, y2, r, g, b, a)
```
**Parameters**:
- `x1` (`number`): The X-coordinate of the starting point.
- `y1` (`number`): The Y-coordinate of the starting point.
- `x2` (`number`): The X-coordinate of the ending point.
- `y2` (`number`): The Y-coordinate of the ending point.
- `r` (`number`): Red component of the line color (`0`-`255`).
- `g` (`number`): Green component of the line color (`0`-`255`).
- `b` (`number`): Blue component of the line color (`0`-`255`).
- `a` (`number`): Alpha (opacity) component of the line color (`0`-`255`).
**Example**:
```lua
-- Draw a green line from (300, 300) to (400, 400)
Renderer.DrawLine(300, 300, 400, 400, 0, 255, 0, 255)
```
**Notes**:
- Lines are drawn with a default thickness (`2.0f` in the C++ code).
- The color's alpha value affects the line's transparency.
---
### 4. Renderer.DrawText
**Description**: Renders text at a specified position on the screen.
**Usage**:
```lua
Renderer.DrawText(x, y, text, r, g, b, a)
```
**Parameters**:
- `x` (`number`): The X-coordinate where the text begins.
- `y` (`number`): The Y-coordinate where the text begins.
- `text` (`string`): The text string to render.
- `r` (`number`): Red component of the text color (`0`-`255`).
- `g` (`number`): Green component of the text color (`0`-`255`).
- `b` (`number`): Blue component of the text color (`0`-`255`).
- `a` (`number`): Alpha (opacity) component of the text color (`0`-`255`).
**Example**:
```lua
-- Draw white text at (500, 500)
Renderer.DrawText(500, 500, "Hello, World!", 255, 255, 255, 255)
```
**Notes**:
- The text uses ImGui's current font and font size.
- Ensure that the `text` parameter is a valid string to avoid rendering issues.
---
### 5. Renderer.DrawEllipse
**Description**: Draws a filled ellipse on the screen.
**Usage**:
```lua
Renderer.DrawEllipse(x, y, rx, ry, r, g, b, a)
```
**Parameters**:
- `x` (`number`): The X-coordinate of the ellipse's center.
- `y` (`number`): The Y-coordinate of the ellipse's center.
- `rx` (`number`): The horizontal radius of the ellipse.
- `ry` (`number`): The vertical radius of the ellipse.
- `r` (`number`): Red component of the ellipse color (`0`-`255`).
- `g` (`number`): Green component of the ellipse color (`0`-`255`).
- `b` (`number`): Blue component of the ellipse color (`0`-`255`).
- `a` (`number`): Alpha (opacity) component of the ellipse color (`0`-`255`).
**Example**:
```lua
-- Draw a semi-transparent yellow ellipse at (600, 600) with radii 80 and 40
Renderer.DrawEllipse(600, 600, 80, 40, 255, 255, 0, 128)
```
**Notes**:
- The number of segments (`24` in the C++ code) determines the smoothness of the ellipse.
- Similar to `DrawCircle`, the alpha value controls transparency.
---
### 6. Renderer.DrawPolygon
**Description**: Draws a filled convex polygon with a specified number of vertices.
**Usage**:
```lua
Renderer.DrawPolygon(n, x1, y1, x2, y2, ..., r, g, b, a)
```
**Parameters**:
- `n` (`number`): The number of vertices (must be at least `3`).
- `x1`, `y1` (`number`): Coordinates of the first vertex.
- `x2`, `y2` (`number`): Coordinates of the second vertex.
- `...` (`number`): Coordinates of subsequent vertices (`x3`, `y3`, etc.).
- `r` (`number`): Red component of the polygon color (`0`-`255`).
- `g` (`number`): Green component of the polygon color (`0`-`255`).
- `b` (`number`): Blue component of the polygon color (`0`-`255`).
- `a` (`number`): Alpha (opacity) component of the polygon color (`0`-`255`).
**Example**:
```lua
-- Draw a green rectangle as a polygon
Renderer.DrawPolygon(4, 700, 700, 800, 700, 800, 800, 700, 800, 0, 255, 0, 255)
```
**Notes**:
- The polygon must be convex. Non-convex polygons may not render correctly.
- Ensure that the number of coordinates matches `n * 2`.
- Alpha (`a`) controls the transparency of the polygon.
---
### 7. Renderer.DrawArc
**Description**: Draws an arc between two angles around a center point.
**Usage**:
```lua
Renderer.DrawArc(x, y, radius, start_angle, end_angle, r, g, b, a)
```
**Parameters**:
- `x` (`number`): The X-coordinate of the arc's center.
- `y` (`number`): The Y-coordinate of the arc's center.
- `radius` (`number`): The radius of the arc.
- `start_angle` (`number`): The starting angle of the arc in degrees.
- `end_angle` (`number`): The ending angle of the arc in degrees.
- `r` (`number`): Red component of the arc color (`0`-`255`).
- `g` (`number`): Green component of the arc color (`0`-`255`).
- `b` (`number`): Blue component of the arc color (`0`-`255`).
- `a` (`number`): Alpha (opacity) component of the arc color (`0`-`255`).
**Example**:
```lua
-- Draw a blue arc from 0 to 180 degrees at (900, 900) with radius 100
Renderer.DrawArc(900, 900, 100, 0, 180, 0, 0, 255, 255)
```
**Notes**:
- Angles are specified in degrees. Ensure correct angle calculations when scripting.
- The arc is drawn as an outline with a default thickness (`2.0f` in the C++ code).
- Alpha (`a`) controls the transparency of the arc.
---
### 8. Renderer.DrawBezierCurve
**Description**: Draws a cubic Bezier curve between two points with two control points.
**Usage**:
```lua
Renderer.DrawBezierCurve(x1, y1, cx1, cy1, cx2, cy2, x2, y2, r, g, b, a)
```
**Parameters**:
- `x1`, `y1` (`number`): Coordinates of the starting point.
- `cx1`, `cy1` (`number`): Coordinates of the first control point.
- `cx2`, `cy2` (`number`): Coordinates of the second control point.
- `x2`, `y2` (`number`): Coordinates of the ending point.
- `r` (`number`): Red component of the curve color (`0`-`255`).
- `g` (`number`): Green component of the curve color (`0`-`255`).
- `b` (`number`): Blue component of the curve color (`0`-`255`).
- `a` (`number`): Alpha (opacity) component of the curve color (`0`-`255`).
**Example**:
```lua
-- Draw a yellow Bezier curve from (1000, 1000) to (1100, 1100) with control points
Renderer.DrawBezierCurve(1000, 1000, 1050, 950, 1150, 1150, 1100, 1100, 255, 255, 0, 255)
```
**Notes**:
- The curve is drawn with a default thickness (`2.0f` in the C++ code).
- Control points influence the curvature; adjusting them alters the shape of the curve.
- Alpha (`a`) controls the transparency of the curve.
---
### 9. Renderer.DrawTriangle
**Description**: Draws a filled triangle defined by three vertices.
**Usage**:
```lua
Renderer.DrawTriangle(x1, y1, x2, y2, x3, y3, r, g, b, a)
```
**Parameters**:
- `x1`, `y1` (`number`): Coordinates of the first vertex.
- `x2`, `y2` (`number`): Coordinates of the second vertex.
- `x3`, `y3` (`number`): Coordinates of the third vertex.
- `r` (`number`): Red component of the triangle color (`0`-`255`).
- `g` (`number`): Green component of the triangle color (`0`-`255`).
- `b` (`number`): Blue component of the triangle color (`0`-`255`).
- `a` (`number`): Alpha (opacity) component of the triangle color (`0`-`255`).
**Example**:
```lua
-- Draw a purple triangle
Renderer.DrawTriangle(1200, 1200, 1250, 1250, 1200, 1300, 128, 0, 128, 255)
```
**Notes**:
- The triangle is filled with the specified color and opacity.
- Ensure that the three points do not lie on a straight line to form a valid triangle.
---
### 10. Renderer.DrawPolyline
**Description**: Draws a series of connected lines (polyline) between multiple points.
**Usage**:
```lua
Renderer.DrawPolyline(n, x1, y1, x2, y2, ..., r, g, b, a)
```
**Parameters**:
- `n` (`number`): The number of points (must be at least `2`).
- `x1`, `y1` (`number`): Coordinates of the first point.
- `x2`, `y2` (`number`): Coordinates of the second point.
- `...` (`number`): Coordinates of subsequent points (`x3`, `y3`, etc.).
- `r` (`number`): Red component of the polyline color (`0`-`255`).
- `g` (`number`): Green component of the polyline color (`0`-`255`).
- `b` (`number`): Blue component of the polyline color (`0`-`255`).
- `a` (`number`): Alpha (opacity) component of the polyline color (`0`-`255`).
**Example**:
```lua
-- Draw a cyan polyline forming a V shape
Renderer.DrawPolyline(3, 1300, 1300, 1350, 1350, 1400, 1300, 0, 255, 255, 255)
```
**Notes**:
- The polyline is not closed; it connects each point sequentially without forming a loop.
- The line thickness is set to `2.0f` in the C++ code.
- Alpha (`a`) controls the transparency of the polyline.
---
## Utility Functions
### GetPlayers
**Description**: Retrieves a table of player information from the C++ side. This function is exposed globally to Lua as `GetPlayers`.
**Usage**:
```lua
players, error = GetPlayers()
```
**Returns**:
- `players` (`table`): A table containing player data. Each entry corresponds to a player with various attributes.
- `error` (`string`, optional): An error message if the retrieval fails. `nil` if successful.
**Player Attributes**:
Each player table includes the following fields:
- `name` (`string`): Player's name.
- `ping` (`number`): Player's ping in milliseconds.
- `health` (`number`): Player's health points.
- `armor` (`number`): Player's armor points.
- `team` (`number`): Player's team identifier.
- `distance` (`number`): Distance from the player to a reference point.
- `hasDefuser` (`boolean`): Indicates if the player has a defuser.
- `hasHelmet` (`boolean`): Indicates if the player has a helmet.
- `position` (`table`): Player's current position with `x`, `y`, `z` coordinates.
- `headPosition` (`table`): Player's head position with `x`, `y`, `z` coordinates.
**Example**:
```lua
local players, err = GetPlayers()
if not players then
Engine.LogError("Failed to retrieve players: " .. err)
else
for i, player in ipairs(players) do
Renderer.DrawText(player.position.x, player.position.y, player.name, 255, 255, 255, 255)
Renderer.DrawCircle(player.position.x, player.position.y, 10, 0, 255, 0, 255) -- Green circle for each player
end
end
```
**Notes**:
- The function returns `nil` and an error message if the players' data pointer is invalid.
- Ensure that the `players` pointer is valid and that player data is populated on the C++ side.
---
## Example Lua Scripts
Below are example Lua scripts demonstrating how to utilize the `Engine` and `Renderer` APIs to perform various tasks.
### Example 1: Simple Debug Logging and Drawing
```lua
-- ExampleScript.lua
-- Log a debug message
Engine.LogDebug("Script initialized successfully.")
-- Called once on script load
function onInit()
Engine.LogDebug("ExampleScript.lua: onInit() called!")
end
-- Get screen size
local width, height = Engine.GetScreenSize()
-- Called every game tick / frame update
-- Draw a red box at the center of the screen
Renderer.DrawBox(width / 2 - 50, height / 2 - 50, 100, 100, 255, 0, 0, 255)
-- Draw a blue circle at the top-left corner
Renderer.DrawCircle(50, 50, 30, 0, 0, 255, 255)
-- Draw white text inside the box
Renderer.DrawText(width / 2 - 40, height / 2 - 20, "Hello!", 255, 255, 255, 255)
```
### Example 2: Dynamic Player Indicators
```lua
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
local players, err = GetPlayers()
if not players then
Engine.LogError("Error retrieving players: " .. err)
return
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)
for _, player in ipairs(players) do
if player.health > 0 then
Renderer.DrawCircle(player.position.x, player.position.y, 15, 0, 255, 0, 255) -- Green circle for alive players
Renderer.DrawText(player.position.x + 20, player.position.y, player.name, 255, 255, 255, 255)
else
Renderer.DrawCircle(player.position.x, player.position.y, 15, 255, 0, 0, 255) -- Red circle for dead players
Renderer.DrawText(player.position.x + 20, player.position.y, player.name, 255, 255, 255, 255)
end
end
end
```
In this example:
### Example 3: Drawing Complex Shapes
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.
```lua
-- Draw an ellipse with semi-transparent purple color
Renderer.DrawEllipse(400, 400, 80, 40, 128, 0, 128, 128)
-- Draw a polygon (triangle) with yellow color
Renderer.DrawPolygon(3, 500, 500, 550, 500, 525, 550, 255, 255, 0, 255)
-- Draw an arc representing a 90-degree section
Renderer.DrawArc(600, 600, 60, 0, 90, 0, 255, 255, 255)
-- Draw a Bezier curve for a smooth path
Renderer.DrawBezierCurve(700, 700, 750, 650, 850, 750, 900, 700, 0, 255, 255, 255)
-- Draw a filled triangle
Renderer.DrawTriangle(1000, 1000, 1050, 1050, 1000, 1100, 255, 0, 255, 255)
-- Draw a polyline forming a zig-zag pattern
Renderer.DrawPolyline(4, 1100, 1100, 1150, 1150, 1200, 1100, 1250, 1150, 0, 255, 255, 255)
```
---
### Quick Reference
## Best Practices
| **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. |
To ensure optimal performance, maintainability, and stability when using the Lua API, adhere to the following best practices:
Use these APIs in your Lua scripts to create overlays, debug messages, or build interactive features.
1. **Validate Inputs**:
- Always provide the correct number and type of arguments when calling API functions.
- Utilize error handling (e.g., checking return values) to manage unexpected scenarios.
2. **Optimize Drawing Calls**:
- Minimize the number of drawing calls within high-frequency functions like `onTick` to prevent performance degradation.
- Batch multiple drawing operations where possible.
3. **Manage Resources Wisely**:
- Ensure that any resources (e.g., textures) used in drawing functions are properly loaded and managed on the C++ side.
- Avoid memory leaks by adhering to proper ownership and lifecycle management of objects.
4. **Use Meaningful Logging**:
- Leverage `Engine.LogDebug` and `Engine.LogError` to trace script execution and debug issues.
- Provide clear and concise log messages to facilitate troubleshooting.
5. **Coordinate Systems Awareness**:
- Understand the screen coordinate system where `(0,0)` typically represents the top-left corner.
- Account for screen resizing by dynamically retrieving screen dimensions using `Engine.GetScreenSize`.
6. **Thread Safety**:
- If interacting with shared resources or multi-threaded systems, ensure that proper synchronization mechanisms are in place to prevent race conditions.
7. **Consistent Style and Naming**:
- Follow consistent naming conventions for variables and functions to enhance code readability.
- Structure your scripts logically, grouping related operations together.
8. **Documentation and Comments**:
- Comment your Lua scripts to explain complex logic or drawing sequences.
- Refer to this documentation as needed to understand the API functions and their usages.
---
## Troubleshooting
### Common Issues and Solutions
1. **Error: "Invalid color identifier: <identifier>"**
**Cause**: The provided `identifier` string does not match any recognized color settings.
**Solution**:
- Verify that the `identifier` matches one of the predefined color identifiers exactly (case-sensitive).
- Refer to the [Engine.Settings.Set](#enginesettingsset) documentation for available identifiers.
**Example**:
```lua
-- Correct identifier
Engine.Settings.Set("g_GlobalColor", {255, 255, 255, 255})
-- Incorrect identifier (case-sensitive)
Engine.Settings.Set("G_GlobalColor", {255, 255, 255, 255}) -- This will cause an error
```
2. **Error: "Renderer.<FunctionName> expects numerical arguments at position <n>"**
**Cause**: One or more arguments provided to a drawing function are not numbers.
**Solution**:
- Ensure all positional arguments are of type `number`.
- Check the order and count of arguments as per the function's documentation.
**Example**:
```lua
-- Correct usage
Renderer.DrawBox(100, 100, 50, 50, 0, 0, 255, 255)
-- Incorrect usage (non-number argument)
Renderer.DrawBox(100, "100", 50, 50, 0, 0, 255, 255) -- Second argument should be a number
```
3. **Error: "Renderer.<FunctionName> expects a lightuserdata for textureID"**
**Cause**: The `textureID` provided to `Renderer.DrawImage` is not a light userdata.
**Solution**:
- Ensure that `textureID` is a valid `ImTextureID` passed as light userdata from the C++ side.
- Confirm that the texture is properly loaded and accessible.
**Example**:
```lua
-- Correct usage (assuming 'texture' is a valid ImTextureID)
Renderer.DrawImage(texture, 300, 300, 100, 100, 255, 255, 255, 255)
-- Incorrect usage
Renderer.DrawImage("invalid_texture", 300, 300, 100, 100, 255, 255, 255, 255) -- Should be lightuserdata, not string
```
4. **Text Not Rendering or Positioned Incorrectly**
**Cause**: The text position may be outside the visible screen area or the `text` string is empty.
**Solution**:
- Verify that the `x` and `y` coordinates are within the screen bounds.
- Ensure that the `text` parameter contains a valid string.
**Example**:
```lua
-- Correct usage
Renderer.DrawText(500, 500, "Player Name", 255, 255, 255, 255)
-- Incorrect usage (out-of-bounds coordinates)
Renderer.DrawText(-10, -10, "Hidden Text", 255, 255, 255, 255)
```
5. **No Visible Drawings Despite Correct Function Calls**
**Cause**: The drawing functions rely on ImGui's drawing system, which may not be initialized or may have rendering issues.
**Solution**:
- Ensure that ImGui is properly initialized in your C++ application.
- Verify that the drawing occurs within a valid rendering loop.
- Check for any ImGui-related errors in the C++ logs.
**Example**:
```cpp
// Ensure ImGui is initialized before running scripts
ImGui::CreateContext();
// ... other ImGui setup code
```
---
## Additional Information
### Extending the API
You can further enhance the Lua API by adding more functions to both the `Engine` and `Renderer` tables. Follow the established patterns for consistency and maintainability. Ensure that each new function includes thorough argument validation and adheres to best practices outlined above.
### Security Considerations
- **Sandboxing**: If Lua scripts are sourced from untrusted inputs, consider sandboxing the environment to prevent malicious operations.
- **Resource Limits**: Implement limits on script execution time and resource usage to prevent scripts from degrading application performance.
### Performance Optimization
- **Minimize Drawing Calls**: Reduce the number of drawing calls within high-frequency loops to enhance performance.
- **Batch Rendering**: Where possible, batch multiple drawing operations into a single call.
- **Profile Scripts**: Use profiling tools to identify and optimize slow-performing scripts.