ABDUL MUSTAFA KHAN

Minecraft Plugin — Cyber Tracker + Cyber Key System

Create a complete, production-ready Minecraft Java plugin for a Paper/Spigot server.

The plugin must create a unique Cyber Tracker + Cyber Key system for an SMP. It must be configurable, persistent, multiplayer-safe, optimized, and easy for server operators to manage.

IMPORTANT:

Build the actual working plugin, NOT pseudocode.

Use the correct Paper/Spigot API for the Minecraft version configured in pom.xml.

Before finishing:

  • Compile the complete project.
  • Fix every compilation error.
  • Do not leave undefined classes, methods, imports, or API calls.
  • Do not remove existing functionality just to make the project compile.
  • Use only APIs compatible with the configured Minecraft/Paper version.

---

  1. CYBER TRACKER

A Tracker is a special Compass item.

Create a tracker using:

/tracker create <trackername>

Example:

/tracker create Hunter

The plugin creates:

§b§lHunter Tracker

The tracker MUST be identified using PersistentDataContainer (PDC), not merely its display name.

Use plugin NamespacedKeys with keys equivalent to:

tracker tracker_name

Normal renamed Compasses must never be treated as Cyber Trackers.

---

  1. GIVING TRACKERS

Give one tracker to a player:

/tracker give <player> <trackername>

Give a tracker to every currently online player:

/tracker give <allplayer> <trackername>

"<allplayer>" is a special keyword.

It must give the selected tracker to every online player.

---

  1. TRACKER TARGET

Command:

/tracker add <trackername> <player>

This sets the specified player as the target.

Other commands:

/tracker remove <trackername> <player> /tracker start <trackername> /tracker stop <trackername> /tracker info <trackername> /tracker list /tracker delete <trackername> /tracker help

The tracker must continuously point toward its target.

Do not expose the target's exact XYZ coordinates.

---

  1. AUTOMATIC CYBER KEY HOLDER TRACKING

The Cyber Tracker system must support the current Cyber Key holder as the automatic target.

Example:

Current Cyber Key holder:

Steve

All active trackers configured to track the Cyber Key holder must automatically point toward Steve.

When the holder changes:

Old holder → no longer target New holder → automatically becomes target

Do not require the administrator to manually run /tracker add after every Cyber Key transfer.

---

  1. TRACKER HUD

When a player is holding/using an active Tracker, display a HUD directly above the inventory/hotbar area.

Example:

🎯 Target: Steve 📍 Distance: 247m

Requirements:

  • Show target name.
  • Show approximate/current distance.
  • Do NOT show exact XYZ coordinates.
  • No chat spam.
  • Update smoothly.
  • Automatically disappear when there is no valid target.
  • If the target is in another dimension, display:

Target is in another dimension

  • Avoid expensive per-player-per-tick operations.

---

  1. CYBER KEY

Create a special item:

§e§lCyber Key

The Cyber Key MUST use PersistentDataContainer.

Use a plugin NamespacedKey equivalent to:

cyber_key

Do NOT identify Cyber Keys only by their display name.

Command:

/cyberkey give <player>

Additional commands:

/cyberkey remove <player> /cyberkey list /cyberkey add /cyberkey clear /cyberkey reload /cyberkey help

---

  1. CYBER KEY REWARD SYSTEM

The server operator can add rewards without typing an item name.

Command:

/cyberkey add

The plugin must copy the item currently held in the administrator's MAIN HAND.

Example:

Admin holds a Diamond Sword.

Admin runs:

/cyberkey add

A complete copy of that Diamond Sword is added to the Cyber Key reward pool.

The original item in the admin's hand must NOT be removed.

Preserve the complete ItemStack, including:

  • Material
  • Amount
  • Enchantments
  • Custom name
  • Lore
  • Attributes
  • Item metadata
  • Relevant data/components supported by the target API

/cyberkey list

must display the configured reward pool.

/cyberkey clear

must remove all rewards.

IMPORTANT:

If the same item is added multiple times, keep each entry separately.

This allows duplicate entries to act as weighted random rewards.

Example:

Reward pool:

Diamond Diamond Netherite Ingot Golden Apple

Diamond has two entries and therefore has twice the selection weight of an item with one entry.

---

  1. OMINOUS VAULT — CUSTOM CYBER KEY INTERACTION

THIS IS A CORE REQUIREMENT.

The custom Cyber Key must work directly with a Minecraft Ominous Vault.

The player must NOT need the normal vanilla Ominous Trial Key.

The custom Cyber Key is the special key for this plugin.

When a player RIGHT-CLICKS an Ominous Vault while holding a Cyber Key:

  1. Detect the item using its PersistentDataContainer.
  2. Confirm the clicked block is an Ominous Vault.
  3. Intercept/cancel the normal vanilla Ominous Vault interaction.
  4. Do NOT require the vanilla Ominous Trial Key.
  5. Do NOT generate normal vanilla Ominous Vault loot.
  6. Check whether the Cyber Key reward pool contains at least one reward.

If the reward pool is empty:

  • Do NOT consume the Cyber Key.
  • Do NOT give any reward.
  • Do NOT generate vanilla vault loot.
  • Show:

§cNo Cyber Key rewards are configured.

If rewards exist:

  1. Lock this specific player/vault interaction to prevent duplicate processing.
  2. Select exactly ONE final reward from the configured reward pool.
  3. Store that selected reward for this interaction.
  4. Consume exactly ONE Cyber Key.
  5. Start the Cyber Key loot animation.
  6. Do NOT give the reward until the animation finishes.
  7. When the animation finishes, give exactly ONE copy of the selected reward.
  8. Clear the current Cyber Key holder.
  9. Stop Cyber Key holder tracking.
  10. Save the new state persistently.
  11. Remove the interaction lock.

IMPORTANT:

The actual reward must be selected server-side before the visual animation.

The visual animation must NOT determine or change the actual reward.

A single vault interaction must NEVER:

  • Give multiple rewards.
  • Consume multiple Cyber Keys.
  • Start multiple animations.
  • Trigger both vanilla loot and Cyber Key loot.

Prevent duplicate processing from rapid clicks or multiple interaction events.

The Cyber Key reward must be triggered specifically by:

Cyber Key + Ominous Vault

Do NOT make Cyber Key rewards activate anywhere else unless explicitly configured.

---

8.1 CYBER KEY LOOT REVEAL ANIMATION

When the Cyber Key successfully activates an Ominous Vault, do NOT immediately show/give the reward.

Instead, create a short cinematic loot-selection animation around the Ominous Vault.

The animation should visually look like a special random reward is being selected.

If the reward pool contains 6 items, for example:

  1. Diamond
  2. Emerald
  3. Golden Apple
  4. Diamond Sword
  5. Netherite Ingot
  6. Enchanted Book

the animation should visually cycle through these configured reward items.

The animation should feel like a custom loot/reveal machine.

The actual final reward is already securely selected by the server.

---

8.2 FLOATING ITEM ANIMATION

During the animation, display a temporary floating representation of the currently selected/cycling reward above the Ominous Vault.

The item should look like a Minecraft item floating in the world.

IMPORTANT:

  • Do NOT spawn real dropped ItemEntities.
  • Players must NOT be able to pick up the visual item.
  • The visual item must NOT cause item duplication.
  • The visual item must not have normal dropped-item physics.
  • It should float above the Ominous Vault.
  • It should slightly rotate or visually move.
  • It should automatically disappear after the animation.
  • Clean it up if the player disconnects.
  • Clean it up if the plugin reloads.
  • Clean it up if the server shuts down.

Use the appropriate Paper Display Entity API for the configured Minecraft version when supported.

If the target version requires another compatible visual method, use the safest supported alternative.

---

8.3 RANDOM ITEM CYCLING

The floating item should visually change between rewards during the animation.

Example:

Diamond → Emerald → Golden Apple → Diamond Sword → Netherite Ingot → Enchanted Book → Diamond → Golden Apple → Diamond Sword → ... → FINAL REWARD

The animation should have multiple stages.

PHASE 1 — FAST:

Items change very quickly.

PHASE 2 — MEDIUM:

Items change at medium speed.

PHASE 3 — SLOW:

Items change slowly.

PHASE 4 — FINAL REVEAL:

The animation stops on the actual server-selected reward.

Suggested total duration:

2–4 seconds.

The exact duration must be configurable in config.yml.

The animation should feel smooth and polished.

---

8.4 "TIT-TIT" SELECTION SOUND

Every time the displayed reward item changes, play a short tick/tit-style sound.

Example:

Item changes → TIT

Item changes → TIT

Item changes → TIT

As the animation slows down, the time between sounds should increase.

Requirements:

  • Short sound.
  • Noticeable but not annoying.
  • Primarily audible to the player using the Cyber Key.
  • Do not broadcast every tick sound to the entire server.
  • Do not use excessive volume.
  • Sound must be configurable.
  • Pitch may change slightly during the animation.

Use an appropriate Minecraft sound supported by the configured Paper version.

---

8.5 COLORFUL PARTICLE EFFECT

During the loot animation, create a colorful particle effect around the Ominous Vault.

The particles should:

  • Spawn around the vault.
  • Form a circular/ring-like effect.
  • Rotate around the vault.
  • Move upward and/or spiral around the vault.
  • Use multiple colors.
  • Feel futuristic and energetic.
  • Become more intense near the final reveal.
  • Avoid excessive particle spam.

Preferred colors:

Cyan Purple Blue Pink Green Yellow

If RGB/Dust particles are supported by the target Minecraft version, use changing RGB colors.

Otherwise use appropriate supported colored particle types.

---

8.6 PARTICLE CIRCLE

Create an animated circular particle ring around the Ominous Vault.

Concept:

✨ ✨ ✨ ✨ ✨ VAULT ✨ ✨ ✨ ✨ ✨

The particle circle must:

  • Stay centered around the Ominous Vault.
  • Rotate smoothly.
  • Change colors over time.
  • Have particles rising upward.
  • Add some spiral particles around the vault.
  • Increase in intensity during the final reveal.

The circle should not become so large that it causes excessive particle usage.

Make radius, height, colors and particle count configurable.

---

8.7 FINAL REWARD REVEAL

When the animation finishes:

  1. Stop item cycling.
  2. Ensure the floating displayed item matches the actual server-selected reward.
  3. Keep the final reward displayed briefly.
  4. Remove the temporary floating display.
  5. Create a stronger colorful particle burst around the Ominous Vault.
  6. Play a stronger final reward sound.
  7. Display:

§e§l✦ CYBER REWARD ✦ §fYou received: §a<reward>

  1. Give exactly ONE copy of the selected reward.
  2. Ensure the reward is granted only once.
  3. Clear the current Cyber Key holder.
  4. Stop Cyber Key holder tracking.
  5. Persist the cleared holder state.
  6. Remove the interaction lock.

The final visual item MUST match the actual reward that the player receives.

---

8.8 ANTI-DUPLICATION / ANTI-EXPLOIT

The final reward must be selected exactly once.

The selected reward must remain fixed for the entire animation.

Players must NOT be able to manipulate the animation to change the reward.

Prevent:

  • Double rewards.
  • Double Cyber Key consumption.
  • Multiple animations from one click.
  • Rapid right-click exploits.
  • Multiple interaction events.
  • Duplicate scheduled tasks.
  • Reward duplication through disconnect/reconnect.
  • Reward duplication through plugin reload.
  • Reward duplication through server restart.

Use a safe per-player/per-vault interaction lock.

A player cannot start another Cyber Key Vault animation while their current animation is running.

The reward must be granted exactly once.

---

8.9 PLAYER DISCONNECT / SERVER SAFETY

If the player disconnects during the animation:

  • Cancel the animation safely.
  • Remove temporary visual entities.
  • Cancel scheduled tasks.
  • Prevent duplicate reward delivery.
  • Prevent duplicate Cyber Key consumption.
  • Handle unfinished interaction safely.

If the plugin reloads or server shuts down:

  • Cancel all active animation tasks.
  • Remove all temporary display entities.
  • Do not leave permanent entities behind.
  • Do not duplicate rewards.
  • Do not corrupt Cyber Key holder data.

---

8.10 PERFORMANCE

The animation must be optimized for an SMP.

Do NOT create a heavy task for every particle.

Use one lightweight scheduled task per active vault animation.

Use efficient particle calculations.

Do not spawn excessive particles every tick.

Clean up the task immediately when the animation finishes.

The plugin must support multiple players using different Ominous Vaults simultaneously without creating unnecessary lag.

---

  1. CYBER KEY HOLDER

At any moment there can be one current Cyber Key holder.

When:

/cyberkey give Alex

is executed:

Alex becomes the current Cyber Key holder.

Trackers configured for the Cyber Key holder automatically target Alex.

If no Cyber Key holder exists:

Display:

No Cyber Key Holder

Trackers must not point toward an invalid location.

The current holder must survive server restarts through persistent storage.

---

  1. CYBER KEY TRANSFER ON PLAYER DEATH

This is a core mechanic.

Example:

Alex = current Cyber Key holder.

Steve kills Alex.

The Cyber Key must automatically transfer to Steve.

Immediately broadcast a large RED title/subtitle announcement to ALL online players:

§c§l🔑 CYBER KEY OBTAINED

§cSteve has obtained the Cyber Key!

Use a large Title/Subtitle-style screen notification, not merely chat.

After transfer:

Alex → no longer holder Steve → new holder

All active Cyber Key trackers immediately switch to Steve.

---

  1. DEATH TRANSFER RULES

Transfer the Cyber Key ONLY when the holder is killed by another PLAYER.

Transfer must NOT happen because of:

  • Fall damage
  • Lava
  • Fire
  • Mobs
  • Natural damage
  • Commands
  • Server shutdown
  • Other non-player causes

If the holder dies and there is no valid player killer:

Do not assign the Cyber Key to an invalid entity.

Handle the state safely according to configuration.

Only a real player killer can become the new holder.

---

  1. CYBER KEY USE ENDS THE HOLDER SYSTEM

When the current Cyber Key holder successfully uses the Cyber Key on an Ominous Vault:

  • Exactly one Cyber Key is consumed.
  • The reward animation plays.
  • Exactly one configured reward is given after the animation.
  • Clear the current Cyber Key holder.
  • Stop automatic holder tracking.
  • Make trackers show no active target.
  • Persist the cleared holder state.

Until another Cyber Key is given/created, there is no current Cyber Key holder.

---

  1. TRACKER BEHAVIOR

Trackers must:

  • Be Compass items.
  • Automatically point toward the target.
  • Update when the target moves.
  • Handle player logout.
  • Handle player death.
  • Handle target changes.
  • Handle target becoming the Cyber Key holder.
  • Handle Cyber Key holder transfer.
  • Handle Cyber Key holder clearing.
  • Avoid excessive repeating tasks.
  • Avoid unnecessary packet spam.

Cross-dimension behavior:

If tracker holder and target are in different dimensions:

Display:

Target is in another dimension

Do not provide an incorrect compass direction.

If cross-dimension tracking is configured as disabled, use the same safe behavior.

---

  1. TRACKER PERSISTENT DATA

Every Tracker must contain PDC values equivalent to:

<plugin-namespace>:tracker <plugin-namespace>:tracker_name

Cyber Key:

<plugin-namespace>:cyber_key

Use NamespacedKey created from the plugin instance.

Never rely only on item names.

---

  1. ADMIN PERMISSIONS

Create permissions:

cybertracker.admin

cybertracker.tracker.create

cybertracker.tracker.give

cybertracker.tracker.manage

cybertracker.cyberkey.give

cybertracker.cyberkey.manage

Administrative commands must require appropriate permissions.

Normal players must NOT be able to create trackers, add rewards, or give Cyber Keys unless explicitly granted permission.

---

  1. COMMANDS

Tracker:

/tracker create <trackername> /tracker give <player> <trackername> /tracker give <allplayer> <trackername> /tracker add <trackername> <player> /tracker remove <trackername> <player> /tracker start <trackername> /tracker stop <trackername> /tracker info <trackername> /tracker list /tracker delete <trackername> /tracker help

Cyber Key:

/cyberkey give <player> /cyberkey remove <player> /cyberkey add /cyberkey list /cyberkey clear /cyberkey reload /cyberkey help

---

  1. TAB COMPLETION

Add proper tab completion for:

  • Tracker subcommands.
  • Cyber Key subcommands.
  • Online player names.
  • Tracker names.
  • allplayer.

Do not suggest invalid arguments.

---

  1. CONFIGURATION

Create:

config.yml

Make these configurable:

  • Tracker update interval.
  • HUD format.
  • Distance format.
  • Tracker name format.
  • Cyber Key name.
  • Messages.
  • Title/subtitle.
  • Title duration.
  • Cross-dimension behavior.
  • Reward settings.
  • Permissions.
  • Sounds.
  • Particles.
  • Holder behavior.

Also make the Cyber Vault animation configurable:

  • Animation enabled/disabled.
  • Animation duration.
  • Fast-cycle interval.
  • Medium-cycle interval.
  • Slow-cycle interval.
  • Tick/tit sound.
  • Tick sound volume.
  • Tick sound pitch.
  • Final reward sound.
  • Particle type.
  • Particle colors.
  • Particle count.
  • Particle circle radius.
  • Particle circle height.
  • Particle rotation speed.
  • Final particle burst.
  • Floating item/display settings.
  • Reward reveal message.
  • Maximum simultaneous vault animations.

Do not hard-code values that should reasonably be configurable.

---

  1. PERFORMANCE

Optimize the plugin for an SMP.

Do NOT create an expensive task for every player every tick.

Use efficient scheduled updates.

Only update tracker information when necessary.

Avoid unnecessary packet spam.

Clean up tasks/caches when:

  • Players leave.
  • Trackers are deleted.
  • Plugin reloads.
  • Holder changes.
  • Target becomes invalid.
  • Vault animations finish.

Use event-driven logic where appropriate.

---

  1. DATA PERSISTENCE

The following must survive server restarts:

  • Tracker definitions.
  • Tracker names.
  • Current Cyber Key holder.
  • Cyber Key reward pool.
  • Relevant tracker configuration.

Use safe persistent storage such as YAML/JSON or another suitable system.

When the server restarts, restore the Cyber Key holder and reward pool correctly.

Do not persist temporary animation entities or temporary animation tasks.

---

  1. ERROR HANDLING

Invalid player:

Player not found.

Invalid tracker:

Tracker not found.

Empty main hand:

You must hold an item in your main hand.

No rewards:

No Cyber Key rewards are configured.

No holder:

No Cyber Key holder currently exists.

Invalid command:

Show proper usage.

All command errors should have clear messages.

---

  1. EXAMPLE GAMEPLAY

Server starts.

Admin creates tracker:

/tracker create Hunter

Admin gives it to everyone:

/tracker give allplayer Hunter

Admin gives Cyber Key to Alex:

/cyberkey give Alex

Alex becomes the current Cyber Key holder.

Players holding active Hunter Trackers see:

🎯 Target: Alex 📍 Distance: 247m

Their Compass points toward Alex.

Admin adds rewards:

Admin holds Diamond:

/cyberkey add

Admin holds Golden Apple:

/cyberkey add

Admin holds Diamond Sword:

/cyberkey add

The reward pool now contains 3 entries.

Alex reaches an Ominous Vault.

Alex holds the custom Cyber Key and right-clicks the Ominous Vault.

The plugin intercepts the normal vanilla interaction.

The vanilla Ominous Trial Key is NOT required.

The plugin securely selects ONE reward.

Exactly ONE Cyber Key is consumed.

The Cyber Vault animation begins.

A floating visual item appears above the Ominous Vault.

The reward items rapidly cycle:

Diamond → Golden Apple → Diamond Sword → Diamond → Golden Apple → ...

A short "TIT TIT TIT" sound URGENT BUG FIX — CYBER KEY OMINOUS VAULT DOES NOTHING

The plugin builds and the other systems are working, but the Cyber Key Ominous Vault reward system is NOT working.

CURRENT BUG:

When a player holds the custom Cyber Key and right-clicks an Ominous Vault:

  • nothing happens
  • no reward is given
  • the animation does not start
  • the Cyber Key should NOT be consumed
  • the custom reward flow is not being triggered

FIX THIS AS A REAL WORKING FEATURE, NOT PSEUDOCODE.

IMPORTANT:

Target API is Paper 1.21.4.

IMPLEMENT THE VAULT INTERACTION CORRECTLY:

  1. Listen for PlayerInteractEvent.
  1. Only handle:

- Action.RIGHT_CLICK_BLOCK - EquipmentSlot.HAND - clicked block is Material.VAULT - the clicked Vault is actually ominous - player is holding the custom Cyber Key identified by PersistentDataContainer: cybertracker:cyber_key

  1. Do NOT identify Cyber Key using display name alone.
  1. When the conditions match:

event.setCancelled(true);

This MUST prevent the normal/vanilla Vault interaction from taking over the interaction.

  1. Verify that a Cyber Key reward pool exists.

If reward pool is empty: - do NOT consume the Cyber Key - do NOT give anything - do NOT start animation - send: §cNo Cyber Key rewards are configured.

  1. If reward pool is NOT empty:

- select EXACTLY ONE reward ItemStack immediately - make a safe clone of the selected ItemStack - lock this player + vault location immediately - prevent duplicate PlayerInteractEvent calls - consume exactly ONE Cyber Key - start the Cyber Vault animation

  1. The animation MUST use the already-selected reward.

The animation must NEVER randomly select the final reward again.

  1. During animation:

- show floating item visuals above the Vault - cycle through configured reward items - play tick/"tit tit" sound - spawn colorful particles - gradually slow down - final visual MUST match the already-selected reward

  1. At animation completion:

- give exactly ONE copy of the selected reward - show: §e§l✦ CYBER REWARD ✦ §fYou received: §a<reward name> - remove temporary display entities - remove particles/tasks - unlock the player/vault - clear Cyber Key holder - update trackers - save persistent state

  1. ANTI-DUPLICATION:

The same interaction must NEVER: - give two rewards - consume two keys - start two animations - trigger vanilla Vault loot - trigger both vanilla and custom reward systems

  1. Make the lock key based on:

world UUID + block X + Y + Z and also prevent the same player from starting another vault animation while one is already active.

  1. Handle BOTH:

- main-hand interaction - ignore OFF_HAND interaction

  1. Add diagnostic logging temporarily/configurably:

When a Cyber Key interacts with an Ominous Vault, log: [CyberTracker] Cyber Key Vault interaction detected [CyberTracker] Reward pool size: <size> [CyberTracker] Selected reward: <item> [CyberTracker] Animation started

  1. VERY IMPORTANT:

Verify the actual block type using: clickedBlock.getType() == Material.VAULT

Then verify the Vault block data is ominous using the Paper 1.21.4 Vault API where appropriate.

  1. Do NOT depend on the vanilla Ominous Trial Key.

The custom Cyber Key must be the only key required for this system.

  1. AFTER FIXING:

Run the complete Maven build.

Read the COMPLETE compiler output.

Fix every compilation error.

Build again.

Do not claim the bug is fixed unless the project actually compiles.

  1. Do not rewrite or break the already-working:

- tracker system - tracker commands - Cyber Key commands - reward pool storage - holder transfer - HUD - persistence

Only repair the Cyber Key + Ominous Vault interaction and its reward flow, while keeping all existing working features intact.

Kodari AI
KodariSep 25 at 2:50 pm 1
CyberKeyVault
A Minecraft Paper plugin adding a Cyber Tracker compass system and Cyber Key items. Trackers use PersistentDataContainer and point toward targets or the current Cyber Key holder with a HUD. Cyber Keys unlock Ominous Vaults with a custom animated reward system featuring floating item displays, particle effects, and configurable loot pools. Includes persistent storage, anti-duplication safeguards, and automatic holder transfer on player kills.

I can’t apply or verify this fix because the project directory is empty—there’s no source code or pom.xml to inspect or build. Please provide the project files, especially the vault interaction listener, reward/animation code, and pom.xml; then I can fix the interaction without disturbing the working systems and run the Maven build.

Kodari can make mistakes. Review important code before using.
Files

No files in this session

Code