From f5e556f6a1c58b9fe40246fdecc8dcd717505faf Mon Sep 17 00:00:00 2001 From: GigabiteStudios Date: Sun, 26 Jan 2025 04:48:35 +0000 Subject: [PATCH] Update README.md --- README.md | 912 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 696 insertions(+), 216 deletions(-) diff --git a/README.md b/README.md index 7fbfc1a..aa46941 100644 --- a/README.md +++ b/README.md @@ -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.`. -### 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.`. -### 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. \ No newline at end of file +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: "** + + **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. expects numerical arguments at position "** + + **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. 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.