> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
title: ESP
icon: view
---

# <ApiPageIcon icon="view" />ESP

<ApiExposes data="[{&#x22;k&#x22;:&#x22;NAMESPACE&#x22;,&#x22;c&#x22;:&#x22;fn&#x22;,&#x22;s&#x22;:&#x22;esp&#x22;,&#x22;h&#x22;:&#x22;#esp-1&#x22;},{&#x22;k&#x22;:&#x22;OBJECT&#x22;,&#x22;c&#x22;:&#x22;method&#x22;,&#x22;s&#x22;:&#x22;esp.Element&#x22;,&#x22;h&#x22;:&#x22;#espelement&#x22;}]" />

<Heading level={2} id="esp-1">
  esp

  <ApiTag label="global table" />
</Heading>

Adds custom elements to the built-in ESP. Your script can draw extra information next to the
ESP of each entity, and the user can turn each element on or off in the menu.

<ApiMembers>
  <ApiMember kind="fn" name="esp.AddItem" summary="Adds a simple ESP element to the given category. The element appears in the ESP options, and the user can turn it on or off. The element does not draw anything by itself. Your script does the drawing." args="category, name" sig="[{&#x22;s&#x22;:&#x22;esp.AddItem&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;category&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;esp.Category&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/esp#esp-Category&#x22;},{&#x22;s&#x22;:&#x22;, &#x22;},{&#x22;s&#x22;:&#x22;name&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;esp.Element&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/esp#espelement&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;esp.Element&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/esp#espelement&#x22;}]]" params="[{&#x22;n&#x22;:&#x22;category&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;esp.Category&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/esp#esp-Category&#x22;}],&#x22;d&#x22;:&#x22;The ESP category to add the element to.&#x22;},{&#x22;n&#x22;:&#x22;name&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;}],&#x22;d&#x22;:&#x22;The name of the element in the menu.&#x22;}]" />

  <ApiMember kind="fn" name="esp.AddText" summary="Adds a custom text element. `callback` is called for each entity and returns the text to draw." args="category, name, preview, callback, position?" sig="[{&#x22;s&#x22;:&#x22;esp.AddText&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;category&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;esp.Category&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/esp#esp-Category&#x22;},{&#x22;s&#x22;:&#x22;, &#x22;},{&#x22;s&#x22;:&#x22;name&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;},{&#x22;s&#x22;:&#x22;, &#x22;},{&#x22;s&#x22;:&#x22;preview&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;},{&#x22;s&#x22;:&#x22;, &#x22;},{&#x22;s&#x22;:&#x22;callback&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;esp.AddText.Callback&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/esp#esp-AddText-Callback&#x22;},{&#x22;s&#x22;:&#x22;[, &#x22;},{&#x22;s&#x22;:&#x22;position&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;esp.Position&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/esp#esp-Position&#x22;},{&#x22;s&#x22;:&#x22;]&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;esp.Element&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/esp#espelement&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;esp.Element&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/esp#espelement&#x22;}]]" params="[{&#x22;n&#x22;:&#x22;category&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;esp.Category&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/esp#esp-Category&#x22;}],&#x22;d&#x22;:&#x22;The ESP category to add the element to.&#x22;},{&#x22;n&#x22;:&#x22;name&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;}],&#x22;d&#x22;:&#x22;The name of the element in the menu.&#x22;},{&#x22;n&#x22;:&#x22;preview&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;}],&#x22;d&#x22;:&#x22;The sample text that is shown in the preview in the menu.&#x22;},{&#x22;n&#x22;:&#x22;callback&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;esp.AddText.Callback&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/esp#esp-AddText-Callback&#x22;}],&#x22;d&#x22;:&#x22;Called for each entity. Returns the text to draw.&#x22;},{&#x22;n&#x22;:&#x22;position&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;esp.Position&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/esp#esp-Position&#x22;}],&#x22;d&#x22;:&#x22;The default position. Defaults to `esp.Position.kBottom`.&#x22;,&#x22;o&#x22;:true}]" />

  <ApiMember kind="fn" name="esp.AddBar" summary="Adds a custom bar element, similar to the built-in health bar. `callback` is called for each entity and returns the values of the bar." args="category, name, callback, position?" sig="[{&#x22;s&#x22;:&#x22;esp.AddBar&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;category&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;esp.Category&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/esp#esp-Category&#x22;},{&#x22;s&#x22;:&#x22;, &#x22;},{&#x22;s&#x22;:&#x22;name&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;},{&#x22;s&#x22;:&#x22;, &#x22;},{&#x22;s&#x22;:&#x22;callback&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;esp.AddBar.Callback&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/esp#esp-AddBar-Callback&#x22;},{&#x22;s&#x22;:&#x22;[, &#x22;},{&#x22;s&#x22;:&#x22;position&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;esp.Position&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/esp#esp-Position&#x22;},{&#x22;s&#x22;:&#x22;]&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;esp.Element&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/esp#espelement&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;esp.Element&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/esp#espelement&#x22;}]]" params="[{&#x22;n&#x22;:&#x22;category&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;esp.Category&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/esp#esp-Category&#x22;}],&#x22;d&#x22;:&#x22;The ESP category to add the element to.&#x22;},{&#x22;n&#x22;:&#x22;name&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;}],&#x22;d&#x22;:&#x22;The name of the element in the menu.&#x22;},{&#x22;n&#x22;:&#x22;callback&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;esp.AddBar.Callback&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/esp#esp-AddBar-Callback&#x22;}],&#x22;d&#x22;:&#x22;Called for each entity. Returns the values of the bar.&#x22;},{&#x22;n&#x22;:&#x22;position&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;esp.Position&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/esp#esp-Position&#x22;}],&#x22;d&#x22;:&#x22;The default position. Defaults to `esp.Position.kBottom`.&#x22;,&#x22;o&#x22;:true}]" />

  <ApiMember kind="type" name="esp.AddText.Callback" summary="The callback of a custom text element. It is called for each entity and returns the text to draw for that entity." ret="[[{&#x22;s&#x22;:&#x22;fun&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;entity&#x22;},{&#x22;s&#x22;:&#x22;:&#x22;},{&#x22;s&#x22;:&#x22; &#x22;},{&#x22;s&#x22;:&#x22;client.C_BaseEntity&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/dumped_data/schema/client/C_BaseEntity&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;:&#x22;},{&#x22;s&#x22;:&#x22; &#x22;},{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;}]]" params="[{&#x22;n&#x22;:&#x22;entity&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;client.C_BaseEntity&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/dumped_data/schema/client/C_BaseEntity&#x22;}]}]" returns="[{&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;}]}]">
    <ApiNotes>
      Return an empty string to hide the text for that entity. The callback receives **nil** when
      there is no entity. Return an empty string in that case.

      If the callback throws an error or returns a value that is not a string, nothing is drawn and
      the error is shown as a script error.
    </ApiNotes>
  </ApiMember>

  <ApiMember kind="type" name="esp.AddBar.Callback" summary="The callback of a custom bar element. It is called for each entity. The values are converted to integers." ret="[[{&#x22;s&#x22;:&#x22;fun&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;entity&#x22;},{&#x22;s&#x22;:&#x22;:&#x22;},{&#x22;s&#x22;:&#x22; &#x22;},{&#x22;s&#x22;:&#x22;client.C_BaseEntity&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/dumped_data/schema/client/C_BaseEntity&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;:&#x22;},{&#x22;s&#x22;:&#x22; &#x22;},{&#x22;s&#x22;:&#x22;integer&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#integer&#x22;},{&#x22;s&#x22;:&#x22;,&#x22;},{&#x22;s&#x22;:&#x22; &#x22;},{&#x22;s&#x22;:&#x22;integer&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#integer&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]]" params="[{&#x22;n&#x22;:&#x22;entity&#x22;,&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;client.C_BaseEntity&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/dumped_data/schema/client/C_BaseEntity&#x22;}]}]" returns="[{&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;integer&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#integer&#x22;}]},{&#x22;t&#x22;:[{&#x22;s&#x22;:&#x22;integer&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#integer&#x22;},{&#x22;s&#x22;:&#x22;?&#x22;}]}]">
    <ApiNotes>
      Return the current value, and optionally the maximum value. If you return a maximum, the bar is
      filled to the current value as a percentage of the maximum, from 0 to 100, and the bar shows the
      current value. If you do not return a maximum, the current value is used directly as the fill.

      Return a negative current value to hide the bar. A maximum of 0 or less also hides the bar. The
      callback receives **nil** when there is no entity. Return -1 in that case.

      If the callback throws an error or returns a value that is not a number, nothing is drawn and
      the error is shown as a script error.
    </ApiNotes>
  </ApiMember>

  <ApiMember kind="type" name="esp.Category" summary="The ESP categories that a custom element can be added to. The first two are the player ESP lists. The others are the world ESP lists. Each world list draws its own kind of entity." ret="[[{&#x22;s&#x22;:&#x22;integer&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#integer&#x22;}]]">
    <ApiEnum name="esp.Category" values="[[&#x22;kEnemy&#x22;,&#x22;0&#x22;,&#x22;The player ESP for enemies.&#x22;],[&#x22;kTeammates&#x22;,&#x22;1&#x22;,&#x22;The player ESP for teammates.&#x22;],[&#x22;kBomb&#x22;,&#x22;2&#x22;,&#x22;The world ESP for the planted and the dropped C4.&#x22;],[&#x22;kWeapon&#x22;,&#x22;3&#x22;,&#x22;The world ESP for dropped weapons.&#x22;],[&#x22;kHostages&#x22;,&#x22;4&#x22;,&#x22;The world ESP for hostages.&#x22;],[&#x22;kGrenades&#x22;,&#x22;5&#x22;,&#x22;The world ESP for grenades in flight and grenades that are deployed.&#x22;]]" />
  </ApiMember>

  <ApiMember kind="type" name="esp.Position" summary="The side of the ESP box where a custom text or bar element is placed at first. This value is only the default. If the user saved a position for the element, the saved position is used." ret="[[{&#x22;s&#x22;:&#x22;integer&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#integer&#x22;}]]">
    <ApiEnum name="esp.Position" values="[[&#x22;kLeft&#x22;,&#x22;0&#x22;,&#x22;On the left of the box.&#x22;],[&#x22;kTop&#x22;,&#x22;1&#x22;,&#x22;Above the box.&#x22;],[&#x22;kRight&#x22;,&#x22;2&#x22;,&#x22;On the right of the box.&#x22;],[&#x22;kBottom&#x22;,&#x22;3&#x22;,&#x22;Below the box.&#x22;]]" />

    <ApiNotes>
      The world ESP categories always place their elements at the bottom. They accept any value, but
      they always use `kBottom`.
    </ApiNotes>
  </ApiMember>
</ApiMembers>

## esp.Element<ApiTag label="object type" />

A handle to a custom ESP element that was created by `esp.AddItem`, `esp.AddText` or
`esp.AddBar`. Reading or writing a field that does not exist throws an error.

<ApiMembers>
  <ApiMember kind="prop" name="esp.Element.name" summary="The name of the element in the menu. Read-only." ret="[[{&#x22;s&#x22;:&#x22;string&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#string&#x22;}]]" />

  <ApiMember kind="prop" name="esp.Element.value" summary="Whether the user has turned the element on. You can also set this field." ret="[[{&#x22;s&#x22;:&#x22;boolean&#x22;,&#x22;k&#x22;:&#x22;prim&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/lua/base#boolean&#x22;}]]" />

  <ApiMember kind="method" name="esp.Element:AddGroup" summary="Returns the options group of the colour picker of the element. You can add more controls to this group." args="" sig="[{&#x22;s&#x22;:&#x22;esp.Element:AddGroup&#x22;},{&#x22;s&#x22;:&#x22;(&#x22;},{&#x22;s&#x22;:&#x22;)&#x22;},{&#x22;s&#x22;:&#x22;: &#x22;},{&#x22;s&#x22;:&#x22;ui.Group&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/ui#uigroup&#x22;}]" ret="[[{&#x22;s&#x22;:&#x22;ui.Group&#x22;,&#x22;k&#x22;:&#x22;class&#x22;,&#x22;h&#x22;:&#x22;/cs2/api_reference/rendering/ui#uigroup&#x22;}]]" />
</ApiMembers>
