📄
pasted-code-1787032568251.txt
txt
2197 lines
▶
# BossPowers SMP — Complete Master Development Specification
Create and maintain a complete, production-ready Minecraft SMP powers plugin called:
**BossPowers**
The plugin should be inspired by the general gameplay concept of popular powers/gem SMP plugins such as Bliss SMP, but it must be a completely original implementation.
**DO NOT copy Bliss SMP's:**
- Source code
- Decompiled code
- Powers
- Ability implementations
- Names
- Textures
- Recipes
- Proprietary systems
The uploaded BlissGems JAR may only be used as a conceptual reference for understanding how an ability-binding architecture can work.
The final BossPowers plugin must have its own architecture, classes, systems, abilities and mechanics.
---
# 1. EXISTING PROJECT — IMPORTANT
This is an update/continuation of an existing BossPowers plugin.
The existing:
- Commands
- INVENTORY GUI
- Power system
- Item system
- Recipe system
- Configuration
- Storage
- Permissions
- Other already-working functionality
must NOT be unnecessarily rewritten or broken.
Before changing anything:
1. Understand the existing project architecture.
2. Identify already-working systems.
3. Reuse existing managers where appropriate.
4. Only refactor systems that are necessary.
5. Preserve backwards compatibility with existing configuration where possible.
The major systems being improved are:
- Ability activation
- Ability targeting
- Click/key detection
- Combined abilities
- Cooldowns
- Countdown timers
- Ring effects
- Power crafting events
- Crafting limits
- Recipe difficulty
- Region/claim protection
- Command permissions
---
# 2. PLATFORM & COMPATIBILITY
Primary Minecraft target:
- Minecraft 1.21.x
Server platforms:
- Paper
- Spigot
- Folia
Proxy environments:
- BungeeCord
- Velocity
The plugin must operate server-side without requiring players to install a client-side mod.
Use a compatibility abstraction.
Do not unnecessarily hard-code Paper-only APIs.
If a feature requires platform-specific implementation, isolate it behind a compatibility layer.
Recommended architecture:
```text
compatibility/
PlatformAdapter
PaperAdapter
SpigotAdapter
FoliaAdapter
```
The plugin should be structured so additional Minecraft versions can be supported later.
---
# 3. CRITICAL REGION / LAND-CLAIM PROTECTION
This is a mandatory security requirement.
**BossPowers MUST NEVER bypass, override, ignore, or circumvent existing land-claim or region-protection plugins.**
BossPowers abilities must respect protection systems already installed on the server.
The plugin must NOT provide a way for abilities to bypass:
- WorldGuard regions
- GriefPrevention claims
- Residence claims
- Lands claims
- Towny protection
- Plot/plot-claim plugins
- Other land-claim plugins
- Other region-protection plugins
- Server protection APIs
- Build protection
- PvP protection
- Interaction protection
The protection system must be designed as a compatibility layer.
Recommended:
```text
protection/
ProtectionManager
ProtectionProvider
WorldGuardProvider
GriefPreventionProvider
ResidenceProvider
LandsProvider
TownyProvider
PlotProvider
```
Only load providers for plugins that are actually installed.
If a protection plugin provides an official API, use its API instead of trying to detect protection through unsafe workarounds.
---
# 4. NEVER BYPASS PROTECTED REGIONS
BossPowers must never force an ability through a protected region.
For example, if a player is standing inside a WorldGuard region where they are not allowed to use abilities, BossPowers MUST block the ability.
Likewise, if a player is inside another player's land claim and the claim prevents the relevant action, BossPowers MUST respect that restriction.
Do NOT:
- Temporarily disable WorldGuard
- Temporarily disable claims
- Modify region flags
- Modify claim ownership
- Force block changes
- Force entity damage
- Force entity interactions
- Bypass protection events
- Directly modify protected blocks while ignoring protection
- Use fake permissions to bypass protection
- Use unsafe NMS methods to circumvent protection
---
# 5. ABILITY PROTECTION CHECK
Every BossPowers ability MUST perform a protection check before executing.
The protection check must happen:
1. When the ability is initially armed if applicable.
2. When a target is selected.
3. Immediately before the ability actually executes.
4. Before any block modification.
5. Before any entity damage/interactions that may violate protection.
The final execution-time check is mandatory.
This prevents situations where:
```text
Player arms ability
↓
Player moves into protected region
↓
Player selects target
↓
Ability bypasses protection
```
Instead:
```text
Ability armed
↓
Player enters protected region
↓
Execution check
↓
ABILITY BLOCKED
```
---
# 6. PLAYER-FACING PROTECTION MESSAGE
If a player attempts to use a BossPowers ability in a protected region/claim where the ability is not permitted, display:
```text
&c✦ You are here in a protected region. You cannot use this ability here.
```
The message should be configurable in:
```text
messages.yml
```
Recommended key:
```yaml
protection:
ability-blocked: "&c✦ You are here in a protected region. You cannot use this ability here."
```
Do not spam the message repeatedly every tick.
Only display it when the player actually attempts an ability action that is blocked.
---
# 7. TARGET PROTECTION CHECK
Protection checks must also consider the target.
Example:
```text
Player A
↓
Uses BossPowers ability
↓
Targets Player B
↓
Player B is inside a protected region
↓
Protection check
↓
If the ability is not allowed:
BLOCK EXECUTION
```
Do not allow BossPowers to damage, teleport, manipulate, trap, freeze, pull, knockback, or otherwise affect protected players when the protection plugin forbids the relevant interaction.
---
# 8. BLOCK-MODIFICATION PROTECTION
Any ability that modifies blocks MUST perform a protection check.
Examples:
- Temporary Obsidian Wall
- Meteor effects
- Any future block-changing ability
- Temporary structures
- Area effects that modify blocks
If the location is protected:
**Do not modify the block.**
Do not temporarily replace the block and restore it later.
Do not use a bypass API unless the protection plugin explicitly requires an official administrative operation and the BossPowers configuration explicitly allows that behavior.
Default behavior:
```yaml
protection:
respect-claims: true
respect-regions: true
allow-protected-block-modification: false
```
---
# 9. WORLDGUARD
If WorldGuard is installed:
BossPowers MUST integrate with WorldGuard properly.
Do not bypass WorldGuard.
Before an ability executes, determine whether the player is permitted to perform the relevant action at the relevant location.
Respect:
- Region membership
- Region flags
- Build protection
- PvP restrictions
- Interaction restrictions
- Entry/exit restrictions where relevant
- Other applicable WorldGuard rules
If the player is not allowed:
```text
&c✦ You are here in a protected region. You cannot use this ability here.
```
The ability must not execute.
WorldGuard integration must use supported WorldGuard APIs.
Never modify WorldGuard regions or flags automatically.
---
# 10. GRIEFPrevention
If GriefPrevention is installed:
BossPowers MUST respect GriefPrevention claims.
Do not bypass:
- Claim ownership
- Build permissions
- Container permissions
- PvP restrictions
- Entity interaction restrictions
- Trust permissions
If the player does not have permission to perform the relevant action inside a claim:
**Block the BossPowers action.**
Display:
```text
&c✦ You are here in a protected land claim. You cannot use this ability here.
```
Use the official GriefPrevention API where available.
Never modify claims to make an ability work.
---
# 11. OTHER LAND-CLAIM PLUGINS
The same rule applies to ANY other protection or claim plugin.
Examples include:
- Residence
- Lands
- Towny
- PlotSquared
- GriefDefender
- Factions claim systems
- Kingdom/territory plugins
- Custom server claim systems
- Any plugin that exposes a protection API
If a compatible provider exists, use it.
If no integration exists:
**Fail safely.**
Never assume that an unrecognized region is unprotected when the plugin may actually be protecting it.
For destructive/block-changing abilities, the safest default should be to deny execution when protection status cannot be determined.
---
# 12. PROTECTION PROVIDER PRIORITY
Create a unified protection API.
Example:
```java
ProtectionResult canUseAbility(
Player player,
Location location,
Ability ability
);
```
Possible result:
```text
ALLOWED
DENIED
UNKNOWN
```
For target-based abilities:
```java
ProtectionResult canAffectEntity(
Player player,
Entity target,
Ability ability
);
```
For block-changing abilities:
```java
ProtectionResult canModifyBlock(
Player player,
Block block,
Ability ability
);
```
BossPowers should never directly contain dozens of WorldGuard/GriefPrevention checks throughout individual abilities.
All protection decisions should go through:
```text
ProtectionManager
```
This keeps the system maintainable and prevents accidental bypasses.
---
# 13. PROTECTION FAILURE BEHAVIOR
If:
```text
ProtectionResult = DENIED
```
then:
1. Do not execute the ability.
2. Do not deal damage.
3. Do not teleport.
4. Do not apply effects.
5. Do not modify blocks.
6. Do not spawn misleading impact effects.
7. Do not start the successful-use cooldown unless configured.
8. Show the configured protection message.
9. Clean up the targeting state if appropriate.
Default:
```yaml
protection:
blocked-use-starts-cooldown: false
```
---
# 14. TARGETING + PROTECTION
Protection checks must work together with the 60-second targeting system.
Example:
```text
RIGHT CLICK
↓
ABILITY 1 ARMED
↓
RING
↓
60 SECOND TARGET WINDOW
↓
PLAYER MOVES INTO PROTECTED REGION
↓
LEFT CLICKS TARGET
↓
FINAL PROTECTION CHECK
↓
BLOCKED
```
The ability must not execute.
If configured:
```yaml
protection:
cancel-targeting-on-block: true
```
then the targeting session should be cancelled.
Otherwise the player may continue selecting another valid target while the original 60-second window remains.
---
# 15. PROTECTION DURING COMBINED ABILITY
Combined abilities MUST also respect all protection systems.
The combined ability must never receive special permission to bypass claims or regions.
For example:
```text
SHIFT + RIGHT CLICK + RIGHT CLICK
↓
COMBINED ABILITY
↓
Protection Check
↓
Allowed → Execute
Denied → Block
```
The fact that an ability is a powerful/combined ability does not give it permission to bypass protection.
---
# 16. COMMAND SECURITY
BossPowers commands must use proper permission checks.
**Normal players MUST NOT be able to use administrative commands.**
Only players with:
```text
bosspowers.admin
```
or the configured administrative permission should be allowed to execute administrative BossPowers commands.
Administrative permissions should default to OP.
---
# 17. PUBLIC COMMANDS
The following commands should remain available to normal players:
```text
/bp help
/bosspowers help
/bp recipes
/bosspowers recipes
```
These commands are explicitly allowed for normal players.
They MUST NOT require administrator permission by default.
---
# 18. ADMIN-ONLY COMMANDS
The following commands MUST require the appropriate permission:
```text
/bp reload
/bp give
/bp giveall
/bp clear
/bp exchange
/bp admin
/bp debug
/bp debug player
/bp info
/bp powers
/bp cooldown
/bp bind
/bp unbind
/bp reset
/bp version
```
At minimum, administrative commands should require:
```text
bosspowers.admin
```
or their dedicated permission.
---
# 19. UNAUTHORIZED COMMAND MESSAGE
If a player without permission attempts to use an administrative command, do NOT execute the command.
Show:
```text
&c✦ You do not have permission to use this command.
```
Configurable:
```yaml
messages:
no-permission: "&c✦ You do not have permission to use this command."
```
Do not reveal administrative information.
Do not execute partial command functionality.
Do not give an item.
Do not open an admin INVENTORY GUI.
Do not expose debug information.
---
# 20. COMMAND SUBCOMMAND SECURITY
Permission checks must happen BEFORE executing subcommand logic.
Example:
```text
/bp give Player VOID
↓
Check permission
↓
NO PERMISSION
↓
Show error
↓
STOP
```
Do not:
```text
Parse command
↓
Create Power
↓
Check permission
```
This could create duplication or unauthorized access.
---
# 21. HELP COMMAND SECURITY
Normal players may use:
```text
/bp help
```
However, the help output should only show commands the sender is actually allowed to use.
For example, a normal player may see:
```text
/bp help
/bp recipes
```
An administrator may additionally see:
```text
/bp reload
/bp give
/bp clear
/bp debug
/bp reset
...
```
Do not advertise inaccessible administrative commands to normal players unless explicitly configured.
---
# 22. RECIPES COMMAND SECURITY
Normal players may use:
```text
/bp recipes
```
This must open the normal recipe INVENTORY GUI.
The recipe INVENTORY GUI must NOT provide administrative functionality.
Normal players cannot:
- Give themselves Powers
- Reset craft counts
- Modify recipes
- Reload configuration
- Open admin INVENTORY GUI
- Modify player data
---
# 23. `/bosspowers` ALIAS
The same permission system must apply to both:
```text
/bp
```
and:
```text
/bosspowers
```
Players must not be able to bypass command permissions by using the alias.
For example:
```text
/bp give
```
and:
```text
/bosspowers give
```
must have identical permission requirements.
---
# 24. COMMAND TAB-COMPLETION SECURITY
Tab completion must also respect permissions.
Normal players should not receive administrative subcommands through tab completion unless explicitly configured.
Example:
Normal player:
```text
/bp
```
should primarily show:
```text
help
recipes
```
Administrator:
```text
/bp
```
may show all permitted administrative subcommands.
Do not leak restricted command names unnecessarily.
---
# 25. ABILITY SYSTEM
Create a dedicated reliable input architecture.
Recommended:
```text
AbilityInputManager
AbilityStateManager
AbilityBindingManager
TargetingManager
CombinationManager
ProtectionManager
```
Supported inputs:
- RIGHT_CLICK
- SHIFT_RIGHT_CLICK
- LEFT_CLICK
- SHIFT_LEFT_CLICK
The system must distinguish:
- Air right click
- Block right click
- Entity right click
- Left click entity
- Shift state
- Main hand
- Offhand
- Duplicate events
Only process the intended hand by default:
`EquipmentSlot.HAND`
Prevent offhand duplicate activation.
---
# 26. CRITICAL ABILITY MECHANIC
This is the most important gameplay mechanic.
## RIGHT CLICK
When a player RIGHT CLICKS their BossPowers Power:
**DO NOT immediately execute the ability.**
Instead:
1. Activate Ability 1.
2. Enter `ARMED_ABILITY_1`.
3. Create an animated ring around the player.
4. Start a 60-second targeting window.
5. Display targeting countdown.
6. Wait for the player to LEFT CLICK a valid entity.
7. Perform the final protection check before execution.
Example:
```text
RIGHT CLICK
↓
ABILITY 1 ARMED
↓
RING APPEARS
↓
TARGET WINDOW: 60s
↓
PLAYER LEFT CLICKS TARGET
↓
PROTECTION CHECK
↓
TARGET SELECTED
↓
RING DISAPPEARS
↓
ABILITY EXECUTES
↓
COOLDOWN STARTS
```
---
# 27. LEFT CLICK TARGETING
While Ability 1 or Ability 2 is armed:
The player MUST select the target using:
**LEFT CLICK / ATTACK**
The ability must NOT activate merely because the player:
- Looks at an entity
- Is near an entity
- Right clicks an entity
- Right clicks the Power while looking at an entity
Only:
**LEFT CLICK ENTITY**
confirms the target.
Supported targets:
- Players
- Hostile mobs
- Passive mobs
- Neutral mobs
according to configuration.
---
# 28. TARGET SELECTION
When the player is targeting and LEFT CLICKS:
- Player
- Zombie
- Skeleton
- Creeper
- Spider
- Enderman
- Any configured mob
the entity becomes the target.
Then:
1. Validate target.
2. Perform protection check.
3. Clear targeting state FIRST.
4. Remove ring.
5. Stop countdown.
6. Remove targeting BossBar.
7. Execute the ability if allowed.
8. Apply damage/effects.
9. Play sound.
10. Spawn particles.
11. Start cooldown.
Clearing the targeting state BEFORE execution is mandatory to prevent duplicate activation.
---
# 29. NORMAL ATTACK PROTECTION
While targeting:
`LEFT CLICK ENTITY`
should be interpreted as:
**Target Selection**
rather than normal combat where configured.
Add:
```yaml
targeting:
consume-attack: true
```
If enabled:
Normal weapon damage should not accidentally interfere with the targeting system.
Prevent:
- Double damage
- Double ability activation
- Double target selection
- Double cooldown
- Duplicate particles
---
# 30. ABILITY 2 — SHIFT + RIGHT CLICK
When:
**SHIFT + RIGHT CLICK**
is performed:
Do NOT immediately execute Ability 2.
Instead:
1. Activate Ability 2.
2. Enter `ARMED_ABILITY_2`.
3. Create the same ring system.
4. Start another 60-second targeting window.
5. Show countdown.
6. Player LEFT CLICKS a valid entity.
7. Perform final protection check.
8. Ring disappears.
9. Ability 2 executes on that target if permitted.
10. Cooldown starts.
---
# 31. TARGETING RING
When Ability 1 or Ability 2 becomes armed:
Create an animated ring around the player.
The ring must:
- Follow the player
- Rotate
- Animate
- Be visible to nearby players
- Have configurable radius
- Have configurable height
- Have configurable particle
- Have configurable animation speed
When target is selected:
**THE RING MUST DISAPPEAR IMMEDIATELY.**
No ghost particles.
No stuck ring.
No permanent scheduler.
---
# 32. TARGETING TIMER
Default targeting duration:
**60 seconds**
This is NOT the ability cooldown.
Display through ActionBar:
```text
✦ TARGET WINDOW: 60s
```
Update once per second.
Optional BossBar:
```text
VOID TARGET | 47s
```
---
# 33. TARGETING TIMEOUT
If the player fails to LEFT CLICK a valid target within 60 seconds:
1. Cancel targeting.
2. Remove ring.
3. Remove targeting BossBar.
4. Stop countdown.
5. Play failure sound.
6. Show:
```text
&c✦ Targeting failed!
```
7. Start a default:
**70-second cooldown**
---
# 34. COOLDOWN SYSTEM
Every ability has an independent cooldown.
Example:
```text
Ability 1: 45 seconds
Ability 2: 60 seconds
Combined: 180 seconds
Timeout: 70 seconds
```
All values must be configurable per Power.
Use timestamp-based cooldowns.
Store:
```text
cooldownEndTimestamp
```
Calculate remaining time from timestamps.
---
# 35. TARGETING TIMER AND COOLDOWN ARE SEPARATE
These systems MUST NEVER overwrite each other.
Example:
```text
RIGHT CLICK
↓
TARGETING: 60s
↓
LEFT CLICK TARGET
↓
ABILITY EXECUTES
↓
COOLDOWN: 45s
```
If timeout:
```text
TARGETING: 60s
↓
0s
↓
TARGETING FAILED
↓
COOLDOWN: 70s
```
---
# 36. ONLY ONE TARGETING SESSION
A player can have only one active targeting session.
Possible states:
```text
IDLE
ARMED_ABILITY_1
ARMED_ABILITY_2
COMBINATION_DETECTION
EXECUTING
COOLDOWN
```
If the player activates another ability while targeting:
1. Cancel previous targeting.
2. Remove ring.
3. Remove BossBar.
4. Stop countdown.
5. Start the new state.
No player should ever be stuck in an invalid state.
---
# 37. COMBINED ABILITY
The combined ability is separate from Ability 1 and Ability 2.
Required input:
**SHIFT + RIGHT CLICK + RIGHT CLICK**
This should activate:
**COMBINED ABILITY**
The combined ability must be significantly more powerful.
It should have:
- Higher damage
- Stronger effects
- Larger area
- Better particles
- Unique sound
- Special animation
- Longer cooldown
The combined ability must NOT accidentally trigger:
- Ability 1
- Ability 2
It must still perform all applicable protection checks.
---
# 38. COMBINATION DETECTION
Create a dedicated:
`CombinationManager`
Track:
- Player UUID
- First click timestamp
- Second click timestamp
- Shift state
- Current Power
- Current ability state
- Cooldown state
Config:
```yaml
combination:
enabled: true
input-window-ms: 500
```
---
# 39. COMBINATION PRIORITY
Input priority MUST be:
1. Combined Ability
2. Shift + Right Click Ability
3. Right Click Ability
If the combination is detected:
**DO NOT execute Ability 1.**
**DO NOT execute Ability 2.**
Only execute:
**Combined Ability.**
---
# 40. DUPLICATE EVENT PROTECTION
Minecraft can generate multiple interaction events.
Prevent:
- Main hand + offhand duplicate
- Double right-click
- Double ability execution
- Double damage
- Double cooldown
- Double particles
Implement configurable debounce:
```yaml
input:
debounce-ms: 350
```
---
# 41. EIGHT UNIQUE POWER DESIGNS
## VOID
Passive:
Void Walker
Ability 1:
Void Rift
Ability 2:
Void Prison
Combined:
Event Horizon
---
## STORM
Passive:
Storm Charge
Ability 1:
Lightning Mark
Ability 2:
Storm Zone
Combined:
Storm Judgment
---
## GRAVITY
Passive:
Knockback Resistance
Ability 1:
Gravity Crush
Ability 2:
Gravity Launch
Combined:
Singularity
---
## TIME
Passive:
Temporal Advantage
Ability 1:
Time Mark
Ability 2:
Time Slow
Combined:
Time Collapse
---
## BLOOD
Passive:
Blood Drain
Ability 1:
Blood Mark
Ability 2:
Blood Burst
Combined:
Blood Eclipse
---
## PHANTOM
Passive:
Phantom Step
Ability 1:
Phantom Dash
Ability 2:
Shadow Clone
Combined:
Phantom Realm
---
## CHAOS
Passive:
Chaos Chance
Ability 1:
Chaos Curse
Ability 2:
Randomized Blast
Combined:
Chaos Event
---
## TITAN
Passive:
Titan Strength
Ability 1:
Titan Smash
Ability 2:
Titan Charge
Combined:
Titan's Wrath
---
# 42. ADDITIONAL SPECIAL ABILITIES
Distribute these across the 8 Powers.
Required mechanics:
- Blindness
- Teleportation
- Meteor Shower
- Temporary Obsidian Wall
- Pull
- Knockback
- Slow
- Freeze
- Area Damage
- Life Steal
- Dash
- Gravity
- Time Manipulation
- Clone
- Shield
- Curse
All such abilities must respect protection systems.
---
# 43. METEOR SHOWER
Meteor Shower MUST NOT destroy terrain.
It MUST NOT:
- Break blocks
- Damage blocks
- Modify terrain
- Destroy structures
It ONLY:
- Creates visual meteors
- Creates particles
- Plays impact sounds
- Damages players/mobs where permitted
- Applies configurable knockback
- Optionally applies fire
Default:
```yaml
meteor:
block-damage: false
block-break: false
terrain-modification: false
```
All entity effects remain subject to protection checks.
---
# 44. TEMPORARY OBSIDIAN WALL
At least one Power should have an Obsidian Wall ability.
The wall:
- Uses Obsidian
- Lasts 15 seconds
- Blocks movement
- Temporarily changes blocks
- Restores the exact original blocks afterward
Before changing each block:
**Check protection permissions for that exact location.**
If the player is not allowed to modify the location:
**Do not place the block there.**
Never use the wall ability to bypass claims or regions.
---
# 45. POWER CRAFTING
Every Power can only be crafted:
**2 TIMES TOTAL**
This is a GLOBAL limit.
Each Power has an independent global count.
---
# 46. POWER CRAFTING EVENT
Crafting a Power starts a:
**5-minute / 300-second Power Forging Event.**
The Power is not given immediately.
Store:
- World
- X
- Y
- Z
- Crafter UUID
- Power ID
- Start timestamp
- End timestamp
- Event state
All crafting event behavior must respect server protection settings.
---
# 47. CRAFTING EVENT PROTECTION
If the forging event creates particles, effects or temporary blocks, these effects must not bypass protected regions.
The event location may be inside a claim/region, but any actual block/entity interaction must be checked against the protection system.
Never use the forging event as a reason to bypass protection.
---
# 48. COMMANDS
Main command:
`/bp`
Alias:
`/bosspowers`
Public commands:
```text
/bp help
/bp recipes
```
Administrative commands:
```text
/bp reload
/bp give
/bp exchange
/bp clear
/bp info
/bp powers
/bp cooldown
/bp admin
/bp version
/bp debug
/bp debug player
/bp bind
/bp unbind
/bp giveall
/bp reset
```
All administrative commands require proper permissions.
---
# 49. PERMISSIONS
Create:
```text
bosspowers.admin
bosspowers.use
bosspowers.give
bosspowers.reload
bosspowers.recipes
bosspowers.exchange
bosspowers.clear
bosspowers.debug
```
Important:
Normal players may use:
```text
bosspowers.help
bosspowers.recipes
```
without administrator permission.
Administrative permissions default to OP.
---
# 50. COMMAND PERMISSION FAILURE
If a player without permission attempts an administrative command:
Show:
```text
&c✦ You do not have permission to use this command.
```
Then immediately stop command execution.
Do not:
- Give Power items
- Modify data
- Reset data
- Open admin interfaces
- Execute partial functionality
- Reveal debug information
---
# 51. HELP COMMAND
`/bp help` is public.
Show only commands available to the sender.
Normal player:
```text
/bp help
/bp recipes
```
Admin:
All commands for which they have permission.
---
# 52. RECIPES COMMAND
`/bp recipes` is public.
It opens the recipe INVENTORY GUI.
It must never allow normal players to:
- Give Powers
- Reset craft limits
- Reload plugin
- Modify configuration
- Access admin functions
---
# 53. WORLDGUARD / CLAIM SECURITY SUMMARY
This requirement has the highest priority alongside ability reliability.
**BossPowers MUST NEVER BYPASS LAND CLAIMS OR REGION PROTECTION.**
The plugin must respect:
```text
WorldGuard
GriefPrevention
Residence
Lands
Towny
PlotSquared
GriefDefender
Factions claim systems
Other claim/region plugins
```
If a player attempts to use an ability where it is prohibited:
```text
&c✦ You are here in a protected region. You cannot use this ability here.
```
If a target is protected from the relevant action:
```text
&c✦ This target is protected here. You cannot use this ability on them.
```
If the player attempts to use a BossPowers administrative command without permission:
```text
&c✦ You do not have permission to use this command.
```
**Only OP/admin users with the appropriate permission may use administrative BossPowers commands.**
The only explicitly public command functions are:
```text
/bp help
/bosspowers help
/bp recipes
/bosspowers recipes
```
No ability, combined ability, crafting event, command, INVENTORY GUI, teleport, damage effect, block modification, or special mechanic may be implemented in a way that circumvents the server's protection systems.
---
# 54. ADMIN DEBUG
`/bp debug`
Display:
- Plugin version
- Minecraft version
- Server platform
- Power system
- Active ability count
- Active targeting sessions
- Cooldown count
- Crafting events
- Storage status
- WorldGuard status
- Detected protection providers
- Protection-provider status
`/bp debug player `
Display:
- Power
- Current state
- Active ability
- Target
- Targeting timer
- Cooldowns
- Crafting state
- Current protection status where relevant
---
# 55. RELOAD
`/bp reload`
requires administrative permission.
It must safely reload:
- config
- powers
- recipes
- messages
- INVENTORY GUI
- cooldown settings
- world settings
- protection settings
Do NOT use Bukkit `/reload`.
Do not corrupt active crafting events.
---
# 56. ABILITY STATE ARCHITECTURE
The ability system MUST use explicit states:
```text
IDLE
ARMED_ABILITY_1
ARMED_ABILITY_2
COMBINATION_DETECTION
EXECUTING
COOLDOWN
```
A player must always have a known state.
No player may remain permanently stuck in:
- targeting
- combination detection
- cooldown
- executing
---
# 57. ACTIVATION ID
Every ability execution must generate a unique activation ID.
Example:
```text
UUID activationId
```
Use this to prevent:
- Double execution
- Duplicate damage
- Duplicate particles
- Duplicate cooldown
- Duplicate target selection
One successful click must produce exactly one ability execution.
---
# 58. BLISS JAR REFERENCE
The uploaded BlissGems JAR was provided only as a conceptual reference.
It may be inspected to understand general concepts such as:
- AbilityBindingManager
- AbilitySlot
- RIGHT_CLICK
- SHIFT_RIGHT_CLICK
- LEFT_CLICK
- SHIFT_LEFT_CLICK
- AbilityManager
- ClickActivationManager
However:
**DO NOT copy, decompile or reproduce BlissGems code.**
BossPowers must use its own implementation.
Recommended BossPowers mapping:
```text
RIGHT_CLICK
→ SLOT_1
→ ARM TARGETING
→ LEFT CLICK ENTITY
→ PROTECTION CHECK
→ EXECUTE
SHIFT_RIGHT_CLICK
→ SLOT_2
→ ARM TARGETING
→ LEFT CLICK ENTITY
→ PROTECTION CHECK
→ EXECUTE
SHIFT + RIGHT_CLICK + RIGHT_CLICK
→ COMBINED ABILITY
→ PROTECTION CHECK
→ EXECUTE
```
---
# 59. BUILD SYSTEM
Create a complete buildable Java project.
Use Maven or Gradle.
Include:
```text
pom.xml / build.gradle
src/main/java/
src/main/resources/
plugin.yml
config files
README.md
```
The final build must produce:
```text
BossPowers.jar
```
Do not leave:
- Pseudocode
- TODO core systems
- Empty methods
- Fake implementations
- Non-functional commands
---
# 60. TESTING REQUIREMENTS
Before declaring the plugin complete, test:
## Ability 1
```text
RIGHT CLICK
↓
Ring
↓
60-second countdown
↓
LEFT CLICK player
↓
Protection check
↓
Ring disappears
↓
Ability executes if permitted
↓
Cooldown
```
## Ability 2
```text
SHIFT + RIGHT CLICK
↓
Ring
↓
60-second countdown
↓
LEFT CLICK mob
↓
Protection check
↓
Ring disappears
↓
Ability executes if permitted
↓
Cooldown
```
## Protected Region
```text
Player enters protected region
↓
Attempts ability
↓
Protection check
↓
Ability blocked
↓
Protection message
↓
No damage
↓
No teleport
↓
No block modification
```
## Protected Claim
```text
Player enters another player's land claim
↓
Attempts BossPowers ability
↓
Claim permission check
↓
Ability blocked if prohibited
↓
No claim bypass
```
## Unauthorized Command
```text
Normal player
↓
/bp give Player VOID
↓
Permission check
↓
No permission
↓
Error message
↓
Nothing happens
```
## Public Commands
```text
Normal player
↓
/bp help
↓
Works
```
```text
Normal player
↓
/bp recipes
↓
Works
```
## Timeout
```text
RIGHT CLICK
↓
Ring
↓
60 seconds
↓
No target
↓
Ring disappears
↓
70-second cooldown
```
## Combined
```text
SHIFT + RIGHT CLICK + RIGHT CLICK
↓
Protection Check
↓
Combined Ability ONLY
```
Verify:
- Ability 1 does NOT activate
- Ability 2 does NOT activate
- Combined cooldown starts
## Crafting
```text
Recipe
↓
Craft
↓
Global count
↓
5-minute event
↓
BossBar
↓
Coordinates
↓
Survive
↓
Power drops
↓
Player picks it up
```
## Third Craft
```text
Power = 2/2
↓
Craft denied
```
## Restart
```text
Active crafting event
↓
Server restart
↓
Event restored
↓
Correct remaining time
```
## INVENTORY GUI
Verify:
- Black glass background
- Power buttons
- Recipe pages
- No item stealing
- No duplication
- Correct craft count
---
# 61. FINAL QUALITY REQUIREMENT
This plugin must feel like a polished premium SMP plugin.
Prioritize:
- Reliable input detection
- Smooth targeting
- Beautiful rings
- Clear countdowns
- Separate cooldown timers
- Powerful combined abilities
- Unique Powers
- Hard progression
- High-risk crafting events
- Good INVENTORY GUI
- Strong exploit protection
- Performance
- Configuration
- Error handling
- Persistent data safety
- **Strict WorldGuard compatibility**
- **Strict land-claim compatibility**
- **Strict command permission enforcement**
MOST IMPORTANT:
Do not simply patch individual event handlers.
Build/refactor the ability system into a proper state-based architecture.
The final result must reliably perform:
```text
RIGHT CLICK
→ ARM
→ RING
→ 60 SEC
→ LEFT CLICK TARGET
→ PROTECTION CHECK
→ EXECUTE
→ COOLDOWN
```
and:
```text
SHIFT + RIGHT CLICK
→ ARM
→ RING
→ 60 SEC
→ LEFT CLICK TARGET
→ PROTECTION CHECK
→ EXECUTE
→ COOLDOWN
```
and:
```text
SHIFT + RIGHT CLICK + RIGHT CLICK
→ COMBINED POWER
→ PROTECTION CHECK
→ HIGHER POWER
→ COMBINED COOLDOWN
```
and:
```text
/bp give
→ PERMISSION CHECK
→ ADMIN ONLY
```
while:
```text
/bp help
/bp recipes
→ PUBLIC
```
Compile and test the entire project.
Fix ALL compilation errors.
Fix ALL runtime errors.
Fix ALL duplicate activation issues.
Fix ALL targeting-state issues.
Fix ALL ring cleanup issues.
Fix ALL cooldown/countdown issues.
Fix ALL crafting duplication issues.
Fix ALL command permission issues.
Fix ALL WorldGuard integration issues.
Fix ALL land-claim integration issues.
Verify that BossPowers **never bypasses WorldGuard, GriefPrevention, or any other installed claim/region protection system**.
Do not claim completion until the final project successfully compiles and the core mechanics, permissions, protection checks, and claim/region compatibility have been tested.
Create the Gradle/Paper project and plugin metadata.
Implement the stateful input, targeting, cooldown, combination, protection, and crafting foundations.
Add the secure command and recipe-GUI surfaces with configurable messages and gameplay settings.
Implementing the activation state machine, claim-safe protection gateway, and persistent forging workflow.
Adding secure commands, crafting limits, recipe browsing, and the concrete ability effects.
Completing the permission-filtered command interface and non-administrative recipe menu.
Created the BossPowers Gradle project with:
Stateful right-click/sneak targeting, timeout cooldowns, duplicate-input protection, and combined abilities.
Eight original Power definitions and persistent forged-count/event storage.
Claim-safe protection gateway with reflective WorldGuard support and fail-safe denial for detected unsupported claim plugins.
Permission-filtered
/bpand/bosspowerscommands, secure tab completion, and public recipe GUI.Configurable gameplay, targeting, protection, cooldown, crafting, and message resources.
Integration testing has not been run in this environment.
package io.kodari.bosspowers;
import io.kodari.bosspowers.ability.AbilityInputListener;
import io.kodari.bosspowers.ability.AbilityManager;
import io.kodari.bosspowers.ability.CombinationManager;
import io.kodari.bosspowers.ability.CooldownManager;
import io.kodari.bosspowers.ability.TargetingManager;
import io.kodari.bosspowers.command.BossPowersCommand;
import io.kodari.bosspowers.compat.PlatformAdapter;
import io.kodari.bosspowers.crafting.CraftingManager;
import io.kodari.bosspowers.gui.RecipeGuiListener;
import io.kodari.bosspowers.power.PowerItemFactory;
import io.kodari.bosspowers.protection.ProtectionManager;
import io.kodari.bosspowers.util.Messages;
import lombok.Getter;
import org.bukkit.command.PluginCommand;
import org.bukkit.plugin.java.JavaPlugin;
@Getter
public final class BossPowersPlugin extends JavaPlugin {
private PlatformAdapter platformAdapter;
private Messages messages;
private ProtectionManager protectionManager;
private CooldownManager cooldownManager;
private CombinationManager combinationManager;
private TargetingManager targetingManager;
private AbilityManager abilityManager;
private CraftingManager craftingManager;
private PowerItemFactory powerItemFactory;
@Override
public void onEnable() {
saveDefaultConfig();
saveResource("messages.yml", false);
this.platformAdapter = PlatformAdapter.create(this);
this.messages = new Messages(this);
this.powerItemFactory = new PowerItemFactory(this);
this.protectionManager = new ProtectionManager(this);
this.cooldownManager = new CooldownManager();
this.combinationManager = new CombinationManager(this);
this.targetingManager = new TargetingManager(this);
this.abilityManager = new AbilityManager(this);
this.craftingManager = new CraftingManager(this);
getServer().getPluginManager().registerEvents(new AbilityInputListener(this), this);
getServer().getPluginManager().registerEvents(new RecipeGuiListener(this), this);
getServer().getPluginManager().registerEvents(craftingManager, this);
PluginCommand command = getCommand("bp");
if (command != null) {
BossPowersCommand executor = new BossPowersCommand(this);
command.setExecutor(executor);
command.setTabCompleter(executor);
}
targetingManager.start();
craftingManager.start();
}
@Override
public void onDisable() {
if (targetingManager != null) targetingManager.shutdown();
if (craftingManager != null) craftingManager.shutdown();
if (platformAdapter != null) platformAdapter.cancelAll();
}
public void reloadPluginConfiguration() {
reloadConfig();
messages.reload();
protectionManager.reload();
}
}