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)| Name | Type | Description |
|---|---|---|
| cmd | table | Mutable 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)| Name | Type | Description |
|---|---|---|
| e.attacker | Entity|nil | nil unless a connected player. |
| e.victim | Entity|nil | nil unless a connected player. |
| e.attacker_index | integer | 1-based; 0 is world or non-player. |
| e.victim_index | integer | 1-based. |
| e.weapon | string | Kill feed name, like "ak47". |
| e.headshot | boolean |
Every server-broadcast death: kills, suicides, world deaths.
on_player_hurt
on_player_hurt(e)| Name | Type | Description |
|---|---|---|
| e.health | integer | Health after hit, clamped to 0. |
| e.armor | integer | Armour damage this hit. |
| e.damage | integer | Health damage this hit. |
| e.fall | boolean | True 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)| Name | Type | Description |
|---|---|---|
| e.winner | string | "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)| Name | Type |
|---|---|
| e.entity | Entity |
| e.index | integer |
You started planting.
The game only tells the planter.
on_bomb_begindefuse
on_bomb_begindefuse(e)| Name | Type |
|---|---|
| e.entity | Entity |
| e.index | integer |
| e.has_kit | boolean |
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)| Name | Type | Description |
|---|---|---|
| e.weapon_id | integer | Engine id of active weapon. |
| e.weapon | string | Like "ak47", or "unknown". |
| e.clip | integer | Rounds 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)| Name | Type | Description |
|---|---|---|
| e.item | string | Classname, like "weapon_ak47"; "" if missing. |
Local player picked up an item.
Never fires on mods without ItemPickup.
on_chat
on_chat(e)| Name | Type | Description |
|---|---|---|
| e.entity | Entity|nil | nil unless a connected player. |
| e.index | integer | 1-based; 0 is server or console. |
| e.name | string | Text before first ": ", or "". |
| e.text | string | Text 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)| Name | Type | Description |
|---|---|---|
| e.entityoptional | Entity|nil | Absent unless a connected player. |
| e.index | integer | Emitter index, correct outside PVS. |
| e.origin | Vector | Emitter hull centre. |
| e.file | string | Like "player/pl_step1.wav". |
| e.volume | number | 0 to 1. |
| e.is_player | boolean | Footsteps, jumps, hits. |
| e.is_weapon | boolean | Gunfire, reloads. |
| e.is_footstep | boolean | File 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)| Name | Type | Description |
|---|---|---|
| msg | NetMessage | Read-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)| Name | Type | Description |
|---|---|---|
| e.map | string | Level path the engine reports. |
| e.previous | string | Last map. |
A new map loaded.
on_player_connect
on_player_connect(e)| Name | Type |
|---|---|
| e.entity | Entity |
| e.index | integer |
| e.name | string |
A player joined.
Not fired for players already on the server when you join.
on_player_disconnect
on_player_disconnect(e)| Name | Type |
|---|---|
| e.index | integer |
| e.name | string |
A player left.
on_player_spawn
on_player_spawn(e)| Name | Type |
|---|---|
| e.entity | Entity |
| e.index | integer |
| e.is_local | boolean |
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)| Name | Type | Description |
|---|---|---|
| e.vk | integer | Key code. |
| e.key | string | Name from input.keys, or "". |
| e.down | boolean | |
| e.keynum | integer | Engine key number. |
| e.binding | string | Command 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)| Name | Type |
|---|---|
| e.position | Vector |
A bullet hit something; any shot your client draws.
on_override_view
on_override_view(view)| Name | Type | Description |
|---|---|---|
| view.origin | Vector | |
| view.angles | Angle | |
| view.fov | number | Horizontal 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)| Name | Type | Description |
|---|---|---|
| t.entity | Entity | |
| t.index | integer | |
| t.bot | string | "rage" or "legit". |
| t.hitbox | integer | |
| t.damage | number | 0 for legit. |
| t.fov | number | |
| t.lethal | boolean | false for legit. |
| t.point | Vector |
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)| Name | Type | Description |
|---|---|---|
| s.id | integer | Same in fire, hit and miss. |
| s.bot | string | "rage" or "legit". |
| s.entity | Entity | |
| s.index | integer | |
| s.hitbox | integer | Aimed hitbox. |
| s.hitgroup | integer | 0 generic, 1 head, 2 chest, 3 stomach, 4-5 arms, 6-7 legs. |
| s.point | Vector | Aim point. |
| s.predicted_damage | integer | The cheat's simulation, not the server's. |
| s.backtrack | boolean | Rage shot at a backtrack record. |
| s.rewind | integer | Expected 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)| Name | Type | Description |
|---|---|---|
| s.id | integer | Same in fire, hit and miss. |
| s.bot | string | "rage" or "legit". |
| s.entity | Entity | |
| s.index | integer | |
| s.hitbox | integer | Aimed hitbox. |
| s.hitgroup | integer | 0 generic, 1 head, 2 chest, 3 stomach, 4-5 arms, 6-7 legs. |
| s.point | Vector | Aim point. |
| s.damage | integer | Predicted damage of the hit. |
| s.headshot | boolean | A 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)| Name | Type | Description |
|---|---|---|
| s.id | integer | Same in fire, hit and miss. |
| s.bot | string | "rage" or "legit". |
| s.entity | Entity | |
| s.index | integer | |
| s.hitbox | integer | Aimed hitbox. |
| s.hitgroup | integer | 0 generic, 1 head, 2 chest, 3 stomach, 4-5 arms, 6-7 legs. |
| s.point | Vector | Aim point. |
| s.predicted_damage | integer | |
| s.reason | string | Always "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)| Name | Type | Description |
|---|---|---|
| e.type | string | "he", "flash" or "smoke". |
| e.position | Vector | |
| e.index | integer |
A grenade went off.
From its sound, so only ones you hear.
on_flashed
on_flashed(e)| Name | Type | Description |
|---|---|---|
| e.duration | number | Fade seconds. |
| e.hold | number | Full white seconds. |
| e.alpha | integer | Peak, 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)| Name | Type | Description |
|---|---|---|
| e.entity | Entity | |
| e.index | integer | |
| e.type | string | normal, player, beam, tempentity or fragmented. |
| e.model | string | |
| e.classname | string | "player", a brush classname, or "". |
| e.render_mode | integer | 0 to 5, writable. |
| e.render_amt | integer | 0 to 255, writable. |
| e.render_color | table | {r, g, b}, writable. |
| e.render_fx | integer | 0 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
| Name | Type | Description |
|---|---|---|
| cmd.viewangles | Angle | Degrees; replace or edit in place. |
| cmd.buttons | integer | IN_* bitmask, integer, 16-bit. |
| cmd.forwardmove | number | Units/s, negative is back. |
| cmd.sidemove | number | Units/s, negative is left. |
| cmd.upmove | number | Units/s (swimming, ladders). |
| cmd.impulse | integer | Like 100 flashlight; integer 0 to 255. |
| cmd.msec | integer | Milliseconds, read-only: changes are discarded. |
| cmd.lerp_msec | integer | Interpolation ms, 16-bit integer. |
| cmd.lightlevel | integer | Integer, 0 to 255. |
| cmd.weaponselect | integer | Silent weapon switch; 0 is none, max 255. |
| cmd.impact_index | integer | Rarely used integer. |
| cmd.impact_position | Vector | Rarely used; must stay a Vector. |
| cmd.send_packet | boolean | Starts 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.choked | integer | Commands already held back in a row. Read-only. |