Functions
Global functions of server-side scripts: events, player slots, chat, commands, custom events and timers.
Server-side scripts run on the game server (gmp_server). All functions are global - no require is needed.
Characters are identified by ids (pid): ids 0 to getMaxSlots() - 1 are players (one per player slot), ids from getMaxSlots() up are server-side NPCs created with createNpc. Functions with Player in the name (Players) work for both; functions with Npc in the name (NPCs) only for server-side NPCs. Common types and constants are shared with the client side.
Events
addEventHandler
addEventHandler(event, handler)Registers a handler for a server event. Several handlers can be registered for the same event;
they are called in the order of registration. Events about characters (onPlayerSpawn,
onPlayerDead, onPlayerHit, onPlayerRespawn) are reported for players and for server-side NPCs;
the id tells which one it is. A handler of onPlayerChat can return false to stop the message
from being shown in the chat.
Custom events sent by clients (triggerServerEvent) use the same function; their handlers get the
id of the sending player first, then the arguments.
addEventHandler("onPlayerConnect", function(pid)
sendMessageToAll(getPlayerName(pid) .. " entered the Colony")
end)
addEventHandler("buyItem", function(pid, item, amount) -- triggerServerEvent("buyItem", ...) on the client
giveItem(pid, item, amount)
end)| Parameter | Type | Description |
|---|---|---|
event | ServerEventName | Name of the event. |
handler | function | Function called when the event occurs; its arguments depend on the event (see Events). |
Returns: boolean - Always true.
removeEventHandler
removeEventHandler(event, handler)Removes a handler registered with addEventHandler (the same function value).
| Parameter | Type | Description |
|---|---|---|
event | ServerEventName | Name of the event. |
handler | function | The registered function. |
Returns: boolean - false when this function was not registered for the event.
triggerClientEvent
triggerClientEvent(pid, name, ...)Sends a custom event to one player's client scripts (addEventHandler(name, ...) on the client).
Arguments may be nil, booleans, numbers, strings and tables of those.
triggerClientEvent(pid, "showScore", 10)| Parameter | Type | Description |
|---|---|---|
pid | integer | Player id. |
name | string | Name of the event (1-64 characters). |
... | any | Arguments. |
Returns: boolean - false when no player is connected on this slot.
triggerClientEventToAll
triggerClientEventToAll(name, ...)Sends a custom event to the client scripts of every connected player.
| Parameter | Type | Description |
|---|---|---|
name | string | Name of the event (1-64 characters). |
... | any | Arguments. |
Returns: boolean - Always true.
Players and ids
getMaxSlots
getMaxSlots()Returns the number of player slots of the server. Player ids are 0 to getMaxSlots() - 1;
ids from getMaxSlots() up belong to server-side NPCs.
for pid = 0, getMaxSlots() - 1 do
if isPlayerConnected(pid) then sendMessage(pid, "Server restart in 5 minutes") end
endReturns: integer - Number of player slots.
getPlayerCount
getPlayerCount()Returns the number of connected players.
Returns: integer
isPlayerConnected
isPlayerConnected(pid)Tells whether a player is connected on the given slot.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Player id (0 to getMaxSlots() - 1). |
Returns: boolean - false for an empty slot and for NPC ids.
kickPlayer
kickPlayer(pid, reason?)Disconnects a player from the server.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Player id. |
reason (optional) | string | Reason shown to the player. |
Returns: boolean - false when no player is connected on this slot.
Chat
sendMessage
sendMessage(pid, text)Sends a chat message to one player.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Player id. |
text | string | Message text (UTF-8). |
Returns: boolean - false when no player is connected on this slot.
sendMessageToAll
sendMessageToAll(text)Sends a chat message to all connected players.
| Parameter | Type | Description |
|---|---|---|
text | string | Message text (UTF-8). |
Commands
registerCommand
registerCommand(name, handler)Registers a chat command. When a player types /name ... in the chat, the handler is called
with the player id and the rest of the line, and the line is not shown in the chat.
registerCommand("ore", function(pid, args)
local amount = tonumber(args) or 10
giveItem(pid, "ItMi_Orenugget", amount)
sendMessage(pid, "The Ore Barons are watching...")
end)| Parameter | Type | Description |
|---|---|---|
name | string | Command name without the slash, e.g. "ore" for /ore. |
handler | function | Called as handler(pid, args): pid = the player who typed the command, args = text after the command name ("" when none). |
Timers
setTimer
setTimer(handler, intervalMs, repeating?)Calls a function after the given time, once or repeatedly.
local announcer = setTimer(function()
sendMessageToAll("Visit the Old Camp market!")
end, 600000, true) -- every 10 minutes| Parameter | Type | Description |
|---|---|---|
handler | function | Function to call (no arguments). |
intervalMs | integer | Time in milliseconds. |
repeating (optional) | boolean | true = call it every intervalMs until killTimer. Default false (once). |
Returns: integer - Id of the timer, for killTimer.
killTimer
killTimer(timerId)Stops a timer started with setTimer.
| Parameter | Type | Description |
|---|---|---|
timerId | integer | Id returned by setTimer. |
Returns: boolean - false when no such timer is running.
Types
ServerEventName
Names of the server events accepted by addEventHandler. See Events for the handler arguments.
Any other name is a custom event sent by a client with triggerServerEvent.
| Value | Description |
|---|---|
"onPlayerConnect" | A player connected to the server (got a slot). |
"onPlayerDisconnect" | A player disconnected from the server. |
"onPlayerSpawn" | A player's character entered the world, or a server-side NPC was created. |
"onPlayerChat" | A player sent a chat message. |
"onPlayerDead" | A player or a server-side NPC died. |
"onPlayerHit" | A player or a server-side NPC was hit. |
"onPlayerRespawn" | A player or a server-side NPC was revived. |
string | A custom event from a client (triggerServerEvent). |