make this a minecraft plugin for 1.2.111 working for both java 21 and 25
--- 📎 Attached 1 file(s):
File: pasted-code-1792288559504.txt
# SHARD SMP — COMPLETE MASTER DEVELOPMENT PROMPT
## 1. PROJECT OVERVIEW
You are a senior Minecraft Java plugin developer, combat-system designer, and visual-effects engineer.
Develop a complete, production-quality Minecraft SMP plugin named **Shard SMP**. The plugin introduces elemental pottery shards that grant players unique abilities and powerful ultimates.
This must be a fully functional plugin, not a prototype, demonstration, or collection of pseudocode.
### Mandatory technical requirements
- **Minecraft version:** Java Edition 1.21.11.
- **Java compatibility:** Must compile and run on both Java 21 and Java 25.
- **Server platform:** Paper for Minecraft 1.21.11.
- **Language:** Java.
- **Build system:** Maven.
- **Plugin name:** ShardSMP.
- **Main package:** `com.shardsmp`.
- **Plugin entry point:** `com.shardsmp.ShardSMP`.
- **Primary configuration:** `config.yml`.
- **Plugin descriptor:** `plugin.yml`.
- **Resource pack:** Support custom pottery shard models and textures.
- **Combat:** PvP-focused, with functional damage, knockback, targeting, cooldowns, and visual effects.
Use the correct Paper API for Minecraft 1.21.11. Verify all API methods, entity types, materials, and event signatures against the target version. Do not copy outdated methods from earlier Minecraft versions.
The plugin must support Java 21 and Java 25 without requiring separate source-code implementations. Compile against Java 21 bytecode unless a verified platform requirement makes another target necessary. Test runtime compatibility on both Java versions.
Do not claim successful compilation or testing unless it has actually been performed.
---
## 2. CORE DEVELOPMENT RULES
Follow these rules throughout the entire project.
1. Implement every specified ability and ultimate.
2. Do not replace actual custom-model shard items with generic particles, snowballs, ordinary projectiles, or placeholder models.
3. Do not invent unrelated abilities or replace the specified mechanics with generic abilities.
4. Do not create unnecessary GUI menus.
5. Do not use a block-built roulette.
6. Do not build a physical roulette wheel.
7. Do not create a roulette consisting of GUI icons or a scrolling inventory strip.
8. Do not leave abilities partially implemented.
9. Do not use fake damage that only plays an animation without affecting valid targets.
10. Do not use real lightning or explosions in a way that unintentionally destroys the world.
11. Do not allow an ability's visual effect to disagree with its actual hit detection.
12. Keep all damage values, cooldowns, durations, ranges, and other balance values configurable.
13. Every ability must have real server-side mechanics, appropriate visual effects, sound effects, and reliable cleanup.
14. All ability effects must work with actual players and supported mannequin targets.
15. Do not make the entire plugin depend on a resource pack being installed. The plugin must remain operational without it, although custom models require the appropriate resource pack.
Prioritize functional mechanics and visual quality equally.
---
# 3. THE SHARDS
The initial version contains four shard types:
1. Air Shard
2. Flame Shard
3. Frost Shard
4. Gravity Shard
**Gravity Shard is reserved for a future update.**
Do not invent, implement, or finalize Gravity Shard abilities in this release. The plugin may recognize Gravity as a reserved shard identifier for the roulette and future compatibility, but players must not receive unfinished Gravity abilities.
All four shard types must be eligible for the initial roulette unless an administrator disables a shard through configuration. If Gravity is selected, award the Gravity Shard item, but do not provide nonexistent abilities. Make the disabled ability status clear in `/shardsmp info`.
Each implemented shard has exactly:
- Ability 1
- Ability 2
- Ultimate
Every shard item must use a pottery shard item base, with a unique custom model, display name, lore, and persistent internal identifier.
Use custom item model assets or the correct item-model override mechanism for Minecraft 1.21.11. Do not rely on display names alone to identify shard items.
Recommended item names:
- `Air Shard`
- `Flame Shard`
- `Frost Shard`
- `Gravity Shard`
Give each shard a distinctive visual identity through its texture, colors, particles, sounds, and animations.
---
# 4. SHARD ITEM CONTROLS
Implement the following controls consistently across all shards.
### Ability 1
The player holds their assigned shard in their main hand and presses the F/offhand-swap key.
- Activate Ability 1.
- Cancel the normal offhand swap when the input is being used for the ability.
- Do not consume or replace the shard.
- Apply its individual cooldown.
- Provide clear action-bar feedback.
### Ability 2
The player holds their assigned shard in their main hand and presses Shift + F.
- Activate Ability 2.
- Distinguish this input from Ability 1 reliably.
- Cancel the normal offhand swap.
- Apply the separate Ability 2 cooldown.
- Prevent accidental activation of both abilities from one input.
If Minecraft's client/server input limitations make exact Shift + F detection unreliable, implement and document a reliable, tested alternative rather than silently claiming unsupported behavior.
### Ultimate
The player equips their assigned shard in the offhand and right-clicks.
- Activate the shard's ultimate.
- Prevent unintended item use.
- Apply the ultimate cooldown.
- Display a clear activation message and cooldown feedback.
Use server-side validation for every activation.
### Input handling requirements
- Prevent duplicate activations from overlapping events.
- Do not allow activation while the player is dead, offline, or otherwise unable to act.
- Prevent invalid shard items from activating abilities.
- Check that the player owns or is authorized to use the relevant shard.
- Handle inventory changes safely.
- Handle cooldowns independently for each ability.
- Prevent ability spam from event duplication.
- Keep controls consistent between all shards.
---
# 5. SHARD SELECTION SYSTEM
## 5.1 Starting the SMP
An administrator runs:
`/shardsmp start`
The plugin must:
1. Verify that the command sender has the required permission.
2. Prevent multiple selection sequences from running simultaneously.
3. Announce the start of Shard SMP to all online players.
4. Identify the eligible players who will participate.
5. Start the pottery-shard roulette for each eligible player.
6. Assign the final result only after the selection animation finishes.
7. Save the resulting assignments.
Use a stylized announcement similar to:
`# SHARDSMP`
`The Shard SMP has been started by an admin!`
Use configurable message formatting and suitable sound effects.
## 5.2 The roulette — critical visual requirement
**THE ROULETTE MUST CONSIST ENTIRELY OF POTTERY SHARD ITEMS.**
There must be:
- No blocks.
- No block-built wheel.
- No physical wheel model.
- No GUI roulette.
- No scrolling inventory strip.
- No numbered wheel segments.
- No unrelated decorative objects forming the roulette.
The actual custom-textured pottery shard items themselves form the circular roulette.
### Construction
Create a circular arrangement of multiple floating shard item models around a central point.
Use Minecraft display entities, item displays, or another suitable implementation to render the actual custom-model pottery shard items.
Arrange the items evenly around the circumference. Each item occupies a position on the circle, with its orientation adjusted to create an attractive, readable 3D arrangement.
The roulette must visually read as a ring of individual pottery shards, not as an invisible wheel covered with decorative objects.
The four shard types should be represented by their actual models:
- Air
- Flame
- Frost
- Gravity
The models must retain their distinctive textures during the animation.
### Spinning animation
The roulette rotates as a complete circular arrangement.
- Every shard travels around the center with the rotating arrangement.
- Each shard maintains its relative position in the ring.
- The ring rotates smoothly around its central axis.
- The rotation accelerates at the beginning.
- The rotation reaches a high speed.
- The rotation gradually decelerates.
- The selected shard becomes clearly identifiable when the roulette stops.
Do not make the player spin around the roulette. Do not make the shards orbit the player's body independently as the primary roulette animation. The circular roulette arrangement itself rotates.
### Five selection rounds
The roulette must have exactly five rounds.
Each round must be a distinct, visible spin and selection sequence. Do not confuse the five rounds with five individual shard icons or five particle bursts.
The animation must provide:
1. An initial gathering and reveal of the shard ring.
2. A first spin and selection.
3. A second spin and selection.
4. A third spin and selection.
5. A fourth spin and selection.
6. A final, more dramatic fifth spin and selection.
The initial presentation and five selection rounds are separate stages.
The final round must have the strongest deceleration and clearest winning-shard reveal.
### Winner determination
The server must determine the result authoritatively.
- Determine the final selected shard using server-side logic.
- Synchronize the visual animation with that result.
- Ensure the displayed winner always matches the awarded shard.
- Never let a client-side animation independently determine the reward.
- Do not award multiple shards accidentally.
- Do not accidentally assign a different shard because of animation timing.
If a selection is displayed during each round, the displayed result must be based on the corresponding server-side selection.
### Final reveal
When the final round ends:
1. Stop the roulette smoothly.
2. Highlight the winning pottery shard.
3. Display its name prominently.
4. Play a distinctive reveal sound.
5. Play suitable shard-colored visual effects.
6. Give the player the corresponding shard item.
7. Save the assignment.
8. Clean up all temporary roulette entities and tasks.
Do not award the shard before the selection is finalized.
### Multiple players
Each eligible player must receive their own properly synchronized selection animation and result.
Animations must not interfere with one another. One player's selection must not change another player's result.
Handle players joining or disconnecting during the selection sequence safely. A disconnected player must not leave behind entities or repeating tasks.
Persist the selection state so an unexpected interruption cannot cause duplicate awards.
---
# 6. TARGETS, MANNEQUINS, AND TESTING
This requirement applies to **every ability and every ultimate**.
## 6.1 Supported target types
Every ability must support valid combat targets that include:
- Real Minecraft players.
- Supported Minecraft mannequin entities.
- Armor-stand-based combat dummies, when configured as mannequin substitutes.
- Other explicitly supported NPC mannequin implementations, when their APIs are available.
For Minecraft 1.21.11, verify whether the intended mannequin is a native entity, a plugin-provided NPC, or an armor stand. Do not assume that every mannequin implementation uses the same entity type.
Use a centralized target-validation system that can recognize supported mannequin implementations without accidentally treating every decorative armor stand as a combat target.
Provide configurable mannequin support.
## 6.2 Every ability must affect mannequins
Mannequins must be valid targets for all of the following:
- Direct projectiles.
- Dash collision attacks.
- Knockback and launch effects.
- Fire damage and burning effects.
- Slow effects.
- Lightning damage.
- Tornado pulling and spinning.
- Ice projectile damage.
- Ice spikes.
- Freezing waves.
- Meteor targeting and impacts.
- Area-of-effect damage.
- Any future ability registered with the plugin.
Do not merely spawn particles around a mannequin. The mannequin must receive the actual applicable combat effect.
Where an entity does not support a vanilla player effect, implement the closest appropriate equivalent through the target adapter. For example, use controlled movement for knockback, timed state tracking for slowing, and plugin-managed damage for targets that lack a standard living-entity health system.
If a mannequin cannot support a specific effect due to its underlying implementation, document that limitation and implement the closest functional equivalent.
## 6.3 Player-targeting abilities
Every ability that selects, follows, tracks, pulls, or damages targets must use a common target-selection system.
A target may be a real player or a supported mannequin.
Examples:
- Stormcall must be able to target real players and mannequins.
- Tempest must pull real players and mannequins into the tornado.
- Armageddon must select real players and mannequins as meteor targets.
- Frost Barrage must damage and slow real players and mannequins.
- Glacial Spear must hit both target types.
- Absolute Zero must affect both target types.
- All Flame Shard attacks must affect both target types.
For effects that specifically follow targets, the target-selection algorithm must not silently ignore mannequins.
However, abilities must never select arbitrary noncombat armor stands, dropped items, item displays, particles, or other decorative entities as combat targets.
## 6.4 Ability caster requirements
Separate the ability's caster from its targets.
- A real player activates abilities using the normal shard controls.
- A supported mannequin may be used as a target and, where required, as an explicitly configured ability caster for testing.
- A mannequin must never be mistaken for a real player when the mechanic genuinely requires a real player account, inventory, client input, or player-specific state.
- Player-only requirements must be checked explicitly rather than inferred from an entity's name or appearance.
Provide an optional administrator-only testing mechanism that allows abilities to be tested against mannequins without weakening normal PvP permissions.
---
# 7. AIR SHARD
The Air Shard specializes in aerial movement, target displacement, lightning, and tornado control.
## ABILITY 1 — CLOUDBURST
### Activation
The player presses F while holding the Air Shard in their main hand.
### Mechanics
1. Play a short activation animation.
2. Create a convincing cloud effect around the player's starting position.
3. Dash diagonally upward and forward in the direction the player is facing.
4. The dash must have both forward movement and upward movement.
5. Detect collisions against valid players and mannequins during the dash.
6. When a valid target is hit, launch it upward.
7. Spawn a cloud trail underneath the target's legs while the target rises.
8. Apply the configured damage and knockback.
9. End the dash safely and restore normal movement.
### Visual requirements
- Smooth diagonal dash.
- Visible cloud formation and trail.
- Clear target-hit effect.
- A cloud effect below the launched target.
- Appropriate wind and impact sounds.
Do not implement this as a plain horizontal dash or a simple particle burst.
## ABILITY 2 — STORMCALL
### Activation
The player presses Shift + F while holding the Air Shard.
### Mechanics
1. Acquire valid targets within the configured range.
2. Spawn two realistic-looking clouds.
3. Have the clouds follow valid player and mannequin targets.
4. Move the clouds smoothly rather than teleporting them visibly.
5. The clouds periodically pause for three seconds.
6. After the pause, they resume tracking.
7. Lightning strikes only when the target is directly beneath the corresponding cloud.
8. Apply configured damage, knockback, and visual effects.
### Vertical alignment
The cloud must be vertically aligned with the intended target when the lightning strikes.
Use actual horizontal-distance checks and vertical positioning. Do not strike an unrelated entity merely because it is nearby.
### Visual requirements
- Actual-looking cloud formations.
- Smooth cloud movement.
- Visible pauses during tracking.
- Lightning effects synchronized with the strike.
- Clear impact feedback.
Lightning must not permanently ignite or destroy the surrounding environment. Use controlled lightning visuals and plugin-managed damage where necessary.
## ULTIMATE — TEMPEST
### Activation
The player equips the Air Shard in the offhand and right-clicks.
### Duration
10 seconds by default.
### Mechanics
1. Spawn a tornado with an appearing animation.
2. Make the tornado look like a coherent, rotating column of wind.
3. The tornado actively tracks valid player and mannequin targets.
4. Targets within three blocks of the tornado are pulled inward.
5. Captured targets spiral around the tornado.
6. Deal two damage points, ignoring armor, per configured damage interval.
7. Continue pulling and spinning targets while the ultimate is active.
8. After ten seconds, play a disappearing animation.
9. Fling captured targets outward with configurable knockback.
10. Release all captured targets and remove the tornado cleanly.
### Important requirements
- The tornado must move toward targets.
- The tornado must not simply remain stationary while particles spin around it.
- Targets must physically move according to the tornado mechanics.
- Mannequins must receive equivalent pulling, spinning, damage, and launch behavior.
- Do not permanently trap targets.
- Do not cause uncontrolled fall damage unless explicitly configured.
The two damage points are the default damage per tick interval, not damage on every server tick. Make the interval configurable.
---
# 8. FLAME SHARD
The Flame Shard specializes in explosive fire attacks, burning effects, and volcanic destruction.
## ABILITY 1 — INFERNO BURST
### Activation
The player presses F while holding the Flame Shard.
### Mechanics
1. Play a fire-charging animation.
2. Create a visually convincing fire projectile.
3. Launch the projectile toward the player's aim direction.
4. Detect collisions with valid players and mannequins.
5. On impact, apply the configured fire damage and burning effect.
6. Launch the target upward.
7. Play a separate fire animation during the upward launch.
8. Apply configurable knockback and impact effects.
### Visual requirements
- Fire projectile with a visible travel path.
- Animated launch.
- Strong impact effect.
- Fire trail and upward-launch animation.
- Suitable fire and impact sounds.
Do not simply throw a vanilla fire charge with no custom animation.
Use plugin-managed fire effects where necessary so the ability does not unintentionally ignite buildings or terrain.
## ABILITY 2 — MAGMA RIFT
This is the proposed second Flame Shard ability.
Implement it as a temporary volcanic fissure that erupts beneath enemies.
### Mechanics
1. The player activates the ability.
2. A crack of glowing magma forms along the ground in the selected direction.
3. The fissure advances in a controlled sequence.
4. Magma eruptions emerge from the fissure at intervals.
5. Valid players and mannequins within the eruption area receive configured damage and knockback.
6. Targets are launched slightly upward when struck by an eruption.
7. The fissure fades away after its duration.
### Visual requirements
- Glowing magma cracks.
- Sequential eruptions.
- Volcanic smoke and heat effects.
- Distinctive eruption sounds.
- A clear indication of where eruptions will occur.
Do not create permanent terrain damage. The ability must remain a temporary combat attack.
Make its range, eruption interval, damage, knockback, and duration configurable.
## ULTIMATE — ARMAGEDDON
Armageddon is a large-scale volcanic meteor attack.
### Activation
The player equips the Flame Shard in the offhand and right-clicks.
### Mechanics
1. Start the ultimate with a dramatic volcanic charging animation.
2. Create an actual-looking temporary volcano structure using controlled visual entities or tracked temporary block changes.
3. Animate the volcano appearing in stages.
4. Acquire valid player and mannequin targets within the configured ultimate range.
5. Summon a meteor toward a selected target.
6. Make the meteor visibly travel toward the target.
7. Spawn subsequent meteors at 2.5-second intervals by default.
8. Each meteor must have a visible trajectory and a clearly readable impact.
9. On impact, create a meteor-shaped crater effect.
10. A direct hit deals six damage points, ignoring armor, by default.
11. Apply configurable splash damage and knockback.
12. Play the volcano's disappearing animation after the ultimate ends.
13. Restore any temporary terrain modifications safely.
### Meteor requirements
- Meteors must be actual visible objects, not merely falling particles.
- Use appropriate custom models or display entities for the meteor visuals.
- Each meteor must have functional collision and impact logic.
- The crater must be visually convincing.
- Direct hits and splash hits must be calculated separately.
- The visual impact point must match the damage location.
### Terrain safety
If actual blocks are temporarily modified, record every affected block and its original state.
Restore the original state reliably, including after player disconnects, plugin shutdowns, or server restarts where practical.
Respect protection plugins and WorldGuard-like regions when available. Never silently overwrite unrelated player constructions.
If terrain modification is not safe, provide a crater made from temporary visual entities instead.
---
# 9. FROST SHARD
The Frost Shard specializes in ranged ice attacks, slowing enemies, and large-scale freezing effects.
## ABILITY 1 — FROST BARRAGE
### Activation
The player presses F while holding the Frost Shard.
### Mechanics
1. Spawn two actual-looking frost crystals.
2. Position one crystal three blocks to the player's left and one three blocks to the player's right.
3. Keep both crystals hovering beside the player.
4. Both crystals fire simultaneously toward the direction the player is looking.
5. Fire a new pair every 0.5 seconds while the ability remains active.
6. Each crystal travels toward the player's aim direction.
7. Detect hits against valid players and mannequins.
8. Apply configured damage.
9. Slow each hit target for two seconds by default.
10. Spawn an ice impact effect when a crystal hits something.
11. End the ability after its configurable duration or projectile limit.
### Visual requirements
- Actual custom-looking ice crystals.
- Stable left and right positioning.
- Smooth crystal hovering.
- Visible frost trails.
- Simultaneous firing.
- Distinctive impact and shatter animations.
The crystals must not be replaced with ordinary snowballs or generic snow particles.
The firing interval must be configurable, with 0.5 seconds as the default.
## ABILITY 2 — GLACIAL SPEAR
### Mechanics
1. The player activates the ability.
2. A large pointed ice spear forms in front of the player.
3. The spear briefly charges with frost energy.
4. Aim the spear toward the player's crosshair direction.
5. Launch the spear as a fast, visible projectile.
6. Detect collisions with valid players and mannequins.
7. Apply configured damage and heavy slowing.
8. On impact, shatter the spear into visible ice fragments.
9. Remove all temporary projectile entities after impact or expiration.
### Visual requirements
- Large, pointed ice spear model.
- A short formation animation.
- Frost charging effects.
- Smooth projectile travel.
- Strong ice impact and shatter effects.
Do not make this a second version of Frost Barrage. Glacial Spear must be one powerful, aimed projectile, while Frost Barrage is a repeated two-crystal attack.
## ULTIMATE — ABSOLUTE ZERO
Absolute Zero must be a powerful, large-area freezing ultimate.
It must be significantly more impactful than an ordinary slowing or single-projectile ability.
### Activation
The player equips the Frost Shard in the offhand and right-clicks.
### Stage 1: Glacier formation
1. Begin a dramatic ultimate activation animation.
2. Create a large frozen domain around the selected combat area.
3. Spawn a huge glacier that appears in multiple animated stages.
4. Add ice formations around the domain.
5. Create a strong blizzard effect.
6. Play low, powerful ice formation sounds.
7. Display an obvious warning to nearby valid targets.
The glacier must be an actual-looking 3D visual structure, using suitable custom models, display entities, or other controlled rendering techniques. It must not just be a cloud of particles.
### Stage 2: Blizzard
1. Maintain the frozen domain.
2. Apply configurable slowing to valid enemies within its range.
3. Spawn periodic ice spikes from the ground.
4. Give targets a readable visual warning before each spike attack.
5. Deal configured damage when the spikes strike.
6. Apply knockback or brief movement restriction as configured.
Players and mannequins must both be affected.
### Stage 3: Freezing wave
1. Charge the glacier with visible frost energy.
2. Display a clear telegraph indicating the incoming freezing wave.
3. Release a large wave through the domain.
4. Briefly immobilize valid targets caught in the wave.
5. Deal significant configurable damage.
6. Use plugin-managed movement restriction when a mannequin cannot receive a standard player freezing effect.
The freezing effect must be temporary. Targets must not remain permanently immobilized.
### Stage 4: Glacier shatter
1. Play a short final charging animation.
2. Shatter the glacier in a large, visually impressive explosion of ice.
3. Launch remaining valid targets outward.
4. Apply the configured final damage.
5. End the blizzard.
6. Remove temporary ice formations and effects.
7. Release any immobilized targets.
8. Restore any temporarily changed terrain.
### Balance and counterplay
- Make the ultimate powerful but readable.
- Provide a clear warning before major attacks.
- Allow targets to escape or avoid telegraphed attacks where appropriate.
- Make duration, range, damage, slow strength, immobilization time, spike interval, and cooldown configurable.
- Prevent repeated damage on every server tick.
- Do not permanently trap players or mannequins.
The final result should feel like a large-scale ice ultimate, not a routine damage ability with a blue particle effect.
---
# 10. GRAVITY SHARD — RESERVED
Gravity Shard is reserved for a later update.
For this release:
- Create its unique item identity and identifier.
- Allow it to appear in the roulette when enabled.
- Allow administrators to assign it manually.
- Display that its abilities are not implemented.
- Do not invent or implement Gravity abilities.
- Do not give it placeholder attacks.
- Do not accidentally inherit another shard's abilities.
Structure the code so its abilities can be added in a later release without rewriting the entire ability system.
---
# 11. DAMAGE, TARGETING, AND COMBAT ENGINE
Create a centralized combat engine used by all abilities.
### Damage handling
Support:
- Configurable normal damage.
- Armor-ignoring damage.
- Direct-hit damage.
- Splash damage.
- Periodic damage.
- Damage intervals.
- Knockback.
- Vertical launching.
- Slowing.
- Temporary immobilization.
- Burning.
- Pulling.
- Controlled target movement.
Use clear internal damage types and documented rules for whether each type respects armor, enchantments, absorption, and other protections.
For real players, use the correct server-side damage and movement mechanisms.
For mannequins, use an adapter that implements the applicable combat effects without assuming the mannequin has a normal player inventory or client.
Do not accidentally damage the caster unless explicitly configured.
### Target validation
Every ability must use a shared method or service to:
- Find eligible targets.
- Exclude the caster when appropriate.
- Exclude dead or invalid entities.
- Recognize supported mannequin types.
- Exclude decorative entities.
- Respect configured team or friendly-fire rules.
- Respect world and region restrictions.
- Prevent repeated hits within the same attack when only one hit is intended.
### Target tracking
Tracking abilities must update their target position throughout their active duration.
Do not calculate the target's location only once and leave the projectile or cloud stationary.
For moving targets, update the relevant trajectory or tracking behavior at an appropriate interval.
Handle targets that disconnect, die, despawn, or become invalid.
---
# 12. VISUAL EFFECTS AND ANIMATIONS
Visual quality is a core feature, not an optional enhancement.
Use the appropriate combination of:
- Custom resource-pack models.
- Item display entities.
- Block display entities where suitable.
- Controlled entity movement.
- Minecraft particles.
- Sound effects.
- Interpolation.
- Animation states.
- Server-side hit detection.
- Temporary visual structures.
### General requirements
1. Every ability needs an activation animation.
2. Every projectile needs a visible trajectory.
3. Every impact needs a readable effect.
4. Every ultimate needs a distinct beginning, active phase, and ending.
5. Effects must match their actual collision and damage mechanics.
6. Visual entities must have appropriate lifetimes.
7. Remove temporary entities when the effect ends.
8. Avoid excessive particles and unnecessary entity spawning.
9. Avoid creating hundreds of individual entities per player without a performance budget.
10. Make animation timing configurable where practical.
Do not pretend an effect is a real model if it is only a small particle cloud.
Where custom models require a resource pack, supply the corresponding model files, texture files, and correct item-model mappings.
Provide a complete resource-pack folder structure and installation instructions. Do not claim a resource pack is embedded in the plugin unless it actually is.
---
# 13. COOLDOWNS AND CONFIGURATION
Every ability and ultimate must have its own configurable cooldown.
Do not hardcode cooldowns throughout the source code.
Use `config.yml` for all balance values, including:
- Ability cooldowns.
- Ultimate cooldowns.
- Damage values.
- Armor-ignoring damage.
- Projectile speeds.
- Projectile lifetimes.
- Target ranges.
- Tracking ranges.
- Cloud pauses.
- Tornado duration and pull radius.
- Tornado damage interval.
- Meteor spawn interval.
- Glacier duration.
- Slow duration and strength.
- Immobilization duration.
- Knockback strength.
- Animation duration.
- Particle settings.
- Sound settings.
- Mannequin support.
- Friendly-fire behavior.
- Terrain restoration.
- Roulette timing.
- Shard availability.
Use sensible defaults based on the specified mechanics.
Do not silently change specified values such as the 10-second Tempest duration, three-block tornado pull radius, three-block Frost Barrage crystal positioning, two-second Frost Barrage slow, 2.5-second meteor interval, or six-point direct meteor damage.
### Cooldown feedback
When a player attempts to activate an ability on cooldown:
- Do not activate the ability.
- Display the remaining cooldown.
- Use an action bar or configurable message.
- Do not spam chat.
- Ensure cooldowns are tracked independently.
Use safe, monotonic time calculations and prevent cooldowns from resetting through reconnecting or changing worlds unless that behavior is explicitly configured.
---
# 14. COMMANDS AND PERMISSIONS
Implement these commands.
### `/shardsmp start`
Starts the SMP and launches the shard-selection process.
Permission: `shardsmp.admin`
### `/shardsmp stop`
Stops active shard abilities and selection sequences, cleans up temporary entities, and safely ends the SMP session.
Permission: `shardsmp.admin`
### `/shardsmp shard <player> <shard>`
Assigns a shard to a player.
Valid identifiers: `air`, `flame`, `frost`, `gravity`.
The command must update the player's saved assignment and grant the appropriate shard item.
Permission: `shardsmp.admin`
### `/shardsmp reset <player>`
Resets the player's shard assignment and associated ability state.
Permission: `shardsmp.admin`
### `/shardsmp info <player>`
Displays the player's assigned shard, available abilities, cooldown status, and whether their shard's abilities are implemented.
Permission: `shardsmp.admin` by default, with an optional self-inspection permission.
### `/shardsmp reload`
Reloads supported configuration values safely.
Permission: `shardsmp.admin`
### Permission defaults
- `shardsmp.admin`: OP.
- `shardsmp.use`: true.
- `shardsmp.info.self`: true.
Register commands, tab completion, usage messages, and permission checks properly.
Do not make an invalid command silently succeed.
---
# 15. PLAYER DATA AND PERSISTENCE
Persist:
- Assigned shard.
- Shard ownership.
- Relevant cooldowns where appropriate.
- Selection status.
- Any state required to prevent duplicate awards.
- Configuration-controlled player preferences, if implemented.
Use UUIDs rather than player names as the primary player identifier.
Store data safely using YAML, JSON, or another appropriate lightweight format. Use atomic writes or another reliable persistence approach where practical.
Handle:
- Server restart.
- Plugin reload.
- Player disconnect.
- Player death.
- World change.
- Shard item loss.
- Duplicate shard items.
- Selection interruption.
Do not permanently store temporary visual entity IDs as though they remain valid across server restarts.
Do not duplicate a player's assigned shard when they reconnect or respawn.
Define clearly whether a shard persists through death and whether a new item is issued after respawn. Make the behavior configurable.
---
# 16. PERFORMANCE AND CLEANUP
All abilities must be implemented with performance in mind.
- Do not create uncontrolled repeating tasks.
- Avoid scanning every entity in the world on every tick.
- Use spatially appropriate target searches.
- Track temporary entities and active ability instances.
- Cancel tasks when abilities end.
- Clean up projectiles on impact or timeout.
- Release captured targets when Tempest ends.
- Release immobilized targets when Absolute Zero ends.
- Remove temporary clouds, crystals, meteors, and other effect entities.
- Stop all active tasks during plugin shutdown.
- Avoid memory leaks.
- Avoid asynchronous access to unsafe Bukkit/Paper APIs.
- Use the correct scheduler and threading model for the target Paper version.
- Keep expensive calculations out of unnecessary per-tick loops.
Do not use blocking operations on the server thread.
Every active ability should have a clear lifecycle and cleanup method.
---
# 17. RESOURCE PACK DELIVERABLES
Provide all custom assets required for the four shard identities and their abilities.
At minimum, provide:
- Air Shard model and texture.
- Flame Shard model and texture.
- Frost Shard model and texture.
- Gravity Shard model and texture.
- Cloudburst visual assets where custom models are used.
- Tempest tornado visuals.
- Inferno Burst projectile visuals.
- Magma Rift visuals.
- Armageddon volcano and meteor visuals.
- Frost Barrage crystal visuals.
- Glacial Spear model.
- Absolute Zero glacier and ice formation visuals.
Use actual custom models where specified, not renamed vanilla projectiles as a substitute.
Supply valid model definitions and textures in the proper resource-pack structure for Minecraft 1.21.11.
Make sure item identifiers and model references match the plugin's implementation.
If an asset cannot be generated directly, provide a complete asset specification and an explicit placeholder designation rather than pretending it is finished.
---
# 18. TESTING REQUIREMENTS
Create a practical test plan and execute the tests that the development environment supports.
### Compatibility tests
- Build against the correct Minecraft 1.21.11 Paper API.
- Compile using Java 21.
- Compile using Java 25.
- Test plugin startup on Java 21.
- Test plugin startup on Java 25.
- Check the plugin descriptor and dependencies.
- Check command registration.
- Check configuration loading.
### Roulette tests
- Verify that the roulette contains only the actual pottery shard item models.
- Verify circular placement.
- Verify that the entire arrangement rotates.
- Verify all five selection rounds.
- Verify final deceleration.
- Verify the displayed winner matches the awarded shard.
- Verify multiple players can roll independently.
- Verify disconnects do not leave entities behind.
- Verify that an interrupted sequence cannot award duplicate shards.
### Ability tests
Test every implemented ability and ultimate individually.
For each ability, verify:
1. Correct activation input.
2. Cooldown behavior.
3. Visual animation.
4. Actual damage or status effect.
5. Correct target detection.
6. Collision and tracking.
7. Correct cleanup.
8. No unintended terrain damage.
### Mannequin tests
Test every ability and ultimate against:
- A real player.
- A supported mannequin.
- A configured armor-stand-based dummy, if supported.
Confirm that player-targeting mechanics also select mannequins when they are eligible.
Confirm that decorative armor stands are not accidentally attacked.
Confirm that mannequin effects use functional equivalents when normal player effects are unavailable.
### Regression tests
- Multiple abilities active simultaneously.
- Multiple targets in one area.
- Player disconnects during an ultimate.
- Player dies during an ultimate.
- Plugin shutdown during an ability.
- World change during tracking.
- Cooldown persistence.
- Missing resource pack.
- Missing or invalid configuration values.
- Protection plugin restrictions.
- Invalid commands and insufficient permissions.
If any test cannot be executed, report it honestly and explain the remaining verification steps.
---
# 19. REQUIRED PROJECT OUTPUT
Deliver a complete project with the following structure or a similarly organized equivalent:
`ShardSMP/`
- `pom.xml`
- `src/main/java/com/shardsmp/ShardSMP.java`
- `src/main/java/com/shardsmp/commands/`
- `src/main/java/com/shardsmp/shards/`
- `src/main/java/com/shardsmp/abilities/`
- `src/main/java/com/shardsmp/combat/`
- `src/main/java/com/shardsmp/targets/`
- `src/main/java/com/shardsmp/roulette/`
- `src/main/java/com/shardsmp/effects/`
- `src/main/java/com/shardsmp/data/`
- `src/main/java/com/shardsmp/config/`
- `src/main/resources/plugin.yml`
- `src/main/resources/config.yml`
- `resource-pack/`
- `README.md`
You may improve the folder structure when necessary, but preserve clear separation between abilities, targeting, combat, roulette, persistence, configuration, and visual effects.
### Deliverables
1. Complete Java source code.
2. Maven build configuration.
3. Correct plugin descriptor.
4. Complete default configuration.
5. Resource-pack files and model mappings.
6. Build instructions.
7. Installation instructions.
8. Command and permission documentation.
9. Mannequin compatibility documentation.
10. A test plan and honest test results.
11. A compiled plugin JAR if the environment allows it.
12. A list of any remaining limitations.
Do not provide only isolated code snippets. Produce the entire project.
Do not omit source files because the answer is long. If output limits prevent delivering the entire project in one response, divide it into clearly numbered parts and keep a file checklist so that no required file is forgotten.
---
# 20. FINAL ACCEPTANCE CRITERIA
The plugin is not complete until all of the following are satisfied:
- [ ] Minecraft Java 1.21.11 support.
- [ ] Java 21 compatibility.
- [ ] Java 25 compatibility.
- [ ] `/shardsmp start` works.
- [ ] Roulette consists exclusively of actual pottery shard item models.
- [ ] Roulette rotates as a complete circular arrangement.
- [ ] Exactly five selection rounds occur.
- [ ] The displayed winning shard matches the awarded shard.
- [ ] Air Shard has Cloudburst, Stormcall, and Tempest.
- [ ] Flame Shard has Inferno Burst, Magma Rift, and Armageddon.
- [ ] Frost Shard has Frost Barrage, Glacial Spear, and Absolute Zero.
- [ ] Gravity Shard is reserved for a future update.
- [ ] All specified mechanics are implemented.
- [ ] Every implemented ability and ultimate works against real players.
- [ ] Every implemented ability and ultimate supports valid mannequin targets.
- [ ] Target-tracking abilities recognize mannequins.
- [ ] Damage, status effects, movement, and collisions are functional.
- [ ] Cooldowns work independently.
- [ ] Commands and permissions work.
- [ ] Player assignments persist safely.
- [ ] Temporary entities and tasks are cleaned up.
- [ ] Terrain changes are safe and reversible.
- [ ] Custom model references are correct.
- [ ] The project builds successfully in the verified build environment.
- [ ] Unverified tests and limitations are explicitly reported.
**Final instruction:** Build Shard SMP as a complete, visually impressive, technically sound Minecraft plugin. Follow the specified mechanics exactly. Prioritize the actual pottery-shard roulette, reliable PvP mechanics, custom visual effects, Java 21 and 25 compatibility, and complete mannequin support. Never substitute a simplified placeholder for a specified mechanic without explicitly explaining the limitation and providing a proper solution.
Set up a Paper 1.21.11 Maven plugin targeting Java 21 bytecode (compatible with Java 25).
Add shard items, UUID persistence, admin commands, five-round display-entity roulette, and lifecycle cleanup.
Implement shared targeting/cooldowns and server-side mechanics for Air, Flame, and Frost; keep Gravity reserved.
Document controls, mannequin setup, and the resource-pack asset limitation.
Created the ShardSMP Paper project targeting Minecraft 1.21.11—interpreting 1.2.111 as the version specified in your attached brief—with Java 21 bytecode intended to run on Java 21 and Java 25.
It includes shard assignment and persistence, admin commands, a five-round pottery-shard display roulette, shared player/tagged-dummy targeting, cooldowns, and server-side mechanics for the Air, Flame, and Frost abilities. Gravity remains reserved.
Limitations: I could not run a build or Java 21/25 server tests here. The custom textures and completed resource pack are not included; texture generation is disabled. Enable it in this project’s Settings → Generation, or at https://kodari.ai/settings?tab=features. The README documents the asset IDs, mannequin setup, controls, and verification checklist.
generate the item textures make sure they look like a shard i gave you permission to texture generate
Generated four 64Ă—64 shard textures:
Air:
resource-pack/assets/minecraft/textures/item/air_shard.pngFlame:
resource-pack/assets/minecraft/textures/item/flame_shard.pngFrost:
resource-pack/assets/minecraft/textures/item/frost_shard.pngGravity:
resource-pack/assets/minecraft/textures/item/gravity_shard.png
They’re shard-shaped inventory icons with distinct elemental colors. Resource-pack model definitions are still needed to display them in Minecraft.
air shard and frost shard look so much alike
Updated the frost shard with a vivid turquoise-and-glacier-blue palette, bright icy facets, and sharper crystal points to set it apart from the air shard.
offhand + right click seems to interfer with offhand and it doesnt even work
Allow Bukkit’s pre-cancelled right-click-air events to reach the ability handler.
Stop cancelling the whole interaction, which can block normal main-hand/offhand behavior.
Keep activation limited to one hand event and preserve the existing shard/session checks.
Fixed offhand right-click in AbilityManager: right-click-air events now reach the handler even when Bukkit pre-cancels them, and activating the shard no longer cancels the player’s normal hand interaction.
Frost shards just stay on the right side and left side when shooting make sure they go the center when shooting they do not both go to the center right side willl go first go to the center waits for 1 second shoots left side comes to the center waits for 1 second shoots and also make a cool appearing particle and all particles seem so bland like they are so skinny and doenst look appealing also frost spear seems to not damage when hitting an entity also stormcall strikes one time and just stops entirely its supposed to strike 5 times then stop
Fix frost shard sequencing: bring the right shard to center and shoot, then the left, with a one-second pause.
Improve the shard appearance and particle effects so they’re more visible and polished.
Fix frost spear entity damage and make Stormcall strike five times.
Frost Barrage sequence: implemented right-side then left-side shard convergence, one-second windups, and sequential shots.
Next: improve the particle visuals for the shard abilities.
Then: fix Glacial Spear damage and Stormcall’s five-strike sequence.
Frost Barrage: the right shard now converges and fires before the left shard follows.
Frost visuals: added a rotating shard-forming effect, brighter formation/impact bursts, and denser trails.
Next: address Glacial Spear’s reported hit damage, then Stormcall’s five strikes.
Updated AbilityManager:
Frost Barrage now brings the right shard to center, waits one second, and fires; then repeats with the left shard.
Added rotating formation particles, fuller shard trails, and brighter impact bursts.
Glacial Spear now checks along its full path instead of only at each tick’s endpoint, preventing it from passing through targets without hitting them.
Stormcall now lands five strikes, spaced 20 ticks apart after its configured pause, then stops.
package com.shardsmp;
import net.kyori.adventure.text.Component;
import org.bukkit.Bukkit;
import org.bukkit.ChatColor;
import org.bukkit.Location;
import org.bukkit.NamespacedKey;
import org.bukkit.Registry;
import org.bukkit.Sound;
import org.bukkit.command.PluginCommand;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.entity.PlayerDeathEvent;
import org.bukkit.event.player.PlayerJoinEvent;
import org.bukkit.event.player.PlayerQuitEvent;
import org.bukkit.event.player.PlayerRespawnEvent;
import org.bukkit.plugin.java.JavaPlugin;
public final class ShardSMP extends JavaPlugin implements Listener {
private PlayerDataStore dataStore;
private ShardItems shardItems;
private CombatEngine combatEngine;
private AbilityManager abilityManager;
private RouletteManager rouletteManager;
@Override
public void onEnable() {
saveDefaultConfig();
dataStore = new PlayerDataStore(this);
shardItems = new ShardItems(this);
combatEngine = new CombatEngine(this);
abilityManager = new AbilityManager(this, combatEngine);
rouletteManager = new RouletteManager(this);
Bukkit.getPluginManager().registerEvents(this, this);
Bukkit.getPluginManager().registerEvents(abilityManager, this);
Bukkit.getPluginManager().registerEvents(rouletteManager, this);
PluginCommand command = getCommand("shardsmp");
if (command == null) {
getLogger().severe("Command shardsmp is missing from plugin.yml; disabling.");
Bukkit.getPluginManager().disablePlugin(this);
return;
}
ShardCommand handler = new ShardCommand(this);
command.setExecutor(handler);
command.setTabCompleter(handler);
getLogger().info("ShardSMP enabled. Java " + Runtime.version().feature() + " detected.");
}
@Override
public void onDisable() {
if (rouletteManager != null) rouletteManager.stopAll();
if (abilityManager != null) abilityManager.stopAll();
}
@EventHandler
public void onJoin(PlayerJoinEvent event) {
dataStore.getShard(event.getPlayer().getUniqueId()).ifPresent(shard -> Bukkit.getScheduler().runTask(this,
() -> shardItems.give(event.getPlayer(), shard)));
}
@EventHandler
public void onDeath(PlayerDeathEvent event) {
if (!getConfig().getBoolean("items.reissue-on-death", true)) return;
event.getDrops().removeIf(item -> shardItems.identify(item).isPresent());
}
@EventHandler
public void onRespawn(PlayerRespawnEvent event) {
if (!getConfig().getBoolean("items.reissue-on-death", true)) return;
Bukkit.getScheduler().runTask(this, () -> dataStore.getShard(event.getPlayer().getUniqueId())
.ifPresent(shard -> shardItems.give(event.getPlayer(), shard)));
}
@EventHandler
public void onQuit(PlayerQuitEvent event) {
abilityManager.cancelFor(event.getPlayer());
}
public void sound(Location location, String key, float volume, float pitch) {
Sound sound = Registry.SOUNDS.get(NamespacedKey.minecraft(key));
if (sound != null) location.getWorld().playSound(location, sound, volume, pitch);
}
public void message(Player player, String message) {
player.sendMessage(ChatColor.translateAlternateColorCodes('&',
getConfig().getString("messages.prefix", "&b&lSHARDSMP &8» &r") + message));
}
public void actionBar(Player player, String message) {
player.sendActionBar(Component.text(ChatColor.stripColor(ChatColor.translateAlternateColorCodes('&', message))));
}
public PlayerDataStore data() { return dataStore; }
public ShardItems items() { return shardItems; }
public CombatEngine combat() { return combatEngine; }
public AbilityManager abilities() { return abilityManager; }
public RouletteManager roulette() { return rouletteManager; }
}