Players & entities

The local player's controller, or nil before you are in a game. Its body methods work too, so ents.local_player():health() is fine.

The local player's pawn.

Whose camera you are looking through: the local player's controller, or, while you are dead and spectating, the player you are watching.

The players' controllers, as a list. With no options that is everybody, the local player included. options filters:

local targets = ents.players( { enemies = true, alive = true } )

Weapons lying in the world. With { dropped = true } only those nobody carries.

Grenades in flight, smokes and fires.

Every entity of one class, found by walking the entity list - for example ents.by_class( "C_PlantedC4" ). The list is capped at 1024 entries. Class names are the game's own; ent:class() tells you the name of one you have.

The entity in a slot of the entity list, 0 to 16383.

The entity a handle - as ent:handle() returns it, or a handle field stored in the game - points to.

The planted bomb, or nil. ent:bomb() reads its timers.

The game rules, as { freeze_period, team_intro, round_start_time, phase }: whether the round is in its freeze period, whether the team intro is playing, the game time the round started, and the game phase as a number. nil outside a game.

Whether the entity still exists.

The entity's index in the entity list; -1 if it cannot be worked out, nil if the entity is gone.

The entity's handle, for ents.from_handle. 0 when it is gone.

The game's class name for it: "C_CSPlayerPawn", "CCSPlayerController", "C_AK47", "C_PlantedC4". An empty string when the entity is gone.

"controller", "pawn", "weapon", "projectile", "other", or "none" when the entity is gone.

Whether the entity's class is exactly class.

The entity's position in the world. For a player it is the point between the feet.

How the body is rotated in the world - not where the player looks, see eye_angles.

Where a player is looking: pitch, yaw, roll in degrees.

Where the player's eyes are: the origin plus the view offset. The point a trace to or from a player should start at.

The speed in units per second, vertical movement included.

The horizontal speed - the one that matters for bunny hopping and for accuracy.

How far the player is crouched: 0 standing, 1 fully crouched.

The movement type - walking, flying, noclip, on a ladder. See ents.move_type.

The entity's flag bits. ents.flags names them.

What the player is standing on.

1 for normal speed; below 1 while the player is slowed, for instance after being hit.

The team number: 1 spectators, 2 terrorists, 3 counter-terrorists, 0 none yet.

Whether the entity is on the other team than the local player. In modes without teams everyone else counts as an enemy. false for an entity that is gone.

A player's name; a weapon's name ("ak47"); for anything else the class name.

The 64-bit Steam id; 0 for bots.

The player's tick base - the tick their movement has been simulated up to.

The body of a player, given either entity.

The controller of a player, given either entity.

The entity that holds or threw this one: the player carrying a weapon, the one who threw a grenade.

Whether the game's walking flag is set - slow, quiet steps.

The game's flash value: above 0 while the player is blinded.

The game's own "spotted" flag for the player.

Whether the player is carrying the bomb.

Who a spectating player is watching.

The recoil punch of the local player, as the engine applies it to the view. nil for anybody else.

The world position of a bone. id is 0 to 26; ents.bone has the names - ents.bone.head, ents.bone.pelvis.

local head = player:bone( ents.bone.head )

All the bones at once: a table from bone id to position, { [0] = vec3, [1] = vec3, ... [26] = vec3 }. The keys are bone ids, so the table starts at 0.

The player's hitboxes: a list of { index, bone, group, mins, maxs, radius } - the hitbox's number, the bone it follows, its hitgroup (see ents.hitgroup), its corners relative to the bone, and its radius for capsule-shaped ones.

The rectangle the player covers on screen: { x, y, x2, y2, w, h } in pixels - top left corner, bottom right corner, size. nil when the player cannot be projected.

Whether the player's head can be seen from the camera - or from the point from, if given. A line is traced to the head, skipping the local player's own body.

The player's active weapon. Given a weapon, the weapon itself.

Every weapon the player carries.

The weapon's item definition index. ents.weapon_id has the names.

Pistol, rifle, sniper, grenade - see ents.weapon_type.

The weapon's name without the weapon_ prefix: "ak47", "awp", "knife", "c4". This is also what render.icon takes.

Rounds in the magazine.

The magazine size.

Rounds in reserve.

The weapon's base damage per bullet.

The fraction of damage that remains after each 500 units - 1 means no falloff.

Seconds between two shots.

How many bullets one shot fires - 1 for rifles, more for shotguns.

How fast the weapon lets its owner run, for the mode - scoped or not - it is in right now.

The engine's current inaccuracy for the weapon - the value a shot's spread is scaled by. Asking does not disturb the weapon's own state.

The weapon's base spread.

Pistols, SMGs, rifles, shotguns, snipers and machine guns.

The game time of the weapon's last shot.

The tick the primary attack is next allowed on.

The game time at which the player may attack again - for a player, not a weapon. Compare it with game.curtime().

local me     = ents.local_pawn( )
local weapon = me and me:weapon( )

if weapon and weapon:is_gun( ) then
	print( weapon:weapon_name( ), weapon:ammo( ) .. "/" .. weapon:max_ammo( ) )
end

For the planted bomb entity - see ents.bomb() - its state as a table; nil for any other entity.

local bomb = ents.bomb( )
local state = bomb and bomb:bomb( )

if state and not state.defused and not state.exploded then
	local seconds_left = state.blow_time - game.curtime( )
end

Reads a field.

• class - the class that declares the field, as the game names it: "C_BaseEntity".
• field - the field: "m_iHealth".
• type - how to read it. See the table below.
• byte_offset - added to the address, to index into arrays and embedded structures.

Answers nil for an entity that is gone or memory that cannot be read, and nil plus a message when the game has no such field or the type is unknown.

local health = ents.local_pawn( ):prop( "C_BaseEntity", "m_iHealth", "i32" )

Writes a field; true if it was written. Writing works for bool, the integer and float types, vec3, color and ptr. A write goes straight into the game's memory - the client's copy, which the server does not see - so it is for visual and client-side changes.

A handle field, resolved to the entity it points to.

Where a field sits inside its class, in bytes; nil when the game has no such field. Offsets are looked up once and remembered.

Item definition indices by name:

local weapon = ents.local_pawn( ):weapon( )

if weapon and weapon:weapon_id( ) == ents.weapon_id.awp then
	-- sniping
end