Perks - Caltinor/Project-MMO-2.0 GitHub Wiki

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

When a perk is configured, it will trigger during the specified event after the custom event trigger but before XP is awarded. This means that perks do not fire if the requirements for an event are not met, and addons can intercept and even change information relevant to perks before they fire. Lastly perks can also add XP awards before they are given and change values of events that pmmo has permitted.

In summary, perks allow any addon maker to add custom behavior to a pmmo event that the player can configure to their liking.

all perk settings are in a server config located in your minecraft folder under /saves/<save name>/serverconfig/pmmo-Perks.toml.

the basic structure of the config looks like

[Perks]
    [Perks.For_Event]
        [Perks.For_Event.EVENT_NAME]
            [Perks.For_Event.EVENT_NAME.skillname]
                perk = "modid:perkid"
            [Perks.For_Event.EVENT_NAME.skillname]
                perk = "modid:otherperkid"
            [Perks.For_Event.EVENT_NAME.otherskillname]
                perk = "modid:perkid"
        [Perks.For_Event.OTHER_EVENT_NAME]
            [Perks.For_Event.OTHER_EVENT_NAME.skillname]
                perk = "modid:perkid"

Note that multiple perks for the same skill have their own skillname section, and that you can have multiple skills in the same event even with the same perk.

Perks are very dynamic and each perk can have any number of settings. Because of this, you should consult with the perk author about what settings their perks have. the PMMO default perk settings are shown at the bottom of this page. Once you know what settings exist, you can define them in the config file. for example let's use the perk pmmo:health which gives extra hearts to the player based on their skill level

[Perks.For_Event.EVENT_NAME.endurance]
    perk = "pmmo:attribute"
    attribute = "minecraft:generic.max_health"
    per_level = 1
    max_boost = 10

This perk has 3 settings attribute, per_level and max_boost. Because we defined this perk under the "endurance" skill, when the EVENT_NAME event is triggered, this perk will be given 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

[Perks.For_Event.EVENT_NAME.endurance]
    perk = "pmmo:attribute"
    attribute = "minecraft:generic.max_health"
    per_level = 1
    max_boost = 10
[Perks.For_Event.EVENT_NAME.combat]
    perk = "pmmo:attribute"
    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.

As noted above, if you want two perks for the same event and skill, you need to define them separately. example:

[[Perks.For_Event.SKILL_UP.agility]]
    perk = "pmmo:attribute"
    attribute = "minecraft:generic.movement_speed"
[[Perks.For_Event.SKILL_UP.agility]]
    skill = "agility"
    perk = "pmmo:fireworks"

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

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.

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

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

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

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.

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

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.

Gives the player an effect for a specific time

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.

Reduces the damage from a fall by a certain amount.

gives the player night vision

gives the player the regen effect for a specified time.