Players
Functions for players and server-side NPCs by id: name, attributes, items, skills, position, combat and state.
These functions take a character id (pid) and work for players (0 to gmp.getMaxSlots() - 1) and for server-side NPCs (gmp.getMaxSlots() and above) alike - gmp.setPlayerHealth heals a player as well as an NPC created with gmp.createNpc. They return false (getters: nil) when the id is not a connected player or an existing server-side NPC.
Name
setPlayerName
gmp.setPlayerName(pid, name)Changes the name of the character - the name the game shows above it, when aiming at it and in conversations, in the game of every player.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
name | string | New name (UTF-8; Polish and other national characters are supported). |
Returns: boolean
getPlayerName
gmp.getPlayerName(pid)Returns the name of the character. For a player it is the nickname they joined with, unless it was
changed with setPlayerName.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
Returns: string | nil - Name in UTF-8.
Attributes
Setters change the BASE value of an attribute; bonuses from rings, amulets, armor and effects are added on top of it by the game. Getters return the CURRENT value including bonuses. The game limits Health to MaxHealth and Mana to MaxMana - set the maximum first.
setPlayerHealth
gmp.setPlayerHealth(pid, value, silent?)Sets the health points of the character (limited to its maximum health).
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
value | number | New health points. |
silent (optional) | boolean | true = no attribute change notification on the player's HUD. Default false. |
Returns: boolean
getPlayerHealth
gmp.getPlayerHealth(pid)Returns the current health points of the character.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
Returns: number | nil
setPlayerMaxHealth
gmp.setPlayerMaxHealth(pid, value, silent?)Sets the maximum health points of the character.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
value | number | New maximum health. |
silent (optional) | boolean | true = no attribute change notification on the player's HUD. Default false. |
Returns: boolean
getPlayerMaxHealth
gmp.getPlayerMaxHealth(pid)Returns the current maximum health points of the character (including bonuses).
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
Returns: number | nil
setPlayerMana
gmp.setPlayerMana(pid, value, silent?)Sets the mana of the character (limited to its maximum mana).
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
value | number | New mana. |
silent (optional) | boolean | true = no attribute change notification on the player's HUD. Default false. |
Returns: boolean
getPlayerMana
gmp.getPlayerMana(pid)Returns the current mana of the character.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
Returns: number | nil
setPlayerMaxMana
gmp.setPlayerMaxMana(pid, value, silent?)Sets the maximum mana of the character.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
value | number | New maximum mana. |
silent (optional) | boolean | true = no attribute change notification on the player's HUD. Default false. |
Returns: boolean
getPlayerMaxMana
gmp.getPlayerMaxMana(pid)Returns the current maximum mana of the character (including bonuses).
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
Returns: number | nil
setPlayerStrength
gmp.setPlayerStrength(pid, value, silent?)Sets the base strength of the character.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
value | number | New base value. |
silent (optional) | boolean | true = no attribute change notification on the player's HUD. Default false. |
Returns: boolean
getPlayerStrength
gmp.getPlayerStrength(pid)Returns the current strength of the character (including bonuses).
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
Returns: number | nil
setPlayerDexterity
gmp.setPlayerDexterity(pid, value, silent?)Sets the base dexterity of the character.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
value | number | New base value. |
silent (optional) | boolean | true = no attribute change notification on the player's HUD. Default false. |
Returns: boolean
getPlayerDexterity
gmp.getPlayerDexterity(pid)Returns the current dexterity of the character (including bonuses).
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
Returns: number | nil
Items
giveItem
gmp.giveItem(pid, item, count, silent?)Gives items to the character (adds them to the backpack).
gmp.giveItem(pid, "ItMi_Orenugget", 10)| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
item | gmp.ItemClass | Class name of the item. |
count | integer | Number of pieces to give (1 or more). |
silent (optional) | boolean | true = no "item received" notification on the player's HUD. Default false. |
Returns: boolean
removeItem
gmp.removeItem(pid, item, amount, silent?)Removes items from the character. Pieces are taken from the backpack first; equipped pieces (weapon, armor, ring, amulet) are unequipped first when they have to be removed too.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
item | gmp.ItemClass | Class name of the item. |
amount | integer | Number of pieces to remove. |
silent (optional) | boolean | true = no attribute change notifications when equipped jewelry is removed. Default false. |
Returns: boolean
equipItem
gmp.equipItem(pid, item, silent?)Equips an item the character has in the inventory. The slot is chosen from the item type
(melee or ranged weapon, armor, ring, amulet), as in the client-side Character:equipItem.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
item | gmp.ItemClass | Class name of the item. |
silent (optional) | boolean | true = no attribute change notifications from jewelry bonuses. Default false. |
Returns: boolean
unequipItem
gmp.unequipItem(pid, item, silent?)Unequips an equipped item into the backpack.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
item | gmp.ItemClass | Class name of the item. |
silent (optional) | boolean | true = no attribute change notifications from jewelry bonuses. Default false. |
Returns: boolean
getPlayerItemCount
gmp.getPlayerItemCount(pid, item)Counts the pieces of an item the character has (backpack and equipped slots together).
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
item | gmp.ItemClass | Class name of the item. |
Returns: integer | nil - Number of pieces (0 = none).
clearPlayerInventory
gmp.clearPlayerInventory(pid)Empties the character's inventory: unequips everything and removes every item.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
Returns: boolean
Skills
grantPlayerSkill
gmp.grantPlayerSkill(pid, skill, silent?)Grants a skill to the character for free. The levels of one skill replace each other: granting a higher level removes the lower one. Magic circles also set the circle level of the character.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
skill | gmp.enum.Skill | The skill and its level. |
silent (optional) | boolean | true = no "new skill" notification on the player's HUD. Default false. |
Returns: boolean
getPlayerSkills
gmp.getPlayerSkills(pid)Returns the skills of the character - one level per skill, including the default ones.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
Returns: gmp.enum.Skill[] | nil
Position
setPlayerPosition
gmp.setPlayerPosition(pid, x, y, z)Teleports the character to the given point. The facing direction does not change.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
x | number | X coordinate (cm). |
y | number | Y coordinate (cm). |
z | number | Z coordinate (cm); give a point slightly above the ground. |
Returns: boolean
getPlayerPosition
gmp.getPlayerPosition(pid)Returns the position of the character.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
Returns:
| Value | Type | Description |
|---|---|---|
x | number | nil | X coordinate (cm), or nil for an unknown id. |
y | number | nil | Y coordinate (cm). |
z | number | nil | Z coordinate (cm). |
setPlayerAngle
gmp.setPlayerAngle(pid, yaw)Sets the facing direction of the character. For a player the camera is turned as well.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
yaw | number | Angle in degrees: 0 = world X axis, 90 = world Y axis. |
Returns: boolean
getPlayerAngle
gmp.getPlayerAngle(pid)Returns the facing direction of the character.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
Returns: number | nil - Angle in degrees, -180 to 180.
Combat and death
killPlayer
gmp.killPlayer(pid)Kills the character, with the death animation.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
Returns: boolean
isPlayerDead
gmp.isPlayerDead(pid)Tells whether the character is dead.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
Returns: boolean | nil
respawnPlayer
gmp.respawnPlayer(pid, keepPlace)Revives a dead character. Health is restored to full if the game does not restore it itself.
Fires the playerRespawn event.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
keepPlace | boolean | true = the character gets up where it died; false = at the place and with the angle where it first appeared in the world (for an NPC - where gmp.createNpc created it). |
Returns: boolean - false also when the character is alive.
hitPlayer
gmp.hitPlayer(attackerId, victimId, hitType, weapon?, impact?, magnitude?)Makes one character hit another, with the game's own damage, reactions and effects. Melee and
ranged hits use the weapon the attacker has equipped. Hit types: see gmp.enum.HitType
(Spell needs weapon = spell projectile definition class, Tick uses magnitude).
gmp.hitPlayer(npcId, pid, gmp.enum.HitType.MeleeHeavy) -- the NPC knocks the player down| Parameter | Type | Description |
|---|---|---|
attackerId | integer | Id of the attacking player or server-side NPC. |
victimId | integer | Id of the player or server-side NPC that is hit. |
hitType | gmp.enum.HitType | Kind of the hit. |
weapon (optional) | gmp.WeaponClass | Weapon override; required for Spell. |
impact (optional) | gmp.ImpactTag | Impact override for Spell. |
magnitude (optional) | number | Health change for Tick (negative = damage). |
Returns: boolean
State
setPlayerImmortal
gmp.setPlayerImmortal(pid, immortal)Makes the character immortal (or mortal again). An immortal character takes hits but does not die.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
immortal | boolean | true = immortal. |
Returns: boolean
isPlayerImmortal
gmp.isPlayerImmortal(pid)Tells whether the character is immortal.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
Returns: boolean | nil
setPlayerKillableWithoutDefeat
gmp.setPlayerKillableWithoutDefeat(pid, killable)Humans in Gothic are normally knocked down at 0 health instead of dying. With this option the character dies right away at 0 health.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
killable | boolean | true = dies without a knockdown; false = the game's default behavior. |
Returns: boolean
setPlayerCollision
gmp.setPlayerCollision(pid, enabled)Enables or disables the character's collision (without it, it passes through characters and the world).
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
enabled | boolean | false = no collision. |
Returns: boolean
setPlayerFrozen
gmp.setPlayerFrozen(pid, frozen)Freezes the character in place (no walking, no gravity); setPlayerPosition still works.
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
frozen | boolean | true = frozen; false = moves normally again. |
Returns: boolean
stopPlayerAnimation
gmp.stopPlayerAnimation(pid)Interrupts the action animation the character is playing (attack swing, throw, gesture).
| Parameter | Type | Description |
|---|---|---|
pid | integer | Id of the player or server-side NPC. |
Returns: boolean