events

Subscribe to player and keyboard events with script-owned callbacks.

events.subscribe(name, callback) -> id subscribes the calling script; events.unsubscribe(id) -> boolean removes its subscription. Unknown names raise errors. At most 128 subscriptions per script; all are removed on stop. Callbacks run on the Lua script owner and receive a copied event table. It is safe to unsubscribe from within a callback. New listeners do not receive events already sampled before registration.

Event name	Payload and timing
player_join	id, generation, name, ped, local_player, modder, reasons; new roster identity after the initial baseline.
player_leave	Same fields copied from the departing identity, which is no longer a valid player reference.
player_spawn	Same fields; ped becomes alive/present, respawns, or changes. Includes local and remote players.
player_modder	Same fields; the shared detection state first marks that identity as a modder.
key_press	key (Windows VK), down, repeat; key-down and key-up window messages, including repeats.

Every payload also contains event. Player events reflect the existing player manager's per-update samples; initial roster contents are a baseline, not synthetic joins. A spawn here means a newly observed live ped, so streaming a remote ped back in can also trigger it. Compare id and generation; slots can be reused. Key messages use a bounded 128-entry queue and never execute Lua in the window callback. events.dropped() reports dropped key messages.

local listener = events.subscribe("key_press", function(event)
    if event.key == 0x77 and event.down and not event["repeat"] then
        util.notify("F8 pressed")
    end
end)
-- events.unsubscribe(listener)