Noah Steiner
📎 1 file 21,463 chars
📄
pasted-code-1790541941296.txt
txt 961 lines
▶
Create a complete Minecraft Java Edition server plugin based on the following specification.

TARGET PLATFORM:

* Paper server
* Use the Paper/Bukkit/Spigot API appropriate for the target Minecraft version.
* This MUST be a server plugin, NOT a Fabric mod, Forge mod, NeoForge mod, or client-side mod.
* Players should not need to install anything on their Minecraft clients.
* Use Java.
* The project must be buildable with Gradle or Maven and openable in IntelliJ IDEA.

The plugin is a multiplayer PvP progression system centered around 12 unique Hearts.

Each Heart is associated with a difficult VANILLA Minecraft advancement.

Each Heart can only exist ONCE per server/world.

Hearts are not crafted.

When the required advancement is completed, the corresponding Heart is automatically awarded.

The Hearts are powerful PvP artifacts that can be transferred between players through PvP.

==================================================

1. HEART UNLOCK SYSTEM
   ==================================================

When a player completes a required vanilla advancement:

1. Check whether that Heart has already been awarded.
2. If it has already been awarded, do nothing.
3. If it has NOT been awarded:

   * Permanently mark that Heart as unlocked in the plugin's persistent server data.
   * Create the corresponding Heart item.
   * Attempt to put it into the player's inventory.
   * If the player's inventory has no available slot, drop it at the player's location.
   * Make the dropped Heart completely protected from normal item destruction.
   * Broadcast a special server-wide announcement.

The announcement must contain:

* Player username
* Heart name
* Exact X, Y, Z coordinates

Example:

✦ INCHLEEE has unlocked the Warden Heart! ✦
Coordinates: X: 1245 Y: 62 Z: -384

Use a distinctive Heart-specific colour.

Use bold formatting.

Make the announcement highly visible in chat.

If the server/API supports modern chat components, use Adventure Components for formatting.

Do NOT announce the Heart again when it changes owners.

The advancement itself should remain a normal vanilla advancement.

==================================================
2. HEART UNIQUENESS
===================

There can only ever be ONE of each Heart on the entire server/world.

Use PersistentDataContainer and/or a persistent server data file to track:

warden_heart_unlocked
shulker_heart_unlocked
elder_guardian_heart_unlocked
evoker_heart_unlocked
breeze_heart_unlocked
blaze_heart_unlocked
brute_heart_unlocked
enderman_heart_unlocked
husk_heart_unlocked
ghast_heart_unlocked
wolf_heart_unlocked
ender_dragon_heart_unlocked

Once a Heart is unlocked, the flag remains permanently true.

Do NOT reset the flag when:

* The Heart is dropped
* The Heart changes owner
* The owner dies
* The owner logs out
* The server restarts

==================================================
3. HEART ITEMS
==============

Create 12 custom Heart items.

IDs/names:

Warden Heart
Shulker Heart
Elder Guardian Heart
Evoker Heart
Breeze Heart
Blaze Heart
Brute Heart
Enderman Heart
Husk Heart
Ghast Heart
Wolf Heart
Ender Dragon Heart

Each Heart should:

* Have a unique item identity using PersistentDataContainer.
* Have a maximum stack size of 1.
* Have a unique display name.
* Have a custom lore/tooltip explaining its ability.
* Clearly state whether its ability is passive or active.
* Be impossible to confuse with normal Minecraft items.
* Ideally use custom-model-data so resource packs can give each Heart its own texture.

The plugin must still function without a resource pack.

==================================================
4. TWO HEART EQUIPMENT SLOTS
============================

Players can equip a maximum of TWO Hearts.

Because this is a plugin-only implementation, do NOT attempt to modify the actual vanilla player inventory GUI in a way Bukkit/Paper cannot safely support.

Instead, create a custom Heart equipment interface.

For example:

/hearts

opens a custom inventory GUI.

The GUI contains:

HEART SLOT 1
HEART SLOT 2

The two slots should be visually distinct and clearly labelled.

The player can place Hearts into these slots.

Prevent:

* More than two Hearts being equipped.
* The same Heart being equipped twice.
* Normal items being placed in Heart slots.
* Heart duplication.
* Removing a Heart without correctly returning the physical item to the player's inventory.

The plugin must save equipped Hearts across:

* Server restarts
* Player logout/login
* Death handling
* Chunk unloads

==================================================
5. ACTIVATION CONTROLS
======================

IMPORTANT PLUGIN LIMITATION:

A normal server plugin cannot add genuine custom G/H keybinds to Minecraft's vanilla Controls menu without a client-side mod.

Therefore implement the plugin-only version using configurable commands.

Default:

/heart1
activates the active ability of the Heart in slot 1.

/heart2
activates the active ability of the Heart in slot 2.

Make these commands configurable in config.yml.

Also allow aliases if desired.

For the Enderman Heart:

Dash activation should use a plugin-compatible method.

Default:
Double-tap jump detection.

Detect two jump actions within a short configurable window.

If the player double-taps jump:

* Activate Enderman Heart Dash if the player has an Enderman Heart equipped.
* Do not activate if they do not have the Heart.
* Enforce the 8-second cooldown.

This must be implemented using available Bukkit/Paper movement/jump events where possible.

If exact double-jump detection is not reliable on the target Paper version, implement the most reliable server-side detection possible without requiring a client mod.

==================================================
6. HEART DEATH SYSTEM
=====================

When a player dies:

Every equipped Heart must be removed from the player's Heart equipment slots.

The physical Heart items must drop at the player's death location.

The Heart abilities immediately stop working.

Another player can pick up the Heart.

The new player can equip it.

The Heart then belongs to the new player.

The world still considers the Heart permanently unlocked.

==================================================
7. HEART ITEM PROTECTION
========================

Heart items must NEVER:

* Despawn
* Burn in fire
* Burn in lava
* Be destroyed by cactus
* Be destroyed by explosions
* Be destroyed by TNT
* Be destroyed by environmental damage
* Be destroyed by normal item-clearing mechanics

Listen to relevant Paper/Bukkit events and cancel destruction where necessary.

Set the item's pickup behavior normally so another player can collect it.

A Heart should remain in the world indefinitely until picked up.

==================================================
8. TARGETING SYSTEM
===================

For abilities that target the nearest player:

Find the nearest valid player to the Heart holder.

Exclude:

* The Heart holder
* Dead players
* Spectators
* Players who cannot be targeted according to server rules

Use actual distance.

Make the maximum target range configurable.

If there is no valid target:

* Do not activate the ability.
* Do not consume the cooldown.

==================================================
9. HEART 1 — WARDEN HEART
=========================

Associated structure:
Ancient City

Vanilla advancement:
minecraft:adventure/sneak_100

Advancement name:
Sneak 100

Ability:
SONIC BOOM

When activated:

* Fire a Warden-style Sonic Boom toward the player's target direction.
* It should behave similarly to the Warden Sonic Boom.
* It should be capable of hitting players at range.
* It should bypass shields in the same general manner as the real Warden Sonic Boom.

DAMAGE:

The custom Sonic Boom deals exactly 50% of the damage of a real Warden Sonic Boom.

Cooldown:
30 seconds.

==================================================
10. HEART 2 — SHULKER HEART
===========================

Associated structure:
End City

Vanilla advancement:
minecraft:end/levitate

Advancement name:
Sky's the Limit

Ability:
SHULKER SHOT

When activated:

* Find the nearest valid enemy player.
* Fire a homing Shulker-style projectile.
* If it hits, apply Levitation for 4 seconds.

Cooldown:
25 seconds.

==================================================
11. HEART 3 — ELDER GUARDIAN HEART
==================================

Associated structure:
Ocean Monument

Vanilla advancement:
minecraft:adventure/kill_all_mobs

Advancement name:
Monsters Hunted

Ability:
GUARDIAN BEAM

When activated:

* Target the nearest valid enemy player.
* Create an Elder Guardian-style beam.
* The beam lasts exactly 8 seconds.
* Track the target while they move.
* Deal exactly 1 heart of damage every 2 seconds.

Total:
4 damage ticks.

Cooldown:
40 seconds.

==================================================
12. HEART 4 — EVOKER HEART
==========================

Associated structure:
Woodland Mansion

Use the relevant vanilla advancement associated with the Evoker/woodland progression available in the target Minecraft version.

Ability:
EVOKER FANGS

When activated:

* Target the nearest enemy player.
* Spawn Evoker-style fangs underneath/around the target.
* Damage the target according to vanilla-like Evoker Fang behavior.

Cooldown:
30 seconds.

==================================================
13. HEART 5 — BREEZE HEART
==========================

Associated structure:
Trial Chamber

Use the appropriate vanilla Trial Chamber advancement available in the target Minecraft version.

Ability:
WIND BLAST

When activated:

* Target the nearest enemy player.
* Create a powerful Breeze-style wind attack.
* Launch the target backward with strong knockback.

Cooldown:
20 seconds.

==================================================
14. HEART 6 — BLAZE HEART
=========================

Associated structure:
Nether Fortress

Vanilla advancement:
minecraft:nether/all_potions

Advancement name:
A Furious Cocktail

Ability:
INFERNO

Target:
Nearest enemy player.

Duration:
20 seconds.

During the ability:

1. Target takes fire damage.
2. This fire damage MUST still affect a player with Fire Resistance.
3. Target receives a 50% outgoing damage increase.

The fire damage must therefore bypass normal Fire Resistance mechanics.

Do not simply set the target on fire and expect Fire Resistance to be bypassed.

Implement custom periodic damage if necessary.

The 50% damage buff means the affected target deals 50% more damage while affected.

Cooldown:
60 seconds.

==================================================
15. HEART 7 — BRUTE HEART
=========================

Associated structure:
Bastion Remnant

Vanilla advancement:
minecraft:nether/loot_bastion

Advancement name:
Those Were the Days

Heart name:
BRUTE HEART

This Heart is PASSIVE ONLY.

While equipped:

Permanent:

* Strength I
* Resistance I
* Fire Resistance

No activation command is required.

When unequipped:

* Remove only the effects provided by this Heart.
* Do not permanently modify the player's normal effects.

==================================================
16. HEART 8 — ENDERMAN HEART
============================

Associated structure:
Stronghold

Vanilla advancement:
minecraft:story/follow_ender_eye

Advancement name:
Eye Spy

This Heart has two abilities and one passive.

PASSIVE:
Permanent Speed I.

ABILITY 1:
VOID DASH

Activation:
Double-tap jump.

Effect:

* Dash the player forward rapidly.
* Use the player's facing/movement direction.
* Intended for escaping fights or pursuing enemies.

Cooldown:
8 seconds.

ABILITY 2:
SPEED III

Activation:
Use /heart1 or /heart2 depending on which Heart slot contains the Enderman Heart.

Effect:

* Speed III
* Duration: 10 seconds

Cooldown:
45 seconds.

The Speed I passive remains active while the Heart is equipped.

==================================================
17. HEART 9 — HUSK HEART
========================

Associated structure:
Desert Pyramid

Use an appropriate existing vanilla advancement associated with desert progression/archaeology for the target Minecraft version.

Ability:
DESERT PRISON

When activated:

* Find the closest enemy player.
* Freeze them for exactly 3 seconds.

During the freeze the target cannot:

* Move
* Attack
* Place blocks
* Break blocks

Implement this as a true action lock rather than merely applying Slowness.

Cooldown:
45 seconds.

==================================================
18. HEART 10 — GHAST HEART
==========================

Associated structure:
Nether

Vanilla advancement:
minecraft:nether/return_to_sender

Advancement name:
Return to Sender

Ability:
HOMING FIREBALL

When activated:

* Find the nearest enemy player.
* Launch a Ghast-style fireball.
* Make it home toward that player.
* Projectile speed must be 50% faster than a normal Ghast fireball.
* It must NOT destroy surrounding blocks.
* It should damage entities.
* A shield must be capable of blocking the attack.

Cooldown:
15 seconds.

==================================================
19. HEART 11 — WOLF HEART
=========================

Advancement requirement:

The player must tame EVERY vanilla wolf breed/variant available in the target Minecraft version.

Do NOT hard-code only the original wolf variant.

Detect all required wolf variants dynamically where possible.

Only after every required wolf breed has been tamed should the Wolf Heart be awarded.

Ability:
WOLF PACK

When activated:

Spawn exactly 5 temporary wolves.

Each wolf:

* Has Strength II.
* Targets the nearest enemy player.
* Does not attack its owner.
* Is temporary.
* Exists for exactly 25 seconds.

After 25 seconds:

* Remove all five summoned wolves.

They must not become permanent pets.

Cooldown:
60 seconds.

==================================================
20. HEART 12 — ENDER DRAGON HEART
=================================

Associated progression:
The End

Vanilla advancement:
minecraft:end/enter_end_gateway

Advancement name:
Remote Getaway

Ability:
DRAGON'S BREATH

When activated:

* Find the nearest enemy player.
* Place a Dragon's Breath-style damaging cloud directly on that player.
* The cloud follows the player while they move.

Duration:
7.5 seconds.

Damage:
20% MORE damage than normal vanilla Dragon's Breath.

Additional effects:

Weakness:
25 seconds

Poison:
10 seconds

Slowness:
10 seconds

Cooldown:
90 seconds.

==================================================
21. COOLDOWN SYSTEM
===================

All active abilities must have server-side cooldowns.

Cooldowns:

Warden:
30 seconds

Shulker:
25 seconds

Elder Guardian:
40 seconds

Evoker:
30 seconds

Breeze:
20 seconds

Blaze:
60 seconds

Brute:
Passive

Enderman Dash:
8 seconds

Enderman Speed III:
45 seconds

Husk:
45 seconds

Ghast:
15 seconds

Wolf:
60 seconds

Ender Dragon:
90 seconds

Cooldowns must be server-authoritative.

Do not allow client-side manipulation to bypass them.

Display remaining cooldown to the player using action-bar messages where appropriate.

Example:

"Heart ability ready"

or

"Warden Heart: 17s"

==================================================
22. CONFIGURATION
=================

Create a config.yml containing configurable values for:

* Ability cooldowns
* Target ranges
* Heart GUI title
* Heart slot positions
* Announcement formatting
* Heart colours
* Ability damage
* Ability durations
* Dash distance
* Dash velocity
* Whether PvP-only targeting is enabled
* Heart item protection
* Messages

Do not hard-code values unnecessarily.

==================================================
23. RESOURCE PACK SUPPORT
=========================

The plugin should function without a resource pack.

However, use CustomModelData or the appropriate modern item-model system for Heart items so a server resource pack can give each Heart a unique appearance.

Provide placeholder textures/model definitions if possible.

Each Heart should visually look unique.

==================================================
24. MULTIPLAYER / DUPLICATION SECURITY
======================================

Prevent:

* Heart duplication
* Inventory duplication
* Death duplication
* Shift-click duplication
* Hopper duplication
* Container duplication
* Logout duplication
* Pickup duplication
* Plugin reload duplication
* Server restart duplication
* Item-frame duplication
* Dropped-item duplication

There must never be two copies of the same Heart.

Use a unique Heart ID in PersistentDataContainer.

==================================================
25. PERSISTENCE
===============

Save:

* Heart unlock states
* Equipped Hearts
* Player Heart data
* Cooldowns where necessary
* Temporary effects/state
* World-level Heart ownership information where useful

Data must survive:

* Server restart
* Plugin reload
* Player logout
* Player login
* Chunk unload
* World reload

Use YAML, JSON, SQLite, or another reliable persistent system.

SQLite is preferred if it makes the implementation more robust.

==================================================
26. ADMIN / TEST COMMANDS
=========================

Create an admin command:

/heartadmin

with subcommands such as:

/heartadmin give  

/heartadmin unlock 

/heartadmin reset 

/heartadmin list

/heartadmin reload

/heartadmin info 

These commands should require an appropriate permission such as:

hearts.admin

The reset command should clearly warn that resetting a Heart can create another copy and should therefore only be used for testing.

==================================================
27. PLAYER COMMANDS
===================

Create:

/hearts

Open the Heart equipment GUI.

/heart1

Activate Heart Slot 1.

/heart2

Activate Heart Slot 2.

/heartinfo

Show equipped Hearts, abilities, and cooldowns.

==================================================
28. DEATH EXAMPLE
=================

Player A has:

Warden Heart
Enderman Heart

Player A dies.

The plugin:

1. Removes both Hearts from the player's equipped slots.
2. Drops both physical Heart items.
3. Removes their Heart abilities immediately.
4. Protects the dropped items from destruction.
5. Allows Player B to pick them up.
6. Player B opens /hearts.
7. Player B equips one or both Hearts.
8. Their abilities immediately become active.

The world still has:

Warden Heart = unlocked
Enderman Heart = unlocked

No additional Hearts can ever be generated.

==================================================
29. FINAL GAMEPLAY PHILOSOPHY
=============================

The plugin should feel like a high-stakes PvP server artifact system.

The Hearts are:

* Rare
* Extremely powerful
* Unique
* Transferable
* Worth fighting over
* Permanently unique
* Impossible to permanently destroy
* Limited to two equipped Hearts
* Balanced primarily through cooldowns
* Earned through difficult vanilla advancements

The most important gameplay loop is:

ADVANCEMENT
↓
UNIQUE HEART AWARDED
↓
SERVER ANNOUNCEMENT
↓
PLAYER EQUIPS HEART
↓
PLAYER GAINS POWER
↓
PLAYER BECOMES A PvP TARGET
↓
PLAYER DIES
↓
HEARTS DROP
↓
ANOTHER PLAYER CLAIMS THEM
↓
THE POWER CHANGES HANDS

==================================================
30. IMPORTANT IMPLEMENTATION REQUIREMENT
========================================

Do not create a Fabric/Forge/NeoForge mod.

Do not require players to install a client-side mod.

Build a standalone Paper plugin.

Where Minecraft's vanilla client prevents a requested feature from being implemented exactly — especially custom keybinds or custom inventory slots — implement the closest possible server-side solution and clearly document the limitation.

The plugin must compile successfully and include all required source files, plugin.yml, configuration files, commands, event listeners, persistent data handling, custom item handling, GUI handling, ability systems, cooldown systems, advancement listeners, death/drop handling, and multiplayer protections.

Before declaring the plugin complete, test:

1. All 12 advancement unlocks.
2. One-per-world restrictions.
3. Inventory-full Heart drops.
4. Server announcements.
5. Heart GUI.
6. Two-Heart limit.
7. Heart activation commands.
8. Enderman double-jump dash.
9. All cooldowns.
10. Passive effects.
11. Player death.
12. Heart drops.
13. Heart pickup.
14. Heart transfer between players.
15. Server restart persistence.
16. Heart destruction protection.
17. Multiplayer synchronization.
18. Duplication prevention.
19. All 12 abilities against real players.
20. Correct removal of passive effects when Hearts are unequipped.
Kodari AI
KodariSep 27 at 8:49 pm 3
HeartboundPvP
A high-stakes PvP artifact plugin where 12 unique Hearts are earned through difficult vanilla advancements. Each Heart grants powerful active or passive abilities, can only exist once per server, and drops on death for other players to claim. Features a custom two-slot Heart equipment GUI, configurable ability cooldowns, server-wide unlock announcements, persistent data storage, and comprehensive duplication protection. Players can equip up to two Hearts, activate abilities via commands or double-tap jump, and battle to steal Hearts from fallen enemies in an endless power struggle.
  1. Set up a Paper 1.21.4 Gradle plugin project and configuration.

  2. Add persistent unique Heart items, advancement unlocks, equipment GUI, commands, and protections.

  3. Implement the 12 abilities, targeting/cooldowns, passive effects, death drops, and admin tools.

  4. Document server-side limitations; the project will be ready for the platform’s automatic build verification.

Created UniqueHearts, a Java 21 / Paper 1.21.4 Gradle plugin with persistent Heart unlocks and equipment, the two-slot GUI, commands, advancement and wolf-variant tracking, cooldowns, abilities, death drops, and item protections.

The README documents server-only limitations and combat approximations. No live-server gameplay tests were run.

Kodari can make mistakes. Review important code before using.
Files
src
build.gradle
README.md
settings.gradle
Code
13 1,326
src/main/java/com/kodari/hearts/HeartPlugin.java
package com.kodari.hearts;

import org.bukkit.Bukkit;
import org.bukkit.ChatColor;
import org.bukkit.NamespacedKey;
import org.bukkit.command.Command;
import org.bukkit.command.CommandExecutor;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerCommandPreprocessEvent;
import org.bukkit.plugin.java.JavaPlugin;

import java.util.HashMap;
import java.util.Map;
import java.util.UUID;

public final class HeartPlugin extends JavaPlugin implements CommandExecutor, Listener {
    private HeartData data;
    private HeartItems items;
    private HeartAbilities abilities;
    private HeartMenu menu;
    private NamespacedKey projectileKey;
    private final Map<UUID, Long> lastJumps = new HashMap<>();
    private final Map<UUID, Boolean> groundedState = new HashMap<>();

    @Override
    public void onEnable() {
        saveDefaultConfig();
        data = new HeartData(this);
        items = new HeartItems(this);
        projectileKey = new NamespacedKey(this, "heart_projectile");
        abilities = new HeartAbilities(this);
        menu = new HeartMenu(this);
        Bukkit.getPluginManager().registerEvents(new HeartListener(this), this);
        Bukkit.getPluginManager().registerEvents(menu, this);
        Bukkit.getPluginManager().registerEvents(this, this);
        for (String name : new String[]{"hearts", "heart1", "heart2", "heartinfo"}) {
            if (getCommand(name) != null) getCommand(name).setExecutor(this);
        }
        if (getCommand("heartadmin") != null) getCommand("heartadmin").setExecutor(new HeartAdminCommand(this));
        getLogger().info("UniqueHearts enabled.");
    }

    @Override
    public void onDisable() {
        if (abilities != null) abilities.shutdown();
        if (data != null) data.save();
    }

    @Override
    public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
        if (!(sender instanceof Player player)) { sender.sendMessage("This command is only available to players."); return true; }
        switch (command.getName().toLowerCase()) {
            case "hearts" -> menu.open(player);
            case "heart1" -> abilities.activate(player, 1);
            case "heart2" -> abilities.activate(player, 2);
            case "heartinfo" -> showInfo(player);
            default -> { return false; }
        }
        return true;
    }

    @EventHandler
    public void onConfiguredCommand(PlayerCommandPreprocessEvent event) {
        String entered = event.getMessage().split(" ", 2)[0].substring(1);
        String slotOne = getConfig().getString("commands.slot-1", "heart1");
        String slotTwo = getConfig().getString("commands.slot-2", "heart2");
        if (entered.equalsIgnoreCase(slotOne) && !entered.equalsIgnoreCase("heart1")) {
            event.setCancelled(true);
            abilities.activate(event.getPlayer(), 1);
        } else if (entered.equalsIgnoreCase(slotTwo) && !entered.equalsIgnoreCase("heart2")) {
            event.setCancelled(true);
            abilities.activate(event.getPlayer(), 2);
        }
    }

    private void showInfo(Player player) {
        player.sendMessage(ChatColor.GOLD + "Your Hearts:");
        for (int slot = 1; slot <= 2; slot++) {
            Heart heart = data.getEquipped(player.getUniqueId(), slot);
            player.sendMessage(ChatColor.YELLOW + "Slot " + slot + ": " + ChatColor.WHITE + (heart == null ? "Empty" : heart.displayName() + " — " + heart.ability()));
            if (heart != null) {
                long remaining = data.cooldownExpiry(player.getUniqueId(), heart.id()) - System.currentTimeMillis();
                if (heart == Heart.ENDERMAN) remaining = Math.max(remaining, data.cooldownExpiry(player.getUniqueId(), "enderman-speed") - System.currentTimeMillis());
                if (remaining > 0) player.sendMessage(ChatColor.GRAY + "Cooldown: " + ((remaining + 999) / 1000) + "s");
            }
        }
    }

    public void activateConfigured(Player player, int slot) { abilities.activate(player, slot); }
    public HeartData data() { return data; }
    public HeartItems items() { return items; }
    public HeartAbilities abilities() { return abilities; }
    public HeartMenu menu() { return menu; }
    public NamespacedKey projectileKey() { return projectileKey; }
    public long lastJump(UUID player) { return lastJumps.getOrDefault(player, 0L); }
    public void lastJump(UUID player, long time) { lastJumps.put(player, time); }
    public void clearLastJump(UUID player) { lastJumps.remove(player); }
    public boolean wasGrounded(UUID player) { return groundedState.getOrDefault(player, true); }
    public void wasGrounded(UUID player, boolean grounded) { groundedState.put(player, grounded); }
}