Character

Every character in the world - the local player, an NPC, a monster or a remote player's puppet - is a Character object. Unless stated otherwise, every method works for all of them - where the game needs a different path for NPCs than for the player, the API picks it automatically. In the examples ch is any Character.

ItemsCopy Anchor Link

giveItemCopy Anchor Link

ch:giveItem(item, count, silent?)

Gives items to the character (adds them to the backpack).

Returns: boolean - true when the items were added.

removeItemCopy Anchor Link

ch:removeItem(item, amount, silent?)

Removes items from the character. Pieces are taken from the backpack first; when equipped pieces have to be removed too (weapon, armor, ring, amulet), they are unequipped first - with their bonuses and visuals removed exactly as when unequipping in the game's inventory screen.

Returns: integer - Number of pieces actually removed (0 = the character had none).

getItemCountCopy Anchor Link

ch:getItemCount(item)

Counts the pieces of an item the character has (backpack and equipped slots together).

Returns: integer | nil - Number of pieces (0 = none), or nil when the character no longer exists.

equipItemCopy Anchor Link

ch:equipItem(item, silent?)

Equips an item the character has in the inventory. The slot is chosen from the item type:

• bow or crossbow -> ranged weapon slot; melee weapon (one- or two-handed) -> melee weapon slot;
• armor -> armor slot; amulet -> amulet slot (replaces the equipped one);
• ring -> a free hand (left first, then right); with both hands taken, a ring other than the one being equipped is replaced.

Equipping a ring or amulet that is already equipped (with no further piece in the backpack) changes nothing and returns true. Not available while a loading screen is shown.

Returns: boolean - false when the item type cannot be equipped, the character does not have the item, or the game rejected it.

unequipItemCopy Anchor Link

ch:unequipItem(item, silent?)

Unequips an equipped item into the backpack. The slot is found automatically (melee or ranged weapon, quick-access bar, armor, rings, amulet); the result is the same as in the game's inventory screen.

Returns: boolean - false when the item is not equipped.

getEquippedItemsCopy Anchor Link

ch:getEquippedItems()

Returns all items equipped by the character, with the place where each one is equipped. The weapon slots can also hold a rune or scroll and the quick-access bar holds potions, food, torches, runes and more - use the type field to tell them apart.

Returns: gmp.EquippedItem[] | nil - List of equipped items (empty when nothing is equipped), or nil when the character no longer exists.

getInventoryCopy Anchor Link

ch:getInventory()

Returns the whole inventory of the character: every stack in the backpack and every equipped item.

Returns: gmp.InventoryItem[] | nil - List of items (empty when the inventory is empty), or nil when the character no longer exists.

clearInventoryCopy Anchor Link

ch:clearInventory()

Empties the character's inventory: unequips everything (without notifications) and removes every item.

Returns: integer | nil - Number of removed item kinds (classes), or nil when the character no longer exists.

AttributesCopy Anchor Link

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 - exactly what the game shows. Example: setStrength(100) with a +15 ring equipped -> getStrength() = 115. The game limits Health to MaxHealth and Mana to MaxMana - set the maximum first.

setStrengthCopy Anchor Link

ch:setStrength(value, silent?)

Sets the base strength of the character.

Returns: boolean

getStrengthCopy Anchor Link

ch:getStrength()

Returns the current strength of the character (including bonuses).

Returns: number | nil

setDexterityCopy Anchor Link

ch:setDexterity(value, silent?)

Sets the base dexterity of the character.

Returns: boolean

getDexterityCopy Anchor Link

ch:getDexterity()

Returns the current dexterity of the character (including bonuses).

Returns: number | nil

setHealthCopy Anchor Link

ch:setHealth(value, silent?)

Sets the health points of the character. The value is limited to the maximum health - to raise health above the current maximum, call setMaxHealth first.

Returns: boolean

getHealthCopy Anchor Link

ch:getHealth()

Returns the current health points of the character.

Returns: number | nil

setMaxHealthCopy Anchor Link

ch:setMaxHealth(value, silent?)

Sets the maximum health points of the character.

Returns: boolean

getMaxHealthCopy Anchor Link

ch:getMaxHealth()

Returns the current maximum health points of the character (including bonuses).

Returns: number | nil

setManaCopy Anchor Link

ch:setMana(value, silent?)

Sets the mana of the character. The value is limited to the maximum mana - to raise mana above the current maximum, call setMaxMana first.

Returns: boolean

getManaCopy Anchor Link

ch:getMana()

Returns the current mana of the character.

Returns: number | nil

setMaxManaCopy Anchor Link

ch:setMaxMana(value, silent?)

Sets the maximum mana of the character.

Returns: boolean

getMaxManaCopy Anchor Link

ch:getMaxMana()

Returns the current maximum mana of the character (including bonuses).

Returns: number | nil

SkillsCopy Anchor Link

grantSkillCopy Anchor Link

ch:grantSkill(skill, silent?)

Grants a skill to the character for free (no learning points, no teacher). The levels of one skill replace each other: granting a higher level removes the lower one (e.g. Melee_OneHanded_Master replaces Melee_OneHanded_Trained).

Magic circles (Mage_Circle_1 ... Mage_Circle_6) also set the character's circle level, so the runes and scrolls of that circle can be used. Mana is not changed - use setMaxMana / setMana.

ch:grantSkill(gmp.enum.Skill.Mage_Circle_2)
ch:setMaxMana(60) ; ch:setMana(60)

Returns: boolean - false when the skill could not be granted.

getSkillsCopy Anchor Link

ch:getSkills()

Returns the skills of the character - one level per skill, including the default ones the character starts with (e.g. Picklock_Untrained).

Returns: gmp.enum.Skill[] | nil - List of skills, or nil when the character no longer exists.

Position and nameCopy Anchor Link

setPositionCopy Anchor Link

ch:setPosition(x, y, z)

Teleports the character to the given point. The facing direction does not change.

Returns: boolean - true when the game accepted the new position.

getPositionCopy Anchor Link

ch:getPosition()

Returns the position of the character.

Returns:

setAngleCopy Anchor Link

ch:setAngle(yaw)

Sets the facing direction of the character. For the local player the camera is turned as well, so it stays behind the character.

Returns: boolean - true when the game accepted the rotation.

getAngleCopy Anchor Link

ch:getAngle()

Returns the facing direction of the character.

Returns: number | nil - Angle in degrees, -180 to 180.

setNameCopy Anchor Link

ch:setName(name)

Changes the name of this character only - the name the game shows above the character, when aiming at it and in conversations. Other characters of the same kind keep their names.

Returns: boolean

getNameCopy Anchor Link

ch:getName()

Returns the name of the character as the game shows it.

Returns: string | nil - Name in UTF-8.

State and behaviorCopy Anchor Link

setImmortalCopy Anchor Link

ch:setImmortal(immortal)

Makes the character immortal (or mortal again). An immortal character takes hits but does not die.

Returns: boolean

isImmortalCopy Anchor Link

ch:isImmortal()

Tells whether the character is immortal.

Returns: boolean | nil

setKillableWithoutDefeatCopy Anchor Link

ch:setKillableWithoutDefeat(killable)

Humans in Gothic are normally knocked down (defeated) at 0 health instead of dying. With this option enabled the character dies right away at 0 health, without being knocked down first.

Returns: boolean

setRelationCopy Anchor Link

ch:setRelation(other, relation)

Sets how this character treats another character. The relation is ONE-WAY: it decides whether this character takes other as a target (attacks it, starts combat music). Damage is also decided by the attacker's relation - e.g. with puppet:setRelation(player, Relation.Neutral) the puppet does not attack the player, while the player can still hit the puppet.

Returns: boolean

getRelationCopy Anchor Link

ch:getRelation(other)

Returns how this character treats another character (one-way, see setRelation).

Returns: gmp.enum.Relation - Relation.Unknown when it cannot be determined.

setPassiveCopy Anchor Link

ch:setPassive(passive)

Makes the character's AI passive: it does not react to threats - does not attack and does not flee. Note: on a character created moments ago, the game's AI initialization can reset this during the first seconds; set it again if needed.

Returns: boolean

setInteractableCopy Anchor Link

ch:setInteractable(interactable)

Enables or disables interacting with the character (talking to it, searching it).

Returns: boolean

setCollisionCopy Anchor Link

ch:setCollision(enabled)

Enables or disables the character's collision. Without collision the character passes through other characters and the world.

Returns: boolean

stopAnimationCopy Anchor Link

ch:stopAnimation()

Interrupts the action animation the character is playing (attack swing, throw, gesture).

Returns: boolean - false when no action animation is playing.

freezeMovementCopy Anchor Link

ch:freezeMovement(frozen)

Freezes the character in place: the game does not move it (no walking, no gravity). setPosition still works on a frozen character.

Returns: boolean

Combat and deathCopy Anchor Link

killCopy Anchor Link

ch:kill()

Kills the character, with the death animation. Works for the player too.

Returns: boolean

isDeadCopy Anchor Link

ch:isDead()

Tells whether the character is dead.

Returns: boolean | nil - true when the character is dead or dying.

respawnCopy Anchor Link

ch:respawn(keepPlace)

Revives a dead character the game's way. Health is restored to full if the game does not restore it itself. After reviving, the "respawn" event is fired.

Returns: boolean - false when the character is alive.

hitCopy Anchor Link

ch:hit(victim, hitType, weapon?, impact?, magnitude?)

Makes this character hit another character, with the game's own damage, reactions and effects. This character is the attacker; melee and ranged hits use the weapon it has equipped.

Hit types (gmp.enum.HitType):

• Fists - a punch;
• Melee - a light swing with the equipped melee weapon (short stagger);
• MeleeMedium - a medium swing: a stronger stagger without a knockdown;
• MeleeHeavy - a heavy swing: knocks the victim down;
• Arrow - a projectile from the equipped bow or crossbow (no knockdown);
• Spell - a spell projectile: weapon = spell projectile definition class, impact = impact tag (default "Combat.HitType.Standard");
• Tick - damage without a weapon (burning, damage over time, falling): magnitude = health change, negative = damage.

attacker:hit(victim, gmp.enum.HitType.MeleeHeavy)
attacker:hit(victim, gmp.enum.HitType.Tick, nil, nil, -25)

World interactionsCopy Anchor Link

The game performs the interaction (walking to the place, animations, finishing) - the API only starts it, like pressing the "use" button. A character that is busy with another interaction cannot start a new one (stand up or leave the ladder first). An NPC is placed in front of the object; the player only when standing farther than 2.5 m away. Not available while a loading screen is shown.

findNearestObjectCopy Anchor Link

ch:findNearestObject(objectType, maxDistance?)

Finds the world object of the given kind nearest to the character.

Returns: gmp.WorldObject | nil - The nearest object, or nil when there is none within the radius.

sitDownCopy Anchor Link

ch:sitDown(seat)

Sits the character down on a bench or chair, on the nearest free place. The character stays seated until standUp is called.

Returns: boolean - false when the object is not a seat, there is no free place, or the game rejected it.

standUpCopy Anchor Link

ch:standUp()

Makes a seated character stand up (with the game's stand-up animation).

Returns: boolean - false when the character is not sitting.

useLadderCopy Anchor Link

ch:useLadder(ladder, fast?)

Makes the character climb a ladder from the side it stands at: from the bottom it climbs up, from the top it climbs down. An NPC climbs to the other end and gets off by itself; the player keeps controlling the climb with the keys, as in the game.

Returns: boolean - false when the object is not a ladder, the ladder cannot be entered from here, or the game rejected it.

setLadderFastCopy Anchor Link

ch:setLadderFast(fast)

Speeds up or slows down a character that is on a ladder - like holding or releasing Shift. Can be called any number of times while on the ladder. After getting off the ladder the speed-up is removed automatically.

Returns: boolean - false when the character is not on a ladder.

lightTorchCopy Anchor Link

ch:lightTorch(torch)

Lights a roadside torch or a fire basket, with the character's animation as in the game. As in the game, the character needs a torch in hand. An object that is already burning is left as it is (returns true).

Returns: boolean - false when the object cannot be lit or the game rejected it.

extinguishTorchCopy Anchor Link

ch:extinguishTorch(torch)

Extinguishes a roadside torch or a fire basket, with the character's animation as in the game. An object that is not burning is left as it is (returns true).

Returns: boolean - false when the object cannot be extinguished or the game rejected it.

CameraCopy Anchor Link

setCameraAngleCopy Anchor Link

ch:setCameraAngle(yaw)

Sets the camera angle of the character. For the local player this turns their camera.

Returns: boolean

getCameraAngleCopy Anchor Link

ch:getCameraAngle()

Returns the camera angle of the character. For the local player - the angle of their camera; for other characters - the angle set with setCameraAngle (or the character's facing).

Returns: number | nil - Angle in degrees.

TypesCopy Anchor Link

EquippedItemCopy Anchor Link

An item equipped by a character (Character:getEquippedItems).

InventoryItemCopy Anchor Link

An item in a character's inventory (Character:getInventory).