> ## 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.

# Entity

> Access CS2 entities and schema fields through typed Lua objects.

Typed entity objects with runtime schema field access.

```lua theme={"dark"}
local pawn = entity.GetLocalPlayer()
if pawn and pawn.m_iHealth > 0 then
    local weapon = pawn.m_pWeaponServices.m_hActiveWeapon  -- pointer chain + handle resolve
    print(weapon.class_name, weapon.m_iClip1)
end
```

## Field access

`pawn.m_iHealth` and `pawn["m_iHealth"]` both work. Assignment writes straight to game memory: `pawn.m_flVelocityModifier = 1.0`.

Unknown fields, unsupported types, and protected memory access raise errors.

| Schema type                                                                                                                                                                        | Lua value                                                         |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `bool`                                                                                                                                                                             | boolean                                                           |
| `int8`…`uint64`, `float32`, `float64`, `CNetworkedQuantizedFloat`, `GameTime_t`, `GameTick_t`                                                                                      | number                                                            |
| `Vector`, `VectorWS`, and the networked variants (`CNetworkVelocityVector`, `CNetworkViewOffsetVector`, `CNetworkOriginQuantizedVector`, `CNetworkOriginCellCoordQuantizedVector`) | [`Vector`](/vector)                                               |
| `QAngle`                                                                                                                                                                           | [`QAngle`](/vector#qangle)                                        |
| `CHandle< T >`                                                                                                                                                                     | entity object (resolved via entity list, runtime class), or `nil` |
| `CUtlString`, `CUtlSymbolLarge`                                                                                                                                                    | string, or `nil`                                                  |
| `T*` (known class)                                                                                                                                                                 | entity object (declared class), or `nil`                          |
| `T*` (unknown class)                                                                                                                                                               | address number, or `nil`                                          |
| embedded schema struct                                                                                                                                                             | entity object at the field's address                              |
| anything else                                                                                                                                                                      | error on access                                                   |

Writable: booleans, numbers, `Vector`/`QAngle` (assign a typed object or the `{x=,y=,z=}` / `{pitch=,yaw=,roll=}` table). Everything else is read-only.

`int64` and `uint64` use Lua numbers and are exact only through 2^53.

## Object properties

|                              |                               |
| ---------------------------- | ----------------------------- |
| `ent.address`                | address as a number           |
| `ent.class_name`             | schema class name             |
| `ent:Cast("C_CSPlayerPawn")` | same address, different class |
| `tostring(ent)`              | `"C_CSPlayerPawn@0x..."`      |
| `a == b`                     | address equality              |

## GetLocalPlayer

```lua theme={"dark"}
local pawn = entity.GetLocalPlayer()
```

Local pawn as an entity object, or `nil` when not spawned.

## GetLocalPlayerOrSpec

```lua theme={"dark"}
local pawn = entity.GetLocalPlayerOrSpec()
```

Returns the local pawn, or the spectated pawn while observing.

## GetLocalController

```lua theme={"dark"}
local ctrl = entity.GetLocalController()
```

Local controller, or `nil`.

## players / controllers

```lua theme={"dark"}
entity.players:ForEach(function(pawn) ... end)
entity.controllers:ForEach(function(ctrl) ... end)
```

Iterates every connected player's pawn / controller as entity objects. Skips empty slots and unresolvable handles.

## GetEyePosition

```lua theme={"dark"}
local eye = entity.GetEyePosition(pawn)
```

Returns the player's eye `Vector` (origin + view offset), or `nil` for non-player entities.

## IsAlive

```lua theme={"dark"}
if entity.IsAlive(pawn) then ... end
```

Returns `true` if the entity has health > 0.

## IsEnemy

```lua theme={"dark"}
if entity.IsEnemy(pawn) then ... end
```

Returns `true` if the entity is an enemy of the local player. Respects `mp_teammates_are_enemies`. Returns `false` when there is no local pawn or the entity isn't a player pawn.

## GetWeaponData

```lua theme={"dark"}
local data = entity.GetWeaponData(pawn_or_weapon)
if data then
    print(data.m_flPenetration, data.m_flRange, data.m_flArmorRatio)
end
```

The weapon's `CCSWeaponBaseVData` as an entity object, or `nil`. Pass a player pawn for its active weapon, or a weapon entity directly.

Weapon stats such as damage, penetration, range, armor ratio, and max speed live on this object.

## GetWeaponType

```lua theme={"dark"}
if entity.GetWeaponType(pawn) == entity.WEAPONTYPE_GRENADE then return end
```

Same argument as `GetWeaponData`. Returns a number, or `nil`.

Use this helper because schema enum fields are not supported by direct field access.

| Constant                          | Value |
| --------------------------------- | ----- |
| `entity.WEAPONTYPE_KNIFE`         | 0     |
| `entity.WEAPONTYPE_PISTOL`        | 1     |
| `entity.WEAPONTYPE_SUBMACHINEGUN` | 2     |
| `entity.WEAPONTYPE_RIFLE`         | 3     |
| `entity.WEAPONTYPE_SHOTGUN`       | 4     |
| `entity.WEAPONTYPE_SNIPER_RIFLE`  | 5     |
| `entity.WEAPONTYPE_MACHINEGUN`    | 6     |
| `entity.WEAPONTYPE_C4`            | 7     |
| `entity.WEAPONTYPE_TASER`         | 8     |
| `entity.WEAPONTYPE_GRENADE`       | 9     |
| `entity.WEAPONTYPE_FISTS`         | 12    |
| `entity.WEAPONTYPE_MELEE`         | 15    |
| `entity.WEAPONTYPE_UNKNOWN`       | -1    |

## Cast

```lua theme={"dark"}
local ent = entity.Cast(addr_or_entity, "C_CSPlayerPawn")
```

Wraps any address (e.g. from [`cheat.FindPattern`](/cheat#findpattern)) or re-types an existing object. Errors on unknown class names. Returns `nil` for a null address.

<Warning>
  Entity objects hold raw pointers. Re-fetch them each tick to avoid stale pointers.
</Warning>

<Info>
  Handles and entity-list results use the runtime class. Pointer fields use their declared class. Use `:Cast` for derived fields. Unknown pointer classes return plain addresses.
</Info>