Describe the solution you'd like
A way to add bonuses and effects to items to act as "powerups" (health regeneration to a shield, absorption to armor, etc) based on a skill requirement.

Ex: The following can go on a shield and would allow for two levels of bonuses based on endurance

{
    "powerups": [
        {
            "requirements": {
                "endurance": 45
            }
            "bonuses": {
                "combat": 1.5
            }
            "effects": {
                "minecraft:regeneration": 1
            }
        },
        {
            "requirements": {
                "endurance": 80
            }
            "bonuses": {
                "combat": 2.0
            }
            "effects": {
                "minecraft:regeneration": 2
            }
        }
    ]
}

This format should also make enumeration in the Glossary easy.

Why is this feature needed
To give something more tangible for skill levels on specific items.

Describe alternatives you've considered
A lovely sunny day without rain.

I like the idea of positive effects when using items as a counter-point to negative effects when you don't have the req. I am not a fan of the layered-by-level bit though for this feature. That said, a perk that factors in when a player is holding an item could be used to filter based on item and skill, which would do the same.

🤔 the question becomes, do i add an EQUIPMENT event that perks can use and let the effect perk do this, or do I add positive effects to the item config. the former covers the above use case 100%, but the latter fits the overall design more cleanly. maybe both?

Perk-based could potentially cause the perk config file to bloat horridly if you were adding a lot of different items. Though this could be worked around a little if it supported NBT tags.

What if perks could be triggered from the items themselves? Use perks to add status effects, trigger commands, or even do specific things (extra damage dealt when DEAL_RANGED_DAMAGE with a bow, boots that give speed when WORN) and trigger them from events per item.

Add a way to specify requirements and random chance, and this would cover the above completely and allow for a lot more. (Could even use it to replace the existing negative_effect system for items.)

Maybe something like this.
per_level would probably be per level over the min_level (starting at 1).
max_boost in these example just makes it into a fixed bonus.
EQUIPPED would need to be an event that basically gives the perk bonus when equipping the item and removes it again when unequipping. For things like pmmo:regen it would need to keep the effect up all the time (similar to how negative effects are applied from items already).
chance is a percentage chance to trigger the perk.
duration would be a way of forcing the perk to disable after a set amount of ticks.

This would give a shield a regen 1 effect while equipped and you have 45 endurance plus a 25% proc chance for a 5 second melee damage buff if you have 60 combat skill.

{
    "perks": {
        "EQUIPPED": {
            {
                "pmmo:regen": {
                    "skill": "endurance",
                    "min_level": 45,
                    "per_level": 1,
                    "max_boost": 1
                }
            }
        }
        "SHIELD_BLOCK": {
            {
                "pmmo:damage": {
                    "skill": "combat",
                    "min_level": 60,
                    "per_level": 5,
                    "max_boost": 5,
                    "chance": .25,
                    "duration": 100
                }
            }
        }
    }
}

What if perks could be triggered from the items themselves

The problem with this is if an item doesn't have an action by default, it doesn't trigger anything PMMO can detect. so only items that already do something on right-click, and even then, only if the conditions to do the thing are met already.

extra damage dealt when DEAL_RANGED_DAMAGE with a bow

already a thing? "pmmo:damage_boost"

Maybe something like this.....

This is essentially perks using JSON instead of TOML. everything you made an example of is pretty much exactly what I had in mind for making an EQUIPPED perk. You added a few extra things, but by and large, what you are trying to achieve is what perks are intended to do. I am happy to add useful perks. The implementation should conform to the design of perks as opposed to new systems, though. for example a regen perk as you have above could look like

[[Perks.For_Event.EQUIPPED.endurance]]
    perk = "pmmo:regen" 
    min_level = 45
    max_boost = 1
    per_level = 1.0
    with_item = "minecraft:shield"

This would give the player a constant effect of regen level 1 as long as they have the shield item and 45 levels of endurance. I could probably make "with_item" a global property like the level ones are since that's probably useful in more places.

That would work. Like I said, with_tag might be another neat thing to add so you could give the effect to all pickaxes or all shovels.

Like I said, this could bloat the TOML file. Perhaps a way to "#include" other TOML files so that you could spread things out logically?

the perks toml is a forge config. it has limitations. I could do tags since we would be after dataloading. I would probably just do "with_item" still but accept "#thing" references and parse them on the backend.

If Perk bloat becomes a legitimate issue, i'm open to the idea of redesigning how it is configured, but i don't see that being the case atm.

If Perk bloat becomes a legitimate issue, i'm open to the idea of redesigning how it is configured, but i don't see that being the case atm.

Can you just tell Forge to load all toml files in a folder? If so, allow for folders to be named pmmo-Perks and pmmo-Skills etc. That would let people organize their data into whatever files they want.

This would give the player a constant effect of regen level 1 as long as they have the shield item and 45 levels of endurance. I could probably make "with_item" a global property like the level ones are since that's probably useful in more places.

A rnd_chance (or similar) global property would be handy too.

Can you just tell Forge to load all toml files in a folder

No, and configs have specific layouts. I use a utility to make it so you can add keys. that's not standard.

A rnd_chance (or similar) global property would be handy too.

This i could add. This makes sense as a global property.

fixed via 0ce6a61