Modding:player (0.9.9.7)

Within the context of modding the 'player' can refer to:

• The player API, a set of functions which can be used to manipulate player specific content during gameplay.
• The player object, a singleton that inherits from being and which represents you, the player, in-game as a standard, alterable object.

These pages will be split our from the 0996 data soon. Original 0996 below

---

The player. AKA you. Runs around half-cocked, blows shit up. The player is a Being and a Thing, but there are also a few properties and functions that are specific to the player. The player is created from the "soldier" being prototype. In lua, there is a global variable called player that holds a reference to the player.

Properties

The player also has all being properties and thing properties.

Player
Boolean	running	This is true when the player is running. Setting this to false will make the player tired.
Boolean	tired	This true when the player is tired. Setting this to false will restore the player to cautious.
Word	runningtime	This is the number of actions the player has until his running tactic expires.
LongInt	exp	This is the player's current experience total. Increasing this value directly won't cause the player to gain a level.
Byte	explevel	This is the player's level. Changing it won't remove traits or trigger level ups. Lowering it can allow the player to achieve lower levels again.
Klass ID	klass	This is the numeric id of the player's class.
Word	nuketime	This is the number of 0.1s intervals remaining until a nuclear explosion occurs. Setting this to 0 will halt the current countdown.
Real	expfactor	All of the player's experience gains are multiplied by this factor. This is normally set based on the difficulty level.
string	killedby	This is the string that indicates how the player was killed (but not where). This is automatically set by the engine at the beginning of mortem output. This property is read-only.
Skill Rank ID	skillrank	This is the numeric id of the player's current skill rank. This property is read-only.
Exp Rank ID	exprank	This is the numeric id of the player's current exp rank. This property is read-only.
LongInt	score	This is the player's current score. This property is read-only.
Byte	depth	This is the level of the dungeon that the player is currently on. (Level generation should usually ignore this, instead using the Modding:Level values.) This property is read-only.

API

The player can also use the being API and thing API.

Player Inferface
void	Player:set_affect(Affect ID affect, integer duration)
boolean	Player:is_affect(Affect ID affect)
void	Player:add_exp(integer exp)
boolean	Player:has_won()
integer	Player:get_trait(Trait ID trait)
string	Player:get_trait_hist()
void	Player:power_backpack()
void	Player:win()
void	Player:choose_trait()
void	Player:level_up()
void	Player:exit(integer level)
void	Player:exit(Level ID level)
boolean	Player:record_badge(Badge ID id)
void	Player:quick_weapon(Item ID id)
void	Player:set_inv_size(integer size)
boolean	Player:found_item(Item ID id)
void	Player:assembled_item(ModArray ID id)
void	Player:mortem_print(string mortemtext)
void	Player:add_medal(Medal ID medal)
void	Player:remove_medal(Medal ID medal)
void	Player:remove_medals(Medal ID list medallist)
boolean	Player:has_medal(Medal ID medal)
void	Player:add_badge(Badge ID badge)
void	Player:remove_badge(Badge ID badge)
boolean	Player:has_badge(Badge ID badge)
void	Player:add_history(string historytext)

Player:set_affect(Affect ID affect, integer duration)

Adds duration actions to the appropriate affect timer. This will properly trigger affect activation hooks.

---

Player:is_affect(Affect ID affect) → boolean

Determines if the given affect is currently active on the player.

---

Player:add_exp(integer exp)

Adds the given amount of experience to the player. This can trigger level ups. (To avoid level ups, player.exp and player.explevel can be modified directly.)

---

Player:has_won() → boolean

Determines if the player has won the game. Typically, this will only be true during mortem generation (if the player has indeed won).

---

Player:get_trait(Trait ID trait) → integer

Counts the number of levels the player has in the given trait.

---

Player:get_trait_hist() → string

Returns a string describing the player's previous trait selections as seen in the mortem.

---

Player:power_backpack()

Adds the BF_BACKPACK flag to the player and then resorts the ammo in the player's inventory.

---

Player:win()

Ends the game; the player is considered to have won the game for the purposes of player:has_won().

---

Player:choose_trait()

Allows the player to pick a new trait (as if a level up had occured).

---

Player:level_up()

Causes the player to level up. Experience is not affected. This is similar to player:choose_trait(), but level up events are triggered, and the player's explevel increases.

---

Player:exit(integer level)

Causes the player to enter the dungeon level given by level. With no argument, the player advances to the next level.

---

Player:exit(Level ID level)

Causes the player to enter the given special level.

---

Player:record_badge(Badge ID id) → boolean

Adds the given badge to the player's profile. (Modules have either separate profiles or no profiles.) Returns false if there is no player profile, or if the player already had the badge.

---

Player:quick_weapon(Item ID id)

Causes the player to prepare a weapon of the given type as though pressing a quickkey. This is affected by BF_JUGGLER. id must be a string id.

---

Player:set_inv_size(integer size)

Sets the player's inventory size. The new size can't be bigger than MAX_INV_SIZE, nor can it be 0. This doesn't do anything with items in the inventory that are already beyond the limit.

---

Player:found_item(Item ID id) → boolean

Determines if the player has previously picked up an item with the given id.

---

Player:assembled_item(ModArray ID id)

Adds the given assembly to the player's list of assemblies that have been created in the current game. If there is a profile, the assembly will be added there as well.

---

Player:mortem_print(string mortemtext)

This can only be called while the mortem is being generated. It adds the given line of text to the player's mortem.

---

Player:add_medal(Medal ID medal)

Adds the given medal to the list of medals the player has achieved in the current game.

---

Player:remove_medal(Medal ID medal)

Removes the given medal from the list of medals the player has achieved in the current game.

---

Player:remove_medals(Medal ID list medallist)

This removes all the medals in medallist from the medals that the player has achieved in the current game. Calling this with nil equates to calling it with the empty list.

---

Player:has_medal(Medal ID medal) → boolean

Determines if the player has achieved the given medal in the current game.

---

Player:add_badge(Badge ID badge)

Adds the given badge to the list of badges the player has achieved in the current game.

---

Player:remove_badge(Badge ID badge)

Removes the given badge from the list of badges the player has achieved in the current game.

---

Player:has_badge(Badge ID badge) → boolean

Determines if the player has achieved the given badge in the current game.

---

Player:add_history(string historytext)

Adds the given line to the history section of the mortem. Unlike print_mortem, this can be done while the game is still ongoing. (The default mortem handler prints the history section, but a custom handler might not.)