events

modkit.events registers handlers and sends events. The events guide explains the paths and the argument rules.

modkit.events.add

modkit.events.add(name, fn)

Shared

Parameter	Type	Description
name	string	event name, built-in or your own
fn	function	handler. On the server, events from a client and built-in player events pass the `player` table first.

Returns: nothing.

Several handlers per name are allowed. They run in the order they were added. An error in one handler is logged and does not stop the others.

modkit.events.add("playerSpawned", function(player)
  player:notify("Good luck, " .. player.name)
end)

modkit.events.remove

modkit.events.remove(name, fn)

Shared

Parameter	Type	Description
name	string	event name
fn	function	the same function value that was passed to `add`

Returns: true when at least one handler was removed.

Removing a handler while its event is being dispatched is safe. The running dispatch still finishes with the old list.

local function once(player)
  modkit.events.remove("playerSpawned", once)
  print("first spawn on this server start: " .. player.name)
end
modkit.events.add("playerSpawned", once)

modkit.events.call

modkit.events.call(name, ...)

Shared

Fires an event on the same side, in every loaded resource including your own. Use it to let resources talk to each other. The arguments are copied through JSON, so only strings, numbers, booleans and nil arrive. There is no player argument unless you pass one yourself, for example as a Steam ID.

On the client modkit.events.trigger is a second name for the same function.

Returns: nothing. The handlers have run when the call returns.

modkit.events.call("economy:paid", player.steamId, 250)

modkit.events.add("economy:paid", function(steamId, amount)
  local player = modkit.players.get(steamId)
  if player then player:notify("You received " .. amount) end
end)

A client can send the same event name with callRemote. In that case the first argument is a player table, not a string. Check the type when the event matters.

modkit.events.callRemote

modkit.events.callRemote(name, ...)

Client

Sends an event to the server scripts. The server handler receives the sender's player table first, then the arguments. Nothing is sent while the script link is down.

Parameter	Type	Description
name	string	event name. The names of built-in server events are dropped by the server.
...	string, number, boolean, nil	arguments

Returns: nothing.

modkit.events.callRemote("shop:buy", "meat", 2)

modkit.events.callAll

modkit.events.callAll(name, ...)

Server

Sends an event to the client scripts of every player.

Returns: nothing.

modkit.events.callAll("round:start", 300)

Built-in server events

Event	Arguments	When
`playerConnected`	`player`	a new player is in the game and the script link is open. Fires once per visit.
`playerSpawned`	`player`	the player controls a new dinosaur. Fires after every respawn, and right after `playerConnected` when the player already has one.
`playerDied`	`player`, `killer`	the dinosaur went from alive to dead
`playerDisconnected`	`player`	the player is gone. The table holds the last known data. Methods that need the player in the game return `false`.
`playerJoined`	`player`	the script link opened. Fires right after `playerConnected`, and again when a dropped link comes back.
`playerLeft`	`player`	the script link closed. The player stays in `modkit.players` until they leave the game or the 45 second grace period ends.
`chat`	`player`, `text`, `mode`	chat message, can be cancelled. See chat.
`chatCommand`	`player`, `line`	a command line was typed. See chat.
`resourceStart`	`name`	a resource finished loading its server scripts
`serverStarted`	none	every resource from `server.cfg` is loaded. Fires once.
`everySecond`	none	once per second, for cheap periodic work without a timer
`playerRejected`	`player`, `reason`	a player was kicked by the ban list, the whitelist, the reserved slots or the launcher check. The launcher check uses the reason `"launcher"`. A player rejected while joining gets neither `playerConnected` nor `playerDisconnected`. A player kicked after a lost script link gets `playerDisconnected` as usual.
`playerChangedSpecies`	`player`, `oldSpecies`	the player controls a dinosaur of another species than at the last check
`playerGrew`	`player`, `step`	growth crossed `0.25`, `0.5`, `0.75` or `1.0` upwards. One event per step. Not fired on spawn or species change.
`playerHealthChanged`	`player`, `oldHealth`, `newHealth`	health moved by at least 5 percent of the maximum since the last event
`populationChanged`	`distribution`, `online`	the species counts changed. `distribution` is a table `species -> count`. See population.
`zoneEnter`, `zoneLeave`	`player`, `zone`	see zones
`garageParking`, `garageRestoring`	`player`, `name` or `slot`	before a park or restore, can be cancelled with `return false`. See garage.
`garageParked`, `garageRestored`	`player`, `slot`	after a park or restore
`garageRestoreFailed`	`steamId`, `slotId`, `reason`	the dinosaur vanished during a restore
`stateApplied`	`player`	`player:applyState` finished its main steps
`aiSpawned`, `aiDespawned`	`id` or `id`, `reason`	an animal with a handle appeared or is gone. See ai.
`aiStateChanged`, `aiTargetChanged`	`id`, `from`, `to` or `id`, `target`	an animal with a brain changed its state or its target
`aiDamaged`, `aiDied`	`id`, `attacker` or `killer`	an animal with a brain was hit or died
`customSpeciesChanged`	`player`, `from`, `to`	the custom species of a player was set or removed. See species.
`customAttack`	`player`, `attackId`	a custom attack is about to start, can be cancelled with `return false`
`customAttackHit`	`player`, `attackId`, `victim`, `damage`	a custom attack hit a player or an animal

The player, zone and population events come from a check that runs twice per second. They can be up to half a second late.

Clients can not send any of these names. The server drops a client event with a built-in name.

The killer argument

killer is what the game reports as the last damage causer (GetMyDamageCauser) at the moment the plugin notices the death.

Value	Meaning
a `player` table	the causer is a dinosaur of an online player
`{ species = "...", ai = true }`	the causer is not a player
`nil`	the game reports nobody, for example after starving or falling

modkit.events.add("playerDied", function(player, killer)
  if killer and killer.steamId then
    modkit.chat.broadcast(killer.name .. " killed " .. player.name)
  elseif killer then
    modkit.chat.broadcast(player.name .. " was killed by a " .. killer.species)
  end
end)

killer is what the game reports at that moment. It can be nil for a kill by a player when the game has already cleared its damage causer.

resourceStart

A resource receives resourceStart for itself and for every resource that loads after it. It does not receive it for resources that loaded earlier. There is no resourceStop. Resources stop only when the server process ends.

Built-in client events

Event	Arguments	When
`onClientReady`	none	all resources are downloaded and started
`onServerConnected`	`address`	right after `onClientReady`. `address` is the server address the launcher passed, for example `"203.0.113.10:7777"`.
`resourceStart`	`name`	a resource finished loading its client scripts. Same rule as on the server.

Client scripts start late. The script link opens about 45 seconds after the game began to connect, then the files are downloaded. By the time onClientReady fires, the player may already be in the game.