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

---
title: Reading Entities
icon: square-mouse-pointer
sidebar_position: 2
---

# Reading Entities

An entity value is a live Source 2 object wrapped for Lua. You can call
Neverlose helper methods on it and, when needed, read raw fields listed in the
Schema tree.

## Start with the right lookup

<Tabs items={["local player", "players", "pawns only", "class list"]}>
  <Tab title="local player">
    ```lua luaintelligence="true" semantic="lua:cs2:cs2/dumped_data/overview/reading-entities:0:4da9aa5bc984"
    local controller, pawn = entity.GetLocalPlayer()

    if controller and pawn then
        print(controller:GetPlayerName(), ": ", pawn:GetHealth(), " hp")
    end
    ```
  </Tab>

  <Tab title="players">
    ```lua luaintelligence="true" semantic="lua:cs2:cs2/dumped_data/overview/reading-entities:1:f3de8650d15d"
    for controller, pawn in entity.IteratePlayers(true, false) do
        print(controller:GetPlayerName(), " at ", pawn:GetAbsOrigin())
    end
    ```
  </Tab>

  <Tab title="pawns only">
    ```lua luaintelligence="true" semantic="lua:cs2:cs2/dumped_data/overview/reading-entities:2:c84080ed698b"
    for _, pawn in ipairs(entity.GetPlayerPawns(false, false)) do
        print(pawn:EntIndex(), ": ", pawn:GetActiveWeapon())
    end
    ```
  </Tab>

  <Tab title="class list">
    ```lua luaintelligence="true" semantic="lua:cs2:cs2/dumped_data/overview/reading-entities:3:ed0e05e417af"
    for _, bomb in ipairs(entity.ListByClassName("C_PlantedC4")) do
        print(bomb:GetAbsOrigin())
    end
    ```
  </Tab>
</Tabs>

`entity.IteratePlayers(enemies_only, include_dead, relative_to)` yields
controller/pawn pairs. `entity.GetPlayerPawns` returns a Lua array of pawns;
`entity.GetPlayerControllers` returns a Lua array of controllers. Their optional
`relative_to` argument chooses the entity used for enemy filtering.

`GetLocalPlayerPawn()` returns the pawn you act as, including a bot you control;
`GetOwnLocalPlayerPawn()` always returns your own player pawn; `GetLocalPawn()`
can be an observer pawn. For overlays that follow the spectator camera,
use `GetViewPawn()` and pass it as `relative_to` when filtering enemies:

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/dumped_data/overview/reading-entities:4:22f9a5f7e00b"
local view_pawn = entity.GetViewPawn()
if view_pawn then
    for controller, pawn in entity.IteratePlayers(true, false, view_pawn) do
        print(controller:GetPlayerName(), ": ", pawn:GetHealth(), " hp")
    end
end
```

## Validate live objects

Entities can become invalid when the game changes level, a round resets, or a
player disconnects. An entity that stops networking becomes dormant instead:
still valid, but with stale fields. Reacquire entities close to where
you use them, and check validity before reading saved references.

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/dumped_data/overview/reading-entities:5:f0d2e0b4bf4f"
local pawn = entity.GetLocalPlayerPawn()

if not pawn or not pawn:IsValid() or pawn:IsDormant() then
    return
end

print(pawn:GetHealth(), " hp at ", pawn:GetAbsOrigin())
```

Use this as the default pattern for per-frame code:

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/dumped_data/overview/reading-entities:6:6e84e71f9263"
events.render(function()
    for controller, pawn in entity.IteratePlayers(true, false) do
        if pawn:IsValid() and not pawn:IsDormant() then
            print(controller:GetPlayerName(), ": ", pawn:GetHealth(), " hp")
        end
    end
end)
```

<Warning>
  `:IsValid()` means the engine can still resolve the entity. `:IsDormant()` means the entity is not currently replicated. A dormant entity can still exist, but raw fields may be stale.
</Warning>

## Use helpers first

Helpers are the readable path for common CS2 data. The following lists show method calls on an already acquired `ent`, `pawn`, or `weapon`; they are reference fragments, not standalone scripts:

<Columns cols={2}>
  <Column>
    **General entity helpers**

    ```lua lines=false
    ent:GetClassName()
    ent:GetDesignerName()
    ent:EntIndex()
    ent:GetRefEHandle()
    ent:GetHealth()
    ent:GetAbsOrigin()
    ent:GetAbsAngles()
    ent:GetAbsVelocity()
    ent:GetOwnerEntity()
    ent:GetSkeleton()
    ```
  </Column>

  <Column>
    **CS2 helpers**

    ```lua lines=false
    pawn:GetPlayerController()
    pawn:GetActiveWeapon()
    pawn:GetMyWeapons()
    pawn:GetEyePosition()
    pawn:GetEyeAngles()
    pawn:GetAbsViewOffset()
    pawn:IsEnemy()
    weapon:GetWeaponData()
    ```
  </Column>
</Columns>

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/dumped_data/overview/reading-entities:9:13eb763104f0"
local pawn = entity.GetLocalPlayerPawn()

if pawn and pawn:IsValid() then
    local weapon = pawn:GetActiveWeapon()
    if weapon and weapon:IsValid() then
        local vdata = weapon:GetWeaponData()
        if vdata then
            print(weapon:GetClassName(), " max clip ", vdata.m_iMaxClip1)
        end
    end
end
```

## Read raw fields when no helper exists

Raw field names must match the Schema page exactly.

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/dumped_data/overview/reading-entities:10:66f30c8b285d"
local pawn = entity.GetLocalPlayerPawn()

if pawn and pawn:IsValid() and not pawn:IsDormant() then
    print(pawn.m_iHealth)
    print(pawn.m_ArmorValue)
    print(pawn.m_fFlags)
end
```

Nested schema objects can be chained:

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/dumped_data/overview/reading-entities:11:fc3fa4c16b1d"
local pawn = entity.GetLocalPlayerPawn()
local weapon = pawn and pawn:IsValid() and pawn:GetActiveWeapon()
local skeleton = weapon and weapon:IsValid() and weapon:GetSkeleton()

if skeleton then
    print(skeleton.m_modelState.m_ModelName)
end
```

## Common singletons

CS2 exposes common game objects directly:

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/dumped_data/overview/reading-entities:12:c24793be774f"
local rules = entity.GetGameRules()
local mode_rules = entity.GetGameModeRules()
local resource = entity.GetPlayerResource()
```

These lookups can return `nil` outside the relevant game state. Check the result
before reading fields. Open their Schema pages for round state, player resource
data, and game-mode-specific values.

## World and designer lookups

Use Schema class names when you know the class, and designer names when you know
the map/entity designer name.

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/dumped_data/overview/reading-entities:13:a445ce597bd5"
for _, grenade in ipairs(entity.ListByClassName("C_BaseCSGrenadeProjectile", true)) do
    print(grenade:GetClassName(), " at ", grenade:GetAbsOrigin())
end

for _, ak in entity.IterateByDesignerName("weapon_ak47") do
    print(ak:EntIndex(), " ", ak:GetDesignerName())
end
```

Use `entity.Iterate()` for all entities, `entity.IterateByClassName(classname,
recursive)` for a class-filtered loop, and `entity.FirstByClassName(classname,
recursive)` when you only need one match. The first-match lookup returns `nil`
when no entity matches.

## Useful Schema pages

<CardGroup cols={3}>
  <Card title="C_BaseEntity" icon="box" href="/cs2/dumped_data/schema/client/C_BaseEntity">
    Base class for many networked objects. Start here for inherited fields.
  </Card>

  <Card title="C_CSPlayerPawn" icon="person-standing" href="/cs2/dumped_data/schema/client/C_CSPlayerPawn">
    The in-world player body: movement, health, armor, view, weapons, and hitboxes.
  </Card>

  <Card title="CCSPlayerController" icon="gamepad-2" href="/cs2/dumped_data/schema/client/CCSPlayerController">
    The player controller: names, slots, user IDs, and pawn ownership.
  </Card>
</CardGroup>
