evennia.contrib.game_systems.turnbattle.tb_items

Simple turn-based combat system with items and status effects

Contrib - Tim Ashley Jenkins 2017

This is a version of the ‘turnbattle’ combat system that includes conditions and usable items, which can instill these conditions, cure them, or do just about anything else.

Conditions are stored on characters as a dictionary, where the key is the name of the condition and the value is a list of two items: an integer representing the number of turns left until the condition runs out, and the character upon whose turn the condition timer is ticked down. Unlike most combat-related attributes, conditions aren’t wiped once combat ends - if out of combat, they tick down in real time instead.

This module includes a number of example conditions:

Regeneration: Character recovers HP every turn Poisoned: Character loses HP every turn Accuracy Up: +25 to character’s attack rolls Accuracy Down: -25 to character’s attack rolls Damage Up: +5 to character’s damage Damage Down: -5 to character’s damage Defense Up: +15 to character’s defense Defense Down: -15 to character’s defense Haste: +1 action per turn Paralyzed: No actions per turn Frightened: Character can’t use the ‘attack’ command

Since conditions can have a wide variety of effects, their code is scattered throughout the other functions wherever they may apply.

Items aren’t given any sort of special typeclass - instead, whether or not an object counts as an item is determined by its attributes. To make an object into an item, it must have the attribute ‘item_func’, with the value given as a callable - this is the function that will be called when an item is used. Other properties of the item, such as how many uses it has, whether it’s destroyed when its uses are depleted, and such can be specified on the item as well, but they are optional.

To install and test, import this module’s TBItemsCharacter object into your game’s character.py module:

from evennia.contrib.game_systems.turnbattle.tb_items import TBItemsCharacter

And change your game’s character typeclass to inherit from TBItemsCharacter instead of the default:

class Character(TBItemsCharacter):

Next, import this module into your default_cmdsets.py module:

from evennia.contrib.game_systems.turnbattle import tb_items

And add the battle command set to your default command set:

# # any commands you add below will overload the default ones. # self.add(tb_items.BattleCmdSet())

This module is meant to be heavily expanded on, so you may want to copy it to your game’s ‘world’ folder and modify it there rather than importing it in your game and using it as-is.

evennia.contrib.game_systems.turnbattle.tb_items.DEF_DOWN_MOD = -15

COMBAT FUNCTIONS START HERE

class evennia.contrib.game_systems.turnbattle.tb_items.ItemCombatRules

Bases: BasicCombatRules

get_attack(attacker, defender)

Returns a value for an attack roll.

Parameters:

• attacker (obj) – Character doing the attacking

• defender (obj) – Character being attacked

Returns:

attack_value (int) –

Attack roll value, compared against a defense value

to determine whether an attack hits or misses.

Notes

This is where conditions affecting attack rolls are applied, as well. Accuracy Up and Accuracy Down are also accounted for in itemfunc_attack(), so that attack items’ accuracy is affected as well.

get_defense(attacker, defender)

Returns a value for defense, which an attack roll must equal or exceed in order for an attack to hit.

Parameters:

• attacker (obj) – Character doing the attacking

• defender (obj) – Character being attacked

Returns:

defense_value (int) –

Defense value, compared against an attack roll

to determine whether an attack hits or misses.

Notes

This is where conditions affecting defense are accounted for.

get_damage(attacker, defender)

Returns a value for damage to be deducted from the defender’s HP after abilities successful hit.

Parameters:

• attacker (obj) – Character doing the attacking

• defender (obj) – Character being damaged

Returns:

damage_value (int) –

Damage value, which is to be deducted from the defending

character’s HP.

Notes

This is where conditions affecting damage are accounted for. Since attack items roll their own damage in itemfunc_attack(), their damage is unaffected by any conditions.

resolve_attack(attacker, defender, attack_value=None, defense_value=None, damage_value=None, inflict_condition=[])

Resolves an attack and outputs the result.

Parameters:

• attacker (obj) – Character doing the attacking

• defender (obj) – Character being attacked

Options:

attack_value (int): Override for attack roll defense_value (int): Override for defense value damage_value (int): Override for damage value inflict_condition (list): Conditions to inflict upon hit, a

list of tuples formated as (condition(str), duration(int))

Notes

This function is called by normal attacks as well as attacks made with items.

spend_item_use(item, user)

Spends one use on an item with limited uses.

Parameters:

• item (obj) – Item being used

• user (obj) – Character using the item

Notes

If item.db.item_consumable is ‘True’, the item is destroyed if it runs out of uses - if it’s a string instead of ‘True’, it will also spawn a new object as residue, using the value of item.db.item_consumable as the name of the prototype to spawn.

use_item(user, item, target)

Performs the action of using an item.

Parameters:

• user (obj) – Character using the item

• item (obj) – Item being used

• target (obj) – Target of the item use

condition_tickdown(character, turnchar)

Ticks down the duration of conditions on a character at the start of a given character’s turn.

Parameters:

• character (obj) – Character to tick down the conditions of

• turnchar (obj) – Character whose turn it currently is

Notes

In combat, this is called on every fighter at the start of every character’s turn. Out of combat, it’s instead called when a character’s at_update() hook is called, which is every 30 seconds by default.

add_condition(character, turnchar, condition, duration)

Adds a condition to a fighter.

Parameters:

• character (obj) – Character to give the condition to

• turnchar (obj) – Character whose turn to tick down the condition on in combat

• condition (str) – Name of the condition

• duration (int or True) – Number of turns the condition lasts, or True for indefinite

itemfunc_heal(item, user, target, **kwargs)

Item function that heals HP.

kwargs:

min_healing(int): Minimum amount of HP recovered max_healing(int): Maximum amount of HP recovered

itemfunc_add_condition(item, user, target, **kwargs)

Item function that gives the target one or more conditions.

kwargs:

conditions (list): Conditions added by the item

formatted as a list of tuples: (condition (str), duration (int or True))

Notes

Should mostly be used for beneficial conditions - use itemfunc_attack for an item that can give an enemy a harmful condition.

itemfunc_cure_condition(item, user, target, **kwargs)

Item function that’ll remove given conditions from a target.

kwargs:

to_cure(list): List of conditions (str) that the item cures when used

itemfunc_attack(item, user, target, **kwargs)

Item function that attacks a target.

kwargs:

min_damage(int): Minimum damage dealt by the attack max_damage(int): Maximum damage dealth by the attack accuracy(int): Bonus / penalty to attack accuracy roll inflict_condition(list): List of conditions inflicted on hit,

formatted as a (str, int) tuple containing condition name and duration.

Notes

Calls resolve_attack at the end.

evennia.contrib.game_systems.turnbattle.tb_items.ITEMFUNCS = {'add_condition': <bound method ItemCombatRules.itemfunc_add_condition of <evennia.contrib.game_systems.turnbattle.tb_items.ItemCombatRules object>>, 'attack': <bound method ItemCombatRules.itemfunc_attack of <evennia.contrib.game_systems.turnbattle.tb_items.ItemCombatRules object>>, 'cure_condition': <bound method ItemCombatRules.itemfunc_cure_condition of <evennia.contrib.game_systems.turnbattle.tb_items.ItemCombatRules object>>, 'heal': <bound method ItemCombatRules.itemfunc_heal of <evennia.contrib.game_systems.turnbattle.tb_items.ItemCombatRules object>>}

PROTOTYPES START HERE

You can paste these prototypes into your game’s prototypes.py module in your /world/ folder, and use the spawner to create them - they serve as examples of items you can make and a handy way to demonstrate the system for conditions as well.

Items don’t have any particular typeclass - any object with a db entry “item_func” that references one of the functions given above can be used as an item with the ‘use’ command.

Only “item_func” is required, but item behavior can be further modified by specifying any of the following:

item_uses (int): If defined, item has a limited number of uses

item_selfonly (bool): If True, user can only use the item on themself

item_consumable(True or str): If True, item is destroyed when it runs

out of uses. If a string is given, the item will spawn a new object as it’s destroyed, with the string specifying what prototype to spawn.

item_kwargs (dict): Keyword arguments to pass to the function defined in

item_func. Unique to each function, and can be used to make multiple items using the same function work differently.

evennia.contrib.game_systems.turnbattle.tb_items.AMULET_OF_WEAKNESS = {'desc': "The one who holds this amulet can call upon its power to gain great weakness. It's not a terribly useful artifact.", 'item_func': 'add_condition', 'item_kwargs': {'conditions': [('Damage Down', 3), ('Accuracy Down', 3), ('Defense Down', 3)]}, 'item_selfonly': True, 'key': 'The Amulet of Weakness'}

CHARACTER TYPECLASS

class evennia.contrib.game_systems.turnbattle.tb_items.TBItemsCharacter(*args, **kwargs)

Bases: TBBasicCharacter

A character able to participate in turn-based combat. Has attributes for current and maximum HP, and access to combat commands.

rules = <evennia.contrib.game_systems.turnbattle.tb_items.ItemCombatRules object>

at_object_creation()

Called once, when this object is first created. This is the normal hook to overload for most object types.

at_turn_start()

Hook called at the beginning of this character’s turn in combat.

apply_turn_conditions()

Applies the effect of conditions that occur at the start of each turn in combat, or every 30 seconds out of combat.

at_update()

Fires every 30 seconds.

exception DoesNotExist

Bases: DoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

path = 'evennia.contrib.game_systems.turnbattle.tb_items.TBItemsCharacter'

typename = 'TBItemsCharacter'

class evennia.contrib.game_systems.turnbattle.tb_items.TBItemsCharacterTest(*args, **kwargs)

Bases: TBItemsCharacter

Just like the TBItemsCharacter, but doesn’t subscribe to the TickerHandler. This makes it easier to run unit tests on.

at_object_creation()

Called once, when this object is first created. This is the normal hook to overload for most object types.

exception DoesNotExist

Bases: DoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

path = 'evennia.contrib.game_systems.turnbattle.tb_items.TBItemsCharacterTest'

typename = 'TBItemsCharacterTest'

class evennia.contrib.game_systems.turnbattle.tb_items.TBItemsTurnHandler(*args, **kwargs)

Bases: TBBasicTurnHandler

This is the script that handles the progression of combat through turns. On creation (when a fight is started) it adds all combat-ready characters to its roster and then sorts them into a turn order. There can only be one fight going on in a single room at a time, so the script is assigned to a room as its object.

Fights persist until only one participant is left with any HP or all remaining participants choose to end the combat with the ‘disengage’ command.

rules = <evennia.contrib.game_systems.turnbattle.tb_items.ItemCombatRules object>

next_turn()

Advances to the next character in the turn order.

exception DoesNotExist

Bases: DoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

path = 'evennia.contrib.game_systems.turnbattle.tb_items.TBItemsTurnHandler'

typename = 'TBItemsTurnHandler'

class evennia.contrib.game_systems.turnbattle.tb_items.CmdFight(**kwargs)

Bases: CmdFight

Starts a fight with everyone in the same room as you.

Usage:

fight

When you start a fight, everyone in the room who is able to fight is added to combat, and a turn order is randomly rolled. When it’s your turn, you can attack other characters.

key = 'fight'

help_category = 'combat'

rules = <evennia.contrib.game_systems.turnbattle.tb_items.ItemCombatRules object>

combat_handler_class

alias of TBItemsTurnHandler

aliases = []

lock_storage = 'cmd:all();'

search_index_entry = {'aliases': '', 'category': 'combat', 'key': 'fight', 'no_prefix': ' ', 'tags': '', 'text': "\nStarts a fight with everyone in the same room as you.\n\nUsage:\n  fight\n\nWhen you start a fight, everyone in the room who is able to\nfight is added to combat, and a turn order is randomly rolled.\nWhen it's your turn, you can attack other characters.\n"}

class evennia.contrib.game_systems.turnbattle.tb_items.CmdAttack(**kwargs)

Bases: CmdAttack

Attacks another character.

Usage:

attack <target>

When in a fight, you may attack another character. The attack has a chance to hit, and if successful, will deal damage.

key = 'attack'

help_category = 'combat'

rules = <evennia.contrib.game_systems.turnbattle.tb_items.ItemCombatRules object>

aliases = []

lock_storage = 'cmd:all();'

search_index_entry = {'aliases': '', 'category': 'combat', 'key': 'attack', 'no_prefix': ' ', 'tags': '', 'text': '\nAttacks another character.\n\nUsage:\n  attack <target>\n\nWhen in a fight, you may attack another character. The attack has\na chance to hit, and if successful, will deal damage.\n'}

class evennia.contrib.game_systems.turnbattle.tb_items.CmdPass(**kwargs)

Bases: CmdPass

Passes on your turn.

Usage:

pass

When in a fight, you can use this command to end your turn early, even if there are still any actions you can take.

key = 'pass'

aliases = ['wait', 'hold']

help_category = 'combat'

rules = <evennia.contrib.game_systems.turnbattle.tb_items.ItemCombatRules object>

lock_storage = 'cmd:all();'

search_index_entry = {'aliases': 'wait hold', 'category': 'combat', 'key': 'pass', 'no_prefix': ' wait hold', 'tags': '', 'text': '\nPasses on your turn.\n\nUsage:\n  pass\n\nWhen in a fight, you can use this command to end your turn early, even\nif there are still any actions you can take.\n'}

class evennia.contrib.game_systems.turnbattle.tb_items.CmdDisengage(**kwargs)

Bases: CmdDisengage

Passes your turn and attempts to end combat.

Usage:

disengage

Ends your turn early and signals that you’re trying to end the fight. If all participants in a fight disengage, the fight ends.

key = 'disengage'

aliases = ['spare']

help_category = 'combat'

rules = <evennia.contrib.game_systems.turnbattle.tb_items.ItemCombatRules object>

lock_storage = 'cmd:all();'

search_index_entry = {'aliases': 'spare', 'category': 'combat', 'key': 'disengage', 'no_prefix': ' spare', 'tags': '', 'text': "\nPasses your turn and attempts to end combat.\n\nUsage:\n  disengage\n\nEnds your turn early and signals that you're trying to end\nthe fight. If all participants in a fight disengage, the\nfight ends.\n"}

class evennia.contrib.game_systems.turnbattle.tb_items.CmdRest(**kwargs)

Bases: CmdRest

Recovers damage.

Usage:

rest

Resting recovers your HP to its maximum, but you can only rest if you’re not in a fight.

key = 'rest'

help_category = 'combat'

rules = <evennia.contrib.game_systems.turnbattle.tb_items.ItemCombatRules object>

aliases = []

lock_storage = 'cmd:all();'

search_index_entry = {'aliases': '', 'category': 'combat', 'key': 'rest', 'no_prefix': ' ', 'tags': '', 'text': "\nRecovers damage.\n\nUsage:\n  rest\n\nResting recovers your HP to its maximum, but you can only\nrest if you're not in a fight.\n"}

class evennia.contrib.game_systems.turnbattle.tb_items.CmdCombatHelp(**kwargs)

Bases: CmdCombatHelp

View help or a list of topics

Usage:

help <topic or command> help list help all

This will search for help on commands and other topics related to the game.

rules = <evennia.contrib.game_systems.turnbattle.tb_items.ItemCombatRules object>

combat_help_text = "Available combat commands:|/|wAttack:|n Attack a target, attempting to deal damage.|/|wPass:|n Pass your turn without further action.|/|wDisengage:|n End your turn and attempt to end combat.|/|wUse:|n Use an item you're carrying."

aliases = ['?']

help_category = 'general'

key = 'help'

lock_storage = 'cmd:all()'

search_index_entry = {'aliases': '?', 'category': 'general', 'key': 'help', 'no_prefix': ' ?', 'tags': '', 'text': '\nView help or a list of topics\n\nUsage:\n  help <topic or command>\n  help list\n  help all\n\nThis will search for help on commands and other\ntopics related to the game.\n'}

class evennia.contrib.game_systems.turnbattle.tb_items.CmdUse(**kwargs)

Bases: MuxCommand

Use an item.

Usage:

use <item> [= target]

An item can have various function - looking at the item may provide information as to its effects. Some items can be used to attack others, and as such can only be used in combat.

key = 'use'

help_category = 'combat'

rules = <evennia.contrib.game_systems.turnbattle.tb_items.ItemCombatRules object>

func()

This performs the actual command.

aliases = []

lock_storage = 'cmd:all();'

search_index_entry = {'aliases': '', 'category': 'combat', 'key': 'use', 'no_prefix': ' ', 'tags': '', 'text': '\nUse an item.\n\nUsage:\n  use <item> [= target]\n\nAn item can have various function - looking at the item may\nprovide information as to its effects. Some items can be used\nto attack others, and as such can only be used in combat.\n'}

class evennia.contrib.game_systems.turnbattle.tb_items.BattleCmdSet(cmdsetobj=None, key=None)

Bases: CharacterCmdSet

This command set includes all the commmands used in the battle system.

path = 'evennia.contrib.game_systems.turnbattle.tb_items.BattleCmdSet'

key = 'DefaultCharacter'

at_cmdset_creation()

Populates the cmdset