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
   1. GetPlayers()
2. Engine Table
   1. Engine.LogDebug(message)
   2. Engine.LogError(message)
   3. Engine.WorldToScreen(x, y, z)
3. Renderer Table
   1. Renderer.DrawBox(x, y, w, h, r, g, b, a)
   2. Renderer.DrawCircle(x, y, radius, r, g, b, a)
   3. Renderer.DrawLine(x1, y1, x2, y2, r, g, b, a)
   4. Renderer.DrawText(x, y, text, r, g, b, a)
4. Lua Script Lifecycle
   1. onInit()
   2. onTick()
5. Player Table Structure
6. Example Lua Script

---

Global Functions

GetPlayers()

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:

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)

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)

Engine.LogError("Something went wrong!")

• Description: Logs an error-level message.
• Parameters:
  • message (string): The error message to log.

Engine.WorldToScreen(x, y, z)

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 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)

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)

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)

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)

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:

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:

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