Quick Start Guide

This guide provides a brief introduction to working with our Lua API, with simple examples to get you started quickly.

Setup

1. Store all your Lua scripts in Documents/My Games

2. Place any asset files (images, sounds, etc.) in the same directory

3. Use the built-in editor or any text editor to write your scripts

Development Environment

Perception Lua API Extension for VS Code

For the best development experience, we recommend using Visual Studio Code with the Perception Lua API extension. This powerful tool enhances your coding experience with:

• Smart Auto-Completion: Get suggestions for namespaces and functions as you type

• Parameter Hints: Function parameters are automatically inserted with proper names

• Hover Documentation: See detailed function information by hovering over any API function

• Full API Documentation: Access the complete API docs right inside VS Code

Installation

1. Open VS Code

2. Click on the Extensions icon in the sidebar

3. Search for "Perception Lua API"

4. Click Install

Or use this direct link: Perception Lua API on VS Code Marketplace

VS Code with Perception Lua API Extension

Basic Script Structure

A typical script consists of:

-- Initialize any required variables
local width, height = render.get_screen_size()
local font = render.create_font("Arial", 16, true)

-- Register callback for rendering
function on_render()
    -- Your drawing code here
    render.draw_text(font, width/2, height/2, "Hello World", 255, 255, 255, 255, true)
end

-- Register the callback with the engine
engine.register_callback("render", on_render)

Common Tasks

Responding to User Input

function on_key_down(key)
    if key == 0x20 then  -- Space key
        engine.log("Space key pressed", 0, 255, 0, 255)
    end
end

engine.register_callback("key_down", on_key_down)

Drawing to the Screen

function on_render()
    -- Draw text
    render.draw_text(font, 100, 100, "Hello", 255, 255, 255, 255, false)
    
    -- Draw shapes
    render.draw_rectangle(200, 200, 100, 50, 255, 0, 0, 255, 1, false)
    render.draw_circle(400, 300, 30, 0, 255, 0, 255, 1, true)
    
    -- Draw line
    render.draw_line(100, 100, 500, 400, 0, 0, 255, 255, 1)
end

Reading and Writing Files

-- Write data to a file
local data = "This is some text data"
local success = fs.write_to_file("my_data.txt", data)

-- Read data from a file
local content = fs.read_file("my_data.txt")
if content then
    engine.log("File content: " .. content, 255, 255, 255, 255)
end

Making HTTP Requests

function on_response(status, response)
    if status == 200 then
        engine.log("Response: " .. response, 0, 255, 0, 255)
    else
        engine.log("Error: " .. status, 255, 0, 0, 255)
    end
end

networking.http_get("https://api.example.com/data", on_response)

Creating a Simple GUI

local window = gui.create_window("My Window", 100, 100, 300, 200)
local button = gui.create_button(window, "Click Me", 100, 50, 100, 30)

function on_button_click()
    engine.log("Button clicked!", 0, 255, 0, 255)
end

gui.set_button_callback(button, on_button_click)

Game-Specific Features

Each game has its own set of functions. Here's a simple example using Counter-Strike 2:

-- Only works when CS2 is running
function on_render()
    local local_player = cs2.get_local_player()
    if not local_player then return end
    
    -- Draw player information
    render.draw_text(font, 10, 10, "Player active", 0, 255, 0, 255, false)
end

Tips and Best Practices

1. Use descriptive variable names to make your code easier to read

2. Comment your code to explain what it does

3. Structure your code into functions for better organization

4. Check for nil values before using them to avoid errors

5. Test your scripts incrementally as you develop them

6. Use the engine.log function to debug your code

7. Install the VS Code extension for better productivity and code completion

Next Steps

Refer to the full documentation for detailed information on all available APIs:

• Engine API for core functionality

• Rendering API for drawing operations

• Input API for handling user interaction

• Game-Specific APIs for game-specific functions