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

Players

NameCopy Anchor Link

setPlayerNameCopy Anchor Link

getPlayerNameCopy Anchor Link

AttributesCopy Anchor Link

setPlayerHealthCopy Anchor Link

getPlayerHealthCopy Anchor Link

setPlayerMaxHealthCopy Anchor Link

getPlayerMaxHealthCopy Anchor Link

setPlayerManaCopy Anchor Link

getPlayerManaCopy Anchor Link

setPlayerMaxManaCopy Anchor Link

getPlayerMaxManaCopy Anchor Link

setPlayerStrengthCopy Anchor Link

getPlayerStrengthCopy Anchor Link

setPlayerDexterityCopy Anchor Link

getPlayerDexterityCopy Anchor Link

ItemsCopy Anchor Link

giveItemCopy Anchor Link

removeItemCopy Anchor Link

equipItemCopy Anchor Link

unequipItemCopy Anchor Link

getPlayerItemCountCopy Anchor Link

clearPlayerInventoryCopy Anchor Link

SkillsCopy Anchor Link

grantPlayerSkillCopy Anchor Link

getPlayerSkillsCopy Anchor Link

PositionCopy Anchor Link

setPlayerPositionCopy Anchor Link

getPlayerPositionCopy Anchor Link

setPlayerAngleCopy Anchor Link

getPlayerAngleCopy Anchor Link

Combat and deathCopy Anchor Link

killPlayerCopy Anchor Link

isPlayerDeadCopy Anchor Link

respawnPlayerCopy Anchor Link

hitPlayerCopy Anchor Link

StateCopy Anchor Link

setPlayerImmortalCopy Anchor Link

isPlayerImmortalCopy Anchor Link

setPlayerKillableWithoutDefeatCopy Anchor Link

setPlayerCollisionCopy Anchor Link

setPlayerFrozenCopy Anchor Link

stopPlayerAnimationCopy Anchor Link

On this page

Name

setPlayerName

getPlayerName

Attributes

setPlayerHealth

getPlayerHealth

setPlayerMaxHealth

getPlayerMaxHealth

setPlayerMana

getPlayerMana

setPlayerMaxMana

getPlayerMaxMana

setPlayerStrength

getPlayerStrength

setPlayerDexterity

getPlayerDexterity

Items

giveItem

removeItem

equipItem

unequipItem

getPlayerItemCount

clearPlayerInventory

Skills

grantPlayerSkill

getPlayerSkills

Position

setPlayerPosition

getPlayerPosition

setPlayerAngle

getPlayerAngle

Combat and death

killPlayer

isPlayerDead

respawnPlayer

hitPlayer

State

setPlayerImmortal

isPlayerImmortal

setPlayerKillableWithoutDefeat

setPlayerCollision

setPlayerFrozen

stopPlayerAnimation