# evennia.contrib.game_systems.turnbattle.tb_basic

Simple turn-based combat system

Contrib - Tim Ashley Jenkins 2017, Refactor by Griatch 2022

This is a framework for a simple turn-based combat system, similar to those used in D&D-style tabletop role playing games. It allows any character to start a fight in a room, at which point initiative is rolled and a turn order is established. Each participant in combat has a limited time to decide their action for that turn (30 seconds by default), and combat progresses through the turn order, looping through the participants until the fight ends.

Only simple rolls for attacking are implemented here, but this system is easily extensible and can be used as the foundation for implementing the rules from your turn-based tabletop game of choice or making your own battle system.

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

> from evennia.contrib.game_systems.turnbattle.tb_basic import TBBasicCharacter

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

> class Character(TBBasicCharacter):

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

> from evennia.contrib.game_systems.turnbattle import tb_basic

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

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

class `evennia.contrib.game_systems.turnbattle.tb_basic.``BasicCombatRules`

  Bases: `object`

  Stores all combat rules and helper methods.

  `roll_init`(character)

    Rolls a number between 1-1000 to determine initiative.

    Parameters

      character (obj) – The character to determine initiative for

    Returns

      initiative (int) – The character’s place in initiative - higher numbers go first.

    Notes

    By default, does not reference the character and simply returns a random integer from 1 to 1000.

    Since the character is passed to this function, you can easily reference a character’s stats to determine an initiative roll - for example, if your character has a ‘dexterity’ attribute, you can use it to give that character an advantage in turn order, like so:

    return (randint(1,20)) + character.db.dexterity

    This way, characters with a higher dexterity will go first more often.

  `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

    By default, returns a random integer from 1 to 100 without using any properties from either the attacker or defender.

    This can easily be expanded to return a value based on characters stats, equipment, and abilities. This is why the attacker and defender are passed to this function, even though nothing from either one are used in this example.

  `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

    By default, returns 50, not taking any properties of the defender or attacker into account.

    As above, this can be expanded upon based on character stats and equipment.

  `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

    By default, returns a random integer from 15 to 25 without using any properties from either the attacker or defender.

    Again, this can be expanded upon.

  `apply_damage`(defender, damage)

    Applies damage to a target, reducing their HP by the damage amount to a minimum of 0.

    Parameters

      - defender (obj) – Character taking damage

      - damage (int) – Amount of damage being taken

  `at_defeat`(defeated)

    Announces the defeat of a fighter in combat.

    Parameters

      defeated (obj) – Fighter that’s been defeated.

    Notes

    All this does is announce a defeat message by default, but if you want anything else to happen to defeated fighters (like putting them into a dying state or something similar) then this is the place to do it.

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

  `combat_cleanup`(character)

    Cleans up all the temporary combat-related attributes on a character.

    Parameters

      character (obj) – Character to have their combat attributes removed

    Notes

    Any attribute whose key begins with ‘combat_’ is temporary and no longer needed once a fight ends.

  `is_in_combat`(character)

    Returns true if the given character is in combat.

    Parameters

      character (obj) – Character to determine if is in combat or not

    Returns

      (bool) – True if in combat or False if not in combat

  `is_turn`(character)

    Returns true if it’s currently the given character’s turn in combat.

    Parameters

      character (obj) – Character to determine if it is their turn or not

    Returns

      (bool) – True if it is their turn or False otherwise

  `spend_action`(character, actions, action_name=None)

    Spends a character’s available combat actions and checks for end of turn.

    Parameters

      - character (obj) – Character spending the action

      - actions (int) – Number of actions to spend, or ‘all’ to spend all actions

    Keyword Arguments

      - action_name (str or None) – If a string is given, sets character’s last action in

      - to provided string (combat) –

`evennia.contrib.game_systems.turnbattle.tb_basic.``COMBAT_RULES` = <evennia.contrib.game_systems.turnbattle.tb_basic.BasicCombatRules object>

class `evennia.contrib.game_systems.turnbattle.tb_basic.``TBBasicCharacter`(*args, **kwargs)

  Bases: `evennia.objects.objects.DefaultCharacter`

  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_basic.BasicCombatRules object>
  `at_object_creation`()

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

  `at_pre_move`(destination)

    Called just before starting to move this object to destination.

    Parameters

      destination (Object) – The object we are moving to

    Returns

      shouldmove (bool) – If we should move or not.

    Notes

    If this method returns False/None, the move is cancelled before it is even started.

  exception `DoesNotExist`

    Bases: `evennia.objects.objects.DefaultCharacter.DoesNotExist`

  exception `MultipleObjectsReturned`

    Bases: `evennia.objects.objects.DefaultCharacter.MultipleObjectsReturned`

  `path` = 'evennia.contrib.game_systems.turnbattle.tb_basic.TBBasicCharacter'
  `typename` = 'TBBasicCharacter'

class `evennia.contrib.game_systems.turnbattle.tb_basic.``TBBasicTurnHandler`(*args, **kwargs)

  Bases: `evennia.scripts.scripts.DefaultScript`

  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_basic.BasicCombatRules object>
  `at_script_creation`()

    Called once, when the script is created.

  `at_stop`()

    Called at script termination.

  `at_repeat`()

    Called once every self.interval seconds.

  `initialize_for_combat`(character)

    Prepares a character for combat when starting or entering a fight.

    Parameters

      character (obj) – Character to initialize for combat.

  `start_turn`(character)

    Readies a character for the start of their turn by replenishing their available actions and notifying them that their turn has come up.

    Parameters

      character (obj) – Character to be readied.

    Notes

    Here, you only get one action per turn, but you might want to allow more than one per turn, or even grant a number of actions based on a character’s attributes. You can even add multiple different kinds of actions, I.E. actions separated for movement, by adding “character.db.combat_movesleft = 3” or something similar.

  `next_turn`()

    Advances to the next character in the turn order.

  `turn_end_check`(character)

    Tests to see if a character’s turn is over, and cycles to the next turn if it is.

    Parameters

      character (obj) – Character to test for end of turn

  `join_fight`(character)

    Adds a new character to a fight already in progress.

    Parameters

      character (obj) – Character to be added to the fight.

  exception `DoesNotExist`

    Bases: `evennia.scripts.scripts.DefaultScript.DoesNotExist`

  exception `MultipleObjectsReturned`

    Bases: `evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned`

  `path` = 'evennia.contrib.game_systems.turnbattle.tb_basic.TBBasicTurnHandler'
  `typename` = 'TBBasicTurnHandler'

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

  Bases: `evennia.commands.command.Command`

  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_basic.BasicCombatRules object>
  `combat_handler_class`

    alias of `TBBasicTurnHandler`

  `func`()

    This performs the actual command.

  `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_basic.``CmdAttack`(**kwargs)

  Bases: `evennia.commands.command.Command`

  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_basic.BasicCombatRules object>
  `func`()

    This performs the actual command.

  `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_basic.``CmdPass`(**kwargs)

  Bases: `evennia.commands.command.Command`

  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_basic.BasicCombatRules object>
  `func`()

    This performs the actual command.

  `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_basic.``CmdDisengage`(**kwargs)

  Bases: `evennia.commands.command.Command`

  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_basic.BasicCombatRules object>
  `func`()

    This performs the actual command.

  `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_basic.``CmdRest`(**kwargs)

  Bases: `evennia.commands.command.Command`

  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_basic.BasicCombatRules object>
  `func`()

    This performs the actual command.

  `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_basic.``CmdCombatHelp`(**kwargs)

  Bases: `evennia.commands.default.help.CmdHelp`

  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_basic.BasicCombatRules 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.|/'
  `func`()

    Run the dynamic help entry creator.

  `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_basic.``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'
  `path` = 'evennia.contrib.game_systems.turnbattle.tb_basic.BattleCmdSet'
  `at_cmdset_creation`()

    Populates the cmdset