Lua API

Gothic Multiplayer servers are scripted in Lua 5.4. Scripts are plain text files - no compilation is needed. They react to game events and change the world through the gmp module.

local gmp = require("gmp")
local E = gmp.enum

-- log every death caused by another character
gmp.on("dead", function(who, killer, weapon)
  if killer then
    print(killer:getName() .. " killed " .. who:getName())
  end
end)

-- a guard that hits hard
local guardRequest = gmp.spawnCharacter("CharacterDefinition_Human_OC_GRD_Jackal_201", 1200, -350, 80, 90)

gmp.on("playerSpawn", function(id, who)
  if id ~= guardRequest or not who then return end
  who:setName("Jackal")
  who:giveItem("ItMw_1H_Sword_01", 1)
  who:equipItem("ItMw_1H_Sword_01")
  who:grantSkill(E.Skill.Melee_OneHanded_Master)
end)

ConventionsCopy Anchor Link

These rules apply to the whole API:

• Characters are objects. The player, NPCs, monsters and remote players' puppets are Character objects, and actions on them are methods: ch:giveItem("ItMi_Orenugget", 10).
• Game classes are passed by name. Items, characters and weapons use the game's class names, e.g. "ItMi_Orenugget" (ore nugget), "ItMw_1H_Sword_01" (one-handed sword), "CommonPlayerDefinition". Names are case-sensitive.
• Units. Distances and positions are in game units: 1 unit = 1 cm. Angles are in degrees (0 = world X axis, 90 = world Y axis).
• Results. Actions return true on success and false when the game rejected the action or the character no longer exists. Getters return nil when the character no longer exists.
• Optional parameters are marked with ? in the reference; silent? parameters hide the notification the game would show on the player's HUD.
• Constants live in gmp.enum and are always used by name: gmp.enum.HitType.MeleeHeavy. Tip: local E = gmp.enum keeps scripts short.

ReferenceCopy Anchor Link

Editor supportCopy Anchor Link

The API ships with definition files for the Lua Language Server. With the Lua extension for VS Code you get completion, inline documentation and type checking for every function and constant while you write your scripts.