gmp

The gmp module is the entry point of every script:

local gmp = require("gmp")

On the client side it registers event handlers, creates and finds characters and controls the story mode. Actions on characters are methods of Character; common types and constants are shared with the server side.

EventsCopy Anchor Link

onCopy Anchor Link

gmp.on(event, handler)

Registers a handler for a game event. Several handlers can be registered for the same event; they are called in the order of registration. Events are reported for every character (the player, NPCs, monsters, puppets), also when the cause is an API call (e.g. ch:kill()).

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

CharactersCopy Anchor Link

spawnCharacterCopy Anchor Link

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

Requests creation of a character at the given point. 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 = gmp.spawnCharacter("SpawnAIAgentDefinition_BigMolerat", 1200, -350, 80, 90)
gmp.on("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.

getCharacterByIdCopy Anchor Link

gmp.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.

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

Returns: gmp.Character | nil - The character, or nil when no character with this id is present on this client (an empty player slot, or an NPC that does not exist or has not been created here yet).

Story modeCopy Anchor Link

disableStoryModeCopy Anchor Link

gmp.disableStoryMode()

Disables the game's story for the rest of the session. It cannot be undone: removed NPCs stay removed (also in a save game, if the game makes one).

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).

Best called before the world loads (in the main menu) - a new game then starts without the intro.

Returns: boolean - Always true.

isStoryModeEnabledCopy Anchor Link

gmp.isStoryModeEnabled()

Tells whether the game's story is enabled.

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

TypesCopy Anchor Link

EventNameCopy Anchor Link

Names of the client-side events accepted by gmp.on. See Events for the handler arguments.