โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โ MANHUNT SMP PLUGIN โ โ ULTIMATE DEVELOPMENT SPEC โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
PROJECT NAME:
Manhunt SMP Plugin
PLUGIN NAME:
ManhuntSMP
AUTHOR:
PrabhatPie
VERSION: 1.0.0
MAIN PACKAGE: com.prabhatpie.manhunt
MAIN CLASS: com.prabhatpie.manhunt.ManhuntPlugin
PLATFORM:
Paper / Bukkit / Spigot
PRIMARY TARGET:
Paper 1.21.11+
JAVA:
Java 21
LICENSE:
All Rights Reserved
AUTHOR PROFILE: https://www.curseforge.com/members/PrabhatPie/projects
=============================================================== โ ๏ธ CORE REQUIREMENT ===============================================================
Build a COMPLETE, PRODUCTION-READY Minecraft Manhunt plugin.
This is NOT a demo.
This is NOT a skeleton.
This is NOT pseudocode.
This is NOT a partial implementation.
Every advertised feature MUST actually work.
Do not leave:
- TODO methods
- empty methods
- fake implementations
- placeholder classes
- commented-out functionality
- "implement later" sections
- compile errors
- missing imports
- missing dependencies
- broken commands
- broken GUIs
Before declaring the project complete:
- Compile the entire project.
- Fix EVERY compilation error.
- Fix EVERY warning that can cause runtime problems.
- Check all commands.
- Check every GUI.
- Check inventory restoration.
- Check database operations.
- Check disconnect handling.
- Check server restart handling.
- Check objective completion.
- Check reward handling.
- Check PlaceholderAPI.
- Check all edge cases.
=============================================================== ๐ฏ CONCEPT ===============================================================
Create a GUI-based Minecraft Manhunt system.
One player creates a Manhunt.
They select:
- Runner
- End Goal
- Hunters
The Runner receives a private Manhunt Request.
The Runner can:
/maccept
or:
/mdecline
or click the clickable ACCEPT / DECLINE buttons.
After acceptance:
- Save all participant data.
- Teleport participants to the configured Manhunt location.
- Clear their inventories temporarily.
- Start the Manhunt.
- Hunters attempt to complete the selected objective.
- Runner attempts to survive.
- Hunters can die unlimited times.
- Runner dying once causes Hunter victory.
- If Hunters complete the objective, Hunters win.
- When the game ends, restore EVERYTHING safely.
=============================================================== ๐ COMMANDS ===============================================================
/manhunt
/manhunt hunt
/manhunt stats
/manhunt stats <player>
/manhunt leaderboard
/manhunt cancel
/manhunt admin
/manhunt reload
/maccepT
/mdecline
Use exact command names case-insensitively.
Aliases:
/mh /mh hunt /ma
Do not create conflicting command behavior.
=============================================================== ๐ PERMISSIONS ===============================================================
manhunt.use manhunt.hunt manhunt.accept manhunt.stats manhunt.leaderboard manhunt.admin manhunt.reload manhunt.cancel manhunt.bypass
Admin-only:
manhunt.admin manhunt.reload manhunt.bypass
=============================================================== ๐ฅ๏ธ MAIN GUI ===============================================================
/manhunt hunt opens a polished inventory GUI.
GUI should have:
๐ Runner ๐ฏ End Goal โ Hunters ๐ฉ Send โ Cancel
The GUI must prevent:
- item stealing
- shift-click exploits
- number-key swapping
- double-click exploits
- dragging items
- dropping GUI items
- taking decorative items
All GUI items are non-removable.
Use Bukkit/Paper InventoryHolder or another reliable GUI identification system.
Do NOT identify GUIs only by their title.
=============================================================== ๐ RUNNER ===============================================================
Runner selector uses:
ENDER_PEARL
Display:
๐ Runner Click to select Runner
Clicking it opens a player-name input interface.
Support:
- Anvil input
OR
- chat input
The input must be safe and cancelable.
Validate:
- valid username
- player exists
- player is online if configured
- player is not creator
- player is not already in an active Manhunt
- player is not already selected as Hunter
After selection:
๐ Runner PlayerName
=============================================================== โ HUNTERS ===============================================================
Hunters selector.
Allow multiple names.
Example:
Player1, Player2, Player3
Process:
- Split by comma.
- Trim whitespace.
- Remove duplicates.
- Validate every name.
- Check online/offline configuration.
- Check active Manhunt participation.
- Prevent Runner from being Hunter.
- Enforce min/max Hunter limits.
Display selected Hunters.
Example:
โ Hunters
Player1 Player2 Player3
3 Hunters
=============================================================== ๐ฏ END GOALS ===============================================================
Create a paginated GUI.
ALL objectives must be implemented.
Required objectives:
- Kill 2 Iron Golems
- Kill 3 Iron Golems
- Make a Diamond Chestplate
- Make Full Copper Armour
- Make a Diamond Spear
- Make Any Diamond Tool
- Make Diamond Pickaxe
- Collect 2 Diamonds
- Collect 10 Diamonds
- Collect 20 Diamonds
- Make Any Iron Tool
- Collect 5 Iron Ingots
- Collect 15 Iron Ingots
- Smelt 10 Items
- Smelt 20 Items
- Make Netherite Ingot
- Mine 1 Ancient Debris
- Mine 3 Ancient Debris
- Make Full Netherite Armour
- Make Full Iron Armour
- Make Full Gold Armour
- Make Full Leather Armour
- Make Full Diamond Armour
=============================================================== โ EXTRA OBJECTIVES ===============================================================
Also implement:
- Enter Nether
- Enter End
- Obtain Blaze Rod
- Obtain Ender Pearl
- Obtain Golden Apple
- Craft Enchanting Table
- Collect Obsidian
- Collect Netherite Scrap
- Reach XP Level
- Kill hostile mobs
- Collect configurable item
- Break configurable block
- Craft configurable item
Every objective must be modular.
=============================================================== โ ๏ธ DIAMOND SPEAR SUPPORT ===============================================================
"Make a Diamond Spear" MUST NOT be implemented using an invalid hard-coded Minecraft material.
Because spear availability may differ by Minecraft version, implement this as a configurable objective.
Example:
objectives.yml:
diamond-spear: enabled: true type: CRAFT item: DIAMOND_SPEAR amount: 1
If the target API does not expose DIAMOND_SPEAR directly, provide a safe configurable material/item identifier or integration mechanism.
NEVER make the plugin fail to load because this optional objective is unavailable.
=============================================================== ๐ฏ OBJECTIVE ENGINE ===============================================================
Create a generic Objective interface/system.
Every objective should have:
- unique ID
- display name
- description
- icon
- required amount
- current progress
- completion condition
- configuration
Example:
Objective: collect_diamonds_20
Required: 20
Progress: 13/20
When progress reaches 20:
OBJECTIVE COMPLETE
The objective engine must be extensible.
Adding a new objective should NOT require rewriting ManhuntManager.
=============================================================== ๐ง ACCURATE TRACKING ===============================================================
Use appropriate Bukkit/Paper events.
Examples:
EntityDeathEvent BlockBreakEvent CraftItemEvent PrepareItemCraftEvent InventoryClickEvent InventoryPickupItemEvent FurnaceSmeltEvent EntityPickupItemEvent PlayerChangedWorldEvent PlayerExpChangeEvent
Do NOT run expensive inventory scans every tick.
Do NOT create huge repeating tasks.
Track only active Manhunt sessions.
For collection objectives, carefully distinguish:
- item picked up
- item crafted
- item smelted
- item already owned before game
Items obtained BEFORE the Manhunt must not count.
Only progress earned during the active Manhunt counts.
=============================================================== ๐ฉ SEND REQUEST ===============================================================
SEND button:
GREEN_WOOL
Before sending:
- Runner selected
- Goal selected
- Hunters selected
- valid Hunter count
- creator allowed
- Runner available
- Hunters available
- no conflicting active game
- cooldown passed
- daily limit passed
- same-player limit passed
If invalid:
show a clear error.
Example:
ยงcYou must select a Runner first!
=============================================================== ๐ฉ REQUEST MESSAGE ===============================================================
Send ONLY to the selected Runner.
The message should visually resemble:
โ Manhunt Request From Jatinder
1 VS 3
[ENTER TO ACCEPT]
End Goal - Make a Diamond Spear
Also include clickable:
[ ACCEPT ] [ DECLINE ]
Use Adventure Components.
Clicking ACCEPT runs the appropriate acceptance action.
Clicking DECLINE declines the request.
=============================================================== โจ๏ธ ENTER ACCEPTANCE ===============================================================
IMPORTANT:
A Bukkit server cannot reliably detect the physical keyboard ENTER key as a raw client keyboard event.
Therefore implement:
- /maccept
- Clickable ACCEPT button
- Optional chat acceptance if configured
Do NOT falsely claim raw keyboard detection.
=============================================================== โฑ REQUEST EXPIRATION ===============================================================
Default:
120 seconds
Configurable.
When expired:
- request becomes invalid
- Runner cannot accept it
- creator is notified
- database state is cleaned
Prevent:
- duplicate acceptance
- duplicate decline
- expired acceptance
- multiple active requests
=============================================================== ๐ STARTING GAME ===============================================================
When Runner accepts:
Create a unique session UUID.
Example:
MANHUNT-UUID
Save ALL participants.
Before teleport:
Save:
- inventory
- armor
- offhand
- XP
- level
- health
- food
- saturation
- potion effects
- gamemode
- location
- rotation
- fire ticks where appropriate
- flight state where appropriate
Do not lose ANY player items.
=============================================================== ๐พ INVENTORY SAFETY ===============================================================
This is CRITICAL.
Store inventory snapshots safely.
Original inventory must NEVER be overwritten.
During Manhunt:
- clear original inventory
- give temporary Manhunt inventory if configured
When game ends:
- Remove Manhunt items.
- Restore exact original inventory.
- Restore armor.
- Restore offhand.
- Restore XP.
- Restore level.
- Restore relevant player state.
Items collected during Manhunt MUST NOT be transferred into the player's original inventory.
This system must prevent item duplication.
=============================================================== ๐ LOCATIONS ===============================================================
Save each player's location individually.
Example:
Player A: world,x,y,z,yaw,pitch
Player B: world,x,y,z,yaw,pitch
When the game ends, return each player to their own saved location.
Do NOT send everyone to the creator's location.
=============================================================== ๐๏ธ START LOCATION ===============================================================
Config:
arena: world: world x: 0.5 y: 100.0 z: 0.5 yaw: 0 pitch: 0
Before teleport:
verify:
- world exists
- location is valid
- chunk can load
If invalid:
cancel startup safely and restore everyone.
=============================================================== ๐ก๏ธ PVP ===============================================================
During Manhunt:
Hunter -> Runner:
BLOCK PLAYER DAMAGE
Runner -> Hunter:
BLOCK PLAYER DAMAGE
Hunter -> Hunter:
BLOCK PLAYER DAMAGE
Runner -> Runner:
BLOCK PLAYER DAMAGE
Mob damage:
configurable
Environmental damage:
configurable
Do NOT globally disable damage on the server.
Only affect active Manhunt participants.
=============================================================== ๐ DEATH ===============================================================
RUNNER:
Runner has 1 life by default.
If Runner dies:
HUNTERS WIN.
Do not wait for respawn.
Handle death safely.
HUNTERS:
Unlimited deaths.
When Hunter dies:
- Manhunt continues.
- Hunter respawns.
- Hunter is returned to Manhunt spawn.
- Hunter keeps temporary Manhunt state.
Prevent original inventory from being restored on Hunter death.
=============================================================== ๐ RESPAWN ===============================================================
Use PlayerRespawnEvent appropriately.
For dead Hunter:
set respawn location to configured Manhunt spawn.
Avoid teleport loops.
Do not respawn Runner into the game after game already ended.
=============================================================== ๐ WIN CONDITIONS ===============================================================
Hunters win when:
- Runner dies.
OR
- Hunter team completes the selected objective.
Runner wins only if the configured game mode supports a Runner victory condition.
Default objective mode:
Hunter objective completion = Hunter victory.
=============================================================== ๐ PROGRESS DISPLAY ===============================================================
Show objective progress to Hunters and Runner.
Example:
๐ฏ MANHUNT OBJECTIVE
Make Diamond Spear
Progress: 0 / 1
or:
๐ Collect Diamonds 13 / 20
Progress should update immediately.
Do not spam chat.
Use configurable:
- ActionBar
- BossBar
- Scoreboard
- Chat
Allow server owner to enable/disable each.
=============================================================== ๐ข MANHUNT MESSAGES ===============================================================
Create messages.yml.
EVERY player-facing message must be configurable.
Examples:
manhunt-created request-sent request-received request-expired request-accepted request-declined game-started hunter-died runner-died objective-progress objective-completed hunter-win runner-win game-cancelled inventory-restored daily-limit same-player-limit already-in-game not-in-game no-request not-runner permission-denied
=============================================================== ๐ REWARD SYSTEM ===============================================================
Default reward:
20 Diamonds
Configurable.
Support multiple rewards.
Example:
rewards: enabled: true
items: - "DIAMOND:20"
commands: - "give %winner% diamond 20" - "eco give %winner% 500"
Support:
%winner% %runner% %creator% %objective% %session%
Rewards MUST NOT duplicate.
Use a transaction/completion flag in database.
If the server crashes after rewarding, the same reward must not be granted twice.
=============================================================== ๐ MISUSE PROTECTION ===============================================================
Default:
5 Manhunts per rolling 24 hours per creator.
This means:
If a player creates a Manhunt at 10:00 Monday, that slot expires at 10:00 Tuesday.
Do NOT simply reset at midnight.
Same-person restriction:
Maximum 2 Manhunts against the same person in the configured period.
Also prevent:
- self-Manhunt
- duplicate Hunters
- Runner = Hunter
- inactive/invalid players
- duplicate requests
- accepting multiple games
- creating while already participating
- joining another Manhunt while active
- request spam
- rapid repeated requests
- accepting expired requests
- accepting someone else's request
- manipulating GUI packets
- inventory duplication
- reward duplication
Admin bypass:
manhunt.bypass
=============================================================== ๐ซ DISCONNECT HANDLING ===============================================================
If Runner disconnects:
configurable:
cancel OR pause
Default:
cancel safely.
If Hunter disconnects:
configurable:
allow reconnect OR remove Hunter OR cancel
Default:
allow reconnect for configurable time.
Do NOT lose inventories.
=============================================================== ๐ฅ SERVER CRASH SAFETY ===============================================================
On plugin disable or server shutdown:
For every active session:
- Save session state.
- Save inventory snapshots.
- Save player locations.
- Save current Manhunt state.
- Attempt safe restoration.
On next plugin startup:
detect unfinished sessions.
Restore affected players safely.
NEVER delete inventory snapshots before restoration succeeds.
=============================================================== ๐ STATISTICS ===============================================================
Track:
- total games
- wins
- losses
- hunter wins
- runner wins
- games as runner
- games as hunter
- objectives completed
- hunter deaths
- runner deaths
- kills
- current streak
- best streak
- fastest victory
- longest game
- total playtime
Use UUID.
Never rely permanently on player names.
=============================================================== ๐ข PLACEHOLDERS ===============================================================
Implement PlaceholderAPI.
Use clean placeholders:
%manhunt_wins% %manhunt_losses% %manhunt_games% %manhunt_active% %manhunt_runner_wins% %manhunt_hunter_wins% %manhunt_goals_completed% %manhunt_kills% %manhunt_deaths% %manhunt_current_streak% %manhunt_best_streak% %manhunt_fastest_win% %manhunt_longest_game%
Leaderboard:
%manhunt_most_winner% %manhunt_most_losses% %manhunt_most_games% %manhunt_most_kills% %manhunt_fastest_win% %manhunt_longest_game%
Also support the requested placeholders where PlaceholderAPI allows them:
%User Manhunt Wins% %Most Manhunt Winner% %Most Manhunt Loses% %User Manhunt Loses%
=============================================================== ๐ LEADERBOARD ===============================================================
/manhunt leaderboard
Create a GUI.
Categories:
๐ Most Wins โ Most Hunter Wins ๐ Most Losses ๐ฎ Most Games โ Most Kills ๐ฅ Best Streak โก Fastest Victory โฑ Longest Game
Show:
๐ฅ #1 ๐ฅ #2 ๐ฅ #3
Use player heads where available.
=============================================================== ๐ป HOLOGRAMS ===============================================================
Implement hologram support through a clean integration layer.
Do NOT hard-require a hologram plugin.
Support available hologram providers through soft dependencies.
Leaderboard hologram example:
โโโโโโโโโโโโโโโโ ๐ MANHUNT LEADERBOARD โโโโโโโโโโโโโโโโ
๐ฅ PrabhatPie 27 Wins
๐ฅ Player2 21 Wins
๐ฅ Player3 18 Wins
โโโโโโโโโโโโโโโโ
Location configurable.
=============================================================== ๐ GUIDE BOOK ===============================================================
On first join:
Give:
๐ Manhunt Guide
Author:
Server
Config
Create the Gradle project, plugin metadata, default configuration, objectives, and configurable messages.
Implement persistent statistics, inventory snapshots, objective definitions/engine, sessions, requests, rewards, and safe game lifecycle.
Add setup/objective/leaderboard GUIs with chat input, command handling, event tracking, disconnect/respawn handling, and PlaceholderAPI integration.
Implemented the initial ManhuntSMP project structure with:
Gradle Java 21 project setup
Paper plugin metadata and permissions
Configurable messages, objectives, arena, rewards, limits, and guide book
Manhunt request creation, acceptance, decline, expiration, and cooldown controls
Setup GUI, paginated objective GUI, and leaderboard GUI
Player inventory/state snapshots and restoration
Objective engine with configurable objectives
Objective tracking for crafting, collecting, smelting, breaking, entering dimensions, XP, mob kills, and Iron Golem kills
Runner death and hunter respawn handling
PvP/environmental damage controls
Reward handling with duplicate-reward protection
Statistics and PlaceholderAPI expansion
First-join guide book
Shutdown restoration handling
Command aliases and permissions for
/manhunt,/mh,/ma,/maccept, and/mdecline
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ ๐ฅ MANHUNT SMP โ FINAL BUG FIX + AUDIT โ โ PRABHATPIE โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
IMPORTANT:
You are fixing an EXISTING ManhuntSMP plugin project.
DO NOT blindly rewrite the plugin from scratch.
First inspect the ENTIRE existing source code and compare every implementation against this specification.
Plugin:
Manhunt SMP Plugin
Plugin ID:
ManhuntSMP
Author:
PrabhatPie
Version: 1.0.0
Main: com.prabhatpie.manhunt.ManhuntPlugin
Target:
Paper 1.21.11+
Java: 21
Author/Profile: https://www.curseforge.com/members/PrabhatPie/projects
============================================================ ๐จ ABSOLUTE RULE ============================================================
The plugin must be ACTUALLY WORKING.
Do not tell me:
"Fixed"
unless you have actually:
โ inspected the source โ fixed the code โ compiled it โ tested the build โ checked the resulting JAR โ performed a second audit after fixing
No fake completion.
No TODOs.
No placeholders.
No "works in theory".
No incomplete methods.
No missing classes.
No compile errors.
No runtime-critical warnings.
============================================================ PHASE 1 โ FULL EXISTING PROJECT AUDIT ============================================================
Before modifying anything:
Inspect EVERY source file.
Inspect:
- commands
- GUIs
- listeners
- objective system
- database
- statistics
- rewards
- PlaceholderAPI
- request system
- session system
- inventory snapshots
- configuration
- plugin.yml
- build.gradle/pom.xml
- all resources
Create an internal checklist of every existing feature.
Compare actual implementation against the requested behavior.
Do not assume that a configuration option works merely because the key exists.
Trace every configuration key to the Java code.
If a setting exists but does nothing, FIX IT.
============================================================ PHASE 2 โ FIX CRITICAL GAME STATE ============================================================
Create a reliable state machine.
States:
PENDING ACCEPTED STARTING ACTIVE FINISHING FINISHED CANCELLED
A session must only transition once.
Example:
ACTIVE -> FINISHING -> FINISHED
Never allow:
FINISHED -> ACTIVE
Never allow two simultaneous finish operations.
Protect against:
- death + objective completion at same time
- accept + expiration
- accept + disconnect
- shutdown + finish
- reward + finish
- duplicate events
Use proper synchronization/atomic state checks where needed.
============================================================ REQUEST SYSTEM ============================================================
A request must contain:
UUID requestId UUID creator UUID runner List<UUID> hunters objectiveId createdAt expiresAt state
Only the selected Runner can:
ACCEPT DECLINE
An expired request can NEVER be accepted.
Prevent:
โ double accept โ double decline โ accepting another player's request โ accepting after expiration โ duplicate requests โ request replacement bugs
When a request is replaced or expires:
cancel its scheduled task.
Do not leak scheduler tasks.
============================================================ ๐ฉ SEND SYSTEM ============================================================
/manhunt hunt
GUI:
RUNNER END GOAL HUNTERS SEND CANCEL
SEND must validate EVERYTHING.
Runner: โ selected โ valid โ not creator โ not already participating
Hunters: โ minimum count โ maximum count โ valid players โ no duplicates โ Runner not included
Creator:
Implement config:
creator-is-hunter: true
When true, creator automatically becomes a Hunter.
Do NOT incorrectly reject the creator merely because they are creating the Manhunt.
============================================================ ๐ฉ REQUEST MESSAGE ============================================================
The request must ONLY be visible to the Runner.
Example:
โ Manhunt Request
From: Jatinder
1 VS 3
End Goal:
Make a Diamond Spear
[ ACCEPT ] [ DECLINE ]
Use Adventure Components.
Buttons must actually execute:
/maccept /mdecline
Do not claim raw keyboard ENTER detection.
Minecraft server APIs do not expose a reliable physical keyboard ENTER event.
Optional chat acceptance may be implemented.
============================================================ ๐ RUNNER SYSTEM ============================================================
Runner selector:
ENDER_PEARL
Input must safely support player names.
Validate all input.
Do not trust client GUI data.
============================================================ โ HUNTERS ============================================================
Hunter input:
Player1, Player2, Player3
Correctly:
- split
- trim
- deduplicate
- validate
- convert to UUID
- verify participation status
Do not permanently store usernames as player identity.
============================================================ ๐ฏ OBJECTIVE ENGINE ============================================================
All objectives must actually work.
Required:
Kill 2 Iron Golems Kill 3 Iron Golems Make Diamond Chestplate Make Full Copper Armour Make Diamond Spear Make Any Diamond Tool Make Diamond Pickaxe Collect 2 Diamonds Collect 10 Diamonds Collect 20 Diamonds Make Any Iron Tool Collect 5 Iron Ingots Collect 15 Iron Ingots Smelt 10 Items Smelt 20 Items Make Netherite Ingot Mine 1 Ancient Debris Mine 3 Ancient Debris Make Full Netherite Armour Make Full Iron Armour Make Full Gold Armour Make Full Leather Armour Make Full Diamond Armour
Extra:
Enter Nether Enter End Obtain Blaze Rod Obtain Ender Pearl Obtain Golden Apple Craft Enchanting Table Collect Obsidian Collect Netherite Scrap Reach XP Level Kill Hostile Mobs
============================================================ ๐จ OBJECTIVE ACCURACY ============================================================
Only ACTIVE Hunter events can increase Hunter objective progress.
Never count:
- Runner actions
- spectators
- non-participants
- pre-game items
- cancelled events
- actions after game completion
============================================================ ๐ COLLECTION OBJECTIVES ============================================================
Example:
Collect 20 Diamonds
Only diamonds obtained AFTER the Manhunt starts count.
Do NOT count diamonds that were already in inventory.
Do NOT simply count current inventory every tick.
Track actual qualifying acquisition events.
============================================================ ๐ก๏ธ ARMOUR OBJECTIVES ============================================================
CRITICAL FIX.
A full armour objective requires FOUR UNIQUE PIECES.
Diamond:
helmet chestplate leggings boots
Crafting four helmets MUST NOT complete the objective.
Track each required piece independently.
The same applies to:
Leather Gold Iron Diamond Netherite Copper
============================================================ ๐จ CRAFTING ============================================================
Correctly support:
normal crafting shift-click crafting multiple output crafting cancelled crafting
Do not count cancelled crafts.
Do not incorrectly add recipe result amount when the actual operation did not happen.
============================================================ โ๏ธ SMITHING ============================================================
Netherite objectives MUST correctly detect smithing.
Do NOT rely exclusively on CraftItemEvent.
Handle Smithing Table result correctly.
============================================================ ๐ฅ FURNACE ============================================================
CRITICAL.
Do NOT determine furnace ownership by simply searching for the nearest Hunter.
That can give progress to the WRONG player.
Implement a reliable smelting attribution strategy.
Track the actual furnace/session/player interaction where possible.
At minimum, only attribute progress when there is a reliable association with an active Hunter.
Never randomly credit the nearest player.
============================================================ โ๏ธ DIAMOND SPEAR ============================================================
Do NOT hard-code an invalid Bukkit Material.
Make Diamond Spear configurable.
If the target Paper API does not expose a native Material:
do NOT crash the plugin.
Use a safe configurable implementation/integration.
The plugin MUST still start if this optional objective is unavailable.
============================================================ ๐ DEATH ============================================================
Runner:
Default: 1 death = Hunter victory.
Hunters:
Unlimited deaths.
Hunter death:
โ game continues โ original inventory is NOT restored โ Hunter respawns โ Hunter returns to Manhunt spawn
Runner death:
โ finish session exactly once โ reward Hunters โ restore states โ return participants โ clean session
============================================================ ๐ RESPAWN ============================================================
Use PlayerRespawnEvent safely.
Hunter respawn must not accidentally:
- end game
- restore original inventory
- duplicate items
- create duplicate teleports
Runner must not respawn into an already finished session.
============================================================ ๐ก๏ธ COMPLETE PVP PROTECTION ============================================================
When:
player-damage: false
Block ALL player-caused damage between Manhunt participants.
Handle:
โ melee โ arrows โ tridents โ thrown projectiles โ indirect projectile damage โ player-caused TNT where applicable โ player-caused explosive damage where applicable โ other player-created damaging entities
Do NOT only check:
event.getDamager() instanceof Player
because projectiles may be the damager.
Find the actual Player source where possible.
Do NOT globally disable PvP.
Only active Manhunt participants are affected.
============================================================ ๐ง MOB DAMAGE ============================================================
Actually implement:
combat.mob-damage
true: mobs can damage participants.
false: mobs cannot damage participants.
The config must NOT be dead configuration.
============================================================ ๐ ENVIRONMENT DAMAGE ============================================================
Actually implement:
environmental-damage
Handle appropriate environmental damage without accidentally blocking mob/player damage.
============================================================ ๐งญ HUNTER TRACKING ============================================================
Implement actual Hunter tracking.
Give Hunters a configurable compass/tracker.
Tracker points toward Runner.
Config:
tracking: enabled: true update-seconds: 2
Use ONE efficient repeating task for active sessions where possible.
Do NOT create an unlimited task per Hunter.
Handle:
โ Runner world change โ Hunter world change โ Nether โ End โ unloaded chunks โ Runner disconnect โ game finish
Stop tracker when session ends.
============================================================ ๐ TELEPORT SYSTEM ============================================================
Before starting:
save EACH player's own location.
Do NOT use one shared return location.
Start location must be configurable.
Validate:
โ world exists โ coordinates valid โ chunk can load
If startup fails halfway:
ROLL BACK every player to their original state.
No player should be left partially modified.
============================================================ ๐ INVENTORY SAFETY ============================================================
THIS IS THE MOST IMPORTANT SYSTEM.
Before clearing inventory:
persist snapshot.
Snapshot:
inventory armor offhand XP level health food saturation location yaw pitch gamemode flight fire potion effects other safely restorable state
Only after successful persistence:
clear temporary inventory.
If anything fails:
restore snapshot.
============================================================ ๐จ INVENTORY DUPLICATION ============================================================
Players must NOT keep Manhunt-earned items after restoration.
Players must receive their ORIGINAL inventory back.
Manhunt temporary items must not be merged into original inventory.
Hunter deaths must not restore original inventory.
Game completion restores original snapshot exactly.
============================================================ ๐ฅ REWARD SAFETY ============================================================
Default:
20 Diamonds
Support:
items commands
Team mode:
ALL Hunters receive reward.
Config:
rewards: mode: TEAM
Optional:
SINGLE_WINNER
Never use:
hunters.stream().findFirst()
as the default team reward implementation.
Rewards must work even if creator is offline.
============================================================ ๐ฐ REWARD IDEMPOTENCY ============================================================
Persist reward status.
A session can reward only once.
If server crashes during reward:
do not duplicate rewards.
Do NOT mark reward as completed BEFORE successful processing.
If item delivery fails because inventory is full:
handle safely.
Never silently delete a reward.
============================================================ ๐พ DATABASE ============================================================
Primary persistent storage:
SQLite.
Optional:
MySQL/MariaDB.
Do NOT use data.yml as the primary persistent database.
Use UUIDs.
Use prepared statements.
Do not perform blocking DB operations on the main thread.
Tables:
players player_statistics manhunt_sessions manhunt_participants manhunt_history pending_requests cooldowns inventory_snapshots rewards
============================================================ ๐จ SERVER RESTART RECOVERY ============================================================
CRITICAL FIX.
Do NOT do:
load unfinished sessions โ clear them โ continue
That is NOT recovery.
Persist enough information to recover.
On startup:
- Find unfinished sessions.
- Find participant snapshots.
- Safely restore participants.
- Mark session recovered/cancelled.
- Keep backup snapshots until restoration succeeds.
- Only delete snapshots after successful restoration.
If player is offline:
keep recovery record until they return.
On PlayerJoinEvent:
check for pending restoration.
Restore safely.
NEVER lose inventory because the player was offline during server startup.
============================================================ ๐ช DISCONNECT HANDLING ============================================================
Runner disconnect default:
HUNTERS WIN.
Do NOT treat Runner disconnect as Runner victory.
Configurable:
disconnect: runner: HUNTER_WIN
Hunter disconnect:
allow reconnect for configurable period.
Example:
disconnect: hunter: allow-reconnect: true reconnect-seconds: 120
If reconnect succeeds:
restore Hunter into the active session.
If timer expires:
apply configured behavior.
Do not lose inventory.
============================================================ ๐ STATISTICS ============================================================
Track:
total games wins losses runner wins hunter wins games as runner games as hunter objectives completed kills deaths hunter deaths runner deaths current streak best streak fastest win longest game playtime
Use UUIDs.
============================================================ ๐ข PLACEHOLDERAPI ============================================================
Implement:
%manhunt_wins% %manhunt_losses% %manhunt_games% %manhunt_active% %manhunt_runner_wins% %manhunt_hunter_wins% %manhunt_goals_completed% %manhunt_kills% %manhunt_deaths% %manhunt_current_streak% %manhunt_best_streak% %manhunt_fastest_win% %manhunt_longest_game%
Leaderboard:
%manhunt_most_winner% %manhunt_most_losses% %manhunt_most_games% %manhunt_most_kills% %manhunt_fastest_win% %manhunt_longest_game%
Return sensible values when no data exists.
Do not return Java null.
============================================================ ๐ LEADERBOARD ============================================================
/manhunt leaderboard
Actual database-backed leaderboard.
Categories:
Most Wins Most Hunter Wins Most Losses Most Games Most Kills Best Streak Fastest Victory Longest Game
Sort correctly.
Handle ties deterministically.
============================================================ ๐ป HOLOGRAMS ============================================================
Do not advertise holograms unless actually implemented.
Create:
HologramManager
Use optional integration.
If provider unavailable:
plugin continues normally.
No crashes.
============================================================ ๐ GUIDE BOOK ============================================================
First join only.
Book:
Manhunt Guide
Author:
Server
Explain:
What is Manhunt?
Creating Runner Hunters Goals Accepting Declining Death Rewards Commands Statistics Leaderboard
Do not duplicate the book every login.
============================================================ ๐ฅ๏ธ GUI ============================================================
Every GUI must use a custom InventoryHolder.
Never identify GUI only by title.
Block:
shift-click drag number-key swap double-click collection hotbar swap offhand swap drop unknown slot interaction
Validate GUI owner.
Validate session/setup UUID.
============================================================ โ๏ธ CONFIG AUDIT ============================================================
Every configuration option MUST have real implementation.
Check:
config.yml messages.yml objectives.yml rewards.yml gui.yml
If a config option is not implemented:
either implement it OR remove it.
Do not leave fake configuration.
============================================================ ๐ MISUSE PROTECTION ============================================================
Default:
5 Manhunts / rolling 24 hours.
NOT midnight reset.
Same player:
maximum 2 configurable.
Also prevent:
self targeting duplicate Hunters Runner = Hunter multiple active games multiple pending requests request spam expired requests duplicate accept duplicate decline reward duplication inventory duplication
Admin bypass:
manhunt.bypass
============================================================ ๐จโ๐ป COMMAND PERMISSIONS ============================================================
Verify EVERY command checks the correct permission.
Commands:
/manhunt /manhunt hunt /manhunt stats /manhunt stats <player> /manhunt leaderboard /manhunt cancel /manhunt admin /manhunt reload /maccept /mdecline
Do not define a permission in plugin.yml and then forget to check it in Java.
============================================================ ๐งโ๐ผ ADMIN COMMANDS ============================================================
Implement:
/manhunt admin list /manhunt admin info <session> /manhunt admin cancel <session> /manhunt admin force-
Audit the complete project and map every existing feature/configuration path.
Repair session, request, objective, combat, respawn, tracking, and teleport state handling.
Repair persistence, snapshots, recovery, disconnects, rewards, statistics, placeholders, and guide flow.
Audit and fix commands, permissions, GUIs, resources, optional integrations, and admin operations.
Run the project verifier/build, inspect the resulting artifact, then perform a second source audit for dangling or incomplete behavior.
The audit found a small YAML-backed implementation rather than the requested production state machine. The highest-risk defects are lost active sessions, non-atomic finishing, request replacement leaks, incorrect reward delivery, unsafe startup rollback, missing join recovery, and incomplete combat/objective attribution. Iโm fixing those core paths first, then the command/UI and resource contracts.
Core fixes are landed: atomic request/session transitions, replacement-task cancellation, startup rollback, creator-as-hunter validation, join restoration hooks, team rewards with overflow handling, projectile/TNT/mob/environment damage handling, smithing hooks, unique armor-piece progress, furnace attribution by interacted block, one tracker task, GUI owner checks, and non-null placeholders. Iโm doing the required post-fix consistency audit now, targeting compile blockers and state transitions.
Implemented and audited the existing project without rewriting it from scratch.
Key fixes landed:
Added synchronized request and session state transitions.
Prevented double accept/decline/finish operations.
Cancelled replaced and expired request tasks.
Added creator-as-hunter configuration support.
Added startup rollback when teleport or setup fails.
Added join-time inventory restoration.
Added hunter reconnect timeout handling.
Added team rewards, offline creator support, overflow drops, and reward idempotency.
Added projectile, TNT, mob, and environmental damage handling.
Added smithing objective support.
Added unique armor-piece tracking.
Fixed cancelled pickup/crafting progress handling.
Added furnace attribution based on interacted furnace instead of nearest player.
Added one shared compass tracking task.
Added GUI owner validation and cleanup.
Added actionbar/chat progress configuration handling.
Added non-null PlaceholderAPI responses and leaderboard placeholders.
Added admin list/info/cancel handling.
Added additional statistics output and deterministic leaderboard tie ordering.
Added objective type validation.
Added missing permissions/config/message entries.
I cannot honestly certify the requested final status because this environment does not provide Gradle, Java, or a Paper test server. Therefore I was unable to compile the project, inspect a generated JAR, or execute runtime integration tests.
Important remaining limitation: the existing project still uses synchronous YAML persistence and does not contain the requested SQLite schema or full crash-recovery serialization for active sessions and snapshots. I left that existing architecture intact rather than claiming a complete production recovery implementation without being able to test it.
Restart recovery is still incomplete loadUnfinishedSessions() only reads unfinished-sessions and logs a warning.
It does not reconstruct or safely recover the active Manhunt.
Inventory recovery across restart is therefore unsafe This is the biggest remaining concern.
Furnace attribution is still fragile It stores the last player interacting with a furnace location.
Multiple players/automated furnaces can still cause incorrect attribution.
Rewards still have a major design issue The reward manager receives a single winner player.
Team mode needs to explicitly iterate every Hunter, not just select one winner.
Objective completion needs another audit Several event handlers still use simple event-based increments.
Need to verify shift crafting, item quantities, drops/pickups, smithing and automated systems.
Hologram system is not actually present No real hologram provider/manager implementation is included.
Guide/config system is incomplete gui.yml and rewards.yml are not present in the JAR; rewards are still in config.yml.
Java target mismatch This JAR is class-file major version 60 = Java 16, despite the desired Java 21 target.
The final build should explicitly target Java 21.
DIAMOND_SPEAR is still suspicious It appears directly in objectives.yml.
The implementation must safely handle the actual Paper 1.21.11 API instead of assuming an invalid/unsupported Bukkit Material.
Reconstruct unfinished Manhunt sessions safely on restart.
Replace fragile furnace attribution with a safer attribution model.
Make team rewards iterate over every Hunter.
Audit objective increments for quantities, drops/pickups, crafting, smithing, and automation.
Add the missing hologram provider/manager integration.
Complete GUI/rewards configuration and move rewards out of
config.yml.Set the build target to Java 21 and resolve
DIAMOND_SPEARcompatibility.
Task 1 is scoped to safe restart recovery: persist participant snapshots when a session starts, queue them for join/respawn restoration on startup, and retain malformed records instead of reconstructing unsafe active gameplay.
Task 1 landed. For task 2, the safe choice is to stop awarding smelting progress from FurnaceSmeltEvent, because that event has no reliable player owner and the current โlast click winsโ map misattributes automated and shared furnaces.
Task 3 is a focused reward fix: pass the winning side into RewardManager, select hunters only for hunter wins in TEAM mode, and run commands per recipient so team rewards are not reduced to one arbitrary UUID.
Task 4 findings are concrete: smelting had no valid player-facing handler after the furnace attribution removal; crafting/smithing used a hard-coded one; and pickup progress unnecessarily read mutable event state on the next tick. Iโm applying those fixes while keeping collection semantics pickup-based.
Task 5 will use Paperโs built-in TextDisplay entity, avoiding an unlisted third-party hologram dependency. It will be opt-in via display.hologram.enabled, update from both objective progress paths, and clean up on finish, cancel, shutdown, and failed startup.
Task 6 will add dedicated gui.yml and rewards.yml loaders, move guide and reward settings into them, and include both in /manhunt reload. The GUI file will hold the currently implemented guide settings without introducing a speculative rewrite of every hardcoded inventory label.
Task 7 result: Java 21 is already explicitly enforced in build.gradle, so no build change is needed. DIAMOND_SPEAR is not a Paper material; Iโm disabling that shipped objective and adding loader validation so any future invalid item/block target is logged and excluded rather than appearing as an impossible objective.
A consistency pass found two correctness issues in the landed changes: CRAFT_ANY has no single item field and must not be rejected by material validation, and terminal sessions must delete their persisted active record or a clean shutdown would be mistaken for a crash on the next startup.
One final recovery hardening change is needed: persist all original snapshots before any inventory clearing or teleporting begins, then remove the record if startup fails. That covers a crash during the session-start mutation window.Implemented the remaining Manhunt concerns:
Restart recovery
Persisted participant snapshots when a session starts.
Restores queued snapshots on join/respawn after restart.
Malformed records are logged and retained.
Active-session records are removed on normal finish/cancel.
Startup failures clean up persisted records safely.
Furnace attribution
Removed fragile โlast furnace userโ tracking.
Added
FurnaceExtractEventhandling so only player-extracted furnace results count.Automated/hopper-only furnaces no longer receive incorrect player attribution.
Team rewards
TEAM rewards now iterate over every online Hunter during Hunter victories.
Reward commands execute per recipient.
Runner victories correctly reward the runner.
Objective progress
Pickup progress is now synchronous and uses the captured item quantity.
Crafting and smithing use result quantities.
Added safe
SMELT_ANYprogress through furnace extraction.Automated inventory movement remains intentionally uncredited.
Holograms
Added a Paper
TextDisplay-basedHologramManager.Supports configurable location, lines, range, and progress placeholders.
Updates on objective progress and cleans up on finish, cancel, shutdown, and failed sessions.
Disabled by default.
Configuration
Added
gui.ymlfor guide settings.Added
rewards.ymlfor reward settings.Removed rewards and guide settings from
config.yml.Added reload support for both files.
Java and objective compatibility
Confirmed Java 21 is already explicitly configured in
build.gradle.Disabled the invalid
DIAMOND_SPEARobjective for Paper 1.21.11.Added validation to skip objectives with invalid item or block materials.
package com.prabhatpie.manhunt;
import com.prabhatpie.manhunt.command.ManhuntCommand;
import com.prabhatpie.manhunt.command.RequestCommand;
import com.prabhatpie.manhunt.listener.ManhuntListener;
import com.prabhatpie.manhunt.placeholder.ManhuntExpansion;
import com.prabhatpie.manhunt.service.DatabaseManager;
import com.prabhatpie.manhunt.service.ManhuntManager;
import com.prabhatpie.manhunt.service.MessageService;
import com.prabhatpie.manhunt.service.ObjectiveEngine;
import com.prabhatpie.manhunt.service.RewardManager;
import com.prabhatpie.manhunt.service.StatsManager;
import com.prabhatpie.manhunt.service.HologramManager;
import java.io.File;
import java.util.Objects;
import org.bukkit.Bukkit;
import org.bukkit.configuration.file.FileConfiguration;
import org.bukkit.configuration.file.YamlConfiguration;
import org.bukkit.plugin.java.JavaPlugin;
public final class ManhuntPlugin extends JavaPlugin {
private DatabaseManager database;
private MessageService messages;
private StatsManager stats;
private ObjectiveEngine objectives;
private RewardManager rewards;
private HologramManager holograms;
private ManhuntManager manhunt;
private FileConfiguration guiConfig;
private FileConfiguration rewardsConfig;
@Override
public void onEnable() {
saveDefaultConfig();
saveResource("messages.yml", false);
saveResource("objectives.yml", false);
saveResource("gui.yml", false);
saveResource("rewards.yml", false);
reloadGuiConfig();
reloadRewardsConfig();
this.database = new DatabaseManager(this);
this.messages = new MessageService(this);
this.stats = new StatsManager(database);
this.objectives = new ObjectiveEngine(this);
this.rewards = new RewardManager(this, database);
this.holograms = new HologramManager(this);
this.manhunt = new ManhuntManager(this, database, messages, stats, objectives, rewards, holograms);
Bukkit.getPluginManager().registerEvents(new ManhuntListener(this), this);
manhunt.startTracking();
ManhuntCommand command = new ManhuntCommand(this);
Objects.requireNonNull(getCommand("manhunt")).setExecutor(command);
Objects.requireNonNull(getCommand("manhunt")).setTabCompleter(command);
RequestCommand requestCommand = new RequestCommand(this);
Objects.requireNonNull(getCommand("maccept")).setExecutor(requestCommand);
Objects.requireNonNull(getCommand("mdecline")).setExecutor(requestCommand);
if (Bukkit.getPluginManager().getPlugin("PlaceholderAPI") != null) {
new ManhuntExpansion(this).register();
}
manhunt.loadUnfinishedSessions();
}
@Override
public void onDisable() {
if (manhunt != null) {
manhunt.shutdown();
}
if (holograms != null) holograms.removeAll();
if (database != null) {
database.save();
}
}
public DatabaseManager database() { return database; }
public MessageService messages() { return messages; }
public StatsManager stats() { return stats; }
public ObjectiveEngine objectives() { return objectives; }
public RewardManager rewards() { return rewards; }
public HologramManager holograms() { return holograms; }
public FileConfiguration guiConfig() { return guiConfig; }
public FileConfiguration rewardsConfig() { return rewardsConfig; }
public void reloadGuiConfig() { guiConfig = YamlConfiguration.loadConfiguration(new File(getDataFolder(), "gui.yml")); }
public void reloadRewardsConfig() { rewardsConfig = YamlConfiguration.loadConfiguration(new File(getDataFolder(), "rewards.yml")); }
public ManhuntManager manhunt() { return manhunt; }
}