Abilities

Abilities are special powers or skills that can be used in combat (and sometimes out of combat) to gain an edge, either dealing damage, gaining increased stats for a while or impeding the enemy’s ability to fight. Abilities usually have a cost of energy, by default that cost is taken from the entity’s energy attribute, however subclasses of Entity can easily implement their own additional energy types.

class pyzork.abilities.Ability(**kwargs)

Super class for all abilitis. Most abilities have two uses, they either have a direct effect or add a Modifier to either an entity or the user of the ability. But really, you have full control over the effect of the ability and you have access to the user casting and its target so go nuts. Similarly to modifiers, entities can have an unlimited number of abilities but they can never have the same abiltiy twice.

Parameters:

• name (Optional[str]) – A name for the ability, if none is provided the library will fallback to the docstring of the class and then to the name of the class itself.
• description (Optional[str]) – A description for the ability, if none is provided the library will fall back to the default of the docstring of the effect function
• cost (Optional[Union[Callable[[Entity, Entity], int], int]]) – An optional cost for using the ability, this can be a function that returns and int or it can simply be an int. By default, the ability will cost 0 energy.

name

Name of the ability

Type:str

description

Optional description of the ability

Type:Optional[str]

cost(user: Entity, target: Entity) → int

Method to implement if you want to give your ability a dynamic costing.

Parameters:

• user (Entity) – The Entity that used the ability. This is made available to allow you to create a dynamic cost the is based on certain items or stats of the user.
• target (Entity) – This is the Entity the ability is aimed at, if the ability is self-cast (user uses ability on himself) then it will be the same entity as the user.

Returns:

The final, calculated cost of casting this ability

Return type:

int

effect(user: Entity, target: Entity)

The method that defines what happens to the target when the ability is cast on it. This can range from directly affecting things like health or energy but it can also do more complex things like add a modifier.

Parameters:

• user (Entity) – The Entity that used the ability. This is made available to allow you to make changes to the user in the cases of a successful cast. For example if you want to restore health for damage dealt or restore energy of the ability successfully lands.
• target (Entity) – This is the Entity the ability is aimed at, if the ability is self-cast (user uses ability on himself) then it will be the same entity as the user.

Examples

There are many ways to create abilities, the simplest being to use the decorator but you can also subclass the Ability parent class as a whole or anything in between. Below are three examples going over some of the possibilities.

Decorator

Decorating a function with @Ability.add() will transform it into a subclass of Ability of the same name as the function. Here we will be creating a simple ability that costs 4 energy and applies the WarRoar modifier (an hypothetical modifiers) to the entity that used the ability.:

from pyzork import Ability

from my_adventure import WarRoarModifier

@Ability.add(cost=4, name="War Scream", description="A loud scream")
def WarRoar(ability, user, target):
    user.add_modifier(WarRoarModifier())

The cost parameter can also take a callable, if you desire for the costing of the ability to be dynamic. In this case the cost of the ability is 10% of the user’s energy.:

from pyzork import Ability

from my_adventure import WarRoarModifier

def callable_cost(ability, user, target):
    return int(user.energy * 0.1)

@Ability.add(cost=callable_cost)
def WarRoar(ability, user, target):
    user.add_modifier(WarRoarModifier())

Subclassing

You can also subclass Ability and overwrite the methods you want. Here we create a simple ability that costs 4 energy and applies the WarRoarModifier to the user:

from pyzork import Ability

from my_adventure import WarRoarModifier

class WarRoar(Ability):
    def cost(self, user, target):
        return 4

    def effect(self, user, target):
        user.add_modifier(WarRoarModifier())