> For the complete documentation index, see [llms.txt](https://valex.gitbook.io/valex/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://valex.gitbook.io/valex/external-lua-environment/main-lua-environment.md).

# Main Lua Environment

### Event System

The event system is how you run code. You must register callbacks to specific event names.

#### `valex.register(event_name, callback)`

Registers a function to be called by the internal event loop.

* **Parameters:** `event_name` \[string], `callback` \[function]
* **Returns:** `void`

**Event Types:**

* `"update"`: Runs every tick (approx 1ms). Use for logic/math.
* `"slow_update"`: Runs every second. Use for scanning instances.
* `"render"`: Runs every frame. **Only draw here.**

```lua
local function on_update()
    print("hey :)");
end

valex.register("update", on_update);
```

```lua
local function on_render()
    valex.draw_text("Hello", 100, 100, color3.white());
end

valex.register("render", on_render);
```

```lua
local function on_slow_update()
	print("i am very slow...");
end

valex.register("slow_update", on_slow_update);
```

***

### Engine

#### `valex.get_game()`

Returns the address of the DataModel.

* **Returns:** `uint64` (address)

```lua
local game = valex.get_game();
print(game);
```

#### `valex.get_place_id()`

Returns the current Place ID.

* **Returns:** `int64`

```lua
local place_id = valex.get_place_id();
print(place_id);
```

#### `valex.get_visual_engine()`

Returns the address of the Visual Engine.

* **Returns:** `uint64` (address)

```lua
local visuals = valex.get_visual_engine();
print(visuals);
```

#### `valex.get_dimensions()`

Returns the width and height of the viewport.

* **Returns:** `float`, `float`

```lua
local width, height = valex.get_dimensions();
print(width, height);
```

#### `valex.world_to_screen(world_position)`

Converts a 3D world position to 2D screen coordinates.

* **Parameters:** `world_position` \[vector3]
* **Returns:** `bool` (visible), `vector3` (x, y, depth)

```lua
local visual_engine = valex.get_visual_engine();
local world_pos = vector3.new(0, 10, 0);
local visible, screen_pos = valex.world_to_screen(world_pos);

if visible then
    print(screen_pos.x, screen_pos.y);
end;
```

***

### Instance

#### `valex.get_name(instance)`

Gets the Name property of an instance.

* **Parameters:** `instance` \[uint64]
* **Returns:** `string`

```lua
local game = valex.get_game();
print(valex.get_name(game)); -- Ugc
```

#### `valex.get_class_name(instance)`

Gets the ClassName property of an instance.

* **Parameters:** `instance` \[uint64]
* **Returns:** `string`

```lua
local game = valex.get_game();
print(valex.get_class_name(game)); -- DataModel
```

#### `valex.get_children(instance)`

Gets a list of child instances.

* **Parameters:** `instance` \[uint64]
* **Returns:** `table` (array of uint64)

```lua
local game = valex.get_game();
for _, child in pairs(valex.get_children(game)) do
    print(valex.get_name(child));
end;
```

#### `valex.get_parent(instance)`

Gets the Parent of an instance.

* **Parameters:** `instance` \[uint64]
* **Returns:** `uint64` (address)

```lua
local game = valex.get_game();
local workspace = valex.find_first_child(game, "Workspace");
local parent = valex.get_parent(workspace);
print(valex.get_name(parent)); -- Ugc
```

#### `valex.find_first_child(instance, name)`

Finds the first child with the specific name.

* **Parameters:** `instance` \[uint64], `name` \[string]
* **Returns:** `uint64` (address)

```lua
local game = valex.get_game();
local workspace = valex.find_first_child(game, "Workspace");
print(workspace);
```

#### `valex.find_first_child_of_class(instance, class_name)`

Finds the first child that matches the ClassName.

* **Parameters:** `instance` \[uint64], `class_name` \[string]
* **Returns:** `uint64` (address)

```lua
local game = valex.get_game();
local workspace = valex.find_first_child_of_class(game, "Workspace");
print(workspace);
```

#### `valex.get_service(instance, class_name)`

Alias for `find_first_child_of_class`, commonly used to get Services.

* **Parameters:** `instance` \[uint64], `class_name` \[string]
* **Returns:** `uint64` (address)

```lua
local game = valex.get_game();
local players = valex.get_service(game, "Players");
print(players);
```

#### `valex.is_a(instance, class_name)`

Checks if an instance inherits from a specific class.

* **Parameters:** `instance` \[uint64], `class_name` \[string]
* **Returns:** `bool`

```lua
local game = valex.get_game();
local workspace = valex.get_service(game, "Workspace");
if valex.is_a(workspace, "Workspace") then
    print("is workspace");
end;
```

***

### Humanoid

#### `valex.get_health(humanoid)`

Gets the current health.

* **Parameters:** `humanoid` \[uint64]
* **Returns:** `float`

```lua
local health = valex.get_health(humanoid_addr);
print(health);
```

#### `valex.get_max_health(humanoid)`

Gets the maximum health.

* **Parameters:** `humanoid` \[uint64]
* **Returns:** `float`

```lua
local max = valex.get_max_health(humanoid_addr);
print(max);
```

#### `valex.get_walk_speed(humanoid)`

Gets the WalkSpeed.

* **Parameters:** `humanoid` \[uint64]
* **Returns:** `float`

```lua
local speed = valex.get_walk_speed(humanoid_addr);
print(speed);
```

#### `valex.get_jump_power(humanoid)`

Gets the JumpPower.

* **Parameters:** `humanoid` \[uint64]
* **Returns:** `float`

```lua
local jump = valex.get_jump_power(humanoid_addr);
print(jump);
```

#### `valex.set_walk_speed(humanoid, value)`

Sets the WalkSpeed.

* **Parameters:** `humanoid` \[uint64], `value` \[float]
* **Returns:** `void`

```lua
valex.set_walk_speed(humanoid_addr, 25.0);
```

#### `valex.set_jump_power(humanoid, value)`

Sets the JumpPower. Must be between 0 and 1000.

* **Parameters:** `humanoid` \[uint64], `value` \[float]
* **Returns:** `void`

```lua
valex.set_jump_power(humanoid_addr, 100.0);
```

***

### Parts

#### `valex.get_part_position(part)`

Gets the world position of a part.

* **Parameters:** `part` \[uint64]
* **Returns:** `vector3`

```lua
local pos = valex.get_part_position(part_addr);
print(pos.x, pos.y, pos.z);
```

#### `valex.get_part_size(part)`

Gets the size of a part.

* **Parameters:** `part` \[uint64]
* **Returns:** `vector3`

```lua
local size = valex.get_part_size(part_addr);
print(size.x, size.y, size.z);
```

#### `valex.get_part_velocity(part)`

Gets the velocity of a part.

* **Parameters:** `part` \[uint64]
* **Returns:** `vector3`

```lua
local vel = valex.get_part_velocity(part_addr);
print(vel.x, vel.y, vel.z);
```

#### `valex.get_part(parent, name)`

Finds a child part by name within a parent instance.

* **Parameters:** `parent` \[uint64], `name` \[string]
* **Returns:** `uint64` (part address, 0 if not found)

```lua
local localPlayer = valex.get_local_player()
local character = valex.get_character(localPlayer)
local head = valex.get_part(character, "Head")
local hrp = valex.get_part(character, "HumanoidRootPart")

if head ~= 0 then
    local pos = valex.get_part_position(head)
    print("Head position: " .. pos.x .. ", " .. pos.y .. ", " .. pos.z)
end
```

***

### Player

#### `valex.get_character(player)`

Gets the character model of a player.

* **Parameters:** `player` \[uint64]
* **Returns:** `uint64` (address)

```lua
local char = valex.get_character(player_addr);
print(valex.get_name(char));
```

#### `valex.get_team(player)`

Gets the team of a player.

* **Parameters:** `player` \[uint64]
* **Returns:** `uint64` (address)

```lua
local team = valex.get_team(player_addr);
print(valex.get_name(team));
```

#### `valex.get_client(players_service)`

Gets the LocalPlayer from the Players service.

* **Parameters:** `players_service` \[uint64]
* **Returns:** `uint64` (address)

```lua
local game = valex.get_game();
local players = valex.get_service(game, "Players");
local local_player = valex.get_client(players);
print(valex.get_name(local_player));
```

***

### Camera

#### `valex.get_camera()`

Gets the current camera address.

* **Returns:** `uint64` (address)

```lua
local cam = valex.get_camera();
print(cam);
```

#### `valex.get_camera_position(camera)`

Gets the absolute world position of the camera.

* **Parameters:** `camera` \[uint64]
* **Returns:** `vector3`

```lua
local cam = valex.get_camera();
local pos = valex.get_camera_position(cam);
print(pos.x, pos.y, pos.z);
```

#### `valex.get_camera_fov(camera)`

Gets the camera Field Of View.

* **Parameters:** `camera` \[uint64]
* **Returns:** `float`

```lua
local cam = valex.get_camera();
print(valex.get_camera_fov(cam));
```

#### `valex.set_camera_fov(camera, value)`

Sets the camera Field Of View.

* **Parameters:** `camera` \[uint64], `value` \[float]
* **Returns:** `void`

```lua
local cam = valex.get_camera();
valex.set_camera_fov(cam, 120.0);
```

***

### Utility

#### `valex.show_console(show)`

Toggles the external debug console.

* **Parameters:** `show` \[bool]
* **Returns:** `void`

```lua
valex.show_console(true);
```

#### `valex.clear_console()`

Clears the console output.

* **Returns:** `void`

```lua
valex.clear_console();
```

#### `valex.get_finger_print()`

Returns the user's unique SID.

* **Returns:** `string`

```lua
print(valex.get_finger_print());
```

#### `valex.get_hwid()`

Alias for get\_finger\_print().

* **Returns:** `string`

```lua
print(valex.get_hwid());
```

#### `valex.set_clipboard(text)`

Copies text to the Windows clipboard.

* **Parameters:** `text` \[string]
* **Returns:** `void`

```lua
valex.set_clipboard("copied from lua");
```

***

### Input

#### `valex.mouse_click(button)`

Simulates a mouse click. Buttons: 0 = Left, 1 = Right, 2 = Middle.

* **Parameters:** `button` \[int32]
* **Returns:** `void`

```lua
valex.mouse_click(0); -- Left click
```

#### `valex.is_clicked(button)`

Checks if a mouse button is physically held down. Buttons: 0 = Left, 1 = Right, 2 = Middle.

* **Parameters:** `button` \[int32]
* **Returns:** `bool`

```lua
if valex.is_clicked(1) then
    print("Right mouse button held");
end;
```

#### `valex.mouse_scroll(delta)`

Simulates a mouse wheel scroll.

* **Parameters:** `delta` \[int32]
* **Returns:** `void`

```lua
valex.mouse_scroll(1); -- Scroll up
```

#### `valex.move_mouse(x, y)`

Moves the mouse to absolute screen coordinates.

* **Parameters:** `x` \[int32], `y` \[int32]
* **Returns:** `void`

```lua
valex.move_mouse(500, 500);
```

#### `valex.press_key(key)`

Simulates pressing a key down.

* **Parameters:** `key` \[int32] ([Virtual Key Code](https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes))
* **Returns:** `void`

```lua
valex.press_key(0x20); -- Spacebar
```

#### `valex.release_key(key)`

Simulates releasing a key.

* **Parameters:** `key` \[int32] ([Virtual Key Code](https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes))
* **Returns:** `void`

```lua
valex.release_key(0x20); -- Spacebar
```

#### `valex.is_key_pressed(key)`

Checks if a key is physically held down.

* **Parameters:** `key` \[int32] ([Virtual Key Code](https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes))
* **Returns:** `bool`

```lua
if valex.is_key_pressed(0x10) then
    print("Shift is held");
end;
```

***

### Files

#### `valex.read_file(filepath)`

Reads a file from the workspace folder.

* **Parameters:** `filepath` \[string]
* **Returns:** `string` (or nil if failed)

```lua
local content = valex.read_file("config.txt");
print(content);
```

#### `valex.write_file(filepath, content)`

Writes a file to the workspace folder.

* **Parameters:** `filepath` \[string], `content` \[string]
* **Returns:** `bool`

```lua
valex.write_file("config.txt", "my settings data");
```

***

### HTTP

#### `valex.http_get(url, headers, callback)`

Performs an asynchronous GET request.

* **Parameters:** `url` \[string], `headers` \[table], `callback` \[function]
* **Returns:** `void`

```lua
local function on_response(body)
    print("Response: ", body);
end;

valex.http_get("https://httpbin.org/get", {
    ["User-Agent"] = "Valex/1.0"
}, on_response);
```

#### `valex.http_post(url, headers, body, callback)`

Performs an asynchronous POST request.

* **Parameters:** `url` \[string], `headers` \[table], `body` \[string], `callback` \[function]
* **Returns:** `void`

```lua
local function on_response(body)
    print("Response: ", body);
end;

local json_body = "{\"key\": \"value\"}";

valex.http_post("https://httpbin.org/post", {
    ["Content-Type"] = "application/json",
    ["User-Agent"] = "Valex/1.0"
}, json_body, on_response);
```

***

### Drawing (Render Callback Only)

These functions can only be used inside a `render` callback.

#### `valex.draw_line(x1, y1, x2, y2, color, thickness, alpha)`

Draws a line.

* **Parameters:** x1, y1, x2, y2 \[float], color \[color3], thickness \[float], alpha \[optional float]

```lua
valex.draw_line(100, 100, 200, 200, color3.white(), 1.0);
```

#### `valex.draw_rect(x, y, w, h, color, thickness, alpha)`

Draws an outlined rectangle.

* **Parameters:** x, y, w, h \[float], color \[color3], thickness \[optional float], alpha \[optional float]

```lua
valex.draw_rect(50, 50, 100, 100, color3.red(), 1.0);
```

#### `valex.draw_filled_rect(x, y, w, h, color, thickness, alpha)`

Draws a filled rectangle.

* **Parameters:** x, y, w, h \[float], color \[color3], thickness \[optional float], alpha \[optional float]

```lua
valex.draw_filled_rect(50, 50, 100, 100, color3.blue(), 1.0);
```

#### `valex.draw_circle(x, y, radius, color, alpha, thickness)`

Draws an outlined circle.

* **Parameters:** x, y, radius \[float], color \[color3], alpha \[optional float], thickness \[optional float]

```lua
valex.draw_circle(500, 500, 50, color3.green());
```

#### `valex.draw_filled_circle(x, y, radius, color, alpha, thickness)`

Draws a filled circle.

* **Parameters:** x, y, radius \[float], color \[color3], alpha \[optional float], thickness \[optional float]

```lua
valex.draw_filled_circle(500, 500, 50, color3.yellow());
```

#### `valex.draw_triangle(x1, y1, x2, y2, x3, y3, color, alpha)`

Draws an outlined triangle.

* **Parameters:** x1, y1, x2, y2, x3, y3 \[float], color \[color3], alpha \[optional float]

```lua
valex.draw_triangle(10, 10, 20, 30, 30, 10, color3.white());
```

#### `valex.draw_filled_triangle(x1, y1, x2, y2, x3, y3, color, alpha)`

Draws a filled triangle.

* **Parameters:** x1, y1, x2, y2, x3, y3 \[float], color \[color3], alpha \[optional float]

```lua
valex.draw_filled_triangle(10, 10, 20, 30, 30, 10, color3.red());
```

#### `valex.draw_text(text, x, y, color, alpha)`

Draws text on the screen.

* **Parameters:** text \[string], x, y \[float], color \[color3], alpha \[optional float]

```lua
valex.draw_text("Hello World", 100, 100, color3.white());
```

#### `valex.get_text_size(text)`

Calculates size of text string.

* **Parameters:** text \[string]
* **Returns:** width \[float], height \[float]

```lua
local w, h = valex.get_text_size("Test");
print(w, h);
valex.get_text_size(text)
Calculates size of text string.
Parameters: text [string]Returns: width [float], height [float]

```

#### `valex.get_local_player()`

Returns the local player's address without needing to pass the Players service.

* **Parameters:** None
* **Returns:** address `[uintptr_t]` - The local player's address, or 0 if not available

```lua
local localPlayer = valex.getlocalplayer()
if localPlayer ~= 0 then
    local name = valex.get_name(localPlayer)
    print("Local player: " .. name)
    
    local character = valex.get_character(localPlayer)
    if character ~= 0 then
        print("Character found!")
    end
end
```

#### `valex.get_mouse_location()`

Returns the current mouse cursor position in screen coordinates.

* **Parameters:** None
* **Returns:** Table with fields:\
  • x \[float] - The X position of the mouse cursor\
  • y \[float] - The Y position of the mouse cursor

```lua
local localPlayer = valex.get_local_player()
if localPlayer ~= 0 then
    local name = valex.get_name(localPlayer)
    print("Local player: " .. name)
    
    local character = valex.get_character(localPlayer)
    if character ~= 0 then
        local head = valex.get_part(character, "Head")
        if head ~= 0 then
            local pos = valex.get_part_position(head)
            print("Head position: " .. pos.x .. ", " .. pos.y .. ", " .. pos.z)
        end
        
        local humanoid = valex.find_first_child(character, "Humanoid")
        if humanoid ~= 0 then
            local health = valex.get_health(humanoid)
            local maxHealth = valex.get_max_health(humanoid)
            print("Health: " .. health .. "/" .. maxHealth)
        end
    end
else
    print("Local player not found")
end
```

#### `valex.get_screen_size()`

Gets the current screen/viewport dimensions and center coordinates.

* **Parameters:** none
* **Returns:** `table`

```lua
local screen = valex.get_screen_size()

print("Width: " .. screen.width)
print("Height: " .. screen.height)
print("Center X: " .. screen.center_x)
print("Center Y: " .. screen.center_y)

valex.register("render", function()
    local s = valex.get_screen_size()
    local size = 10
    
    valex.draw_line(s.center_x - size, s.center_y, s.center_x + size, s.center_y, color3.green(), 2)

    valex.draw_line(s.center_x, s.center_y - size, s.center_x, s.center_y + size, color3.green(), 2)
end)

print("Crosshair drawn at center!")
```

| Field     | Type  | Description                   |
| --------- | ----- | ----------------------------- |
| width     | float | Screen width in pixels        |
| height    | float | Screen height in pixels       |
| center\_x | float | X coordinate of screen center |
| center\_y | float | Y coordinate of screen center |
|           |       |                               |

#### `valex.get_player_health(player_address?)`

Returns the health information for a player. If no player address is provided, returns the local player's health.

* **Parameters:**
  * `player_address` (optional): `number` - The player address. If omitted, uses the local player.
* **Returns:** `table`
  * `health`: `number` - Current health value
  * `max_health`: `number` - Maximum health value
  * `is_alive`: `boolean` - Whether the player is alive (health > 0)

```lua
local function print_all_players_health()
    print("Health Monitor")
    
    local players = aim.get_players(false, false)
    
    for i, player_addr in ipairs(players) do
        local hp = valex.get_player_health(player_addr)
        local info = aim.get_player_info(player_addr)
        
        if info.exists then
            local status = hp.is_alive and "ALIVE" or "DEAD"
            local team_tag = info.is_local and "[YOU]" or (info.is_team and "[TEAM]" or "[ENEMY]")
            
            print(string.format("%s %s: %.0f/%.0f HP (%s)", 
                team_tag, 
                info.name, 
                hp.health, 
                hp.max_health, 
                status
            ))
        end
    end
    
    print("The End")
end

print_all_players_health()

valex.register("slow_update", function()
    print_all_players_health()
end)

print("Health monitor started! Updates every second.")
```