xhookLua
Game

Events

Handlers from callbacks.register run in registration order, get 50 ms each, and return values are ignored.

Events

on_paint

on_paint()

Every frame; all draw.* calls go here, above world, below menu.

Also fires in menus and loading screens; check world state first.

on_create_move

on_create_move(cmd)
NameTypeDescription
cmdtableMutable usercmd shared by all handlers.

Per outgoing usercmd; changed fields copy into the real command.

  • Built-in movement and aim run after and can overwrite it.
  • Wrong types drop silently: integer fields reject floats like 2.0.

on_script_load

on_script_load()

After the script's top-level code runs without error.

  • Register it at top level, or the script misses its own load.
  • Skipped for failed or disabled scripts.

on_script_unload

on_script_unload()

Before teardown by hot reload, disable, deletion or Reload; undo patches here.

Does not fire on cheat unload or raw memory toggle.

on_player_death

on_player_death(e)
NameTypeDescription
e.attackerEntity|nilnil unless a connected player.
e.victimEntity|nilnil unless a connected player.
e.attacker_indexinteger1-based; 0 is world or non-player.
e.victim_indexinteger1-based.
e.weaponstringKill feed name, like "ak47".
e.headshotboolean

Every server-broadcast death: kills, suicides, world deaths.

on_player_hurt

on_player_hurt(e)
NameTypeDescription
e.healthintegerHealth after hit, clamped to 0.
e.armorintegerArmour damage this hit.
e.damageintegerHealth damage this hit.
e.fallbooleanTrue for fall damage.

Local player took damage; other players' damage is never sent.

No attacker field: the message omits who hit you.

on_round_start

on_round_start()

First frame after a ResetHUD, before on_paint.

  • Respawns fire it too, since ResetHUD arrives on every spawn.
  • The first ResetHUD after scripting starts does not fire.

on_round_end

on_round_end(e)
NameTypeDescription
e.winnerstring"T", "CT" or "draw".

Standard round-win message: team win, bomb, hostages, escape, draw.

Custom mod win text never fires it.

on_freeze_end

on_freeze_end()

The freeze time ended and you can move.

on_bomb_planted

on_bomb_planted()

Server announced a bomb plant.

No payload: planter and site are unknown.

on_bomb_beginplant

on_bomb_beginplant(e)
NameType
e.entityEntity
e.indexinteger

You started planting.

The game only tells the planter.

on_bomb_begindefuse

on_bomb_begindefuse(e)
NameType
e.entityEntity
e.indexinteger
e.has_kitboolean

A CT started defusing.

From its sound, so only defuses you hear.

on_bomb_defused

on_bomb_defused()

Server announced a defuse.

on_round_end with winner "CT" usually fires from the same message.

on_weapon_fire

on_weapon_fire(e)
NameTypeDescription
e.weapon_idintegerEngine id of active weapon.
e.weaponstringLike "ak47", or "unknown".
e.clipintegerRounds left after the shot.

Local player shot, detected as a clip drop; runs after on_create_move.

  • Clipless weapons (knife, grenades) never fire it.
  • Other players' shots: use on_sound with is_weapon.

on_item_pickup

on_item_pickup(e)
NameTypeDescription
e.itemstringClassname, like "weapon_ak47"; "" if missing.

Local player picked up an item.

Never fires on mods without ItemPickup.

on_chat

on_chat(e)
NameTypeDescription
e.entityEntity|nilnil unless a connected player.
e.indexinteger1-based; 0 is server or console.
e.namestringText before first ": ", or "".
e.textstringText after name, or whole line.

Every SayText chat line, regardless of custom chat or translator.

  • Cannot hide or block the line.
  • TextMsg chat (AMX print_chat, radio) does not fire it.

on_sound

on_sound(e)
NameTypeDescription
e.entityoptionalEntity|nilAbsent unless a connected player.
e.indexintegerEmitter index, correct outside PVS.
e.originVectorEmitter hull centre.
e.filestringLike "player/pl_step1.wav".
e.volumenumber0 to 1.
e.is_playerbooleanFootsteps, jumps, hits.
e.is_weaponbooleanGunfire, reloads.
e.is_footstepbooleanFile name contains "step".

Engine started a player or weapon sound; locates unseen players.

  • Ambient and world sounds never fire it.
  • Cannot mute the sound.

on_net_message

on_net_message(msg)
NameTypeDescription
msgNetMessageRead-only; msg:name() then read_*() calls.

Messages hooked with net.hook_message(name), before the game's handler.

  • Every handler gets every hooked message; check msg:name() first.
  • Reading after the callback raises an error.

on_map_change

on_map_change(e)
NameTypeDescription
e.mapstringLevel path the engine reports.
e.previousstringLast map.

A new map loaded.

on_player_connect

on_player_connect(e)
NameType
e.entityEntity
e.indexinteger
e.namestring

A player joined.

Not fired for players already on the server when you join.

on_player_disconnect

on_player_disconnect(e)
NameType
e.indexinteger
e.namestring

A player left.

on_player_spawn

on_player_spawn(e)
NameType
e.entityEntity
e.indexinteger
e.is_localboolean

A player went from dead to alive, as your client sees it.

Not fired for players already alive when you join or the map changes.

on_key

on_key(e)
NameTypeDescription
e.vkintegerKey code.
e.keystringName from input.keys, or "".
e.downboolean
e.keynumintegerEngine key number.
e.bindingstringCommand bound to it.

A key went down or up in game.

Return true to keep the key from the game.

on_bullet_impact

on_bullet_impact(e)
NameType
e.positionVector

A bullet hit something; any shot your client draws.

on_override_view

on_override_view(view)
NameTypeDescription
view.originVector
view.anglesAngle
view.fovnumberHorizontal degrees, 90 default.

Every frame before the world draws. Change the fields to move the camera.

Skipped while a screenshot is taken.

on_aim_target

on_aim_target(t)
NameTypeDescription
t.entityEntity
t.indexinteger
t.botstring"rage" or "legit".
t.hitboxinteger
t.damagenumber0 for legit.
t.fovnumber
t.lethalbooleanfalse for legit.
t.pointVector

The aimbot is about to rank a target. Return false to skip it, a number to rank it.

  • Higher numbers win over the bot's own order; the default is 0.
  • Without a handler the bots pick exactly as before.

on_aim_fire

on_aim_fire(s)
NameTypeDescription
s.idintegerSame in fire, hit and miss.
s.botstring"rage" or "legit".
s.entityEntity
s.indexinteger
s.hitboxintegerAimed hitbox.
s.hitgroupinteger0 generic, 1 head, 2 chest, 3 stomach, 4-5 arms, 6-7 legs.
s.pointVectorAim point.
s.predicted_damageintegerThe cheat's simulation, not the server's.
s.backtrackbooleanRage shot at a backtrack record.
s.rewindintegerExpected server rewind, ms.

A bullet left while a bot was aiming.

  • Manual shots fire no events.
  • aimbot.shoot shots fire it when they pass player.

on_aim_hit

on_aim_hit(s)
NameTypeDescription
s.idintegerSame in fire, hit and miss.
s.botstring"rage" or "legit".
s.entityEntity
s.indexinteger
s.hitboxintegerAimed hitbox.
s.hitgroupinteger0 generic, 1 head, 2 chest, 3 stomach, 4-5 arms, 6-7 legs.
s.pointVectorAim point.
s.damageintegerPredicted damage of the hit.
s.headshotbooleanA headshot sound came for this bullet.

The server confirmed that bullet hit.

  • entity / index is the player that was hit.
  • Arrives on the next command, before on_create_move.

on_aim_miss

on_aim_miss(s)
NameTypeDescription
s.idintegerSame in fire, hit and miss.
s.botstring"rage" or "legit".
s.entityEntity
s.indexinteger
s.hitboxintegerAimed hitbox.
s.hitgroupinteger0 generic, 1 head, 2 chest, 3 stomach, 4-5 arms, 6-7 legs.
s.pointVectorAim point.
s.predicted_damageinteger
s.reasonstringAlways "unconfirmed".

Nothing confirmed that bullet within 0.5 s.

  • Far shots and shots right before you die can be false misses.
  • A map change drops open shots without an event.

on_grenade_detonate

on_grenade_detonate(e)
NameTypeDescription
e.typestring"he", "flash" or "smoke".
e.positionVector
e.indexinteger

A grenade went off.

From its sound, so only ones you hear.

on_flashed

on_flashed(e)
NameTypeDescription
e.durationnumberFade seconds.
e.holdnumberFull white seconds.
e.alphaintegerPeak, 0 to 255.

You got flashed.

Fires with No flash on too.

on_draw_3d

on_draw_3d()

Every frame in the world pass, after transparent entities. Use draw3d.* here.

Skipped during screenshots and in streamer mode.

on_add_entity

on_add_entity(e)
NameTypeDescription
e.entityEntity
e.indexinteger
e.typestringnormal, player, beam, tempentity or fragmented.
e.modelstring
e.classnamestring"player", a brush classname, or "".
e.render_modeinteger0 to 5, writable.
e.render_amtinteger0 to 255, writable.
e.render_colortable{r, g, b}, writable.
e.render_fxinteger0 to 255, writable.

An entity is about to be drawn this frame. Return false to hide it.

  • Changes last one frame; set them every frame.
  • Fires for every drawn entity, so keep it short.

Fields

NameTypeDescription
cmd.viewanglesAngleDegrees; replace or edit in place.
cmd.buttonsintegerIN_* bitmask, integer, 16-bit.
cmd.forwardmovenumberUnits/s, negative is back.
cmd.sidemovenumberUnits/s, negative is left.
cmd.upmovenumberUnits/s (swimming, ladders).
cmd.impulseintegerLike 100 flashlight; integer 0 to 255.
cmd.msecintegerMilliseconds, read-only: changes are discarded.
cmd.lerp_msecintegerInterpolation ms, 16-bit integer.
cmd.lightlevelintegerInteger, 0 to 255.
cmd.weaponselectintegerSilent weapon switch; 0 is none, max 255.
cmd.impact_indexintegerRarely used integer.
cmd.impact_positionVectorRarely used; must stay a Vector.
cmd.send_packetbooleanStarts true. false holds this command back (choke) and sends it with the next. Never past what the engine can queue; off in Safe Mode.
cmd.chokedintegerCommands already held back in a row. Read-only.
Events ยท Lua API ยท xhook