Callbacks

Every entry point the engine calls, with parameters.

Callbacks are declared as namespace::name(params) { ... };. Player-scoped callbacks receive playerid as the first argument.

Note

Boolean callbacks (player::chat, player::request_class, player::request_spawn) use the return value as a veto.

Lifecycle

knight

system::start() { AddPlayerClass(0, 1958.4, 1343.2, 15.4, 270.0, 24, 50); };
system::stop()  { Log("shutting down"); };

Player

Callback	Signature
Connect	`player::connect(int playerid)`
Disconnect	`player::disconnect(int playerid, int reason)`
Spawn	`player::spawn(int playerid)`
Death	`player::death(int playerid, Player killer, int reason)`
Chat	`player::chat(int playerid, string message)` → bool
Command	`player::command("/name", ...)`
Request class	`player::request_class(int playerid, int classid)` → bool
Request spawn	`player::request_spawn(int playerid)` → bool
Update	`player::update(int playerid, float x, float y, float z)`
Enter/exit vehicle	`player::enter_vehicle/exit_vehicle(...)`
Aim / weapon shot	`player::aim(...)`, `player::weapon_shot(...)`
Download	`player::request_download(...)`, `player::finished_downloading(...)`

World & vehicle

knight

vehicle::death(int vehicleid, int killer) {
    Log("vehicle {vehicleid} destroyed");
};

world::actor_damage(int actorid, int playerid, float amount, int weaponid, int bodypart) {
    Log("actor {actorid} took {amount}");
};

world::checkpoint(int playerid) {
    SendClientMessage(playerid, "Checkpoint reached!");
};

Dialog, textdraw, timer

knight

dialog::response(int playerid, int id, bool accepted, string input, int listitem) {
    if (id == 100 && accepted) {
        SendClientMessage(playerid, "You chose row {listitem}");
    }
};

textdraw::click(int playerid, int textdrawid) {
    if (textdrawid == 3) {
        SendClientMessage(playerid, "clicked");
    }
};

timer::every(60s) {
    SendClientMessageToAll("One minute passed.");
};

Complete callback index

Callback	Parameters	Returns	Description
`dialog::response`	`(int playerid, int id, bool accepted, string input, int listitem)`		A player responded to a dialog; `accepted` is false on cancel, `listitem` is the selected row.
`player::aim`	`(int playerid, int camMode, int camZoom, int weaponState)`		A player is aiming; exposes camera mode/zoom and weapon state.
`player::chat`	`(int playerid, string message)`	bool	A player sent chat text; return true to relay it, false to swallow it.
`player::command`	`(int playerid)`	bool	A player ran a command declared as `player::command("/name", ...)`.
`player::connect`	`(int playerid)`		A player has connected; send a welcome, open a login dialog or set the camera.
`player::death`	`(int playerid, Player killer)`		A player died; `killer` is null when there is no attacker.
`player::disconnect`	`(int playerid)`		A player has disconnected; clean up per-player state.
`player::enter_vehicle`	`(int playerid, Vehicle car)`		A player entered a vehicle (as driver or passenger).
`player::exit_vehicle`	`(int playerid, Vehicle car)`		A player exited a vehicle.
`player::finished_downloading`	`(int playerid, int virtualworld)`		A 0.3.DL client finished downloading custom models for a virtual world.
`player::key_state_change`	`(int playerid, int newkeys, int oldkeys)`		A player's key state changed; compare newkeys/oldkeys for press/release.
`player::pickup`	`(int playerid, int pickupid)`		A player picked up a pickup.
`player::request_class`	`(int playerid, int classid)`	bool	A player requested a class; return false to veto the selection.
`player::request_class_done`	`(int playerid, int classid, int skin)`		The class response was sent to the client; apply the chosen skin/camera here.
`player::request_download`	`(int playerid, int type, int crc)`	bool	A 0.3.DL client requested a custom model/texture; return false to deny, or call RedirectDownload.
`player::request_spawn`	`(int playerid)`	bool	A player requested to spawn; return false to veto the spawn.
`player::select_object`	`(int playerid, int objecttype, int objectid, int modelid, float x, float y, float z)`		A player selected an object in the map editor.
`player::spawn`	`(int playerid)`		A player has spawned; reset health/armour and initialise gameplay state.
`player::state_change`	`(int playerid, int newstate, int oldstate)`		A player's state changed (on foot, driving, dead, ...).
`player::stats`	`(int playerid, int money, int drunk)`		A player's money/drunk statistics changed.
`player::trailer_sync`	`(int playerid, int vid)`		A trailer synced to a vehicle.
`player::unoccupied_sync`	`(int playerid, int vid, float health)`		An unoccupied vehicle synced; raw vehicle health sample.
`player::update`	`(int playerid, float x, float y, float z)`		A player sync update arrived; raw position for anticheat and logic.
`player::weapon_shot`	`(int playerid, int weaponid, int hittype, int hitid, float hx, float hy, float hz)`		A player fired a weapon; reports the hit type, target and coordinates.
`system::start`	`()`		Fires once when the gamemode loads; set up globals, classes and world state here.
`system::stop`	`()`		Fires when the server shuts down; release resources and persist state here.
`textdraw::click`	`(int playerid, TextDraw td)`		A player clicked a selectable text draw (65535 = cancel/empty area).
`textdraw::create`	`(int x, int y, string text)`	TextDraw	Factory event to construct a text draw; return the created TextDraw.
`timer::every`	`()`		Periodic timer callback context; use with the timer natives.
`vehicle::create`	`(int model, float x, float y, float z)`	Vehicle	Factory event to construct a vehicle; return the created Vehicle.
`vehicle::damage_status_update`	`(int vid, int pid, int panels, int doors, int lights, int tyres)`		A vehicle's panel/door/light/tyre damage changed.
`vehicle::death`	`(int vid, int killer)`		A vehicle was destroyed; `killer` is the responsible player id.
`vehicle::spawn`	`()`		A vehicle respawned.
`world::actor_damage`	`(int actorid, int playerid, float amount, int weaponid, int bodypart)`		An actor took damage; reports attacker, amount, weapon and body part.
`world::area_enter`	`(int playerid, int area)`		A player entered a dynamic area.
`world::area_leave`	`(int playerid, int area)`		A player left a dynamic area.
`world::checkpoint`	`(int playerid, float x, float y, float z)`		A player entered their checkpoint.
`world::checkpoint_leave`	`(int playerid)`		A player left their checkpoint.
`world::object_create`	`(int model, float x, float y, float z)`	Object	Factory event to construct an object; return the created Object.
`world::race_checkpoint_enter`	`(int playerid)`		A player entered their race checkpoint.
`world::race_checkpoint_leave`	`(int playerid)`		A player left their race checkpoint.