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.

ItemsKopiuj link do sekcji

giveItemKopiuj link do sekcji

ch:giveItem(item, count, silent?)

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

Returns: boolean - true when the items were added.

removeItemKopiuj link do sekcji

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

getItemCountKopiuj link do sekcji

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.

equipItemKopiuj link do sekcji

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.

unequipItemKopiuj link do sekcji

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.

getEquippedItemsKopiuj link do sekcji

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.

getInventoryKopiuj link do sekcji

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.

clearInventoryKopiuj link do sekcji

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.

AttributesKopiuj link do sekcji

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.

setStrengthKopiuj link do sekcji

ch:setStrength(value, silent?)

Sets the base strength of the character.

Returns: boolean

getStrengthKopiuj link do sekcji

ch:getStrength()

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

Returns: number | nil

setDexterityKopiuj link do sekcji

ch:setDexterity(value, silent?)

Sets the base dexterity of the character.

Returns: boolean

getDexterityKopiuj link do sekcji

ch:getDexterity()

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

Returns: number | nil

setHealthKopiuj link do sekcji

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

getHealthKopiuj link do sekcji

ch:getHealth()

Returns the current health points of the character.

Returns: number | nil

setMaxHealthKopiuj link do sekcji

ch:setMaxHealth(value, silent?)

Sets the maximum health points of the character.

Returns: boolean

getMaxHealthKopiuj link do sekcji

ch:getMaxHealth()

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

Returns: number | nil

setManaKopiuj link do sekcji

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

getManaKopiuj link do sekcji

ch:getMana()

Returns the current mana of the character.

Returns: number | nil

setMaxManaKopiuj link do sekcji

ch:setMaxMana(value, silent?)

Sets the maximum mana of the character.

Returns: boolean

getMaxManaKopiuj link do sekcji

ch:getMaxMana()

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

Returns: number | nil

SkillsKopiuj link do sekcji

grantSkillKopiuj link do sekcji

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.

getSkillsKopiuj link do sekcji

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 nameKopiuj link do sekcji

setPositionKopiuj link do sekcji

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.

getPositionKopiuj link do sekcji

ch:getPosition()

Returns the position of the character.

Returns:

setAngleKopiuj link do sekcji

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.

getAngleKopiuj link do sekcji

ch:getAngle()

Returns the facing direction of the character.

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

setNameKopiuj link do sekcji

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

getNameKopiuj link do sekcji

ch:getName()

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

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

State and behaviorKopiuj link do sekcji

setImmortalKopiuj link do sekcji

ch:setImmortal(immortal)

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

Returns: boolean

isImmortalKopiuj link do sekcji

ch:isImmortal()

Tells whether the character is immortal.

Returns: boolean | nil

setKillableWithoutDefeatKopiuj link do sekcji

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

setRelationKopiuj link do sekcji

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

getRelationKopiuj link do sekcji

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.

setPassiveKopiuj link do sekcji

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

setInteractableKopiuj link do sekcji

ch:setInteractable(interactable)

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

Returns: boolean

setCollisionKopiuj link do sekcji

ch:setCollision(enabled)

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

Returns: boolean

stopAnimationKopiuj link do sekcji

ch:stopAnimation()

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

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

freezeMovementKopiuj link do sekcji

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 deathKopiuj link do sekcji

killKopiuj link do sekcji

ch:kill()

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

Returns: boolean

isDeadKopiuj link do sekcji

ch:isDead()

Tells whether the character is dead.

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

respawnKopiuj link do sekcji

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.

hitKopiuj link do sekcji

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 interactionsKopiuj link do sekcji

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.

findNearestObjectKopiuj link do sekcji

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.

sitDownKopiuj link do sekcji

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.

standUpKopiuj link do sekcji

ch:standUp()

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

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

useLadderKopiuj link do sekcji

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.

setLadderFastKopiuj link do sekcji

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.

lightTorchKopiuj link do sekcji

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.

extinguishTorchKopiuj link do sekcji

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.

Puppets and removalKopiuj link do sekcji

makePuppetKopiuj link do sekcji

ch:makePuppet()

Prepares the character to be a remote player's puppet - all of the following at once:

• AI muted: passive, does not talk, does not walk around on its own, does not draw weapons;
• neutral towards the local player (the player can still hit it);
• its own native damage is cancelled - the puppet's hits are dealt through Character:hit;
• nobody can start a conversation with it; it dies without a knockdown;
• empty inventory (without the items of its character definition);
• the player's appearance and animations.

Usually called in the "playerSpawn" handler for a character created from "CommonPlayerDefinition".

Returns: boolean - false when called on the local player.

destroyKopiuj link do sekcji

ch:destroy()

Removes the character from the world (NPC, monster, puppet). The local player cannot be removed.

Returns: boolean - false when called on the local player.

Movement controlKopiuj link do sekcji

Characters other than the player are steered with "keys" (gmp.enum.Control), like a player with a keyboard: a pressed key works until it is released. Directions are relative to the character's camera angle (setCameraAngle), not to its facing - like the W key, which moves the player where the camera looks. The character turns towards its movement by itself and all movement and animations are done by the game. A dead character does not move, but its keys stay pressed.

setControlStateKopiuj link do sekcji

ch:setControlState(control, pressed)

Presses or releases a control "key" of the character. Not available for the local player (the player steers by themselves).

npc:setCameraAngle(90)
npc:setControlState(gmp.enum.Control.Forward, true)  -- runs along the Y axis until released

Returns: boolean - false when called on the local player.

getControlStateKopiuj link do sekcji

ch:getControlState(control)

Tells whether a control "key" of the character is pressed. For the local player this reads their real controls (keyboard or gamepad) in the current frame; for other characters - what was set with setControlState.

Returns: boolean | nil

resetControlsKopiuj link do sekcji

ch:resetControls()

Releases all control "keys" of the character (it stops moving).

Returns: boolean - false when called on the local player.

setCameraAngleKopiuj link do sekcji

ch:setCameraAngle(yaw)

Sets the camera angle of the character - the direction the movement keys refer to. Until it is set, the angle the character was facing when its first key was pressed is used. For the local player this turns their camera.

Returns: boolean

getCameraAngleKopiuj link do sekcji

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.

TypesKopiuj link do sekcji

EquippedItemKopiuj link do sekcji

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

InventoryItemKopiuj link do sekcji

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