Modifiers

A Modifier is the way the library refers to object that cause a change to an entity over a certain period of time. This distinction is important as while abilities can apply modifiers to change stats such as the player’s current health they can also simply change it directly from the ability.

class pyzork.modifiers.Modifier(**kwargs)[source]

Modifiers define changes to the stats of the entity they are attached to. They can do stuff like increase the attack of an ally for 3 turns or deal poison damage to an enemy over 5 turns. You can stack as many different modifiers as you want on a single entity but you can never give an entity the same modifier twice. This is the default behavior for every entity but it can be overwritten.

Parameters:
  • duration (int) – How many “turns” a buff lasts. A turn is all the players and enemies present in the battle doing one action. This can be a positive int to demonstrate a temporary modifier which will expire after a certain number of turns or it can be -1 to represent a permanent buff which will only expire at the end of the battle.
  • stat_type (Optional[StatEnum]) – An optional StatEnum that defines which stat this modifiers affect, this is only necessary if you have defined the buff method.
  • name (Optional[str]) – An optional string to give a name to the modifier, if this is not provided, the library will fall back to the docstring of the class and if this isn’t provided either it will fallback to the nameof the class
  • description (Optional[str]) – An optional string to give a short (or long) description about the buff and its effects. If this is not provided the library will fall back to combining the docstring of the buff and effect method.
name

Name of the ability

Type:str
description

Optional description of the ability

Type:Optional[str]
duration

How long the ability lasts

Type:int
stat_type

Optional enum that dictates which stat is affected

Type:Optional[StatEnum]
classmethod add_buff(**kwargs)[source]

Decorator function to allow the user to define a buff by decorating a function. Takes the same parameters as the class. Since this specifically adds a buff, the stat_type parameter is required

classmethod add_effect(**kwargs)[source]

Decorator function to allow the user to define an effect by decorating a function. Takes the same parameters as the class.

buff(entity: pyzork.entities.Entity)[source]

Method to implement to provide a stat buff to an entity. This method is called everytime the library calculates the stat that this modifier changes. There is no guarantee that this method will only be called once per turn so don’t make any permanent changes to the player such as restoring health or granting experience.

Parameters:entity (Entity) – The entity this modifier is attached to.
effect(entity: pyzork.entities.Entity)[source]

Method to implement to do a once per turn change to an entity. This method is called exactly once per turn (given the buff is not expired) during the end turn phase. This is where you can do stuff like restore or take away health from the entity or make other permanent changes that the entity will carry on beyond this battle.

Parameters:entity (Entity) – The entity this modifier is attached to.
is_expired()[source]

Simple method to check if is a buff is expired.

Returns:Whether or not the modifier is expired
Return type:bool

Examples

There are few different ways to create a modifier. The most common is to use the builtin class method add_effect or add_buff. This allows you to add either a buff or an effect, these can be chained to add both a buff and effect to the Modifier. Using the decorator will transform the function into a Modifier subclass.

Decorator Buff

This shows you how to create a basic debuff using the decorator that will reduce the entity’s attack by 3 for 5 turns.:

from pyzork import Modifier, StatEnum

@Modifier.add_buff(stat_type=StatEnum.attack, duration=5)
def Debuff(modifier, entity):
    return -3

Calling Debuff will now return an instance of the class Debuff which is a sublcass of the Modifier class. Since you have access to the entity instance you can of course do some more complex changes, for example you could make a debuff which reduces the entity’s attack by 25%:

from pyzork import Modifier, StatEnum

@Modifier.add_buff(stat_type=StatEnum.attack, duration=5)
def Debuff(modifier, entity):
    return player.base_damage * 0.25

When using modifiers in such a manner remember you only have access to the base stats, if you try and modify the calculated stats you will create an endless loop which will crash your adventure when you reach the recursion limit.

Decorator Effect

This shows you how to create a basic effect using the decorator that will deal 2 damage per turn to the entity for 4 turns.:

from pyzork import Modifier

@Modifier.add_effect(duration=4)
def Poison(modifier, entity):
    entity.take_pure_damage(2)

Calling Debuff will now return an instance of the class Debuff which is a sublcass of the Modifier class.

Combining

You can combine both the decorators to add a buff or effect to an existing modifier. Here we’ll show how to do this, combining the effect and buff from the previous examples. The finished product will deal 2 damage and reduce the attack of the entity by 3 for 5 turns:

from pyzork import Modifier, StatEnum

Modifier.add_effect(duration=5)
def Poison(modifier, entity):
    entity.take_pure_damage(2)

@Poison.add_buff(stat_type=StatEnum.attack)
def poison_buff(modifier, entity):
    return -3

Since Poison is already a subclass of the Modifier, the function poison_buff will remain untouched.

Subclassing

Of course, if you don’t feel like messing around with decorators you can simply subclass modifiers and overwrite either buff, effect or both. Retaking our example from Combining:

from pyzork import Modifier, StatEnum

class Poison(Modifier):
    def __init__(self):
        super().__init__(duration=5, stat_type=StatEnum.attack)

    def effect(self, entity):
        entity.take_pure_damage(2)

    def buff(self, entity):
        return -3

There, it has the exact same result. You will now have access to a class Poison to allow you to create an instance of the modifier.