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

# ESP

> Add custom text, flags, and bars to the player ESP.

Add custom text and bars to player ESP. Position them in the preview.

Register elements when the script loads, outside callbacks. Each call takes a unique string `id` and an `options` table, and returns an element handle.

## esp.AddText / esp.AddFlag

`esp.AddText` and `esp.AddFlag` are aliases.

| Option        | Type / values                                   | Default  |
| ------------- | ----------------------------------------------- | -------- |
| `label`       | String; name shown while dragging               | ID       |
| `preview`     | String; sample text                             | Label    |
| `side`        | `left`, `right`, `top`, `bottom`                | `right`  |
| `color`       | `Color`; default text color                     | White    |
| `enabled`     | Boolean                                         | `true`   |
| `player_type` | `all`, `enemies`, `teammates`, `local`          | `all`    |
| `value`       | Function returning text and an optional `Color` | Required |

```lua theme={"dark"}
local flag = esp.AddText("status", {
    preview = "READY",
    color = Color(100, 255, 100),
    value = function(pawn, player)
        return "READY"
    end
})
```

## esp.AddBar

`esp.AddBar(id, options)` adds a bar.

| Option        | Type / values                                                     | Default  |
| ------------- | ----------------------------------------------------------------- | -------- |
| `label`       | String; name shown while dragging                                 | ID       |
| `preview`     | Number from `0` to `1`; sample fill                               | `0.65`   |
| `side`        | `left`, `right`, `top`, `bottom`                                  | `left`   |
| `color`       | `Color`; default bar color                                        | White    |
| `enabled`     | Boolean                                                           | `true`   |
| `player_type` | `all`, `enemies`, `teammates`, `local`                            | `all`    |
| `value`       | Function returning a fill from `0` to `1` and an optional `Color` | Required |

```lua theme={"dark"}
local bar = esp.AddBar("armor", {
    preview = 0.65,
    color = Color(100, 175, 255),
    value = function(pawn, player)
        return player.armor / 100
    end
})
```

## Layout

Layouts are saved per player type. Custom elements cannot attach to other elements.

## Value callback

`value(pawn, player)` runs for each player shown by ESP. `pawn` is an [entity](/entity); `player` contains:

| Fields                          | Description                        |
| ------------------------------- | ---------------------------------- |
| `health`, `max_health`, `armor` | Health and armor                   |
| `ammo`, `max_ammo`              | Weapon clip and capacity           |
| `index`, `name`                 | Pawn index and player name         |
| `player_type`                   | `enemies`, `teammates`, or `local` |

Return `nil` or `false` to hide an element without leaving a gap. Text flags also accept empty text. Bar fills must be finite and are clamped to `0–1`.

The preview uses the `preview` option. A callback error stops the script's callbacks until reload.

## Methods

All handles support these methods. `SetPreview` takes a string for text flags or a number for bars, followed by an optional `Color`.

```lua theme={"dark"}
flag:SetEnabled(false)           -- hide in ESP and preview
flag:IsEnabled()                 -- returns a boolean
flag:SetPreview("SAMPLE", Color(255, 180, 90))
bar:SetPreview(0.8)              -- color is optional
flag:Remove()                    -- true once, then false
```

Methods can be used in callbacks. `SetPreview` also updates the default color if supplied. Removed handles cannot be updated. Unloading the script removes its elements.