evennia.contrib.game_systems.turnbattle.tb_magic

Simple turn-based combat system with spell casting

Contrib - Tim Ashley Jenkins 2017, Refactor by Griatch, 2022

This is a version of the ‘turnbattle’ contrib that includes a basic, expandable framework for a ‘magic system’, whereby players can spend a limited resource (MP) to achieve a wide variety of effects, both in and out of combat. This does not have to strictly be a system for magic - it can easily be re-flavored to any other sort of resource based mechanic, like psionic powers, special moves and stamina, and so forth.

In this system, spells are learned by name with the ‘learnspell’ command, and then used with the ‘cast’ command. Spells can be cast in or out of combat - some spells can only be cast in combat, some can only be cast outside of combat, and some can be cast any time. However, if you are in combat, you can only cast a spell on your turn, and doing so will typically use an action (as specified in the spell’s funciton).

Spells are defined at the end of the module in a database that’s a dictionary of dictionaries - each spell is matched by name to a function, along with various parameters that restrict when the spell can be used and what the spell can be cast on. Included is a small variety of spells that damage opponents and heal HP, as well as one that creates an object.

Because a spell can call any function, a spell can be made to do just about anything at all. The SPELLS dictionary at the bottom of the module even allows kwargs to be passed to the spell function, so that the same function can be re-used for multiple similar spells.

Spells in this system work on a very basic resource: MP, which is spent when casting spells and restored by resting. It shouldn’t be too difficult to modify this system to use spell slots, some physical fuel or resource, or whatever else your game requires.

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

from evennia.contrib.game_systems.turnbattle.tb_magic import TBMagicCharacter

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

class Character(TBMagicCharacter):

Note: If your character already existed you need to also make sure to re-run the creation hooks on it to set the needed Attributes. Use update self to try on yourself or use py to call at_object_creation() on all existing Characters.

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

from evennia.contrib.game_systems.turnbattle import tb_magic

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

# # any commands you add below will overload the default ones. # self.add(tb_magic.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.

class evennia.contrib.game_systems.turnbattle.tb_magic.MagicCombatRules

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

spell_healing(caster, spell_name, targets, cost, **kwargs)

Spell that restores HP to a target or targets.

kwargs:

healing_range (tuple): Minimum and maximum amount healed to

each target. (20, 40) by default.

spell_attack(caster, spell_name, targets, cost, **kwargs)

Spell that deals damage in combat. Similar to resolve_attack.

kwargs:

attack_name (tuple): Single and plural describing the sort of

attack or projectile that strikes each enemy.

damage_range (tuple): Minimum and maximum damage dealt by the

spell. (10, 20) by default.

accuracy (int): Modifier to the spell’s attack roll, determining

an increased or decreased chance to hit. 0 by default.

attack_count (int): How many individual attacks are made as part

of the spell. If the number of attacks exceeds the number of targets, the first target specified will be attacked more than once. Just 1 by default - if the attack_count is less than the number targets given, each target will only be attacked once.

spell_conjure(caster, spell_name, targets, cost, **kwargs)

Spell that creates an object.

kwargs:

obj_key (str): Key of the created object. obj_desc (str): Desc of the created object. obj_typeclass (str): Typeclass path of the object.

If you want to make more use of this particular spell funciton, you may want to modify it to use the spawner (in evennia.utils.spawner) instead of creating objects directly.

evennia.contrib.game_systems.turnbattle.tb_magic.COMBAT_RULES = <evennia.contrib.game_systems.turnbattle.tb_magic.MagicCombatRules object>

In this section, each spell is matched to a function, and given parameters that determine its MP cost, valid type and number of targets, and what function casting the spell executes.

This data is given as a dictionary of dictionaries - the key of each entry is the spell’s name, and the value is a dictionary of various options and parameters, some of which are required and others which are optional.

Required values for spells:

cost (int): MP cost of casting the spell target (str): Valid targets for the spell. Can be any of:

“none” - No target needed “self” - Self only “any” - Any object “anyobj” - Any object that isn’t a character “anychar” - Any character “other” - Any object excluding the caster “otherchar” - Any character excluding the caster

spellfunc (callable): Function that performs the action of the spell.

Must take the following arguments: caster (obj), spell_name (str), targets (list), and cost (int), as well as **kwargs.

Optional values for spells:

combat_spell (bool): If the spell can be cast in combat. True by default. noncombat_spell (bool): If the spell can be cast out of combat. True by default. max_targets (int): Maximum number of objects that can be targeted by the spell.

1 by default - unused if target is “none” or “self”

Any other values specified besides the above will be passed as kwargs to ‘spellfunc’. You can use kwargs to effectively re-use the same function for different but similar spells - for example, ‘magic missile’ and ‘flame shot’ use the same function, but behave differently, as they have different damage ranges, accuracy, amount of attacks made as part of the spell, and so forth. If you make your spell functions flexible enough, you can make a wide variety of spells just by adding more entries to this dictionary.

evennia.contrib.game_systems.turnbattle.tb_magic.SPELLS = {'cactus conjuration': {'combat_spell': False, 'cost': 2, 'obj_desc': 'An ordinary green cactus with little spines.', 'obj_key': 'a cactus', 'spellfunc': <bound method MagicCombatRules.spell_conjure of <evennia.contrib.game_systems.turnbattle.tb_magic.MagicCombatRules object>>, 'target': 'none'}, 'cure wounds': {'cost': 5, 'spellfunc': <bound method MagicCombatRules.spell_healing of <evennia.contrib.game_systems.turnbattle.tb_magic.MagicCombatRules object>>, 'target': 'anychar'}, 'flame shot': {'attack_name': ('A jet of flame', 'jets of flame'), 'cost': 3, 'damage_range': (25, 35), 'noncombat_spell': False, 'spellfunc': <bound method MagicCombatRules.spell_attack of <evennia.contrib.game_systems.turnbattle.tb_magic.MagicCombatRules object>>, 'target': 'otherchar'}, 'full heal': {'cost': 12, 'healing_range': (100, 100), 'spellfunc': <bound method MagicCombatRules.spell_healing of <evennia.contrib.game_systems.turnbattle.tb_magic.MagicCombatRules object>>, 'target': 'anychar'}, 'magic missile': {'accuracy': 999, 'attack_count': 3, 'attack_name': ('A bolt', 'bolts'), 'cost': 3, 'damage_range': (4, 7), 'max_targets': 3, 'noncombat_spell': False, 'spellfunc': <bound method MagicCombatRules.spell_attack of <evennia.contrib.game_systems.turnbattle.tb_magic.MagicCombatRules object>>, 'target': 'otherchar'}, 'mass cure wounds': {'cost': 10, 'max_targets': 5, 'spellfunc': <bound method MagicCombatRules.spell_healing of <evennia.contrib.game_systems.turnbattle.tb_magic.MagicCombatRules object>>, 'target': 'anychar'}}

evennia.contrib.game_systems.turnbattle.tb_magic.ACTIONS_PER_TURN = 1

class evennia.contrib.game_systems.turnbattle.tb_magic.TBMagicCharacter(*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, access to combat commands and magic.

rules = <evennia.contrib.game_systems.turnbattle.tb_magic.MagicCombatRules object>

at_object_creation()

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

Adds attributes for a character’s current and maximum HP. We’re just going to set this value at ‘100’ by default.

You may want to expand this to include various ‘stats’ that can be changed at creation and factor into combat calculations.

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_magic.TBMagicCharacter'

typename = 'TBMagicCharacter'

class evennia.contrib.game_systems.turnbattle.tb_magic.TBMagicTurnHandler(*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_magic.MagicCombatRules 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_magic.TBMagicTurnHandler'

typename = 'TBMagicTurnHandler'

class evennia.contrib.game_systems.turnbattle.tb_magic.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_magic.MagicCombatRules object>

combat_handler_class

alias of TBMagicTurnHandler

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_magic.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_magic.MagicCombatRules 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_magic.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 = ['hold', 'wait']

help_category = 'combat'

rules = <evennia.contrib.game_systems.turnbattle.tb_magic.MagicCombatRules object>

lock_storage = 'cmd:all();'

search_index_entry = {'aliases': 'hold wait', 'category': 'combat', 'key': 'pass', 'no_prefix': ' hold wait', '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_magic.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_magic.MagicCombatRules 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_magic.CmdLearnSpell(**kwargs)

Bases: evennia.commands.command.Command

Learn a magic spell.

Usage:

learnspell <spell name>

Adds a spell by name to your list of spells known.

The following spells are provided as examples:

|wmagic missile|n (3 MP): Fires three missiles that never miss. Can target

up to three different enemies.

|wflame shot|n (3 MP): Shoots a high-damage jet of flame at one target.

|wcure wounds|n (5 MP): Heals damage on one target.

|wmass cure wounds|n (10 MP): Like ‘cure wounds’, but can heal up to 5

targets at once.

|wfull heal|n (12 MP): Heals one target back to full HP.

|wcactus conjuration|n (2 MP): Creates a cactus.

key = 'learnspell'

help_category = 'magic'

func()

This performs the actual command.

aliases = []

lock_storage = 'cmd:all();'

search_index_entry = {'aliases': '', 'category': 'magic', 'key': 'learnspell', 'no_prefix': ' ', 'tags': '', 'text': "\n Learn a magic spell.\n\n Usage:\n learnspell <spell name>\n\n Adds a spell by name to your list of spells known.\n\n The following spells are provided as examples:\n\n |wmagic missile|n (3 MP): Fires three missiles that never miss. Can target\n up to three different enemies.\n\n |wflame shot|n (3 MP): Shoots a high-damage jet of flame at one target.\n\n |wcure wounds|n (5 MP): Heals damage on one target.\n\n |wmass cure wounds|n (10 MP): Like 'cure wounds', but can heal up to 5\n targets at once.\n\n |wfull heal|n (12 MP): Heals one target back to full HP.\n\n |wcactus conjuration|n (2 MP): Creates a cactus.\n "}

class evennia.contrib.game_systems.turnbattle.tb_magic.CmdCast(**kwargs)

Bases: evennia.commands.default.muxcommand.MuxCommand

Cast a magic spell that you know, provided you have the MP to spend on its casting.

Usage:

cast <spellname> [= <target1>, <target2>, etc…]

Some spells can be cast on multiple targets, some can be cast on only yourself, and some don’t need a target specified at all. Typing ‘cast’ by itself will give you a list of spells you know.

key = 'cast'

help_category = 'magic'

rules = <evennia.contrib.game_systems.turnbattle.tb_magic.MagicCombatRules object>

func()

This performs the actual command.

Note: This is a quite long command, since it has to cope with all the different circumstances in which you may or may not be able to cast a spell. None of the spell’s effects are handled by the command - all the command does is verify that the player’s input is valid for the spell being cast and then call the spell’s function.

aliases = []

lock_storage = 'cmd:all();'

search_index_entry = {'aliases': '', 'category': 'magic', 'key': 'cast', 'no_prefix': ' ', 'tags': '', 'text': "\n Cast a magic spell that you know, provided you have the MP\n to spend on its casting.\n\n Usage:\n cast <spellname> [= <target1>, <target2>, etc...]\n\n Some spells can be cast on multiple targets, some can be cast\n on only yourself, and some don't need a target specified at all.\n Typing 'cast' by itself will give you a list of spells you know.\n "}

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

Bases: evennia.commands.command.Command

Recovers damage and restores MP.

Usage:

rest

Resting recovers your HP and MP to their 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_magic.MagicCombatRules 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 and restores MP.\n\n Usage:\n rest\n\n Resting recovers your HP and MP to their maximum, but you can\n only rest if you're not in a fight.\n "}

class evennia.contrib.game_systems.turnbattle.tb_magic.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'

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

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_magic.BattleCmdSet(cmdsetobj=None, key=None)

Bases: evennia.commands.default.cmdset_character.CharacterCmdSet

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

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

key = 'DefaultCharacter'

at_cmdset_creation()

Populates the cmdset