xhookLua
Game

Entity

Entity handle by index; most accessors raise once the entity is gone, so check is_valid() first.

Methods

ent:is_valid

ent:is_valid() -> boolean

True while the entity exists; never raises.

Dormant players are still valid; see is_dormant().

ent:index

ent:index() -> integer

Players are 1 to max_players; works on stale handles.

ent:name

ent:name() -> string

Player or NPC target name; usually empty otherwise.

ent:origin

ent:origin() -> Vector

Position; for players the hull centre (feet 36 below, 18 ducked).

ent:eye_position

ent:eye_position() -> Vector

Where a player's shots and traces start.

Estimated for NPC targets; not tracked for plain entities.

ent:velocity

ent:velocity() -> Vector

Player or NPC target velocity.

Returns Units per second

ent:angles

ent:angles() -> Angle

For players, the view direction.

ent:health

ent:health() -> integer

Player or NPC target health.

  • Enemy health may be an estimate when the server doesn't send it.
  • Unknown NPC health reads 100; plain entities read 0.

ent:armor

ent:armor() -> integer

Armour points; local player only, others read 0.

ent:team

ent:team() -> integer

0 unassigned, 1 terrorist, 2 counter-terrorist, 3 spectator.

NPC targets report a team by hostility; use is_enemy() or is_ally().

ent:money

ent:money() -> integer

Scoreboard money.

Returns Dollars, or -1 if unknown

Local player reads 0, not -1, when unknown or dead.

ent:speed

ent:speed() -> number

Horizontal speed.

Returns Units per second

ent:is_alive

ent:is_alive() -> boolean

Player or NPC target alive; plain entities read false.

ent:is_dead

ent:is_dead() -> boolean

Player or NPC target dead.

ent:is_player

ent:is_player() -> boolean

True for players, local included.

ent:is_local

ent:is_local() -> boolean

True for the local player.

ent:is_enemy

ent:is_enemy() -> boolean

Enemy player or hostile NPC target.

False for the local player, non-targets, or with no local player.

ent:is_ally

ent:is_ally() -> boolean

Teammate or friendly NPC target; false for yourself and non-targets.

ent:is_npc

ent:is_npc() -> boolean

NPC tracked as a target, hostile or friendly.

ent:steam_id

ent:steam_id() -> string | nil

SteamID64 as a decimal string.

nil for non-players, bots and non-Steam IDs.

ent:in_pvs

ent:in_pvs() -> boolean

In the latest server update (not dormant).

ent:is_dormant

ent:is_dormant() -> boolean

Out of PVS; data is the last known state.

ent:dormant_time

ent:dormant_time() -> number

Seconds since last in PVS, 0 while visible.

ent:is_scoped

ent:is_scoped() -> boolean

Zoomed through a scope; local player only, others false.

ent:on_ground

ent:on_ground() -> boolean

Standing on the ground.

ent:is_ducking

ent:is_ducking() -> boolean

Crouched.

ent:in_water

ent:in_water() -> boolean

Submerged past the waist.

ent:on_ladder

ent:on_ladder() -> boolean

On a ladder.

ent:has_c4

ent:has_c4() -> boolean

Carries the bomb (scoreboard flag).

ent:has_defuser

ent:has_defuser() -> boolean

Has a defuse kit (scoreboard flag).

ent:has_shield

ent:has_shield() -> boolean

Holds a tactical shield, from the weapon model.

ent:fov

ent:fov() -> integer

Degrees, 90 unless zoomed; real only for the local player.

ent:sequence

ent:sequence() -> integer

Activity bit flags, 0 idle or dormant; raw number via prop("sequence").

1 shooting, 2 reloading, 4 dying, 8 throwing, 16 planting C4, 32 shield, 64 shield side.

ent:sequence_frame

ent:sequence_frame() -> integer

Current animation frame, as a whole number.

ent:gait_yaw

ent:gait_yaw() -> number

Leg yaw in degrees; can differ from view yaw.

ent:fall_velocity

ent:fall_velocity() -> number

Negated vertical velocity: positive while falling.

ent:observer_state

ent:observer_state() -> integer

Spectator mode.

0 none, 1 chase locked, 2 chase free, 3 roaming, 4 in-eye, 5 free map, 6 chase map.

ent:model_name

ent:model_name() -> string

Model path; brush entities report "*N".

Returns Like "models/player/leet/leet.mdl"

ent:weapon_model

ent:weapon_model() -> string

Held weapon's third-person model, "" when none.

Returns Like "models/p_ak47.mdl"

ent:weapon

ent:weapon() -> table

What a player holds: {id, name, model}.

Returns nil with nothing in hand

  • Others from the weapon model the game sends, you from the real weapon.
  • id 0 = a model the table does not know (custom server weapons).

ent:class

ent:class() -> string

Coarse type guessed from the model; never raises.

  • player, brush, grenade, c4, hostage, chicken, weapon, viewmodel, unknown, world (index 0), invalid (stale).
  • NPCs usually report "unknown"; use is_npc().

ent:class_id

ent:class_id() -> integer

0 unknown, 1 local player, 2 other player, 3 non-player.

ent:prev_origin

ent:prev_origin() -> Vector

Position from the previous update.

ent:distance

ent:distance() -> number

Distance from the local player, cached at last update.

Stale while dormant; distance_to() is live.

ent:distance_to

ent:distance_to(point) -> number
NameType
pointVector

3D distance from the entity's origin to point.

ent:frags

ent:frags() -> integer

Scoreboard kills; players only, works on stale handles.

ent:deaths

ent:deaths() -> integer

Scoreboard deaths; players only, works on stale handles.

ent:ping

ent:ping() -> integer

Scoreboard ping in ms; players only, works on stale handles.

ent:prop

ent:prop(name) -> integer | number | Vector
NameTypeDescription
namestringCase-sensitive field, see notes.

Raw networked state field; raises on unknown names or missing engine entity.

  • Vector: origin, angles, velocity, basevelocity, mins, maxs, startpos, endpos, vuser1 to vuser4. Float: msg_time, frame, scale, animtime, framerate, friction, gravity, flFallVelocity, fov, impacttime, starttime, fuser1 to fuser4.
  • Integer: entityType, number, messagenum, modelindex, sequence, colormap, effects, rendermode, renderamt, renderfx, movetype, body, aiment, owner, team, playerclass, health, weaponmodel, gaitsequence, usehull, oldbuttons, onground, iStepLeft, weaponanim, spectator, iuser1 to iuser4, skin, solid, eflags, rendercolor_r/g/b (0 to 255).

ent:set_prop

ent:set_prop(name, value)
NameTypeDescription
namestringSame names as prop()
valueinteger | number | VectorMatches the field's type.

Writes the client's copy of a field; server updates overwrite most.

  • Non-integers for integer fields raise; Vector fields need a Vector.
  • Client-side only; re-apply render fields (rendermode, renderamt, renderfx, rendercolor) each frame.

ent:backtrack_records

ent:backtrack_records() -> table

Past positions the ragebot and backtrack can rewind to.

Returns Array of records, see fields

ent:set_velocity

ent:set_velocity(velocity)
NameTypeDescription
velocityVectorUnits per second.

Overrides local predicted velocity for the next step; call every on_create_move tick.

  • Prediction only; rubber-bands on normal servers.
  • Raises on any entity but the local player.

ent:set_origin

ent:set_origin(position)
NameType
positionVector

Client-side teleport of the local predicted position; re-apply every tick.

  • Prediction only, like set_velocity.
  • Raises on any entity but the local player.

ent:hitbox_position

ent:hitbox_position(index) -> Vector
NameTypeDescription
indexinteger0 to 20, see notes.

World-space hitbox centre from the last model setup.

  • 0 stomach, 1 left foot, 2 left calf, 3 left thigh, 4 right foot, 5 right calf, 6 right thigh, 7 lower chest, 8 chest, 9 upper chest, 10 neck, 11 head, 12 left upper arm, 13 left hand, 14 left forearm, 15 left wrist, 16 right upper arm, 17 right hand, 18 right forearm, 19 right wrist, 20 shield.
  • Out-of-range index raises; stale while dormant.

ent:head_position

ent:head_position() -> Vector

Head hitbox centre, same as hitbox_position(11).

ent:hitbox_min

ent:hitbox_min(index) -> Vector
NameTypeDescription
indexinteger0 to 20.

Min corner of the hitbox's world-space bounds.

Bad index raises, like hitbox_position.

ent:hitbox_max

ent:hitbox_max(index) -> Vector
NameTypeDescription
indexinteger0 to 20.

Max corner of the hitbox's world-space bounds.

Bad index raises, like hitbox_position.

ent:obb_min

ent:obb_min(index) -> Vector
NameTypeDescription
indexinteger0 to 20.

Oriented box min corner in bone space; transform with hitbox_matrix().

Bad index raises, like hitbox_position.

ent:obb_max

ent:obb_max(index) -> Vector
NameTypeDescription
indexinteger0 to 20.

Oriented box max corner in bone space.

Bad index raises, like hitbox_position.

ent:hitbox_points

ent:hitbox_points(index) -> Vector[]
NameTypeDescription
indexinteger0 to 20.

Multipoint positions the aimbots scan around the hitbox.

Returns 8 Vectors, 1-based

Bad index raises, like hitbox_position.

ent:hitbox_matrix

ent:hitbox_matrix(index) -> number[12]
NameTypeDescription
indexinteger0 to 20.

Transform of the hitbox's bone.

Returns Row-major 3x4, translation at 4, 8, 12

Bad index raises, like hitbox_position.

ent:bbox

ent:bbox() -> Vector, Vector

Player box matching the built-in ESP, 32 units wide.

Returns World-space mins, maxs

Uses player hull sizes, so wrong for non-player entities.

ent:bone_count

ent:bone_count() -> integer

Bones in the captured pose, 0 when none.

  • Poses capture only once a script asks, so poll every frame.
  • A pose older than 250 ms counts as none.

ent:bone_position

ent:bone_position(bone) -> Vector | nil
NameTypeDescription
boneinteger | string0-based index or case-insensitive name.

World position from the last drawn pose.

nil with no recent pose, a bad index or unknown name.

ent:bone_angles

ent:bone_angles(bone) -> Angle | nil
NameTypeDescription
boneinteger | string0-based index or name.

Bone orientation; forward(), right(), up() give its axes.

nil like bone_position.

ent:bone_matrix

ent:bone_matrix(bone) -> number[12] | nil
NameTypeDescription
boneinteger | string0-based index or name.

World transform of a bone.

Returns Row-major 3x4, translation at 4, 8, 12

nil like bone_position.

ent:bone_parent

ent:bone_parent(bone) -> integer | nil
NameTypeDescription
boneinteger | string0-based index or name.

Parent bone index, -1 for the root.

nil with no recent pose, missing bone or unreadable model.

ent:bone_names

ent:bone_names() -> table

Names by 0-based index; ipairs skips [0], loop to bone_count() - 1.

ent:bone_local

ent:bone_local(bone) -> Vector, Quaternion | nil
NameTypeDescription
boneinteger | string0-based index or name.

Bone position and rotation relative to its parent bone.

  • While posed, it is the animation's pose, before your overrides.
  • nil for the root bone unless the entity is posed.
  • nil with no recent pose or a missing bone.

ent:set_bone_local

ent:set_bone_local(bone, pos, rot [, scale]) -> boolean
NameTypeDescription
boneinteger | string0-based index or name.
posVector | nilnil keeps the animation's position.
rotQuaternion | Angle | nilnil keeps the animation's rotation.
scaleoptionalnumberSizes the bone and all under it, 0.01 to 100.

Replaces a bone's position and rotation relative to its parent.

Returns false for an unknown bone, or when 64 other entities are posed

  • Call it every frame; the bone goes back 0.25 s after the last call.
  • Only the drawn model changes; hitboxes, aimbot and ESP boxes stay.
  • A bone name fails until the entity was drawn once; an index works.
  • Scale on the root bone sizes the whole model.

ent:offset_bone

ent:offset_bone(bone, pos, rot [, scale]) -> boolean
NameTypeDescription
boneinteger | string0-based index or name.
posVector | nilOffset in the bone's own space.
rotQuaternion | Angle | nilTurn in the bone's own space.
scaleoptionalnumberSizes the bone and all under it, 0.01 to 100.

Moves, turns and sizes a bone on top of its animation.

Lifetime and return value as set_bone_local.

ent:set_bone_matrix

ent:set_bone_matrix(bone, matrix) -> boolean
NameTypeDescription
boneinteger | string0-based index or name.
matrixMatrix3x4 | number[12]Row-major, as ent:bone_matrix returns.

Puts a bone at a world transform.

Lifetime and return value as set_bone_local.

ent:clear_bones

ent:clear_bones([bone])
NameTypeDescription
boneoptionalinteger | string0-based index or name.

Drops one bone's override now, or all of the entity's.

ent:attachment

ent:attachment(index) -> Vector | nil
NameTypeDescription
indexintegerSlot 0 to 3, per model.

Model attachment point where the engine last drew it.

nil, no error, outside 0 to 3 or without a model.

a == b

Entity == Entity -> boolean

Same entity index.

Index only: an old handle matches whoever takes that slot later.

tostring(ent)

tostring(Entity) -> string

Readable index and name; never raises.

Returns Like Entity(3, "name")

Fields

ent:backtrack_records() item

NameTypeDescription
originVectorRecorded position
timenumberServer animation time
latencynumberFake latency in seconds to rewind
Entity ยท Lua API ยท xhook