# evennia.contrib.game_systems.turnbattle.tb_equip

Simple turn-based combat system with equipment

Contrib - Tim Ashley Jenkins 2017, Refactor by Griatch 2022

This is a version of the ‘turnbattle’ contrib with a basic system for weapons and armor implemented. Weapons can have unique damage ranges and accuracy modifiers, while armor can reduce incoming damage and change one’s chance of getting hit. The ‘wield’ command is used to equip weapons and the ‘don’ command is used to equip armor.

Some prototypes are included at the end of this module - feel free to copy them into your game’s prototypes.py module in your ‘world’ folder and create them with the @spawn command. (See the tutorial for using the @spawn command for details.)

For the example equipment given, heavier weapons deal more damage but are less accurate, while light weapons are more accurate but deal less damage. Similarly, heavy armor reduces incoming damage by a lot but increases your chance of getting hit, while light armor is easier to dodge in but reduces incoming damage less. Light weapons are more effective against lightly armored opponents and heavy weapons are more damaging against heavily armored foes, but heavy weapons and armor are slightly better than light weapons and armor overall.

This is a fairly bare implementation of equipment that is meant to be expanded to fit your game - weapon and armor slots, damage types and damage bonuses, etc. should be fairly simple to implement according to the rules of your preferred system or the needs of your own game.

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

> from evennia.contrib.game_systems.turnbattle.tb_equip import TBEquipCharacter

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

> class Character(TBEquipCharacter):

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

> from evennia.contrib.game_systems.turnbattle import tb_equip

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

> # # any commands you add below will overload the default ones. # self.add(tb_equip.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_equip.``ACTIONS_PER_TURN` = 1

class `evennia.contrib.game_systems.turnbattle.tb_equip.``EquipmentCombatRules`

  Bases: `evennia.contrib.game_systems.turnbattle.tb_basic.BasicCombatRules`

  Has all the methods of the basic combat, with the addition of equipment.

  `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

    In this example, a weapon’s accuracy bonus is factored into the attack roll. Lighter weapons are more accurate but less damaging, and heavier weapons are less accurate but deal more damage. Of course, you can change this paradigm completely in your own game.

  `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

    Characters are given a default defense value of 50 which can be modified up or down by armor. In this example, wearing armor actually makes you a little easier to hit, but reduces incoming damage.

  `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

    Damage is determined by the attacker’s wielded weapon, or the attacker’s unarmed damage range if no weapon is wielded. Incoming damage is reduced by the defender’s armor.

  `resolve_attack`(attacker, defender, attack_value=None, defense_value=None)

    Resolves an attack and outputs the result.

    Parameters

      - attacker (obj) – Character doing the attacking

      - defender (obj) – Character being attacked

    Notes

    Even though the attack and defense values are calculated extremely simply, they are separated out into their own functions so that they are easier to expand upon.

`evennia.contrib.game_systems.turnbattle.tb_equip.``COMBAT_RULES` = <evennia.contrib.game_systems.turnbattle.tb_equip.EquipmentCombatRules object>

class `evennia.contrib.game_systems.turnbattle.tb_equip.``TBEquipTurnHandler`(*args, **kwargs)

  Bases: `evennia.contrib.game_systems.turnbattle.tb_basic.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_equip.EquipmentCombatRules object>
  exception `DoesNotExist`

    Bases: `evennia.contrib.game_systems.turnbattle.tb_basic.TBBasicTurnHandler.DoesNotExist`

  exception `MultipleObjectsReturned`

    Bases: `evennia.contrib.game_systems.turnbattle.tb_basic.TBBasicTurnHandler.MultipleObjectsReturned`

  `path` = 'evennia.contrib.game_systems.turnbattle.tb_equip.TBEquipTurnHandler'
  `typename` = 'TBEquipTurnHandler'

class `evennia.contrib.game_systems.turnbattle.tb_equip.``TBEWeapon`(*args, **kwargs)

  Bases: `evennia.objects.objects.DefaultObject`

  A weapon which can be wielded in combat with the ‘wield’ command.

  `rules` = <evennia.contrib.game_systems.turnbattle.tb_equip.EquipmentCombatRules object>
  `at_object_creation`()

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

  `at_drop`(dropper)

    Stop being wielded if dropped.

  `at_give`(giver, getter)

    Stop being wielded if given.

  exception `DoesNotExist`

    Bases: `evennia.objects.objects.DefaultObject.DoesNotExist`

  exception `MultipleObjectsReturned`

    Bases: `evennia.objects.objects.DefaultObject.MultipleObjectsReturned`

  `path` = 'evennia.contrib.game_systems.turnbattle.tb_equip.TBEWeapon'
  `typename` = 'TBEWeapon'

class `evennia.contrib.game_systems.turnbattle.tb_equip.``TBEArmor`(*args, **kwargs)

  Bases: `evennia.objects.objects.DefaultObject`

  A set of armor which can be worn with the ‘don’ command.

  `at_object_creation`()

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

  `at_pre_drop`(dropper)

    Can’t drop in combat.

  `at_drop`(dropper)

    Stop being wielded if dropped.

  `at_pre_give`(giver, getter)

    Can’t give away in combat.

  `at_give`(giver, getter)

    Stop being wielded if given.

  exception `DoesNotExist`

    Bases: `evennia.objects.objects.DefaultObject.DoesNotExist`

  exception `MultipleObjectsReturned`

    Bases: `evennia.objects.objects.DefaultObject.MultipleObjectsReturned`

  `path` = 'evennia.contrib.game_systems.turnbattle.tb_equip.TBEArmor'
  `typename` = 'TBEArmor'

class `evennia.contrib.game_systems.turnbattle.tb_equip.``TBEquipCharacter`(*args, **kwargs)

  Bases: `evennia.contrib.game_systems.turnbattle.tb_basic.TBBasicCharacter`

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

  `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: `evennia.contrib.game_systems.turnbattle.tb_basic.TBBasicCharacter.DoesNotExist`

  exception `MultipleObjectsReturned`

    Bases: `evennia.contrib.game_systems.turnbattle.tb_basic.TBBasicCharacter.MultipleObjectsReturned`

  `path` = 'evennia.contrib.game_systems.turnbattle.tb_equip.TBEquipCharacter'
  `typename` = 'TBEquipCharacter'

class `evennia.contrib.game_systems.turnbattle.tb_equip.``CmdFight`(**kwargs)

  Bases: `evennia.contrib.game_systems.turnbattle.tb_basic.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_equip.EquipmentCombatRules object>
  `command_handler_class`

    alias of `TBEquipTurnHandler`

  `aliases` = []
  `lock_storage` = 'cmd:all();'
  `search_index_entry` = {'aliases': '', 'category': 'combat', 'key': 'fight', 'no_prefix': ' ', 'tags': '', 'text': "\n Starts a fight with everyone in the same room as you.\n\n Usage:\n fight\n\n When you start a fight, everyone in the room who is able to\n fight is added to combat, and a turn order is randomly rolled.\n When it's your turn, you can attack other characters.\n "}

class `evennia.contrib.game_systems.turnbattle.tb_equip.``CmdAttack`(**kwargs)

  Bases: `evennia.contrib.game_systems.turnbattle.tb_basic.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_equip.EquipmentCombatRules object>
  `aliases` = []
  `lock_storage` = 'cmd:all();'
  `search_index_entry` = {'aliases': '', 'category': 'combat', 'key': 'attack', 'no_prefix': ' ', 'tags': '', 'text': '\n Attacks another character.\n\n Usage:\n attack <target>\n\n When in a fight, you may attack another character. The attack has\n a chance to hit, and if successful, will deal damage.\n '}

class `evennia.contrib.game_systems.turnbattle.tb_equip.``CmdPass`(**kwargs)

  Bases: `evennia.contrib.game_systems.turnbattle.tb_basic.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_equip.EquipmentCombatRules object>
  `lock_storage` = 'cmd:all();'
  `search_index_entry` = {'aliases': 'wait hold', 'category': 'combat', 'key': 'pass', 'no_prefix': ' wait hold', 'tags': '', 'text': '\n Passes on your turn.\n\n Usage:\n pass\n\n When in a fight, you can use this command to end your turn early, even\n if there are still any actions you can take.\n '}

class `evennia.contrib.game_systems.turnbattle.tb_equip.``CmdDisengage`(**kwargs)

  Bases: `evennia.contrib.game_systems.turnbattle.tb_basic.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_equip.EquipmentCombatRules object>
  `lock_storage` = 'cmd:all();'
  `search_index_entry` = {'aliases': 'spare', 'category': 'combat', 'key': 'disengage', 'no_prefix': ' spare', 'tags': '', 'text': "\n Passes your turn and attempts to end combat.\n\n Usage:\n disengage\n\n Ends your turn early and signals that you're trying to end\n the fight. If all participants in a fight disengage, the\n fight ends.\n "}

class `evennia.contrib.game_systems.turnbattle.tb_equip.``CmdRest`(**kwargs)

  Bases: `evennia.contrib.game_systems.turnbattle.tb_basic.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_equip.EquipmentCombatRules object>
  `aliases` = []
  `lock_storage` = 'cmd:all();'
  `search_index_entry` = {'aliases': '', 'category': 'combat', 'key': 'rest', 'no_prefix': ' ', 'tags': '', 'text': "\n Recovers damage.\n\n Usage:\n rest\n\n Resting recovers your HP to its maximum, but you can only\n rest if you're not in a fight.\n "}

class `evennia.contrib.game_systems.turnbattle.tb_equip.``CmdCombatHelp`(**kwargs)

  Bases: `evennia.contrib.game_systems.turnbattle.tb_basic.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_equip.EquipmentCombatRules object>
  `aliases` = ['?']
  `help_category` = 'general'
  `key` = 'help'
  `lock_storage` = 'cmd:all()'
  `search_index_entry` = {'aliases': '?', 'category': 'general', 'key': 'help', 'no_prefix': ' ?', 'tags': '', 'text': '\n View help or a list of topics\n\n Usage:\n help <topic or command>\n help list\n help all\n\n This will search for help on commands and other\n topics related to the game.\n '}

class `evennia.contrib.game_systems.turnbattle.tb_equip.``CmdWield`(**kwargs)

  Bases: `evennia.commands.command.Command`

  Wield a weapon you are carrying

  Usage:

    wield <weapon>

  Select a weapon you are carrying to wield in combat. If you are already wielding another weapon, you will switch to the weapon you specify instead. Using this command in combat will spend your action for your turn. Use the “unwield” command to stop wielding any weapon you are currently wielding.

  `key` = 'wield'
  `help_category` = 'combat'
  `rules` = <evennia.contrib.game_systems.turnbattle.tb_equip.EquipmentCombatRules object>
  `func`()

    This performs the actual command.

  `aliases` = []
  `lock_storage` = 'cmd:all();'
  `search_index_entry` = {'aliases': '', 'category': 'combat', 'key': 'wield', 'no_prefix': ' ', 'tags': '', 'text': '\n Wield a weapon you are carrying\n\n Usage:\n wield <weapon>\n\n Select a weapon you are carrying to wield in combat. If\n you are already wielding another weapon, you will switch\n to the weapon you specify instead. Using this command in\n combat will spend your action for your turn. Use the\n "unwield" command to stop wielding any weapon you are\n currently wielding.\n '}

class `evennia.contrib.game_systems.turnbattle.tb_equip.``CmdUnwield`(**kwargs)

  Bases: `evennia.commands.command.Command`

  Stop wielding a weapon.

  Usage:

    unwield

  After using this command, you will stop wielding any weapon you are currently wielding and become unarmed.

  `key` = 'unwield'
  `help_category` = 'combat'
  `rules` = <evennia.contrib.game_systems.turnbattle.tb_equip.EquipmentCombatRules object>
  `func`()

    This performs the actual command.

  `aliases` = []
  `lock_storage` = 'cmd:all();'
  `search_index_entry` = {'aliases': '', 'category': 'combat', 'key': 'unwield', 'no_prefix': ' ', 'tags': '', 'text': '\n Stop wielding a weapon.\n\n Usage:\n unwield\n\n After using this command, you will stop wielding any\n weapon you are currently wielding and become unarmed.\n '}

class `evennia.contrib.game_systems.turnbattle.tb_equip.``CmdDon`(**kwargs)

  Bases: `evennia.commands.command.Command`

  Don armor that you are carrying

  Usage:

    don <armor>

  Select armor to wear in combat. You can’t use this command in the middle of a fight. Use the “doff” command to remove any armor you are wearing.

  `key` = 'don'
  `help_category` = 'combat'
  `rules` = <evennia.contrib.game_systems.turnbattle.tb_equip.EquipmentCombatRules object>
  `func`()

    This performs the actual command.

  `aliases` = []
  `lock_storage` = 'cmd:all();'
  `search_index_entry` = {'aliases': '', 'category': 'combat', 'key': 'don', 'no_prefix': ' ', 'tags': '', 'text': '\n Don armor that you are carrying\n\n Usage:\n don <armor>\n\n Select armor to wear in combat. You can\'t use this\n command in the middle of a fight. Use the "doff"\n command to remove any armor you are wearing.\n '}

class `evennia.contrib.game_systems.turnbattle.tb_equip.``CmdDoff`(**kwargs)

  Bases: `evennia.commands.command.Command`

  Stop wearing armor.

  Usage:

    doff

  After using this command, you will stop wearing any armor you are currently using and become unarmored. You can’t use this command in combat.

  `key` = 'doff'
  `help_category` = 'combat'
  `rules` = <evennia.contrib.game_systems.turnbattle.tb_equip.EquipmentCombatRules object>
  `func`()

    This performs the actual command.

  `aliases` = []
  `lock_storage` = 'cmd:all();'
  `search_index_entry` = {'aliases': '', 'category': 'combat', 'key': 'doff', 'no_prefix': ' ', 'tags': '', 'text': "\n Stop wearing armor.\n\n Usage:\n doff\n\n After using this command, you will stop wearing any\n armor you are currently using and become unarmored.\n You can't use this command in combat.\n "}

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

  Bases: `evennia.commands.default.cmdset_character.CharacterCmdSet`

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

  `key` = 'DefaultCharacter'
  `at_cmdset_creation`()

    Populates the cmdset

  `path` = 'evennia.contrib.game_systems.turnbattle.tb_equip.BattleCmdSet'