> ## Documentation Index
> Fetch the complete documentation index at: https://lua.wingless.one/llms.txt
> Use this file to discover all available pages before exploring further.

# ESP

> Custom ESP elements drawn alongside the built-in player ESP.

Custom ESP elements drawn alongside the built-in player ESP.

## Functions

| Function | Description |
| - | - |
| `esp.add_text(name, fn [, options])` | Add a text element |
| `esp.add_bar(name, fn [, options])` | Add a bar element |
| `esp.add_icon(name, fn [, options])` | Add an icon element |
| `esp.remove(name)` | Remove by name |

### Callback

The callback receives the player pawn and returns what to draw:

```lua theme={null}
-- text callback: return string [, color]
esp.add_text('ping', function(pawn)
    local ctrl = entity.from_handle(pawn:get('m_hController', 'handle'))
    if not ctrl then return end
    return tostring(ctrl:ping()) .. 'ms', color(200, 200, 200)
end)

-- bar callback: return fraction (0..1) [, color]
esp.add_bar('speed', function(pawn)
    local vel = pawn:velocity():length2d()
    return math.clamp(vel / 250, 0, 1), color(100, 200, 255)
end)

-- icon callback: return texture [, color]
esp.add_icon('rank', function(pawn)
    return my_icon, color(255, 255, 255)
end)
```

### Options

| Field | Type | Default | Description |
| - | - | - | - |
| `side` | `string` | `"right"` | Position: `"left"`, `"right"`, `"top"`, `"bottom"` |
| `color` | `color` | white | Default color |
| `target` | `string` | `"enemy"` | `"enemy"`, `"team"`, `"all"` |

## Element methods

| Method | Returns | Description |
| - | - | - |
| `elem:remove()` | | Remove this element |
| `elem:settings([target])` | `table` | Per-target settings: `{enabled, side, color, second, size, text}` |

## player\_esp event

Called after a player's ESP box is drawn. Use `render.*` to draw custom visuals next to the box.

```lua theme={null}
events.on('player_esp', function(pawn, box)
    render.text(box.right + 4, box.top, color(255, 255, 255), 'custom', 's')
end)
```

**`box` fields:** `left`, `top`, `right`, `bottom` (screen coordinates).

## Example

```lua theme={null}
local hp = esp.add_text('hp_text', function(pawn)
    local h = pawn:health()
    local c = color(255, 255, 255):lerp(color(255, 50, 50), 1 - h / 100)
    return h .. ' HP', c
end, { side = 'left' })
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.