Functions

Client-side scripts are sent by the server and run in the game of every player. All functions below are global - no require is needed.

They register event handlers, create and find characters and control the story mode. Actions on characters are methods of Character; common types and constants are shared with the server side.

EventsCopy Anchor Link

addEventHandlerCopy Anchor Link

addEventHandler(event, handler)

Registers a handler for an event. Several handlers can be registered for the same event; they are called in the order of registration. Game events are reported for every character (the local player, NPCs, monsters, remote players), also when the cause is an API call (e.g. ch:kill()). Custom events sent by the server with triggerClientEvent use the same function.

addEventHandler("dead", function(who, killer, weapon)
  if killer then
    print(killer:getName() .. " killed " .. who:getName())
  end
end)

addEventHandler("showScore", function(points)   -- triggerClientEvent(pid, "showScore", 10) on the server
  addChatMessage("Score: " .. points)
end)

Returns: boolean - Always true.

removeEventHandlerCopy Anchor Link

removeEventHandler(event, handler)

Removes a handler registered with addEventHandler (the same function value).

Returns: boolean - false when this function was not registered for the event.

triggerServerEventCopy Anchor Link

triggerServerEvent(name, ...)

Sends a custom event to the server. Server scripts receive it with addEventHandler(name, function(pid, ...) end) - the id of the sending player comes first. Arguments may be nil, booleans, numbers, strings and tables of those (no functions or characters; send ch:getId() instead of a character). At most 64 KB together.

triggerServerEvent("buyItem", "ItFo_Potion_Health_01", 2)

Returns: boolean - false when the client is not connected to a server (yet).

CharactersCopy Anchor Link

getLocalPlayerCopy Anchor Link

getLocalPlayer()

Returns the local player's character.

Returns: Character | nil - nil before the character exists (loading screen).

getLocalPlayerIdCopy Anchor Link

getLocalPlayerId()

Returns the server id of the local player (their player slot).

Returns: integer | nil - nil when not connected to a server.

getCharacterByIdCopy Anchor Link

getCharacterById(serverId)

Returns the character with the given server id. The server gives every character it manages an id:

• 0 to slots - 1 - players, one id per player slot of the server (the local player has one too);
• slots and above - NPCs created by server-side scripts.

slots is the number of player slots configured on the server. Characters far away from the local player are not present in this game (the server streams only the nearby ones), so the function can return nil for a connected player.

local ch = getCharacterById(0)
if ch then print(ch:getName()) end

Returns: Character | nil - The character, or nil when no character with this id is present in this game.

spawnCharacterCopy Anchor Link

spawnCharacter(class, x, y, z, angle)

Requests creation of a character at the given point - only in this game (other players do not see it; for characters everyone sees use createNpc on the server). The game creates characters asynchronously, so the function returns a request number immediately and the ready character arrives about 1 second later in the "characterSpawned" event (with the same id).

The character is created exactly as the game makes it - only the facing angle is set. Many characters can be requested at once (each request has its own number). Different human character definitions requested in quick succession are created one after another (about 1-3 seconds each).

local requestId = spawnCharacter("SpawnAIAgentDefinition_BigMolerat", 1200, -350, 80, 90)
addEventHandler("characterSpawned", function(id, who)
  if id == requestId and who then who:setName("Molerat") end
end)

Returns: integer | nil - Request number, or nil when the class is not a valid character class, there is no world, or the game rejected the request.

Chat and timersCopy Anchor Link

addChatMessageCopy Anchor Link

addChatMessage(text, color?)

Shows a line in the local chat window (only for this player; to send to everyone use the server's sendMessageToAll).

setTimerCopy Anchor Link

setTimer(handler, intervalMs, repeating?)

Calls a function after the given time, once or repeatedly.

Returns: integer - Id of the timer, for killTimer.

killTimerCopy Anchor Link

killTimer(timerId)

Stops a timer started with setTimer.

Returns: boolean - false when no such timer is running.

Story modeCopy Anchor Link

disableStoryModeCopy Anchor Link

disableStoryMode()

Disables the game's story for the rest of the session. In multiplayer it is always disabled already (the client does it at start); the function is useful for offline tests. It cannot be undone: removed NPCs stay removed.

Effects:

• story cutscenes do not start - neither the intro after the loading screen nor any later one; a cutscene that is already running is skipped;
• no NPC pulls the player into a conversation (e.g. Diego's greeting); conversations started by the player work as usual;
• all NPCs and monsters of the game are removed from the world, including those that appear later (respawns, streamed-in parts of the world); characters created through the API stay;
• the glossary is not updated by the removed NPCs (no "Glossary updated" notifications).

Returns: boolean - Always true.

isStoryModeEnabledCopy Anchor Link

isStoryModeEnabled()

Tells whether the game's story is enabled.

Returns: boolean - false after disableStoryMode() was called.

TypesCopy Anchor Link

ClientEventNameCopy Anchor Link

Names of the client-side game events accepted by addEventHandler. See Events for the handler arguments. Any other name is a custom event sent by the server with triggerClientEvent.