Levels

Levels are one of the few objects in pyzork that do not need to be subclassed or used as decorators in order to fully function. The ExperienceLevels class handles both the current experience of the entity it is attached to and its level.

Whenever an entity defeats another entity (by default) they gain some amount of experience, when they reach a certain treshold they level up. When an entity levels up, the treshold is substracted from their total experience, their level increments by one and they gain a reward. In the case of this library a reward is attributed through a function being called. By default this function simply prints “You leveled up! You are now level [entity.level]” and does nothing else but it provides you access to the entity that leveled up, which means you can do anything to that entity. In addition, leveling up also sends out a on_level event to the Quest Manager

class pyzork.levels.ExperienceLevels(**kwargs)

ExperienceLevels are handlers for an entity’s epxerience and rank. You can pass a hardcoded list of experience requirements and rewards or you can generate those automatically using certain parameters.

Parameters:

• requirements (Optional[List[int]]) – A list of int meant to represent the amount of xp it takes to get from one rank to the next. The first representing the amount it takes to go from level 0 to level 1. If this parameter is provided you won’t need to provide either of the max_level, requirement or modifier arguments.
• requirement (Optional[int]) – A single int, representing the xp it takes to get from level 0 to level 1. All further requirements will be derived from this one and the modifier. If this argument is provided then modifier and max_level must also be provided.
• max_level (Optional[int]) – A single int, meant to represent the maximum leve that can be reached, once that level is reached experience can still be acumulated but no level up event will occur and no extra rewards will be granted.
• modifier (Optional[float]) – A float which defines by how much the next requirement is increased by. For example, with a starting requirement of 100 and a modifier of 1.2, from level 0 to 1 you’ll need a 100 exp, from 1 to 2 you’ll need 120, from 2 to 3 you’ll need 144 and so on.
• rXX (Optional[int]) – An abstract keyword argument, there is not literal rXX argument, rather the XX can be replaced with the level of the requirement you wish to change, this allows you automatically generate the requirements but still have some control over the system.
• rewards (Optional[List[Callable[[ExperienceLevels], None]]]) – A list of functions to be called when a user levels up, with the first element being when the user goes from level 0 to level 1. This allows you complete control over the rewards. If you provide this parameter you do not have to provide reward.
• reward (Optional[Callable[[ExperienceLevels], None]]) – A single reward, which will be used as the default for every level up. If you provide this argument you do not have to provide rewards. You can then further customise individual level up rewards using the lXX keywords where XX is the level they need to reach to get the reward.
• lXX (Optional[Callable[[ExperienceLevels], None]]) – This is an abstract keyword argument, there is no literal lXX argument, rather you can replace XX with the level of the reward you wish to change. This argument takes a standard reward callable.
• experience_gain (Optional[float]) – Multiplicative stat to define experience gain, 1 by default

max_level

The max level the class (and by extension the attached entity) can reach.

Type:int

experience

The current experience the entity has

Type:int

requirement

How much experience the entity needs to have total to reach the next level

Type:int

remaining

How much experience the entity still needs to reach the next level

Type:int

level

The entity’s current level (starts at 0)

Type:int

experience_gain

The current multiplier for gained experienced

Type:float

total

The total amount of experience that has been gained, the sum of all the past requirements and the current amount of experience the entity has.

Type:int

Examples

The ExperienceLevels class gives you a lot of flexibility on if you want to hardcode every level and every reward or if you just want to generate those with some base parameters. For example, here’s a basic example that just makes use of the default reward (which is just a message saying you leveled up):

from pyzork.levels import ExperienceLevels

basic = ExperienceLevels(requirement=100, modifier=1.2, max_level=10)

This basic can then be passed to the Entity class. The requirement from level 0 to 1 is 100 and then any requirement after that is multiplied by 1.2 with the final requirement being level 9 to 10. You can also hardcode everything, if you want to have complete control over the way the experience is distributed. Still using the default reward:

from pyzork.levels import ExperienceLevels

basic = ExperienceLevels(requirements=[2, 33, 56, 23, 78])

In this case, the max level is 5 because there are 5 requirements. Finally, you can also mix and match automatically generated and hardcoded using the abstract keyword argument. For example, here we take our first example, but change the level 5 requirement so it’s 500:

from pyzork.levels import ExperienceLevels

basic = ExperienceLevels(
    requirement=100,
    modifier=1.2,
    max_level=10,
    r5=500
)

You can apply a similar process for rewards, a reward can be the same for every level. In this case our reward is that the entity health, damage and max health is increased by 10% every level:

from pyzork.levels import ExperienceLevels

def basic_reward(levels):
    levels.entity.base_damage *= 1.1
    levels.entity.base_defense *= 1.1

    bonus_health = levels.entity.base_max_health * 0.1
    levels.entity.base_max_health *= 1.1
    levels.entity.health += bonus_health


basic = ExperienceLevels(
    requirement=100,
    modifier=1.2,
    max_level=10,
    reward=basic_reward
)

Similarly, we can hardcode every reward. Note that while you don’t have to provide a reward system in order to create a valid ExperienceLevels instance you must provide requirements in one form or another:

from pyzork.levels import ExperienceLevels

def basic_reward_1(levels):
    levels.entity.base_damage *= 1.1
    levels.entity.base_defense *= 1.1

    bonus_health = levels.entity.base_max_health * 0.1
    levels.entity.base_max_health *= 1.1
    levels.entity.health += bonus_health

def basic_reward_2(levels):
    levels.entity.base_damage *= 1.2
    levels.entity.base_defense *= 1.2

    bonus_health = levels.entity.base_max_health * 0.2
    levels.entity.base_max_health *= 1.2
    levels.entity.health += bonus_health

basic = ExperienceLevels(
    requirement=100,
    modifier=1.2,
    max_level=2,
    rewards=[basic_reward_1, basic_reward_2]
)

Finally, as with requirements, you have complete control and can mix and match reward generation. For example, standard 10% increase in stats for all levels apart from level 5 where we get a 20% increase in stats:

from pyzork.levels import ExperienceLevels

def basic_reward(levels):
    levels.entity.base_damage *= 1.1
    levels.entity.base_defense *= 1.1

    bonus_health = levels.entity.base_max_health * 0.1
    levels.entity.base_max_health *= 1.1
    levels.entity.health += bonus_health

def l5_reward(levels):
    levels.entity.base_damage *= 1.2
    levels.entity.base_defense *= 1.2

    bonus_health = levels.entity.base_max_health * 0.2
    levels.entity.base_max_health *= 1.2
    levels.entity.health += bonus_health

basic = ExperienceLevels(
    requirement=100,
    modifier=1.2,
    max_level=2,
    reward=basic_reward,
    l5=l5_reward
)