Special Abilities, "Perks"

Perks are a highly configurable system that allows users to trigger certain abilities when events happen in PMMO. While PMMO ships with a number of built in perks, the API allows other mods to add their own, which you can then configure to your liking.

For Developers go HERE

How do perks work

Perks are configured in the perks config. When an gameplay event occurs, requirements are checked first. If the player is not prohibitted from the action, special event triggers from addons occur. After those, all perks configured for that event will attempt to activate. Most perks have conditions such as specific skills, cooldowns, damage types, weapons used, etc. For all that meet their conditions, they activate and their special abilities go into effect. After this, any applicable experience is awarded.

Perks are also not tied to any specific skill or event. For example fireworks are configured for when players level up in skills, but they don't have to be. You could have them activate after a monster kill instead. The options are really limited only by your imagination.

Individual Perk Configurations

Perks are very dynamic and each perk can have any number of settings. For example let's use the perk pmmo:attribute with Minecraft's generic.max_health which gives extra hearts to the player based on their skill level

"EVENT_NAME": [
    {
        "perk": "pmmo:attribute",
        "skill": "endurance",
        "attribute": "minecraft:generic.max_health",
        "per_level": 1,
        "max_boost": 10
    }
]

This perk has 4 settings skill, attribute, per_level and max_boost. When the EVENT_NAME event is triggered, this perk will use the player's endurance level. This particular perk is then going to give the player extra hearts according to the settings. In this case it's one half-heart per 1 level of the skill. So at 9 endurance, the player gets 4.5 hearts. The max boost sets a cap on how much extra health the player can get from skills. In this case it is set at 10, or 5 hearts.

Suppose this was my configuration though

"EVENT_NAME": [
    {
        "perk": "pmmo:attribute",
        "skill": "endurance",
        "attribute": "minecraft:generic.max_health",
        "per_level": 1,
        "max_boost": 10
    },
    {
        "perk": "pmmo:attribute",
        "skill": "combat",
        "attribute": "minecraft:generic.max_health",
        "per_level": 1,
        "max_boost": 20
    }
]

in this case the perk is calculated based on my endurance level AND my combat level. And combat has a higher cap. You can start to see how perks are dynamic.

Event Configuration

In the above section, we used a generic "EVENT_NAME", but you should be using actual event names. The full list of event names can be found HERE.

It is important to know what your perks do, so that you know what events to put them under. For example, it may not make sense to use "pmmo:jump_boost" under "BLOCK_BREAK" and have the player hop every time they break a block (as funny as that looks).

Default Properties

All perks are affected by the following properties. The below table lists them and the effect it will have on your perk.

PMMO Perks

These are all the perks PMMO provides without any addons. The defaults listed below are the values if you omit the property in your configuration. By using a property in your pmmo-Perks.toml, the default is ignored.

pmmo:break_speed

Modifies the break-speed of blocks. Only works with the BREAK_SPEED event.

pmmo:fireworks

Shoots a firework into the air above the player. Only works with the SKILL_UP event.

pmmo:attribute

Gives the player an attribute modifier. This works with modded attributes. For the full list of vanilla attribute IDs, go HERE

pmmo:temp_attribute

Gives the player an attribute for a specific duration, then removes it.

pmmo:jump_boost

Gives the player a vertical boost. If used with the JUMP event, will add to the jump, otherwise the perk will just launch the player into the air a certain amount.

pmmo:breath

Restores a portion of the breath bar after the last breath bubble dissapears

pmmo:damage_reduce

Reduces damage received when used with the RECEIVE_DAMAGE event.

pmmo:damage_boost

Increases damage to attacks. This is the only damage booster for archery, magic, and gunslinging. Note that melee attack boosting should use pmmo:attribute and use the vanilla attack damage attribute.

pmmo:effect

Gives the player an effect for a specific time

pmmo:command

Runs the specified command or function when triggered. Note the Glossary entry for this perk will display the property literally. It is advised to name your functions something intuitive, if using functions.

pmmo:villager_boost

Reduces the villager's trades to post-cured level when interacted with. Only works with the ENTITY event.

pmmo:tame_boost

Increases the attributes of the tamed animal. Only works with the TAMING event. Currently, all attributes modified are hardcoded to these values.