Player Abilities

Player Abilities is a framework for adding abilities to players. It supports active abilities the player uses on demand, always-on passives, and triggered abilities that fire on their own when a condition is met. Abilities have levels, cooldowns, and optional requirements, and everything can be tuned from datapacks. There are also many configuration options.

Please check out the website for detailed instructions on how to use this mod. You can also look at the Player Abilities: Reverie mod to see some implementations. 

This mod adds no abilities, it just adds the API and framework to create and add abilities to the game. It’s intended for you to make your own abilities for your own use. If you want to try out some abilities you can download my companion mod to this one that implements abilities for my modpack, Player Abilities: Reverie.

Three kinds of abilities

Active abilities are selected and used by the player. An ability can fire instantly, charge up (hold to wind up, then release), or channel (the effect runs while you maintain it). Using an ability can require standing still and can be interrupted by damage, with a progress bar and countdown on screen.

The current selected ability will show up on the HUD.

To select a new ability you can open up the ability wheel (default ‘z’). It will show each ability you have access to. If you have more than 10 abilities (or the config to separate abilities by type) you can scroll between ability wheels with the wheel open by using the mouse scroll.

Passive abilities are on while you have them. They can grant attribute bonuses like health, speed, reach, or jump strength, or run custom always-on behavior. Passives can be turned off and on from the Ability Book.

Triggered abilities fire automatically when their condition happens. Examples: survive a hit that would have killed you, gain speed after taking damage. Triggers exist for kills, deaths, crits, shield blocks, falls, jumps, eating, sleeping, gaining XP, respawning, dropping below a health threshold, and more. Each triggered ability has its own cooldown and shows a notification when it fires and when it is ready again.

\*These are all test abilities and are not included in the mod.

undefined

Core systems

• Ability levels. Abilities can scale their effects, cooldowns, and wind-up times by level.
• Cooldowns and requirements. An ability can have a cooldown plus requirements like kills or damage taken. All of them must be met before it can be used again.
• Effects. Abilities can apply timed effects when used, either standard potion effects or fully custom ongoing behavior written by a developer.
• A cooldown reduction attribute that gear and effects can modify.

Ability Tomes

Every registered ability, including abilities added by other mods, automatically gets an Ability Tome item. Using the tome teaches the player that ability. Tomes are color coded by ability kind and collected in their own creative tab. They work well in loot tables and as quest rewards.

Controls

Four keybinds, all rebindable in the controls menu. The defaults do not conflict with any vanilla key:

• Z: Ability Wheel (open the radial selector; scroll to page through categories).
• X: Use Selected Ability.
• C: Cycle Selected Ability.
• N: View Abilities (the ability book).

UI

• A radial wheel for selecting active abilities, grouped into pages by category.
• An Ability Book listing everything you know, tabbed by kind, with tooltips showing descriptions, cooldowns, levels, and requirements. Passives are toggled here.
• A HUD widget showing the selected ability, its cooldown, active effect timers, and ready notifications. It has four display modes (always, contextual, minimized, hidden) and can be placed in any corner of the screen.

Datapack configuration

Every gameplay value can be overridden per ability from a datapack: cooldowns, wind-up times, requirements, max levels, effect durations, attribute and effect grants, categories, and the mod compat wiring below. No config file is required for any ability. Datapack values override the defaults.

Mod compat (all optional)

• Project MMO: gate ability use behind skill levels, and grant ability levels from skill progression.
• Pufferfish’s Skills: skill tree nodes can grant and level abilities. Grants stay in sync with the tree, including respecs.
• Iron’s Spells ‘n Spellbooks: mana costs for abilities (planned).

The mod works standalone. Compat activates automatically when the other mods are installed.

For developers

Player Abilities is built as an API. Abilities are registered through a registry. Attribute and effect grants are declared in a single method. Triggered abilities subscribe to built-in trigger points, and mods can define and fire their own. The framework handles grants, levels, cooldowns, requirements, persistence, syncing, and UI. Cancelable events let other mods gate or observe ability use.

Roadmap

• Archetypes: custom races and classes, defined as leveled bundles of abilities and granted as a unit.
• Iron’s Spellbooks mana integration.
• More trigger points and requirement types.
• A documentation site with full details.

Requires NeoForge for Minecraft 1.21.1.