### Full GUI API Test Example - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Perception GUI API.md

This Lua example demonstrates the creation and interaction with various GUI elements using the Perception API. It initializes a new panel, adds different types of widgets (checkbox, sliders, input text, static text, keybind, color picker, single/multi-select dropdowns, and single/multi-select lists), and includes a button with a callback function that prints the current state of all created widgets to the console.

```Lua
ui_state = {}
local tab = gui.get_tab("lua")
ui_state.panel = tab:create_panel("Full API Test", true)
-- Core widgets
ui_state.checkbox = ui_state.panel:add_checkbox("Enable Feature")
ui_state.slider_int = ui_state.panel:add_slider_int("Int Slider", 0, 10, 5)
ui_state.slider_float = ui_state.panel:add_slider_float("Float Slider", 0.0, 1.0, 0.5)
ui_state.input = ui_state.panel:add_input_text("Input Field", "default")
ui_state.text = ui_state.panel:add_text("Dynamic Text")
ui_state.keybind = ui_state.panel:add_keybind("Keybind", 45, key_mode.toggle)
ui_state.color_picker = ui_state.panel:add_color_picker("Color Picker", 255, 0, 0, 255)
-- Single & multi select
ui_state.single_select = ui_state.panel:add_single_select("Single Select", { "Option 1", "Option 2", "Option 3" }, 2)
ui_state.multi_select = ui_state.panel:add_multi_select("Multi Select", { "A", "B", "C" })
ui_state.multi_select:set(1, true)
ui_state.multi_select:set(3, true)
-- Input lists
ui_state.input_list_single = ui_state.panel:add_singleselect_list("Input List Single", { "Red", "Green", "Blue" })
ui_state.input_list_single:set(2)
ui_state.input_list_multi = ui_state.panel:add_multiselect_list("Input List Multi", { "One", "Two", "Three" })
ui_state.input_list_multi:set(1, true)
ui_state.input_list_multi:set(2, true)
-- Button with full test logic
ui_state.button = ui_state.panel:add_button("Test Button", function()
    print("[lua] Button pressed!")
    print("[lua] checkbox:", ui_state.checkbox:get())
    print("[lua] int slider:", ui_state.slider_int:get())
    print("[lua] float slider:", ui_state.slider_float:get())
    print("[lua] input:", ui_state.input:get())
    print("[lua] single select:", ui_state.single_select:get())
    print("[lua] color:", table.unpack({ ui_state.color_picker:get() }))
    print("[lua] keybind key:", ui_state.keybind:get_key(), "mode:", ui_state.keybind:get_mode(), "active:", ui_state.keybind:is_active())
    print("[lua] multi_select[1]:", ui_state.multi_select:get(1))
    print("[lua] multi_select[3]:", ui_state.multi_select:get(3))
    print("[lua] input_list_single:", ui_state.input_list_single:get())
    print("[lua] input_list_multi[1]:", ui_state.input_list_multi:get(1))
end)
```

--------------------------------

### Complete Process Attachment and Memory Reading Example (Lua)

Source: https://github.com/shadowthijs/perception-docs/blob/master/Process Functions.md

This comprehensive example showcases a full workflow: attaching to 'notepad.exe' by name, retrieving its base address, and then reading a specific 32-bit integer (DWORD) from a calculated offset within the process's memory. It includes robust error handling and logging for each step, demonstrating how to interact with process memory after successful attachment.

```lua
-- Attempt to attach to Notepad by process name
if not proc.attach_by_name("notepad.exe") then
    engine.log("Failed to attach to Notepad!", 255, 0, 0, 255)
    return
end
engine.log("Successfully attached to Notepad!", 0, 255, 0, 255)

-- Get the base address of Notepad
local base_address = proc.base_address()
if base_address == nil then
    engine.log("Failed to get Notepad base address!", 255, 0, 0, 255)
    return
end
engine.log("Base Address: " .. string.format("0x%X", base_address), 255, 255, 255, 255)

-- Define the offset for e_lfanew in the DOS header
local e_lfanew_offset = 0x3C
-- Read the e_lfanew value (DWORD) from the PE header
local e_lfanew = proc.read_int32(base_address + e_lfanew_offset)
if e_lfanew == nil then
    engine.log("Failed to read e_lfanew!", 255, 0, 0, 255)
    return
end
engine.log("e_lfanew: " .. e_lfanew, 0, 255, 0, 255)
```

--------------------------------

### Using Raw TCP Sockets for HTTP GET in Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Networking API.md

This snippet illustrates how to use the low-level socket API in Lua to perform a raw HTTP GET request. It demonstrates hostname resolution, establishing a TCP connection, sending raw HTTP headers, receiving a response chunk, and proper socket cleanup, providing fine-grained control over network communication.

```Lua
--Using socket API
local function log_info(msg)
    engine.log(msg, 255,255,255,255)
end
local function log_error(msg)
    engine.log(msg, 255,  0,  0,255)
end
-- resolve hostname
local ip = net.resolve("google.com")
if not ip then
    log_error("resolve failed for google.com")
    return
end
log_info("Resolved google.com → " .. ip)
-- open plain‐text HTTP on port 80
local sock, err = net.create_socket(ip, 80)
if not sock then
    log_error("connect failed: " .. err)
    return
end
log_info("Connected to " .. ip .. ":80")
-- build & send GET /
local req = table.concat({
    "GET / HTTP/1.1",
    "Host: google.com",
    "Connection: close",
    "",
    ""
}, "\r\n")
local sent, serr = sock:send(req)
if not sent then
    log_error("send failed: " .. serr)
    sock:close()
    return
end
log_info("Sent " .. sent .. " bytes")
-- receive up to 4096 bytes
local chunk, rerr = sock:receive(4096)
if not chunk then
    log_error("recv failed: " .. rerr)
else
    -- only log the first 200 chars
    local snippet = chunk:sub(1,200)
    log_info("Response snippet:\n" .. snippet)
end
-- cleanup
sock:close()
log_info("Socket closed")
```

--------------------------------

### Attaching to Process by Name (Lua)

Source: https://github.com/shadowthijs/perception-docs/blob/master/Process Functions.md

This example illustrates attaching to a process using its executable name, such as 'notepad.exe'. It includes error handling to log a failure message if the attachment is unsuccessful and then proceeds to log success. The 'has_corrupt_cr3' parameter is available for specific anti-cheat scenarios.

```lua
if not proc.attach_by_name("notepad.exe") then
    engine.log("Failed to attach to Notepad!", 255, 0, 0, 255)
    return
end
engine.log("Successfully attached to Notepad!", 0, 255, 0, 255)
```

--------------------------------

### Demonstrating Memory Allocation and I/O in Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Memory API.md

This Lua example illustrates the complete workflow of memory management using the 'm' API. It allocates a 64-byte memory block, writes different data types (32-bit integer, float, double, and 8-bit integer) to specific offsets, then reads these values back, logs them to the engine, and finally deallocates the memory. The snippet also includes a check for successful memory allocation.

```Lua
-- Allocate a memory block of 64 bytes
local memory_handle = m.alloc(64)

-- Check if allocation was successful
if memory_handle ~= nil then
    engine.log("Memory allocated successfully!", 0, 255, 0, 255)

    -- Write values to the allocated memory
    m.write_int32(memory_handle, 0, 123456)       -- Write a 32-bit integer at offset 0
    m.write_float(memory_handle, 4, 3.14)        -- Write a float at offset 4
    m.write_double(memory_handle, 8, 2.71828)    -- Write a double at offset 8
    m.write_int8(memory_handle, 16, 127)         -- Write an 8-bit integer at offset 16

    -- Read values from the allocated memory
    local int_value = m.read_int32(memory_handle, 0)
    local float_value = m.read_float(memory_handle, 4)
    local double_value = m.read_double(memory_handle, 8)
    local int8_value = m.read_int8(memory_handle, 16)

    -- Log the values read from memory
    engine.log("Read int32: " .. int_value, 255, 255, 255, 255)
    engine.log("Read float: " .. float_value, 255, 255, 255, 255)
    engine.log("Read double: " .. double_value, 255, 255, 255, 255)
    engine.log("Read int8: " .. int8_value, 255, 255, 255, 255)

    -- Free the allocated memory
    m.free(memory_handle)
    engine.log("Memory freed successfully!", 0, 255, 0, 255)
else
    engine.log("Memory allocation failed!", 255, 0, 0, 255)
end
```

--------------------------------

### Performing Process Memory Operations in Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Process API.md

This Lua example demonstrates comprehensive interaction with a process's memory using the 'proc' API. It covers checking if a process is attached, retrieving its ID, base address, and main module information. The snippet also shows how to find specific modules, read and write integer and string values in memory, and verify if the attached process has exited.

```Lua
-- Check if a process is attached
if proc.is_attached() then
    engine.log("Process is attached!", 0, 255, 0, 255)

    -- Get process details
    local process_id = proc.pid()
    local process_base = proc.base_address()
    local main_module, module_size = proc.get_base_module()

    engine.log("Process ID: " .. process_id, 255, 255, 255, 255)
    engine.log("Base Address: " .. process_base, 255, 255, 255, 255)
    engine.log("Main Module: " .. main_module .. " | Size: " .. module_size, 255, 255, 255, 255)

    -- Find a module by name
    local module_base, module_size = proc.find_module("example.dll")
    if module_base ~= nil then
        engine.log("Module 'example.dll' found at: " .. module_base, 0, 255, 0, 255)
    else
        engine.log("Module 'example.dll' not found!", 255, 0, 0, 255)
    end

    -- Read and write process memory
    local address = process_base + 0x1000  -- Example offset
    local original_value = proc.read_int32(address)
    engine.log("Original Value: " .. original_value, 255, 255, 255, 255)

    proc.write_int32(address, 99999)  -- Modify memory value
    engine.log("Modified Value: " .. proc.read_int32(address), 0, 255, 0, 255)

    -- String manipulation
    local str_address = process_base + 0x2000  -- Example string address
    local read_str = proc.read_string(str_address, 20)
    engine.log("Read String: " .. read_str, 255, 255, 255, 255)

    proc.write_string(str_address, "New String")
    engine.log("String Written Successfully!", 0, 255, 0, 255)

    -- Cleanup check
    if proc.did_exit() then
        engine.log("Attached process has exited!", 255, 0, 0, 255)
    end
else
    engine.log("No process is attached!", 255, 0, 0, 255)
end
```

--------------------------------

### Retrieving System Uptime with winapi.get_tickcount64 (Lua)

Source: https://github.com/shadowthijs/perception-docs/blob/master/Windows API.md

This function returns the system uptime in milliseconds as a 64-bit integer. It can be used to measure the duration since the system was last started.

--------------------------------

### Attaching to a Process and Reading Memory in Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Attach to a Process.md

This Lua snippet demonstrates how to attach to a process, specifically 'notepad.exe', using its name. After successful attachment, it retrieves the process's base address and then reads a 32-bit integer (DWORD) from a specific offset (0x3C, typically `e_lfanew` in a PE header) relative to the base address. The example includes error handling and logging for each step.

```Lua
-- Attempt to attach to Notepad by process name
if not proc.attach_by_name("notepad.exe") then
    engine.log("Failed to attach to Notepad!", 255, 0, 0, 255)
    return
end
engine.log("Successfully attached to Notepad!", 0, 255, 0, 255)
-- Get the base address of Notepad
local base_address = proc.base_address()
if base_address == nil then
    engine.log("Failed to get Notepad base address!", 255, 0, 0, 255)
    return
end
engine.log("Base Address: " .. string.format("0x%X", base_address), 255, 255, 255, 255)
-- Define the offset for e_lfanew in the DOS header
local e_lfanew_offset = 0x3C
-- Read the e_lfanew value (DWORD) from the PE header
local e_lfanew = proc.read_int32(base_address + e_lfanew_offset)
if e_lfanew == nil then
    engine.log("Failed to read e_lfanew!", 255, 0, 0, 255)
    return
end
engine.log("e_lfanew: " ..e_lfanew, 0, 255, 0, 255)
```

--------------------------------

### Getting Foreground Window Handle with winapi.get_foreground_window (Lua)

Source: https://github.com/shadowthijs/perception-docs/blob/master/Windows API.md

This function returns the handle (HWND) of the currently active foreground window. This is useful for interacting with the window that currently has user focus.

--------------------------------

### Checking Process Attachment Status (Lua)

Source: https://github.com/shadowthijs/perception-docs/blob/master/Process Functions.md

This example demonstrates how to use 'proc.is_attached()' to determine if a process is currently attached. It logs a message indicating whether a process is attached or not, providing a simple way to check the current state of process interaction.

```lua
if proc.is_attached() then
    engine.log("Process is attached", 0, 255, 0, 255)
else
    engine.log("No process is attached", 255, 0, 0, 255)
end
```

--------------------------------

### Handling User Input with Engine Tick in Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Input System API.md

This snippet demonstrates how to integrate various input functions (keyboard, mouse, clipboard, menu/overlay) into an `engine.on_engine_tick` callback in Lua. It shows how to detect key presses (is_key_pressed, is_key_down, is_key_toggled), get mouse coordinates and movement (get_mouse_position, get_mouse_move_delta, get_scroll_delta), manage clipboard data (get_clipboard, set_clipboard), and control overlay cursor behavior (is_menu_open, set_overlay_force_cursor_active).

```Lua
-- Check if a key is pressed and log it
function check_key_input()
    if input.is_key_pressed(32) then -- Spacebar key
        engine.log("Spacebar pressed!", 255, 255, 255, 255)
    end

    if input.is_key_down(17) then -- Ctrl key
        engine.log("Ctrl key is being held down!", 255, 255, 255, 255)
    end

    if input.is_key_toggled(20) then -- Caps Lock key
        engine.log("Caps Lock is toggled!", 255, 255, 255, 255)
    end
end

-- Get mouse position and movement delta
function check_mouse_input()
    local x, y = input.get_mouse_position()
    local dx, dy = input.get_mouse_move_delta()
    local scroll_delta = input.get_scroll_delta()

    engine.log("Mouse Position: " .. x .. ", " .. y, 255, 255, 255, 255)
    engine.log("Mouse Movement Delta: " .. dx .. ", " .. dy, 255, 255, 255, 255)
    engine.log("Mouse Scroll Delta: " .. scroll_delta, 255, 255, 255, 255)
end

-- Clipboard operations
function clipboard_example()
    local clipboard_text = input.get_clipboard()
    engine.log("Clipboard Content: " .. clipboard_text, 255, 255, 255, 255)

    input.set_clipboard("New Clipboard Data")
    engine.log("Clipboard updated!", 255, 255, 255, 255)
end

-- Menu and overlay handling
function menu_overlay_example()
    if input.is_menu_open() then
        engine.log("Menu is open!", 255, 255, 255, 255)
    else
        engine.log("Menu is closed!", 255, 255, 255, 255)
    end

    -- Force the cursor to remain active
    input.set_overlay_force_cursor_active(true)
    engine.log("Overlay cursor forced active!", 255, 255, 255, 255)
}

-- Register functions to be called every engine tick
engine.register_on_engine_tick(function()
    check_key_input()
    check_mouse_input()
    menu_overlay_example()
end)
```

--------------------------------

### Getting Window Handle with winapi.get_hwnd (Lua)

Source: https://github.com/shadowthijs/perception-docs/blob/master/Windows API.md

This function returns a window handle (HWND) as an integer. Both `class_name` and `window_name` parameters can be `nil` to perform a broader match for window identification.

--------------------------------

### Retrieving Transform Position - Rust - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Supported Games & Functions.md

This function retrieves the world-space transform position (X, Y, Z coordinates) from a given transform component address. It takes an integer pointer to the transform as input and returns three numbers representing the X, Y, and Z coordinates. The example shows how to log these coordinates using engine.log.

```Lua
local x, y, z = rust.get_transform_position(address)
engine.log("Transform position: (" .. x .. ", " .. y .. ", " .. z .. ")", 0, 255, 0, 255)
```

--------------------------------

### Getting Window Thread and Process IDs with winapi.get_window_thread_process_id (Lua)

Source: https://github.com/shadowthijs/perception-docs/blob/master/Windows API.md

This function returns the thread ID (tid) and process ID (pid) associated with the given window handle. This is useful for inter-process communication or debugging.

```Lua
local info = winapi.get_window_thread_process_id(some_window)
local tid = info.tid
local pid = info.pid
```

--------------------------------

### Retrieving Player Name - Fortnite - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Supported Games & Functions.md

This function retrieves the decrypted player name from a specified memory address. It requires an integer memory address as input and returns the player's name as a string. The example demonstrates logging the retrieved name using the engine.log function.

```Lua
local name = fortnite.get_player_name(address)
engine.log("Player name: " .. name, 0, 255, 0, 255)
```

--------------------------------

### Getting mat4 Column - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Returns the specified index (1-based) column of the matrix as a 4-component vector (vec4). This method is useful for extracting column vectors for further calculations.

```Lua
mat4:column(index)
```

--------------------------------

### Getting mat4 Element - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Retrieves the value at the specified row and col (1-based indexing) within the 4x4 matrix. This method allows direct access to individual elements of the matrix.

```Lua
mat4:get(row, col)
```

--------------------------------

### Getting mat4 Row - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Returns the specified index (1-based) row of the matrix as a 4-component vector (vec4). This method is useful for extracting row vectors for further calculations.

```Lua
mat4:row(index)
```

--------------------------------

### Demonstrating Basic Rendering Operations in Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/rendering API.md

This Lua snippet illustrates the usage of the `render` API for drawing various graphical elements. It initializes a font, retrieves screen dimensions, and then, within an `enginetick_callback` function, demonstrates drawing lines, filled rectangles, filled circles, text with an outline, and triangles, showcasing real-time rendering capabilities.

```Lua
-- Create a font for rendering text
local font_handle = render.create_font("verdana.ttf", 25)

-- Get the screen size
local screen_size_x, screen_size_y = render.get_viewport_size()

-- Callback function for rendering
function enginetick_callback()
    -- Draw a white diagonal line
    render.draw_line(500, 500, 600, 600, 255, 255, 255, 255, 5)

    -- Draw a filled yellow rectangle
    render.draw_rectangle(700, 700, 50, 50, 255, 255, 0, 255, 1, true)

    -- Draw a filled red circle
    render.draw_circle(900, 900, 25, 255, 0, 0, 255, 5, true)

    -- Draw text in magenta with a white outline
    render.draw_text(font_handle, "Test", 1000, 1000, 255, 0, 255, 255, 5, 255, 255, 255, 255)

    -- Draw a red triangle
    render.draw_triangle(500, 500,600, 600, 800, 800, 255, 0, 0, 255, 1, false)
end
```

--------------------------------

### Initializing UI Component Values in Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Perception GUI API.md

This code snippet shows how to programmatically set initial values for various UI components. It covers setting boolean states for checkboxes, numerical values for sliders, text for input fields, selected indices for single-selects, RGBA values for color pickers, and key codes/modes for keybinds. This is crucial for setting up the default state of a user interface.

```Lua
-- Initial setup for values
ui_state.checkbox:set(true)
ui_state.slider_int:set(7)
ui_state.slider_float:set(0.75)
ui_state.input:set("new input text")
ui_state.single_select:set(1)
ui_state.color_picker:set(0, 255, 128, 200)
ui_state.keybind:set_key(87)
ui_state.keybind:set_mode(key_mode.onhotkey)
ui_state.text:set("Click the button to see values!")
```

--------------------------------

### Managing Files with Filesystem API in Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/File System API.md

This Lua snippet demonstrates conditional file operations. It checks for the existence of 'test.txt'; if found, it reads, logs, and deletes the file. Otherwise, it creates 'test.txt' with 'test data' and logs its initial absence. It uses `fs` functions for file manipulation and `engine.log` for console output, with access restricted outside Documents/My Games.

```Lua
-- Check if the file "test.txt" exists
if fs.does_file_exist("test.txt") == true then
    -- Read the file contents
    local read_data = fs.read_from_file("test.txt")

    -- Delete the file after reading
    fs.delete_file("test.txt")

    -- Log the file contents
    engine.log(read_data, 255, 255, 255, 255)
else
    -- Create and write data to the file
    fs.write_to_file("test.txt", "test data")

    -- Log that the file did not exist
    engine.log("File does not exist", 255, 255, 255, 255)
end
```

--------------------------------

### Playing Sound Files with winapi.play_sound (Lua)

Source: https://github.com/shadowthijs/perception-docs/blob/master/Windows API.md

This function plays a specified sound file, supporting both .wav and .mp3 formats. The `file_name` can be a full path or a file located in the My Games directory.

--------------------------------

### Attaching to Process by Window (Lua)

Source: https://github.com/shadowthijs/perception-docs/blob/master/Process Functions.md

This snippet shows how to attach to a process by specifying its window class and window name. It includes a check for successful attachment and logs appropriate messages. This method is useful when the process name or PID is not readily available, but the window properties are known.

```lua
if not proc.attach_by_window("Notepad", "Untitled - Notepad") then
    engine.log("Failed to attach to Notepad window!", 255, 0, 0, 255)
    return
end
engine.log("Successfully attached to Notepad window!", 0, 255, 0, 255)
```

--------------------------------

### Sending HTTP Requests and Handling Responses in Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Networking API.md

This snippet demonstrates how to send an HTTP POST request to a specified URL with custom headers and POST data, and how to register a callback function to process the network response. The response data is written to a file and logged to the engine console, showcasing a common pattern for asynchronous network operations.

```Lua
-- Callback function to handle network responses
function network_callback(response_data,  url)
    fs.write_to_file_from_buffer("dump.txt", response_data)
    engine.log("Received network response: " .. m.read_string(response_data,0), 0, 255, 0, 255)
end

-- Register the network callback
engine.register_on_network_callback(network_callback)

-- Function to send an HTTP request
function send_example_request()
    local url = "https://example.com/api/data"
 
    -- Example headers
    local headers = "MyLuaClient/1.0";

    -- Example POST data
    local post_fields = "param1=value1&param2=value2"

    -- Send the HTTP request
    net.send_request(url, headers, post_fields)
 
    engine.log("Request sent to: " .. url, 255, 255, 255, 255)
end

-- Execute the function to send the request
send_example_request()
```

--------------------------------

### Constructing a 3D Vector - vec3 API

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Initializes a new 3D vector instance with specified X, Y, and Z components.

```Lua
vec3(x, y, z)
```

--------------------------------

### Constructing a 4D Vector - vec4 API

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Initializes a new 4D vector instance with specified X, Y, Z, and W components.

```Lua
vec4(x, y, z, w)
```

--------------------------------

### Compiling Lua to Bytecode and Stripping Debug Info (Bash)

Source: https://github.com/shadowthijs/perception-docs/blob/master/Lua to ByteCode.md

This `bash` command uses `luac.exe` to compile a Lua source file (`hello.lua`) into a bytecode file (`hello.luac`). The `-s` flag is crucial as it strips all debug information, resulting in a smaller and potentially more secure bytecode file. Be aware that some platforms or marketplaces may not accept Lua scripts in bytecode format.

```Bash
luac.exe -s -o hello.luac hello.lua
```

--------------------------------

### Constructing a 2D Vector - vec2 API

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Initializes a new 2D vector instance with specified X and Y components.

```Lua
vec2(x, y)
```

--------------------------------

### Performing Math and Utility Operations on 4D Vectors - vec4 API

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Functions for common vector mathematics including dot product, cloning, linear interpolation, clamping length, projection, and reflection off a surface normal.

```Lua
vec4:dot(v)
```

```Lua
vec4:clone()
```

```Lua
vec4:lerp(v, t)
```

```Lua
vec4:clamp_length(min, max)
```

```Lua
vec4.project_onto(v)
```

```Lua
vec4:reflect(normal)
```

--------------------------------

### Sending Windows Messages with winapi.post_message (Lua)

Source: https://github.com/shadowthijs/perception-docs/blob/master/Windows API.md

This function sends a Windows message to the specified window handle (`hwnd`). All arguments (`hwnd`, `msg`, `wparam`, `lparam`) must be integers. It returns a boolean indicating the success of the message posting operation.

--------------------------------

### Attaching to Process by PID (Lua)

Source: https://github.com/shadowthijs/perception-docs/blob/master/Process Functions.md

This snippet demonstrates how to attach to a process using its Process ID (PID). It checks the return value of 'proc.attach_by_pid' to determine if the attachment was successful and logs the outcome. The 'has_corrupt_cr3' parameter can be optionally set to true for games protected by Easy Anti-Cheat.

```lua
local process_id = 1234  -- Replace with actual PID
if proc.attach_by_pid(process_id) then
    engine.log("Successfully attached to process " .. process_id, 0, 255, 0, 255)
else
    engine.log("Failed to attach to process " .. process_id, 255, 0, 0, 255)
end
```

--------------------------------

### Retrieving Window Dimensions with winapi.get_window_rect (Lua)

Source: https://github.com/shadowthijs/perception-docs/blob/master/Windows API.md

This function returns the position and size of a window, providing `left`, `top`, `right`, and `bottom` coordinates. This allows for calculating the window's width and height.

```Lua
local rect = winapi.get_window_rect(some_window)
local width = rect.right - rect.left
local height = rect.bottom - rect.top
```

--------------------------------

### Checking Window Enabled State with winapi.is_window_enabled (Lua)

Source: https://github.com/shadowthijs/perception-docs/blob/master/Windows API.md

This function returns `true` if the specified window is enabled (i.e., accepts user input), and `false` otherwise. This is important for checking interactive capabilities.

--------------------------------

### Performing Operations on 3D Vectors - vec3 API

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Defines various arithmetic, negation, length, and equality comparison operators for 3D vectors, enabling common mathematical manipulations.

```Lua
vec3 + vec3
```

```Lua
vec3 - vec3
```

```Lua
vec3 * scalar
```

```Lua
vec3 / scalar
```

```Lua
-vec3
```

```Lua
#vec3
```

```Lua
vec3 == vec3
```

--------------------------------

### Creating Look-At View mat4 - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Constructs a view matrix that simulates a camera looking from an eye position towards a target point, with a specified up direction. This is commonly used to define the camera's orientation in a 3D scene.

```Lua
mat4.look_at(eye, target, up)
```

--------------------------------

### Checking Window Visibility with winapi.is_window_visible (Lua)

Source: https://github.com/shadowthijs/perception-docs/blob/master/Windows API.md

This function returns `true` if the specified window is currently visible, and `false` otherwise. It's useful for determining if a window is displayed on the screen.

--------------------------------

### Accessing 3D Vector Components - vec3 API

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Provides direct access to the individual X, Y, and Z components of a 3D vector.

```Lua
vec3.x
```

```Lua
vec3.y
```

```Lua
vec3.z
```

--------------------------------

### Accessing 4D Vector Components - vec4 API

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Provides direct access to the individual X, Y, Z, and W components of a 4D vector.

```Lua
vec4.x
```

```Lua
vec4.y
```

```Lua
vec4.z
```

```Lua
vec4.w
```

--------------------------------

### Registering Engine Lifecycle Callbacks in Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Registering Callbacks & Engine API.md

This Lua snippet demonstrates how to define and register various engine lifecycle callback functions. It includes callbacks for continuous execution on every engine tick, for logging a message when the script is unloaded, and for handling incoming network responses, ensuring proper event management within the engine.

```Lua
-- Callback function for engine tick (executed every tick)
function enginetick_callback()
    -- Your logic here (executed on every engine tick)
end

-- Callback function for when the script is unloaded
function on_unload_callback()
    engine.log("Script is being unloaded", 255, 255, 255, 255)
end

-- Callback function for network responses
function on_net_callback(str)
    engine.log("Network Response: " .. str, 255, 255, 255, 255)
end

-- Register the callbacks with the engine
engine.register_on_engine_tick(enginetick_callback)
engine.register_onunload(on_unload_callback)
engine.register_on_network_callback(on_net_callback)
```

--------------------------------

### Performing Operations on 4D Vectors - vec4 API

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Defines various arithmetic, negation, length, and equality comparison operators for 4D vectors, enabling common mathematical manipulations.

```Lua
vec4 + vec4
```

```Lua
vec4 - vec4
```

```Lua
vec4 * scalar
```

```Lua
vec4 / scalar
```

```Lua
-vec4
```

```Lua
#vec4
```

```Lua
vec4 == vec4
```

--------------------------------

### Retrieving Window Style with winapi.get_window_style (Lua)

Source: https://github.com/shadowthijs/perception-docs/blob/master/Windows API.md

This function returns the window style value as an integer. This value can be used to determine various visual and behavioral attributes of the window.

--------------------------------

### Parsing and Stringifying JSON in Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/JSON API.md

This snippet demonstrates how to parse a JSON string into a Lua table using `json.parse` and then convert the modified Lua table back into a JSON string using `json.stringify`. It shows accessing table elements, modifying them, and logging the results.

```Lua
-- Example JSON string
local raw = '{"name": "Nightlings", "version": 1.0, "features": ["gui", "overlay", "lua"]}'

-- Parse JSON into Lua table
local tbl = json.parse(raw)
engine.log("Project: " .. tbl.name)
engine.log("Version: " .. tostring(tbl.version))
engine.log("First feature: " .. tbl.features[1])

-- Modify the table
tbl.debug = true
tbl.features[#tbl.features + 1] = "json_api"

-- Convert back to JSON
local out = json.stringify(tbl)
engine.log("Updated JSON:")
engine.log(out)
```

--------------------------------

### Performing Operations on 2D Vectors - vec2 API

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Defines various arithmetic, negation, length, and equality comparison operators for 2D vectors, allowing for common mathematical manipulations.

```Lua
vec2 + vec2
```

```Lua
vec2 - vec2
```

```Lua
vec2 * scalar
```

```Lua
vec2 / scalar
```

```Lua
-vec2
```

```Lua
#vec2
```

```Lua
vec2 == vec2
```

--------------------------------

### Managing 3D Vector Angles and Orientation - vec3 API

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Methods for converting between angle representations (e.g., Euler angles to direction vectors), normalizing and clamping angles, and creating vectors from pitch/yaw values.

```Lua
vec3:to_forward()
```

```Lua
vec3:to_right()
```

```Lua
vec3:to_up()
```

```Lua
vec3:to_qangle()
```

```Lua
vec3:normalize_angles()
```

```Lua
vec3:clamp_angles()
```

```Lua
vec3.normalize_angle(angle)
```

```Lua
vec3.from_qangle(pitch, yaw)
```

--------------------------------

### Utilizing 2D Vector Methods - vec2 API

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Exposes a suite of methods for common vector operations including length calculation, normalization, dot product, distance, cloning, rotation, interpolation, projection, clamping, and reflection.

```Lua
vec2:length()
```

```Lua
vec2:length_squared()
```

```Lua
vec2:normalize()
```

```Lua
vec2:dot(v)
```

```Lua
vec2:distance(v)
```

```Lua
vec2:clone()
```

```Lua
vec2:perpendicular()
```

```Lua
vec2:angle()
```

```Lua
vec2:rotate(radians)
```

```Lua
vec2:lerp(v, t)
```

```Lua
vec2:project_onto(v)
```

```Lua
vec2:clamp_length(min, max)
```

```Lua
vec2:reflect(normal)
```

--------------------------------

### Performing Math and Directional Operations on 3D Vectors - vec3 API

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Functions for advanced vector mathematics including dot and cross products, distance calculation, angle determination, reflection, projection, and rotation around an arbitrary axis.

```Lua
vec3:dot(v)
```

```Lua
vec3:cross(v)
```

```Lua
vec3:distance(v)
```

```Lua
vec3:angle_between(v)
```

```Lua
vec3:reflect(normal)
```

```Lua
vec3.project_onto(v)
```

```Lua
vec3:rotate_axis(angle, axis)
```

--------------------------------

### Accessing 3D Vector Memory - vec3 API

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Provides functions to read and write 3D vector data from and to memory addresses, supporting both single and double-precision floating-point formats.

```Lua
vec3.read_float(address)
```

```Lua
vec3.read_double(address)
```

```Lua
vec3.write_float(address, v)
```

```Lua
vec3.write_double(address, v)
```

--------------------------------

### Creating Perspective Projection mat4 - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Constructs a perspective projection matrix. This matrix is essential for rendering 3D scenes, defining the camera's field of view (fov_y), aspect ratio (aspect), and the near and far clipping planes.

```Lua
mat4.perspective(fov_y, aspect, near, far)
```

--------------------------------

### Accessing 2D Vector Components - vec2 API

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Provides direct access to the individual X and Y components of a 2D vector.

```Lua
vec2.x
```

```Lua
vec2.y
```

--------------------------------

### Accessing 4D Vector Memory - vec4 API

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Provides functions to read and write 4D vector data from and to memory addresses, supporting both single and double-precision floating-point formats.

```Lua
vec4.read_float(address)
```

```Lua
vec4.read_double(address)
```

```Lua
vec4.write_float(address, v)
```

```Lua
vec4.write_double(address, v)
```

--------------------------------

### Accessing 2D Vector Memory - vec2 API

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Provides functions to read and write 2D vector data from and to memory addresses, supporting both single and double-precision floating-point formats.

```Lua
vec2.read_float(address)
```

```Lua
vec2.read_double(address)
```

```Lua
vec2.write_float(address, v)
```

```Lua
vec2.write_double(address, v)
```

--------------------------------

### Utilizing 3D Vector Utility Methods - vec3 API

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Provides general utility methods such as creating a copy of the vector, and performing linear or spherical linear interpolation between two vectors.

```Lua
vec3:clone()
```

```Lua
vec3:lerp(v, t)
```

```Lua
vec3:slerp(v, t)
```

--------------------------------

### Calculating 3D Vector Length and Normalization - vec3 API

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Methods for computing the length of a 3D vector (both 3D and 2D projections), its squared length, normalization, and clamping its magnitude within a specified range.

```Lua
vec3:length()
```

```Lua
vec3:length_2d()
```

```Lua
vec3:length_2d_squared()
```

```Lua
vec3:normalize()
```

```Lua
vec3:clamp_length(min, max)
```

--------------------------------

### Calculating 4D Vector Length and Normalization - vec4 API

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Methods for computing the magnitude of a 4D vector and returning a normalized version of it.

```Lua
vec4:length()
```

```Lua
vec4:normalize()
```

--------------------------------

### Creating mat4 from TRS Components - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Constructs a 4x4 transformation matrix from separate translation (position), rotation (rotation_quat as a quaternion), and scale (scale) components. This is a convenient way to build a combined transformation matrix.

```Lua
mat4.trs(position, rotation_quat, scale)
```

--------------------------------

### Toggling UI Element Visibility in Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Perception GUI API.md

This snippet demonstrates how to toggle the active state (visibility) of all UI elements within the `ui_state` table. It retrieves the current state of a checkbox and iterates through all UI components, calling their `set_active` method if available. This is typically used for dynamic UI display control.

```Lua
    print("[lua] input_list_multi[2]:", ui_state.input_list_multi:get(2))
    -- Toggle visibility
    local toggle = not ui_state.checkbox:get()
    for k, v in pairs(ui_state) do
        if v.set_active then v:set_active(toggle) end
    end
    print("[lua] Toggled all element visibility to:", toggle)
end)
```

--------------------------------

### Constructing mat4 from Lua Table - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Constructs a new 4x4 matrix from a given nested Lua table. This static method allows for easy initialization of matrices from Lua-native data structures, typically used for deserialization.

```Lua
mat4.from_table(table)
```

--------------------------------

### Comparing mat4 Equality - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Compares the current 4x4 matrix with another matrix (other) for equality. An optional tolerance (epsilon) can be provided for floating-point comparisons, allowing for slight numerical differences.

```Lua
mat4:equals(other, tolerance?)
```

--------------------------------

### Creating Identity mat4 - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Constructs and returns a new 4x4 identity matrix. This matrix has ones on its main diagonal and zeros elsewhere, serving as a neutral element for matrix multiplication.

```Lua
mat4()
```

--------------------------------

### Cloning mat4 - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Creates and returns a deep copy of the current 4x4 matrix. This ensures that modifications to the cloned matrix do not affect the original matrix.

```Lua
mat4:clone()
```

--------------------------------

### Creating Orthographic Projection mat4 - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Constructs an orthographic projection matrix. This matrix is used for 2D rendering or specific 3D views where perspective distortion is not desired, defining the viewing volume's bounds.

```Lua
mat4.orthographic(left, right, bottom, top, near, far)
```

--------------------------------

### Scaling mat4 - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Applies a scaling transformation to the matrix using the components of a 3-component vector (vec3). This modifies the matrix to scale subsequent transformations along the X, Y, and Z axes.

```Lua
mat4:scale(vec3)
```

--------------------------------

### Reading mat4 from Memory - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Reads a 4x4 matrix from the specified memory address. This static method is used for retrieving matrix data directly from external memory locations, assuming a default precision (likely float).

```Lua
mat4.read(address)
```

--------------------------------

### Transposing mat4 - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Returns a new matrix that is the transpose of the current 4x4 matrix. The transpose operation swaps rows and columns, which is useful in various linear algebra and graphics contexts.

```Lua
mat4:transpose()
```

--------------------------------

### Setting mat4 Element - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Sets the value at the specified row and col (1-based indexing) within the 4x4 matrix to the given value. This method allows modification of individual elements of the matrix.

```Lua
mat4:set(row, col, value)
```

--------------------------------

### Translating mat4 - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Applies a translation transformation to the matrix using the components of a 3-component vector (vec3). This modifies the matrix to shift subsequent transformations by the specified X, Y, and Z offsets.

```Lua
mat4:translate(vec3)
```

--------------------------------

### Inverting mat4 - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Returns a new matrix that is the inverse of the current 4x4 matrix. The inverse matrix, when multiplied by the original, yields the identity matrix, effectively 'undoing' the original transformation.

```Lua
mat4:inverse()
```

--------------------------------

### Applying mat4 Transformation to vec3 - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Applies the matrix's transformation to a 3-component vector (vec3). This is typically used for transforming points or directions in 3D space, ignoring the perspective component of the matrix.

```Lua
mat4:apply_to_vec3(vec3)
```

--------------------------------

### Converting mat4 to Lua Table - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Converts the 4x4 matrix into a nested Lua table representation. This can be useful for serialization, debugging, or interoperability with Lua-native data structures.

```Lua
mat4:to_table()
```

--------------------------------

### Multiplying mat4 by mat4 - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Performs matrix multiplication between two 4x4 matrices. This operation combines transformations represented by the matrices, resulting in a new matrix that represents the composite transformation.

```Lua
mat4 * mat4
```

--------------------------------

### Reading vec4 from Memory (Double) - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Reads a 4-component vector (vec4) from the specified memory address, interpreting the data as double-precision floating-point numbers. This function is used for retrieving double-precision vector data from external memory locations.

```Lua
vec4.read_double(address)
```

--------------------------------

### Writing vec4 to Memory (Double) - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Writes a 4-component vector (vec4) v to the specified memory address, storing the data as double-precision floating-point numbers. This function is used for persisting double-precision vector data to external memory locations.

```Lua
vec4.write_double(address, v)
```

--------------------------------

### Writing vec4 to Memory (Float) - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Writes a 4-component vector (vec4) v to the specified memory address, storing the data as single-precision floating-point numbers. This function is used for persisting float-precision vector data to external memory locations.

```Lua
vec4.write_float(address, v)
```

--------------------------------

### Reading vec4 from Memory (Float) - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Reads a 4-component vector (vec4) from the specified memory address, interpreting the data as single-precision floating-point numbers. This function is used for retrieving float-precision vector data from external memory locations.

```Lua
vec4.read_float(address)
```

--------------------------------

### Decomposing mat4 - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Decomposes the 4x4 matrix into its fundamental components: position (translation), rotation (as a quaternion), and scale (as a vec3). This is useful for extracting individual transformation properties from a combined matrix.

```Lua
mat4:decompose()
```

--------------------------------

### Transforming vec4 with mat4 - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Transforms a 4-component vector (vec4) using a 4x4 matrix. This operation applies the linear transformation (and potentially translation if the matrix is affine) represented by the matrix to the vector.

```Lua
mat4 * vec4
```

--------------------------------

### Calculating mat4 Determinant - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Calculates and returns the determinant of the 4x4 matrix. The determinant is a scalar value that provides information about the matrix's properties, such as whether it is invertible or if it represents a volume-preserving transformation.

```Lua
mat4:determinant()
```

--------------------------------

### Rotating mat4 - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Applies a rotation transformation to the matrix by a given angle (in radians) around a specified axis (vec3). This modifies the matrix to rotate subsequent transformations around the defined axis.

```Lua
mat4:rotate(angle, axis)
```

--------------------------------

### Checking mat4 Identity - Lua

Source: https://github.com/shadowthijs/perception-docs/blob/master/Vec2, Vec3, Vec4 & Mat4 API.md

Returns true if the current 4x4 matrix is an identity matrix, and false otherwise. This check is useful for determining if a matrix represents no transformation.

```Lua
mat4:is_identity()
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.