Entities

Find entities, read their schema fields, and use the built-in helpers.

Players, weapons, grenades, the bomb: every entity in the game as a read-only object.

import entities from "@native/entities";

Values update once per tick, so they don’t change between tick and the render frames after it.

Overview

Lookup

getByIndex, getByHandle, getEntities, find, getPlayers, getLocalPlayer, getLocalController.

Entity objects

alive, index, handle, className, address.

Schema fields

m_iHealth and friends, read, bytes.

Helpers

Origin, eyes, bounds, visibility, hitboxes, bones, weapon data.

EntityQuery

filter, forEach, toArray, first, count, map, some, every.

Anywhere an entity is expected you can also pass its index (EntityRef).

---

Lookup

getByIndex

entities.getByIndex(index: number): IEntityBase | null

The entity at index, or null when there’s none.

const ent = entities.getByIndex(64);
console.log(ent?.className ?? "empty slot");

getByHandle

entities.getByHandle(handle: number): IEntityBase | null

The entity with this handle, or null once it’s gone.

const saved = pawn.handle;
// later
const same = entities.getByHandle(saved);   // null if that pawn was destroyed

getEntities

entities.getEntities(): IEntityBase[]

Every entity.

const counts = new Map<string, number>();
for (const ent of entities.getEntities())
    counts.set(ent.className, (counts.get(ent.className) ?? 0) + 1);

find

entities.find(className: string): EntityQuery
entities.find(options: { className?: string; parent?: string }): EntityQuery

className matches exactly that class, parent matches it and every class deriving from it. Both together is an AND; an unknown name matches nothing. Returns an EntityQuery typed by the class you asked for.

const bomb = entities.find("C_PlantedC4").first();
const grenades = entities.find({ parent: "C_BaseCSGrenadeProjectile" }).count();
const loaded = entities.find({ parent: "C_CSWeaponBase" }).filter((w) => w.m_iClip1 > 0).toArray();

getPlayers

entities.getPlayers(options?: { skipLocal?: boolean }): IPlayerPawn[]

The pawn of every player, in controller order. skipLocal leaves yours out.

for (const pawn of entities.getPlayers({ skipLocal: true })) {
    if (pawn.className !== "C_CSPlayerPawn") continue;   // dead or spectating
    console.log(pawn.controller?.m_iszPlayerName, pawn.m_iHealth);
}

A dead or spectating player’s pawn is a C_CSObserverPawn, not a C_CSPlayerPawn. Check className before using player-only fields or getViewAngles().

getLocalPlayer

entities.getLocalPlayer(): IPlayerPawn | null

Your pawn, null when you’re not in a game. Same observer-pawn rule as getPlayers.

const me = entities.getLocalPlayer();
if (me?.className === "C_CSPlayerPawn") console.log(me.m_iHealth, me.getViewAngles());

getLocalController

entities.getLocalController(): ICCSPlayerController | null

Your player controller, null when you’re not in a game. Name, score, money and other per-player state live here.

const ctrl = entities.getLocalController();
console.log(ctrl?.m_iszPlayerName, ctrl?.m_iPing);

---

Entity objects

Member
alive: boolean	the entity still exists
index: number	entity index
handle: number	id for getByHandle; m_h* fields hold these
className: string	schema class, e.g. "C_CSPlayerPawn"
address: Pointer | null	address in game memory, see Pointer
toString(): string	"Entity(12, C_CSPlayerPawn)", with ", stale" once it’s gone

The same entity is always the same object, so === and Map keys work. Once it’s destroyed, alive is false for good and fields, address, read, bytes and helpers return null; index, handle and className still work.

let target: IPlayerPawn | null = null;

on("tick", () => {
    if (target && !target.alive) target = null;
    target ??= entities.getPlayers({ skipLocal: true })[0] ?? null;
});

Field types don’t include null (m_iHealth is typed number), but a stale entity reads null. Check alive on anything you keep across ticks.

---

Schema fields

Every schema field is a read-only property under its schema name: pawn.m_iHealth, pawn.m_ArmorValue. Autocompletion shows what each class has; the type for class C_CSPlayerPawn is IC_CSPlayerPawn.

Schema type	Reads as
integers, floats, enums	number (bigint for 64-bit)
bool	boolean
Vector, QAngle, Quaternion, Vector2D, Color	Vector, QAngle, Quaternion, Vector2, Color
char[N], CUtlString, CUtlSymbolLarge	string
CHandle (m_h*)	the entity, or null
pointer to a struct or entity (m_p*)	that object, or null
other pointers	Pointer, or null
T[N], CUtlVector	an array (CUtlVector can be null)
anything else	Uint8Array copy of the bytes

const me = entities.getLocalPlayer();
if (me?.className === "C_CSPlayerPawn") {
    const weapon = me.m_pWeaponServices?.m_hActiveWeapon;   // struct pointer, then handle
    console.log(me.m_iHealth, me.m_ArmorValue, me.m_bIsScoped, weapon?.className);
}

Nested structs (m_pWeaponServices above, getWeaponData()) have address, read, bytes and toString as well.

read

entity.read<T extends ScalarType>(type: T, offset: number): ScalarValue<T> | null

Reads one value offset bytes into the object, for data the schema doesn’t name. Types are the Pointer ones. RangeError past the end of the object.

const health = pawn.read("int32", 0x34C);
const origin = pawn.read("vector", 0x1224);

bytes

entity.bytes(offset?: number, size?: number): Uint8Array | null

A copy of size bytes from offset, defaulting to the whole object. RangeError past the end.

const raw = pawn.bytes(0x300, 0x40);

---

Helpers

Helpers return null when the data isn’t there (entity gone, no model).

Every entity
getOrigin(): Vector | null	world position
getVelocity(): Vector | null
getBounds(): Bounds | null	world-space collision box { mins, maxs } at the current origin
isEnemy(other: EntityRef): boolean | null	on a different team, honours mp_teammates_are_enemies

Model entities (pawns, weapons, props)
getEyePosition(): Vector | null	origin + m_vecViewOffset
getModelName(): string | null
isVisible(target: EntityRef, point?: Vec3Like): boolean | null	see isVisible
getHitboxes(), getHitbox(nameOrIndex)	see Hitboxes and bones
getBones(), getBone(nameOrIndex)

Players and weapons
controller: ICCSPlayerController | null	the controller owning a pawn
getViewAngles(): QAngle | null	m_angEyeAngles, C_CSPlayerPawn only
getWeaponData(): ICCSWeaponBaseVData | null	the weapon’s static data: name, damage, clip size…

const weapon = me.m_pWeaponServices?.m_hActiveWeapon;
const data = weapon?.getWeaponData();
console.log(data?.m_szName, data?.m_nDamage, me.getBounds()?.maxs);

isVisible

entity.isVisible(target: EntityRef, point?: Vec3Like): boolean | null

Line of sight through world geometry from this entity’s eyes (box centre if it isn’t a pawn) to target’s eyes or box centre. Pass point to test that spot instead. null when no map is loaded.

if (me.isVisible(enemy)) console.log("eyes visible");

const head = enemy.getHitbox("head_0");
if (head && me.isVisible(enemy, head.start)) console.log("head visible");

Players never block the line. For more control use trace.

Hitboxes and bones

entity.getHitboxes(): Hitbox[] | null
entity.getHitbox(nameOrIndex: string | number): Hitbox | null
entity.getBones(): Bone[] | null
entity.getBone(nameOrIndex: string | number): Bone | null

Hitboxes and bones of the current pose, in model order. Look one up by name, or by Hitbox.index (the model’s hitbox id) / bone index. null when the model has none or the name doesn’t exist.

Hitbox
index, name	model hitbox id and name
bone, boneName	the bone it’s attached to
group	1 head, 2 chest, 3 stomach, 4/5 arms, 6/7 legs, 8 neck
radius	capsule radius, 0 for boxes
start, end	world-space ends
mins, maxs	bone-space bounds
shapeType, surfaceProperty

Bone has index, name (null if the model has none), position, rotation and scale.

const head = enemy.getHitbox("head_0");
const aimAt = head && head.start.lerp(head.end, 0.5);

for (const bone of enemy.getBones() ?? [])
    if (bone.name?.startsWith("hand")) console.log(bone.name, bone.position);

---

EntityQuery

What find returns. filter returns a new query and leaves the original unchanged.

Method	Returns
filter(predicate)	a new EntityQuery, narrowed by type guards
forEach(callback)	void
toArray()	T[]
first()	T | null
count()	number
map(callback)	R[]
some(predicate), every(predicate)	boolean

const weapons = entities.find({ parent: "C_CSWeaponBase" });
const dropped = weapons.filter((w) => w.m_hOwnerEntity === null);   // weapons is unchanged

console.log(weapons.count(), dropped.count());
dropped.forEach((w) => console.log(w.className, w.getOrigin()));

---

Example

Name and distance of the closest visible enemy.

import entities from "@native/entities";
import render from "@native/render";

let closest: { pawn: IPlayerPawn; dist: number } | null = null;

on("tick", () => {
    closest = null;
    const me = entities.getLocalPlayer();
    const eye = me?.getEyePosition();
    if (!me || !eye) return;

    for (const pawn of entities.getPlayers({ skipLocal: true })) {
        if (pawn.className !== "C_CSPlayerPawn" || pawn.m_iHealth <= 0 || !pawn.isEnemy(me)) continue;
        const pos = pawn.getEyePosition();
        if (!pos || !me.isVisible(pawn)) continue;
        const dist = eye.distTo(pos);
        if (!closest || dist < closest.dist) closest = { pawn, dist };
    }
});

on("render", () => {
    if (!closest?.pawn.alive) return;
    const name = closest.pawn.controller?.m_iszPlayerName ?? "?";
    render.text([20, 200], `${name}  ${Math.round(closest.dist)}u`, "#ff4040");
});