This Issue captures a breaking change coming to Perk configurations in 1.20.

Introduction

This change will involve a redesign of how perks are configured by users. If that is all that is changing, this would be a minor change and could be released in 1.19, however, the fundamental structure of the configs and the way that is tied to the perk definitions means this is going to be a major change and one I will wait for 1.20 to release to spare addon authors the pain.

The main change is to swap the configuration nesting of the perk ID and the skillname. Therefore instead of

[[Perks.For_Event.SKILL_UP.magic]]
  perk = "pmmo:health"
  per_level = 0.01

the configuration would now use

[[Perks.For_Event.SKILL_UP."pmmo:health"]]
  with_skill = "magic"
  per_level = 0.01

Why is this feature needed

This change is needed because of the disconnect between skills, perks, and events. When perks were first implemented, they were designed as a replacement for hard-coded skill abilities. This meant that every implementation used a specific skill and applied a per_level logic to it. As perks have expanded, there are new perks that do not use the skill at all or only use the name, not the level. As such the nested order of Event => skill => perkID no longer makes sense. the event and perkID will always be present, but the necessity of a skill does not. For users attempting to configure a skill-less perk, it is confusing to put a placeholder skill in their configuration. This change conforms better to the application of the feature in its current form.

Impact on Addons

Currently addons are TriFunctions which take a player, nbt tag, and level integer arguments. This change would eliminate the level integer as a parameter and instead provide it in the NBT. This would make the implementations BiFunctions instead. for example suppose a player had lvl 25 in agility and the player had the following configuration

[[Perks.For_Event.SOME_EVENT."youraddon:yourperk"]]
  with_skill = "agility"

Your perk would receive the following NBT

{
  "with_skill": "agility",
  "skill_level": 25
}

This is how you will receive the player level for use with things like per_level properties.

If the configuration does not provide the "with_skill" property and your defaults to not specify a skill, the "skill_level" property will still be returned, but will return a zero.

Conclusion (tl;dr)

Perks definitions: TriFunction => BiFunction
Perk level integer from former tri-function: moved to nbt value
Configuration: perkID taking the place of skill in the toml maps. skills being optional properties now.

Details for Consideration:

• The proposed format would prohibit multiple instances of the same perk in the same event.
• Finally address compounding perks (eg two sources of an attribute not overwriting each other)
• Update configurations to use an information supplier that can be used to display perk info in the glossary

Responses in Implementation

• The proposed format would prohibit multiple instances of the same perk in the same event.

List format is ambivalent to duplicates and keeps map levels flatter.

• Finally address compounding perks (eg two sources of an attribute not overwriting each other)

this is a perk implementation issue unique to the attribute perk, which was addressed in implementation.

• Update configurations to use an information supplier that can be used to display perk info in the glossary

implemented via description and status component suppliers.