> For the complete documentation index, see [llms.txt](https://stevetautonico.gitbook.io/tarbs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stevetautonico.gitbook.io/tarbs/documentation/1.-player.md).

# 1. Player

## 1. The Player Class

### 1.1 Player Initialization

For every project, there should only be one player class. The player class is the main class that the user controls. This class is the object that contains the users inventory, equipped weapons and shield, as well as attack enemies and interacts with NPCs. Setting up a player class goes as follows: 

You must supply 4 parameters when creating an instance of the player class:

*  `name`
  * Name of the player
* `hp`
  * Current HP, usually set to the same value of the `maxhp` (for debug purposes)
* `minatk`
  * Player's minimum attack damage
* `maxatk`
  * Player's maximum attack damage

#### Create a player like this:

```python
player = TARBSengine.Player("Steve", 20, 5, 10)
# A player with the name "Steve". Has 20 HP currently, 20 HP max,
# minimum attack damage of 5 and maximum attack damage of 10
```

###

### 1.2 add\_item

#### add\_item(item, amnt)

Add new items to the players inventory and change amount of items that already exist in the players inventory. If debugging is enabled, (learn how to enable debugging [here](/tarbs/documentation/7.-debugging.md)), outputs the item give and the amount.

{% hint style="warning" %}
This function no longer belongs to the `Player` class. It is only kept here because it only deals with the player's inventory.
{% endhint %}

Required parameters:

* `item`
  * The item to give the player
* `amnt`
  * The amount of items to add to the players inventory.

{% hint style="warning" %}
The item parameter must be a class instance.
{% endhint %}

#### Add an item to the players inventory like this:

```python
player.add_item(sword, 1)
## Debugger: item given Sharp Sword x 1
```

#### Edit the amount of items that are already in the players inventory: 

```python
player.add_item(sword, 2)
## Debugger: item given sword x 2
## This will set the number of swords that the player has to 2 
## regardless of how many they currently have in their inventory.
```

{% hint style="info" %}
Changing the amount of items a player has will have its own function in Beta 1.0
{% endhint %}

### 1.3 remove\_item

#### Player.remove\_item(item, amnt)

 `Player.remove_item` is used to negate the amount of items the player has based on the parameters given. This function is a replacement for `Player.add_item`. This is because the `Player.add_item` would not accept negative values. `Player.remove_item` subtracts the amount of a specific items the player has by a set value.

{% hint style="warning" %}
This function no longer belongs to the `Player` class. It is only kept here because it only deals with the player's inventory.
{% endhint %}

#### Player.remove\_item() usage example:

```python
player.remove_item(sword, 1)
## Debugger: removed Sharp Sword x 1 from player
```

### 1.4 Player.atk

#### Player.atk(opponent)

Preform a basic attack on the opponent. Attack automatically factors in the extra damage from the current weapon the player is holding. If debugging is enabled, the function outputs the total damage done and how much HP the opponent has left. Function will also automatically delete the instance of opponent if the opponent HP reaches 0. (This feature is subject to change and mostly for debugging purposes at the moment.)

{% hint style="warning" %}
The opponent argument must be a class instance
{% endhint %}

#### Usage example:

```python
player.atk(zombie)
## Damage done: 7
## Enemy HP: 13
```

### 1.5 Player.equip\_weapon

#### Player.equip\_weapon(weapon)

Adds the weapon to the `Player.weapon_one`  var. The name of the weapon can also be referenced by referring to `Weapon.name`  for dialogue when equipping the weapon. When equipping the weapon, the `Weapon.atk` var is also stored in the `Player.weapon_one_atk` for adding the amount of extra damage that the weapon provides when calling `Player.atk()`.

{% hint style="warning" %}
The weapon argument must be a class instance.
{% endhint %}

#### Usage:

```python
player.equip_weapon(sword)
# Equipped weapon: Sharp Sword, Damage: 5
```

### 1.6 Player.equip\_shield

#### Player.equip\_shield(shield)

`Player.equip_shield` essentially does the opposite that `Player.equip_weapon` does. The shield reduces the amount of damage taken from an opposing attack by a set value. This value is stored in the `Player.shield_protect`. The shield's name is stored in `Player.shield` for reference in dialogue such as when equipping the shield or having an NPC or the player speak about it.

#### Usage:

```python
player.equip_shield(super_shield)
# Equipped shield: Super Shield, Damage reduction: 5
```

### 1.7 Player.unequip\_weapon

#### Player.unequip\_weapon(weapon)

This function does the opposite of `Player.equip_weapon`. If the player has  a weapon equipped, calling `Player.unequip_weapon` would remove the weapon from the player's weapon slot, as well as add the weapon back to the inventory.

#### Usage:

```python
player.unequip_weapon(sword)
# Debugger: Sharp Sword unequipped.
```

### 1.8 Player.unequip\_shield

#### Player.unequip\_shield(shield)

This function does the opposite of `Player.equip_shield`. If the player has  a shield equipped, calling `Player.unequip_shield` would remove the shield from the player's shield slot, as well as add the shield back to the inventory.

### 1.9 Player.use\_hp\_potion

#### Player.use\_hp\_potion(potion)

This function takes potion class instances as perimeters. It consumes the potion, restores the hp to the player (set by the `Potion.hp` var) and removes the 1 potion of that type from the players inventory. Checking if the player's hp is already at max happens automatically. If the player is at max hp, the potion is not consumed and the function ends.

#### Usage:

```python
player.use_hp_potion(hp_potion)
## 5 health restored, current health: 12

# Or if HP is already at max

player.use_hp_potion(hp_potion)
## HP already at max!
```

### 1.10 Player.say

#### Player.say(text)

`Player.say` is used for dialogue. It outputs the text along with the player's name.

#### Usage:

```python
player.say("I think this engine is neat!")
## Steve: I think this engine is neat!
```

### 1.11 Player.open\_chest

#### Player.open\_chest(loot)

Delivers randomly chosen loot from a set list of possible options. Adds the chosen loot to the player's inventory. The chance of gaining one item over the other are completely random. One item doesn't have a greater chance to drop over another item. (This functionality may be added in a later version, currently no plans) Debug output returns the item that was chosen.

{% hint style="warning" %}
The loot argument must be a list.
{% endhint %}

#### Usage:

```python
loot = [sword, hp_potion, super_shield]
player.open_chest(loot)
## Reward from chest: Sharp Sword
```

### 1.12 Player.kill

#### Player.kill(deathmessage, \*endgame)

It kills the player and displays a death message. The optional `endgame` argument decides if the game should exit it set to `True`.

#### Usage:

```python
player.kill("Steve fell off a cliff", True)
## Steve fell off a cliff 
## *Game Exits*
```

### 1.13 Player.think

#### Player.think(thought)

`Player.think` is used mainly for games with a story line. You can communicate the players thoughts directly to the user. `Player.think` is distinguished from regular speech because it has a border around it.

{% hint style="info" %}
Further configuration of the border is a [planned feature](https://github.com/tman540/T.A.R.B.S.-Engine/issues/14).
{% endhint %}

#### Usage:

```python
player.think("Hmm, I could really use a new sword")
# +----------------------------+
# | Hmm, I could really use a  |
# |         new sword          |
# +----------------------------+
```

### 1.14 Player.equip\_armor

#### Player.equip\_armor(armor)

Calling this function with an instance of the `Armor` class equips that piece of armor into the appropriate slot and adds some damage reduction when taking hits from opponents.

#### Usage:

```python
player.equip_armor(helmet)
# Debugger: equipped Protective Helmet head slot
# DEBUG:root: 01:00:26: Debugger: equipped Protective Helmet head slot
```

### 1.15 Player.unequip\_armor

#### Player.unequip\_armor(armor)

This function to used to do the opposite of `Player.equip_armor`. Calling this function with the parameter `armor` removes the armor from the proper player slot and removes the damage protection that it offers.

#### Usage:

```python
player.unequip_armor(helmet)
# Debugger: unequipped Protective Helmet head slot
# DEBUG:root: 01:00:26: Debugger: unequipped Protective Helmet head slot
```

### 1.16 Player.levelup

#### Player.levelup()

When calling this function, the `Player.level` var is incremented by one. 

#### Usage:

```python
player.levelup()
# Level Up! Current Level: 2
# Debugger: Player leveled up to 2
# DEBUG:root: 09:46:51: Debugger: Player leveled up to 2
```

### 1.17 Player.lowerlevel

#### Player.lowerlevel(amnt)

This function is used as the opposite of `Player.levelup()`. Usually, in RPG games, the player's level doesn't go down. `Player.lowerlevel()` is used in special circumstances. The `amnt` parameter is the amount of levels that the player's level goes down.

#### Usage:

```python
player.lowerlevel(2)
# Debugger: Player leveled lowered 2 levels to 3
# DEBUG:root: 09:46:51: Debugger: Player leveled lowered 2 levels to 3
```