esp

ESP 元素注册。每个 ESP element 4 个 scenario 各自独立配色（INV / VIS / DWN / ALLY），由系统按玩家状态自动选；脚本读 esp.scenario 取当前预览 scenario，对 element 用 el:set_color(value, scenario) 改单个 scenario，或用 el.colors = {c0,c1,c2,c3} 一行批量。

---

esp.add(id, fn, opts?) → ESPElement

参数

• id : string — 元素唯一标识
• fn : function(p : PlayerEntity, ctx : table) — 每个玩家调用，返值多态：

fn 返回	行为
string	text 元素
number 0..1	bar 元素
table {text=, text_color=, bar=, bar_color=}	混合
nil（已使用 ctx.dl 画）	自由绘制
nil（未画）	不显示该玩家

• opts? —— 可选 table

  • label : string — 默认 = id

  • colors : table —— 4 元素 {c_inv, c_vis, c_dwn, c_ally}，每个 = {r,g,b,a}

  • dist : table —— {min_m, max_m}

  • settings : function(group : Groupbox) —— 元素额外控件 callback

  • kind : string —— "text"（默认）/ "bar" / "mixed" / "free"，控制 slot drag 行为：

    • "text" → 6 槽（顶 / 左上 / 左下 / 右上 / 右下 / 底）
    • "bar" → 4 槽（顶 / 左中 / 右中 / 底）
    • "mixed" → 4 bar 槽（约束最严，fn 同时返 text + bar）
    • "free" → 不进 slot UI（无 drag handle），用户用 ctx.dl / draw.* 全自由； scenarios / dist / cleanup 仍生效；fn 返回值任意（slot 系统不消费）

    必须和 fn 返回类型一致："text" 配 string / table.text；"bar" 配 number / table.bar；"mixed" 配 table {text=, bar=}；"free" 不消费 fn 返回值（用户自画）。不识别的值会 LOG_WARN 并回退 "text"。

ctx 字段：

字段	类型	说明
ctx.scenario	int	0..3，由系统按玩家状态决定
ctx.box	{min=Vec2, max=Vec2}	屏幕 bounding box
ctx.distance	number	距离（米）
ctx.dl	DrawList	当前帧前景 draw list（kind="free" 必用）

---

esp.find(id) → ESPElement | nil

esp.remove(id)

esp.elements : map<id, ESPElement> (pairs 可遍历)

esp.scenario : int (read-only)

esp.INV / esp.VIS / esp.DWN / esp.ALLY = 0 / 1 / 2 / 3

---

ESPElement 方法 / 字段

el:get_color(scenario?) → table<r,g,b,a> / el:set_color(value, scenario?)

不传 scenario = 当前 scenario。

el:get_enabled(scenario?) → bool / el:set_enabled(value, scenario?)

el.colors = {c0, c1, c2, c3}

一次性设 4 个 scenario 颜色。

el.enableds = {b0, b1, b2, b3}

一次性设 4 个 scenario enabled。

el.dist : table = {min_m, max_m}

el.label : string

---

示例

-- 文本元素：返字符串
esp.add("tag", function(p, ctx)
    if p.is_teammate then return "ALLY" end
    if p.is_visible  then return "VIS"  end
    return "INV"
end, {
    label  = "Tag",
    kind   = "text",
    colors = {
        { 0.85, 0.85, 0.85, 1.0 },  -- INV
        { 1.00, 0.35, 0.35, 1.0 },  -- VIS
        { 1.00, 0.80, 0.20, 1.0 },  -- DWN
        { 0.35, 0.85, 1.00, 1.0 },  -- ALLY
    },
    dist = { 5.0, 300.0 },
})

-- bar 元素：返 0..1
esp.add("hp_bar", function(p, ctx)
    local total = (p.health or 0) + (p.shield or 0)
    return total / 200.0
end, { kind = "bar" })

-- 自由绘制：用 ctx.dl 自画，fn 返 nil
esp.add("crosshair", function(p, ctx)
    local cx, cy = (ctx.box.min.x + ctx.box.max.x) * 0.5, ctx.box.min.y - 10
    draw.line(cx - 5, cy, cx + 5, cy, draw.rgba(1, 0, 0, 1))
    return nil
end, { kind = "free" })