> 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/teleport-library-lua-environment.md).

# Teleport Library Lua Environment

## TP (Teleport) Library Documentation

The `tp` library provides functions for teleporting and position management.

***

### Position

#### `tp.get_position()`

Returns the local player's current position.

* **Returns:** `table` with fields:
  * `x` \[float] - X coordinate
  * `y` \[float] - Y coordinate
  * `z` \[float] - Z coordinate
  * `valid` \[bool] - Whether position is valid

```lua
local pos = tp.get_position()
if pos.valid then
    print("Position: " .. pos.x .. ", " .. pos.y .. ", " .. pos.z)
end
```

#### `tp.get_player_position(player_addr)`

Returns a player's current position.

* **Parameters:** `player_addr` \[uint64] - Player address
* **Returns:** `table` with fields:
  * `x` \[float] - X coordinate
  * `y` \[float] - Y coordinate
  * `z` \[float] - Z coordinate
  * `valid` \[bool] - Whether position is valid

```lua
local players = aim.get_players()
for _, addr in ipairs(players) do
    local pos = tp.get_player_position(addr)
    if pos.valid then
        local info = aim.get_player_info(addr)
        print(info.name .. " is at: " .. pos.x .. ", " .. pos.y .. ", " .. pos.z)
    end
end
```

***

### Teleportation

#### `tp.to_position(x, y, z)`

Teleports the local player to coordinates.

* **Parameters:**
  * `x` \[float] - X coordinate
  * `y` \[float] - Y coordinate
  * `z` \[float] - Z coordinate
* **Returns:** `bool` - Success

```lua
if tp.to_position(0, 100, 0) then
    print("Teleported!")
end
```

#### `tp.to_vector(position)`

Teleports the local player to a vector3 position.

* **Parameters:** `position` \[vector3] - Target position
* **Returns:** `bool` - Success

```lua
local target = vector3(100, 50, 200)
tp.to_vector(target)
```

#### `tp.to_player(player_addr, offset_x?, offset_y?, offset_z?)`

Teleports to another player's position.

* **Parameters:**
  * `player_addr` \[uint64] - Target player address
  * `offset_x` \[optional float] - X offset (default: 0)
  * `offset_y` \[optional float] - Y offset (default: 0)
  * `offset_z` \[optional float] - Z offset (default: 0)
* **Returns:** `bool` - Success

```lua
local target = aim.get_closest_target()
if target.address ~= 0 then
    tp.to_player(target.address, 5, 0, 0)
end
```

#### `tp.to_closest(team_check?, offset_x?, offset_y?, offset_z?)`

Teleports to the closest player.

* **Parameters:**
  * `team_check` \[optional bool] - Skip teammates (default: false)
  * `offset_x` \[optional float] - X offset (default: 0)
  * `offset_y` \[optional float] - Y offset (default: 0)
  * `offset_z` \[optional float] - Z offset (default: 0)
* **Returns:** `bool` - Success

```lua
valex.register("update", function()
    if aim.is_key_held(aim.keys.F) then
        tp.to_closest(false, 0, 5, 0)
    end
end)
```

#### `tp.offset(x, y, z)`

Moves the local player by a relative offset.

* **Parameters:**
  * `x` \[float] - X offset
  * `y` \[float] - Y offset
  * `z` \[float] - Z offset
* **Returns:** `bool` - Success

```lua
valex.register("update", function()
    if aim.is_key_held(aim.keys.UP) then
        tp.offset(0, 5, 0)
    end
end)
```

#### `tp.behind_player(player_addr, distance?)`

Teleports behind a player.

* **Parameters:**
  * `player_addr` \[uint64] - Target player address
  * `distance` \[optional float] - Distance behind (default: 5)
* **Returns:** `bool` - Success

```lua
valex.register("update", function()
    if aim.is_key_held(aim.keys.G) then
        local target = aim.get_closest_target()
        if target.address ~= 0 then
            tp.behind_player(target.address, 3)
        end
    end
end)
```

***

### Distance

#### `tp.get_distance(player_addr)`

Returns the distance to a player in studs.

* **Parameters:** `player_addr` \[uint64] - Player address
* **Returns:** `float` - Distance in studs (-1 if invalid)

```lua
local players = aim.get_players()
for _, addr in ipairs(players) do
    local dist = tp.get_distance(addr)
    local info = aim.get_player_info(addr)
    print(info.name .. ": " .. dist .. " studs away")
end
```

#### `tp.get_distance_to_position(x, y, z)`

Returns the distance to a position in studs.

* **Parameters:**
  * `x` \[float] - X coordinate
  * `y` \[float] - Y coordinate
  * `z` \[float] - Z coordinate
* **Returns:** `float` - Distance in studs (-1 if invalid)

```lua
local dist = tp.get_distance_to_position(0, 0, 0)
print("Distance to origin: " .. dist .. " studs")
```

#### `tp.get_players_by_distance(exclude_team?, exclude_dead?)`

Returns all players sorted by distance (closest first).

* **Parameters:**
  * `exclude_team` \[optional bool] - Exclude teammates (default: false)
  * `exclude_dead` \[optional bool] - Exclude dead players (default: true)
* **Returns:** `table` - Array of player entries with:
  * `address` \[uint64] - Player address
  * `distance` \[float] - Distance in studs
  * `name` \[string] - Player name

```lua
local players = tp.get_players_by_distance(false, true)
print("Closest players:")
for i, player in ipairs(players) do
    print(i .. ". " .. player.name .. " - " .. player.distance .. " studs")
    if i >= 5 then break end
end
```

***

### Complete Examples

#### Teleport Tool

```lua
-- Press F to teleport to closest player
-- Press G to teleport behind closest player
-- Press H to teleport up 50 studs

valex.register("update", function()
    if aim.is_key_held(aim.keys.F) then
        tp.to_closest()
    end
    
    if aim.is_key_held(aim.keys.G) then
        local target = aim.get_closest_target()
        if target.address ~= 0 then
            tp.behind_player(target.address, 5)
        end
    end
    
    if aim.is_key_held(aim.keys.H) then
        tp.offset(0, 50, 0)
    end
end)

print("Teleport Tool loaded!")
print("F = TP to closest | G = TP behind | H = TP up")
```

#### Player Distance ESP

```lua
valex.register("render", function()
    local players = tp.get_players_by_distance(false, true)
    
    local y_offset = 100
    for i, player in ipairs(players) do
        local text = player.name .. ": " .. math.floor(player.distance) .. " studs"
        valex.draw_text(text, 10, y_offset, color3.white())
        y_offset = y_offset + 20
        
        if i >= 10 then break end
    end
end)

print("Distance ESP loaded!")
```

#### Save/Restore Position

```lua
local saved_position = nil

valex.register("update", function()
    -- Press 1 to save position
    if aim.is_key_held(aim.keys["1"]) then
        saved_position = tp.get_position()
        if saved_position.valid then
            print("Position saved: " .. saved_position.x .. ", " .. saved_position.y .. ", " .. saved_position.z)
        end
    end
    
    -- Press 2 to restore position
    if aim.is_key_held(aim.keys["2"]) then
        if saved_position and saved_position.valid then
            tp.to_position(saved_position.x, saved_position.y, saved_position.z)
            print("Teleported to saved position!")
        else
            print("No position saved!")
        end
    end
end)

print("Position Saver loaded!")
print("1 = Save position | 2 = Restore position")
```