An architectural guide and sample implementation for a highly versatile, reactive Ability System for Minecraft (Paper/Spigot).
This project serves as a design guide rather than a feature-complete plugin. It demonstrates a robust way to decouple ability logic from the Bukkit API using a reactive workflow.
The core philosophy is to minimize "hard-coding" of ability logic and instead provide a flexible framework where abilities can be composed of reusable components.
This project is designed as a learning resource. Check out the detailed guides in the docs/ folder:
- Core Workflow: How the Trigger -> Restriction -> Action pipeline works.
- Adding Triggers: How to hook into new events.
- Implementing Restrictions: How to create filters (cooldowns, permissions, etc.).
- Actions & Mixed Types: Executing logic and modifying events.
- Context & Metadata: Type-safe data sharing and persistence.
- Ability Types: Guides for Cast Abilities and Toggle Abilities.
- Homework: Exercises to improve your implementation.
api/: The core framework. Contains the abstractions for triggers, restrictions, actions, and metadata management.example-plugin/: A reference implementation. Shows how to use the API to create a "Hero" system with specific character abilities (e.g., Hulk, Iron Man).
The system follows a three-step workflow for every ability:
- Trigger: An event occurs (e.g., player takes damage, moves, or manually activates an ability). This builds the Context.
- Restrictions: Rules are applied to the context (e.g., "Is the player on cooldown?", "Does the player have enough mana?", "Is the damage self-inflicted?").
- Actions: If all restrictions pass, the logic is executed (e.g., modify damage, send a message, play a sound).
A flexible metadata system allows storing information tied to either a player or an ability. This is used for tracking state like:
- Cooldown timestamps
- Active/Inactive states (for toggles)
- "Stacks" of a specific buff
- Custom player data