Events, commands and timers

`EventHandlerOpts`

Fields

propagate (optional) boolean — Fire for descendant sources too (default true).
priority (optional) "high"|"normal"|"low" — Dispatch order (default "normal").

`CommandHandlerOpts`

Fields

case_sensitive (optional) boolean — Match the command name case-sensitively (default false).
priority (optional) "high"|"normal"|"low" — Dispatch order (default "normal").

`dlmp.add_event_handler`

Registers an event handler. event must be a built-in event name; most handlers' return value is ignored (use explicit SDK calls for side effects). Events reach handlers one at a time, in the order the server raised them, regardless of kind; the effects of a handler (a kick, a respawn, a seat change) are dispatched after the current event, in the same server step. Built-in events and their arguments: resource_start, resource_stop, player_connecting(name, ip), player_auth(pending), player_connect(player), player_disconnect(player, reason), player_spawn(player), player_pause(player, paused), player_waypoint(player, x, y) (nil, nil: taken off), player_weapon_switch(player, previous, current), player_weapon_reload(player, weapon), player_suspicion(player, class, value, limit, witnesses), player_key_change(player, key, pressed), player_state_change(player, state, previous), player_interior_change(player, interior, previous), player_stealth_kill(player, victim), player_death(player, killer, weapon, body_part), player_weapon_fire(player, weapon, x, y, z, hit_player, hit_vehicle, hit_object), player_projectile_create(player, weapon), player_damage(victim, attacker, weapon, body_part, amount), pickup_interact(player, pickup, info), checkpoint_enter(player, checkpoint), checkpoint_leave(player, checkpoint), colshape_enter(colshape, player, vehicle), colshape_leave(colshape, player, vehicle) (one of the two is set), player_chat(player, text), player_action(player, name, pressed), player_enter_vehicle(player, vehicle, seat, jacked), player_exit_vehicle(player, vehicle, seat, jacker), vehicle_death(vehicle, cause, killer), vehicle_damage(vehicle, player), vehicle_control(vehicle, player, control, on), vehicle_start_enter(vehicle, player, seat, jacked), spectate_lost(player, target), player_stream_in(player, for_player), player_stream_out(player, for_player), vehicle_jack(vehicle, jacker, victim), vehicle_syncer(vehicle, syncer, previous), vehicle_respawn(vehicle), trailer_attach(trailer, tractor, player), trailer_detach(trailer, tractor, player), winch_attach(vehicle, heli, player), winch_detach(vehicle, heli, player), player_remote_enter(player, rc), player_remote_exit(player, rc, reason), player_detonate_satchels(player). player_weapon_fire fires for each accepted shot; x, y, z is where its ray ended, and at most one of the hits is set. A hit is what the shooter's game saw, as far as the server can verify it (near the end of the ray, visible to the shooter): it neither deals nor proves damage (player_damage does), so do not reward or punish based on it. hit_object is set only for the resource that created the object; an object on a bone or a broken object is never hit (it has no collision), except by a shot fired before the shooter saw the object break. An object counts as hit within its model's size of the ray's end, and an object on a vehicle within 40 m of the vehicle: use it to score small, free-standing targets. player_key_change fires for each key that goes down or up (names as in Player:keys), up to 20 keys per second per player: a quick tap may arrive late but is never lost. A death, a freeze or a pause releases all keys. Observe-only. player_weapon_reload fires when the held weapon starts reloading. Observe-only.

player_suspicion fires when a player's client reports something implausible, at most once per class every 5 s: class is "teleport", "speed" or "fly" (the player's own frames), "vehicle_teleport" or "vehicle_speed" (a vehicle it controls), "god_mode" (hits it ignores, or health it gave itself) or "vehicle_god_mode"; value compared to limit shows the margin, in the class's own unit. The server already enforces the limits on the frame; any sanction is up to the gamemode (player:kick). False positives are possible, so weigh repeated reports: a single shooter can shoot through a wall and make its target look like "god_mode". witnesses is the number of players whose shots the report is based on, 0 if none. Observe-only. player_state_change (states as in Player:state) and player_interior_change fire up to 50 ms after the change: a change reverted within that time raises nothing. A disconnect raises only player_disconnect. Observe-only. player_stealth_kill fires when a player's stealth kill passes the server's checks, before any client plays it; return false to refuse it, and neither ped plays anything (the attacker's next attempt waits the usual interval). The vehicle events fire for a player's own enter/exit (and for the seat freed by its death); put_player_in_vehicle/remove_player_from_vehicle do not raise them. A jack raises the driver's player_exit_vehicle (jacker set), then the jacker's player_enter_vehicle (jacked = that driver); both are nil otherwise. vehicle_start_enter fires when a player requests a seat it is allowed to take, before it gets in (jacked is the driver it would take the vehicle from, nil otherwise); return false to refuse it, and the player does not get in. A locked, full, too distant or wrecked vehicle is refused before this event; a handler that respawns the vehicle or disables jacking also refuses it. vehicle_jack fires when a player starts taking a vehicle from its driver (only while dlmp.vehicle_jacking()), after vehicle_start_enter allowed it; return false to refuse it, and the jacker takes a free passenger seat instead, as when jacking is disabled. spectate_lost fires when a spectate ends on its own: the target changed world or left the server (target nil). By then the camera is back with the player; a handler may spectate someone else. Observe-only. player_stream_in / player_stream_out fire when the server starts or stops showing player to for_player: they share a world and are within stream distance (a seated player follows its vehicle; a spectated player is always shown). This is the server's decision; the client may create the player a moment later. A disconnect raises only player_disconnect. Observe-only. vehicle_syncer fires when the player syncing a driverless vehicle changes (syncer nil = nobody syncs it, e.g. it got a driver; previous nil = nobody did, or that player left), at most once per vehicle per server step: a syncer that changes and changes back within one step raises nothing. Observe-only. vehicle_respawn fires after dlmp.respawn_vehicle brings a vehicle back, whichever resource called it. Observe-only. trailer_attach fires when a player's tractor hitches a trailer (player drives the tractor, or syncs it without a driver); return false to refuse it, and the trailer is unhitched again. trailer_detach fires when a player's tractor loses its trailer. Neither is raised by dlmp.attach_trailer/detach_trailer, nor when the core unhitches a trailer that gets a driver, explodes, respawns or is destroyed (or whose tractor does). winch_attach fires when the magnet of a player's helicopter picks up a vehicle (player pilots the helicopter, or syncs it without a pilot); return false to refuse it, and the vehicle drops again. winch_detach fires when the pilot releases it. Neither fires when the core releases a vehicle that gets a driver, explodes, respawns or is destroyed (or whose helicopter does), nor for dlmp.set_vehicle_winch. player_remote_enter fires when a player on foot who drives no RC vehicle takes control of one within a few meters with its key (F; not a locked one, nor one someone else drives); return false to refuse it. dlmp.set_remote_vehicle does not raise it. player_remote_exit fires when a player stops driving its RC vehicle on its own (reason "exit": its exit key) or the RC vehicle gets farther from the player's body than dlmp.rc_range() (reason "range"); the RC vehicle is already released. dlmp.remove_remote_vehicle, a death, a world change, taking a seat, and the RC vehicle exploding or respawning end control without raising it. player_connecting fires on dlmp.root when a new connection passes the server's own checks, before it gets a player id: no player exists yet, and the name is only the client's claim. Return false to refuse it, optionally with a reason as a second value (return false, "Members only"): printable UTF-8, up to 20 bytes, shown to the player. A reason that does not fit is logged and dropped; the refusal still applies. player_auth reaches only the auth resource ([auth] resource), once per new connection after player_connecting: decide with pending:accept() or pending:reject(reason), immediately or later. A handler that returns without deciding defers the decision; one that raises an error rejects. A connection still undecided after [auth] timeout_seconds is rejected. player_detonate_satchels fires when a player presses its detonator while it has a satchel placed; return false to refuse it, and its satchels stay in place on every client (presses arrive at most once per second). dlmp.detonate_satchels does not raise it. vehicle_death fires once when a vehicle explodes (cause "explosion") or sinks and drowns (cause "water"; it keeps its appearance and last health); its source is the vehicle, which is parented to the creating resource's resource_root. killer is the Player credited with the explosion (nil for none, a drowning, or a departed player); everyone who died inside gets the same killer and weapon 51 in player_death. The vehicle stays a wreck until the resource calls dlmp.respawn_vehicle. vehicle_damage fires when the player driving (or syncing) a vehicle reports new visible damage; a status set through dlmp.set_vehicle_damage_status / dlmp.repair_vehicle does not raise it. player_weapon_switch fires when the weapon a player holds changes (its own switch, a pickup or a weapon call; 0 = fists), once its sync confirms the change; the unarmed start after a respawn does not raise it. vehicle_control fires when a driver asks to switch a param (control "engine" or "lights"; locking is up to the gamemode, with dlmp.set_vehicle_locked; on is the requested state); return false to refuse it, otherwise it is applied like dlmp.set_vehicle_*. For player_death/player_damage, killer/attacker is a Player or nil (environmental damage / unattributed death / departed attacker); weapon/body_part are integers and amount is the total hp+armor loss. For an explosion or fire, weapon is what started it: 16 grenade, 19 rocket, 39 satchel, 18 molotov, 37 flamethrower or dlmp.create_fire, 51 a vehicle explosion or dlmp.create_explosion. Environmental damage (no attacker) carries its cause: 53 drowning, 54 fall, 37 fire, 51 explosion, 49/50 a vehicle nobody drives; a death whose last damage was environmental has no killer and has that cause, unless the player was in a vehicle that exploded within the last few seconds: then the vehicle's killer is the killer. Both are observe-only. player_death fires once per life: on the player's own report of its death, or from the server when it counted the player dead (health 0, the vehicle it was in exploded, a stealth kill on it) and no report arrived within about a second; if the player leaves in that time, player_death fires before its player_disconnect. player_chat can be refused too: return false to cancel the default chat broadcast (reply with player:send_message(...), or send the line to a team or world with player:send_chat(...)); nil or true allows the broadcast. Every event that can be refused (vehicle_start_enter, vehicle_jack, vehicle_control, trailer_attach, winch_attach, player_remote_enter, player_detonate_satchels, player_stealth_kill, player_chat, player_connecting) fails closed: a handler that raises an error or exceeds the time limit refuses it, as false would. All handlers still run; the return value of any other event is ignored. An event whose source vehicle an earlier handler already destroyed is not raised (a refusable event is refused). Player events reach dlmp.root handlers, not dlmp.resource_root ones: players belong to no resource.

Parameters

event string
element Element
fn fun(...):boolean? — , string?
opts (optional) EventHandlerOpts