evennia.contrib.game_systems.turnbattle.tb_range

Simple turn-based combat system with range and movement

Contrib - Tim Ashley Jenkins 2017

This is a version of the ‘turnbattle’ contrib that includes a system for abstract movement and positioning in combat, including distinction between melee and ranged attacks. In this system, a fighter or object’s exact position is not recorded - only their relative distance to other actors in combat.

In this example, the distance between two objects in combat is expressed as an integer value: 0 for “engaged” objects that are right next to each other, 1 for “reach” which is for objects that are near each other but not directly adjacent, and 2 for “range” for objects that are far apart.

When combat starts, all fighters are at reach with each other and other objects, and at range from any exits. On a fighter’s turn, they can use the “approach” command to move closer to an object, or the “withdraw” command to move further away from an object, either of which takes an action in combat. In this example, fighters are given two actions per turn, allowing them to move and attack in the same round, or to attack twice or move twice.

When you move toward an object, you will also move toward anything else that’s close to your target - the same goes for moving away from a target, which will also move you away from anything close to your target. Moving toward one target may also move you away from anything you’re already close to, but withdrawing from a target will never inadvertently bring you closer to anything else.

In this example, there are two attack commands. ‘Attack’ can only hit targets that are ‘engaged’ (range 0) with you. ‘Shoot’ can hit any target on the field, but cannot be used if you are engaged with any other fighters. In addition, strikes made with the ‘attack’ command are more accurate than ‘shoot’ attacks. This is only to provide an example of how melee and ranged attacks can be made to work differently - you can, of course, modify this to fit your rules system.

When in combat, the ranges of objects are also accounted for - you can’t pick up an object unless you’re engaged with it, and can’t give an object to another fighter without being engaged with them either. Dropped objects are automatically assigned a range of ‘engaged’ with the fighter who dropped them. Additionally, giving or getting an object will take an action in combat. Dropping an object does not take an action, but can only be done on your turn.

When combat ends, all range values are erased and all restrictions on getting or getting objects are lifted - distances are no longer tracked and objects in the same room can be considered to be in the same space, as is the default behavior of Evennia and most MUDs.

This system allows for strategies in combat involving movement and positioning to be implemented in your battle system without the use of a ‘grid’ of coordinates, which can be difficult and clunky to navigate in text and disadvantageous to players who use screen readers. This loose, narrative method of tracking position is based around how the matter is handled in tabletop RPGs played without a grid - typically, a character’s exact position in a room isn’t important, only their relative distance to other actors.

You may wish to expand this system with a method of distinguishing allies from enemies (to prevent allied characters from blocking your ranged attacks) as well as some method by which melee-focused characters can prevent enemies from withdrawing or punish them from doing so, such as by granting “attacks of opportunity” or something similar. If you wish, you can also expand the breadth of values allowed for range - rather than just 0, 1, and 2, you can allow ranges to go up to much higher values, and give attacks and movements more varying values for distance for a more granular system. You may also want to implement a system for fleeing or changing rooms in combat by approaching exits, which are objects placed in the range field like any other.

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

from evennia.contrib.game_systems.turnbattle.tb_range import TBRangeCharacter

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

class Character(TBRangeCharacter):

Do the same thing in your game’s objects.py module for TBRangeObject:

from evennia.contrib.game_systems.turnbattle.tb_range import TBRangeObject class Object(TBRangeObject):

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

from evennia.contrib.game_systems.turnbattle import tb_range

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

# # any commands you add below will overload the default ones. # self.add(tb_range.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_range.ACTIONS_PER_TURN = 2

class evennia.contrib.game_systems.turnbattle.tb_range.RangedCombatRules

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

get_attack(attacker, defender, attack_type)

Returns a value for an attack roll.

Parameters

• attacker (obj) – Character doing the attacking

• defender (obj) – Character being attacked

• attack_type (str) – Type of attack (‘melee’ or ‘ranged’)

Returns

attack_value (int) –

Attack roll value, compared against a defense value

to determine whether an attack hits or misses.

Notes

By default, generates a random integer from 1 to 100 without using any properties from either the attacker or defender, and modifies the result based on whether it’s for a melee or ranged attack.

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, attack_type='melee')

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

• attack_type (str) – Type of attack (‘melee’ or ‘ranged’)

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_range(obj1, obj2)

Gets the combat range between two objects.

Parameters

• obj1 (obj) – First object

• obj2 (obj) – Second object

Returns

range (int or None) – Distance between two objects or None if not applicable

distance_inc(mover, target)

Function that increases distance in range field between mover and target.

Parameters

• mover (obj) – The object moving

• target (obj) – The object to be moved away from

distance_dec(mover, target)

Helper function that decreases distance in range field between mover and target.

Parameters

• mover (obj) – The object moving

• target (obj) – The object to be moved toward

approach(mover, target)

Manages a character’s whole approach, including changes in ranges to other characters.

Parameters

• mover (obj) – The object moving

• target (obj) – The object to be moved toward

Notes

The mover will also automatically move toward any objects that are closer to the target than the mover is. The mover will also move away from anything they started out close to.

withdraw(mover, target)

Manages a character’s whole withdrawal, including changes in ranges to other characters.

Parameters

• mover (obj) – The object moving

• target (obj) – The object to be moved away from

Notes

The mover will also automatically move away from objects that are close to the target of their withdrawl. The mover will never inadvertently move toward anything else while withdrawing - they can be considered to be moving to open space.

resolve_attack(attacker, defender, attack_value=None, defense_value=None, attack_type='melee')

Resolves an attack and outputs the result.

Parameters

• attacker (obj) – Character doing the attacking

• defender (obj) – Character being attacked

• attack_type (str) – Type of attack (melee or ranged)

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_status_message(fighter)

Sends a message to a player with their current HP and distances to other fighters and objects. Called at turn start and by the ‘status’ command.

evennia.contrib.game_systems.turnbattle.tb_range.COMBAT_RULES = <evennia.contrib.game_systems.turnbattle.tb_range.RangedCombatRules object>

class evennia.contrib.game_systems.turnbattle.tb_range.TBRangeTurnHandler(*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_range.RangedCombatRules object>

init_range(to_init)

Initializes range values for an object at the start of a fight.

Parameters

to_init (object) – Object to initialize range field for.

join_rangefield(to_init, anchor_obj=None, add_distance=0)

Adds a new object to the range field of a fight in progress.

Parameters

to_init (object) – Object to initialize range field for.

Keyword Arguments

• anchor_obj (object) – Object to copy range values from, or None for a random object.

• add_distance (int) – Distance to put between to_init object and anchor object.

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

In this example, characters are given two actions per turn. This allows characters to both move and attack in the same turn (or, alternately, move twice or attack twice).

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.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_range.TBRangeTurnHandler'

typename = 'TBRangeTurnHandler'

class evennia.contrib.game_systems.turnbattle.tb_range.TBRangeCharacter(*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.

rules = <evennia.contrib.game_systems.turnbattle.tb_range.RangedCombatRules object>

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_range.TBRangeCharacter'

typename = 'TBRangeCharacter'

class evennia.contrib.game_systems.turnbattle.tb_range.TBRangeObject(*args, **kwargs)

Bases: evennia.objects.objects.DefaultObject

An object that is assigned range values in combat. Getting, giving, and dropping the object has restrictions in combat - you must be next to an object to get it, must be next to your target to give them something, and can only interact with objects on your own turn.

at_pre_drop(dropper)

Called by the default drop command before this object has been dropped.

Parameters

• dropper (Object) – The object which will drop this object.

• **kwargs (dict) – Arbitrary, optional arguments for users overriding the call (unused by default).

Returns

shoulddrop (bool) – If the object should be dropped or not.

Notes

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

at_drop(dropper)

Called by the default drop command when this object has been dropped.

Parameters

• dropper (Object) – The object which just dropped this object.

• **kwargs (dict) – Arbitrary, optional arguments for users overriding the call (unused by default).

Notes

This hook cannot stop the drop from happening. Use permissions or the at_pre_drop() hook for that.

at_pre_get(getter)

Called by the default get command before this object has been picked up.

Parameters

• getter (Object) – The object about to get this object.

• **kwargs (dict) – Arbitrary, optional arguments for users overriding the call (unused by default).

Returns

shouldget (bool) – If the object should be gotten or not.

Notes

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

at_get(getter)

Called by the default get command when this object has been picked up.

Parameters

• getter (Object) – The object getting this object.

• **kwargs (dict) – Arbitrary, optional arguments for users overriding the call (unused by default).

Notes

This hook cannot stop the pickup from happening. Use permissions or the at_pre_get() hook for that.

at_pre_give(giver, getter)

Called by the default give command before this object has been given.

Parameters

• giver (Object) – The object about to give this object.

• getter (Object) – The object about to get this object.

• **kwargs (dict) – Arbitrary, optional arguments for users overriding the call (unused by default).

Returns

shouldgive (bool) – If the object should be given or not.

Notes

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

at_give(giver, getter)

Called by the default give command when this object has been given.

Parameters

• giver (Object) – The object giving this object.

• getter (Object) – The object getting this object.

• **kwargs (dict) – Arbitrary, optional arguments for users overriding the call (unused by default).

Notes

This hook cannot stop the give from happening. Use permissions or the at_pre_give() hook for that.

exception DoesNotExist

Bases: evennia.objects.objects.DefaultObject.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.objects.objects.DefaultObject.MultipleObjectsReturned

path = 'evennia.contrib.game_systems.turnbattle.tb_range.TBRangeObject'

typename = 'TBRangeObject'

class evennia.contrib.game_systems.turnbattle.tb_range.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_range.RangedCombatRules object>

combat_handler_class

alias of TBRangeTurnHandler

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

Bases: evennia.contrib.game_systems.turnbattle.tb_basic.CmdAttack

Attacks another character in melee.

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. You can only attack engaged targets - that is, targets that are right next to you. Use the ‘approach’ command to get closer to a target.

key = 'attack'

help_category = 'combat'

rules = <evennia.contrib.game_systems.turnbattle.tb_range.RangedCombatRules 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 in melee.\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. You can only\n attack engaged targets - that is, targets that are right next to\n you. Use the 'approach' command to get closer to a target.\n "}

class evennia.contrib.game_systems.turnbattle.tb_range.CmdShoot(**kwargs)

Bases: evennia.commands.command.Command

Attacks another character from range.

Usage:

shoot <target>

When in a fight, you may shoot another character. The attack has a chance to hit, and if successful, will deal damage. You can attack any target in combat by shooting, but can’t shoot if there are any targets engaged with you. Use the ‘withdraw’ command to retreat from nearby enemies.

key = 'shoot'

help_category = 'combat'

rules = <evennia.contrib.game_systems.turnbattle.tb_range.RangedCombatRules object>

func()

This performs the actual command.

aliases = []

lock_storage = 'cmd:all();'

search_index_entry = {'aliases': '', 'category': 'combat', 'key': 'shoot', 'no_prefix': ' ', 'tags': '', 'text': "\n Attacks another character from range.\n\n Usage:\n shoot <target>\n\n When in a fight, you may shoot another character. The attack has\n a chance to hit, and if successful, will deal damage. You can attack\n any target in combat by shooting, but can't shoot if there are any\n targets engaged with you. Use the 'withdraw' command to retreat from\n nearby enemies.\n "}

class evennia.contrib.game_systems.turnbattle.tb_range.CmdApproach(**kwargs)

Bases: evennia.commands.command.Command

Approaches an object.

Usage:

approach <target>

Move one space toward a character or object. You can only attack characters you are 0 spaces away from.

key = 'approach'

help_category = 'combat'

rules = <evennia.contrib.game_systems.turnbattle.tb_range.RangedCombatRules object>

func()

This performs the actual command.

aliases = []

lock_storage = 'cmd:all();'

search_index_entry = {'aliases': '', 'category': 'combat', 'key': 'approach', 'no_prefix': ' ', 'tags': '', 'text': '\n Approaches an object.\n\n Usage:\n approach <target>\n\n Move one space toward a character or object. You can only attack\n characters you are 0 spaces away from.\n '}

class evennia.contrib.game_systems.turnbattle.tb_range.CmdWithdraw(**kwargs)

Bases: evennia.commands.command.Command

Moves away from an object.

Usage:

withdraw <target>

Move one space away from a character or object.

key = 'withdraw'

help_category = 'combat'

rules = <evennia.contrib.game_systems.turnbattle.tb_range.RangedCombatRules object>

func()

This performs the actual command.

aliases = []

lock_storage = 'cmd:all();'

search_index_entry = {'aliases': '', 'category': 'combat', 'key': 'withdraw', 'no_prefix': ' ', 'tags': '', 'text': '\n Moves away from an object.\n\n Usage:\n withdraw <target>\n\n Move one space away from a character or object.\n '}

class evennia.contrib.game_systems.turnbattle.tb_range.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_range.RangedCombatRules 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_range.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_range.RangedCombatRules 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_range.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_range.RangedCombatRules 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_range.CmdStatus(**kwargs)

Bases: evennia.commands.command.Command

Gives combat information.

Usage:

status

Shows your current and maximum HP and your distance from other targets in combat.

key = 'status'

help_category = 'combat'

rules = <evennia.contrib.game_systems.turnbattle.tb_range.RangedCombatRules object>

func()

This performs the actual command.

aliases = []

lock_storage = 'cmd:all();'

search_index_entry = {'aliases': '', 'category': 'combat', 'key': 'status', 'no_prefix': ' ', 'tags': '', 'text': '\n Gives combat information.\n\n Usage:\n status\n\n Shows your current and maximum HP and your distance from\n other targets in combat.\n '}

class evennia.contrib.game_systems.turnbattle.tb_range.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_range.RangedCombatRules object>

combat_help_text = 'Available combat commands:|/|wAttack:|n Attack an engaged target, attempting to deal damage.|/|wShoot:|n Attack from a distance, if not engaged with other fighters.|/|wApproach:|n Move one step cloer to a target.|/|wWithdraw:|n Move one step away from a target.|/|wPass:|n Pass your turn without further action.|/|wStatus:|n View current HP and ranges to other targets.|/|wDisengage:|n End your turn and attempt to end combat.|/'

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_range.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_range.BattleCmdSet'

at_cmdset_creation()

Populates the cmdset