Modern Minecraft Item Repair Plugin Based on PDC Data-Driven Technology

Plugin Introduction
SagaRepair is an advanced item repair plugin designed specifically for Minecraft Paper 1.20.1 servers. It uses PDC (PersistentDataContainer) data-driven technology to provide a complete custom item durability system for servers, supporting intelligent repair interfaces, drag-and-drop repair, custom repair tools, and other advanced features.

Core Features

• PDC Data-Driven - Uses Paper's officially recommended data storage method
• Intelligent Repair System - Supports both GUI interface and drag-and-drop repair modes
• ️ Complete Item Protection - Configurable zero-durability item handling mechanism
• Modern Interface - Intuitive placeholder hints and user-friendly design
• ⚡ PlaceholderAPI Integration - Supports dynamic placeholders and server information display

Core Function Modules
✨ PDC-Driven Durability System

• Dynamic Durability Display - Only displays durability lore for items containing PDC data
• Intelligent Color Changes - Automatically adjusts colors based on durability percentage (Green→Yellow→Red)
• Unified PDC Naming - Standardized key-value management using sagarepair_pdc_ prefix
• Real-time Updates - Automatically updates item display when durability changes

️ Intelligent Item Protection System

• Zero Durability Handling - Configurable destroy or protect mode
• ⚠️ ActionBar Warnings - Displays dynamic warning messages at low durability
• Equipment Restrictions - Automatically prevents wearing of broken equipment
• Status Management - Intelligently recognizes repair status to prevent misoperations

Multi-Mode Repair System

• ️ GUI Repair Interface - Intuitive repair interface with placeholder hints
• ⚡ Drag-and-Drop Repair - Quick drag-and-drop repair in inventory and GUI
• ️ Custom Repair Tools - Special repair items stored via Base64 serialization
• Intelligent Material Validation - Automatically recognizes traditional materials and custom tools

Complete Command System

• Tab Completion - Intelligent command completion based on permissions
• Item Information Viewing - Detailed PDC data display
• ⚙️ Administrator Tools - Item initialization, repair tool creation, etc.
• Hot Reload - Supports real-time configuration file reloading

Command System Details
Complete Command List
Command Function Description Permission Required Usage Example
/srr repairgui Open repair interface sagarepair.use Open directly, no need to hold item
/srr info View held item PDC information sagarepair.use Shows durability, protection status, etc.
/srr help Display help information sagarepair.use Shows available commands based on permissions
/srr reload Reload all configuration files sagarepair.reload Hot reload config without server restart
/srr setdurability <max_durability> Initialize complete PDC data for held item sagarepair.admin /srr setdurability 100
/srr removedurability <amount> Reduce durability of held item sagarepair.admin /srr removedurability 10
/srr settool <repair_points> Set held item as custom repair tool sagarepair.admin /srr settool 50
Command Aliases
/srr # Main alias (recommended)
/sagarepair # Full name

⚡ Intelligent Tab Completion System

• Permission Aware - Dynamically shows available commands based on player permissions
• Parameter Suggestions - Provides common suggestion values for numeric parameters
  • setdurability: 1, 10, 50, 100, 500, 1000
  • settool: 1, 5, 10, 25, 50, 100
  • removedurability: 1, 10, 50, 100, 500, 1000
• Real-time Filtering - Automatically filters matching options while typing

Permission System Details
Permission Node Default Permission Function Scope
sagarepair.use ✅ All players Basic functions: repair, view info, help
sagarepair.admin Administrators Admin functions: set durability, create tools, remove durability
sagarepair.reload Administrators Reload configuration files
Complete Item Repair Guide
Method 1: GUI Repair Interface (Recommended for beginners)
┌─────────────────────────────────┐
│ ️ Repair Interface Layout │
├─────────────────────────────────┤
│ [ ] [ ] [ ] │
│ [ ] [] [ ] ← Repair Slot │
│ [ ] [ ] [ ] │
│ [ ] [] [ ] ← Material Slot │
│ [ ] [ ] [ ] │
│ [ ] [✅] [ ] ← Confirm Button │
└─────────────────────────────────┘

Detailed Operation Steps
Step 1: Open Repair Interface

/srr repairgui

New Feature: No need to hold item, can open repair interface directly

Step 2: Place Item to Repair

• Drag the item that needs repair to the yellow glass pane position
• ✅ System automatically validates if item contains PDC durability data
• ️ Perfect support for safe operation of zero-durability items

Step 3: Place Repair Materials

• Traditional Repair Materials: Materials required according to item PDC data (like iron ingots, diamonds, etc.)
• ⭐ Custom Repair Tools: Special repair items created by administrators
• Drag materials to the green glass pane position

Step 4: Execute Repair

• ️ Click the green confirm button
• ⚡ System automatically validates materials and executes repair
• Items automatically return to inventory after successful repair

⚡ Method 2: Drag-and-Drop Repair (Advanced users)
Inventory Drag-and-Drop Repair
Operation: Hold repair tool → Drag to target item
Use Case: Quick repair without opening GUI
Technical Requirement: SWAP_WITH_CURSOR mouse operation

Operation Steps:

1. Hold repair material or custom repair tool
2. Find the item that needs repair in inventory
3. ️ Use mouse to drag repair tool onto target item
4. ⚡ System automatically executes repair and consumes materials

️ GUI Drag-and-Drop Repair
Operation: Drag directly onto item in repair GUI
Use Case: Quick repair in GUI, skip confirmation step
Special Advantage: Supports safe operation of zero-durability items

Operation Steps:

1. Open repair GUI (/srr repairgui)
2. Place item to repair in repair slot
3. Hold repair tool and drag directly onto item in repair slot
4. ⚡ Complete repair immediately without clicking confirm

Repair Completion Effects

• ✨ Durability Recovery: Restores durability based on repair tool's repair points
• Status Reset: Removes "broken" mark, restores normal usage
• Lore Update: Durability display automatically updates to new values
• Material Consumption: Consumes corresponding materials based on actual repair amount

Item Information Viewing System
PDC Data Viewing
Basic Operation

1. Hold Target Item
   
   # Hold the item you want to view
   
   
2. Execute View Command
   
   /srr info
   
   
3. View Detailed Information
   System will display complete PDC data information
   

Information Display Content
Data Item Display Content Description
Durability Info Current/Max Durability (Percentage) Real-time PDC durability data
️ Protection Status Protected / Unprotected Whether PDC protection mechanism is enabled
Broken Status Broken / Normal Current item usage status
Repair Material Material Type x Quantity Materials required for traditional repair
⭐ Repairability Repairable / Cannot Repair Whether contains complete PDC data
No PDC Data Prompt
⚠️ This item has no PDC durability data
Only items containing PDC data can use repair functions

Repair Interface Details
️ Intelligent GUI Design
┌─────────────────────────────────────────┐
│ ️ SagaRepair Repair Interface - Player Name │
├─────────────────────────────────────────┤
│ [] [] [] │
│ [] [] [] ← Repair Item Slot │
│ [] [] [] (Yellow glass pane hint) │
│ [] [] [] ← Repair Material Slot │
│ [] [] [] (Green glass pane hint) │
│ [] [✅] [] ← Confirm Repair Button │
└─────────────────────────────────────────┘

Slot Function Details
Repair Item Slot (Slot 11)

• Function: Place items that need repair
• ✅ Validation: Automatically checks if item contains PDC durability data
• ️ Protection: Supports safe operation of zero-durability items
• Hint: Yellow glass pane displays operation guidance

Repair Material Slot (Slot 15)

• Traditional Materials: Materials required according to item PDC data
• ⭐ Custom Tools: Special repair items created by administrators
• Intelligent Recognition: Automatically validates material type and quantity
• Hint: Green glass pane displays operation guidance

✅ Confirm Repair Button (Slot 22)

• ️ Function: Execute repair operation
• ⚡ Validation: Checks validity of items and materials
• Processing: Automatically consumes materials and restores durability
• Return: Automatically returns items after repair completion

️ Safety Guarantee Mechanisms
Item Safety System

• Intelligent Return: Automatically returns all real items when closing GUI
• Glass Pane Filtering: Will not return hint glass panes
• Drop Protection: Safely drops to ground with notification when inventory is full
• ⚠️ Exception Handling: Ensures items are not lost in case of disconnection, etc.

Special Support for Zero-Durability Items

• ️ Status Protection: Pauses forced movement logic during repair
• ⚡ Drag Support: Supports drag-and-drop repair of zero-durability items
• Status Management: Intelligently manages player repair status
• Auto Cleanup: Automatically cleans protection status after operation completion

️ Custom Repair Tool System
⭐ What are Custom Repair Tools?
Custom repair tools are special items created by administrators using Base64 serialization technology, with the following characteristics:

• Fixed Repair Points: Each tool has preset repair capability
• Universal Repair: Can repair any item containing PDC data
• Complete Serialization: Uses Paper API's serializeAsBytes() method to store complete item data
• Intelligent Recognition: System automatically recognizes and validates custom repair tools

Administrator Creation Guide
Creation Steps
Step 1: Prepare Item

# Hold any item as repair tool template
# Recommend using items with special appearance or names

Step 2: Execute Creation Command

/srr settool <repair_points>

# Examples:
/srr settool 50 # Create tool that repairs 50 durability points
/srr settool 100 # Create tool that repairs 100 durability points
/srr settool 25 # Create tool that repairs 25 durability points

Step 3: Confirm Creation Result

• ✅ System automatically serializes item data to Base64 format
• Tool information saved to tool.yml configuration file
• Item gains special repair attribute identification

Technical Features
Technical Feature Implementation Advantage
Data Storage Base64 Serialization Completely saves all item attributes
Recognition Mechanism Byte-level precise comparison 100% accurate tool recognition
Configuration Management tool.yml dynamic configuration Supports hot reload and batch management
Compatibility Paper API standard Perfect compatibility with all Paper servers
Player Usage Guide
️ GUI Usage

1. Open Repair Interface: /srr repairgui
2. Place Repair Item: Drag to repair slot
3. ⭐ Place Custom Tool: Drag to material slot
4. ✅ Confirm Repair: Click green button

⚡ Drag Quick Repair

1. Hold Custom Tool
2. ️ Drag to Target Item: Directly drag onto item that needs repair
3. ⚡ Complete Immediately: System automatically executes repair

Intelligent Consumption Mechanism

• Consume as Needed: Consumes tools based on actual durability points repaired
• Quantity Management: Automatically handles tool quantity increase/decrease
• ⚡ Efficiency Optimization: Prioritizes using tools with most suitable repair points

⚙️ Configuration System Details
Configuration File Structure
SagaRepair uses a multi-file configuration system to ensure functional modularity and easy management:

plugins/SagaRepair/
├── config.yml # Main configuration file
├── message.yml # Message configuration file
├── debugmessage.yml # Debug message configuration
└── tool.yml # Custom tool configuration (auto-generated)

Main Configuration File (config.yml)
Complete Configuration Example
Message Configuration File (message.yml)
Message Configuration Structure
Configuration Hot Reload
Use the following command to hot reload all configuration files:

/srr reload

Reload Scope:

• ✅ config.yml - Main configuration settings
• ✅ message.yml - All message text
• ✅ debugmessage.yml - Debug messages
• ✅ tool.yml - Custom repair tools

PlaceholderAPI Integration
Supported Placeholders
SagaRepair fully integrates with PlaceholderAPI, providing dedicated %ssr_% placeholder series:

SagaRepair Dedicated Placeholders
️ Placeholder Function Description Use Case Example Value
%ssr_current% Current durability value Display item current durability 85
%ssr_max% Maximum durability value Display item maximum durability 100
%ssr_percentage% Durability percentage Display durability percentage 85.0
%ssr_protected% Protection status Display item protection status Protected/Unprotected
%ssr_broken% Broken status Display item broken status Normal/Broken
%ssr_repair_material% Repair material Display required repair material IRON_INGOT
%ssr_repair_count% Repair count Display required repair quantity 3
%ssr_durability_format% Formatted durability display Complete durability information 85/100 (85.0%)
%ssr_status% Comprehensive status Overall item status Normal/Low Durability/Broken
General PlaceholderAPI Placeholders
Also supports all standard PlaceholderAPI placeholders:

️ Placeholder Function Description Use Case
%player_name% Player name GUI title, message personalization
%player_displayname% Player display name Support nickname systems
%server_name% Server name Multi-server environment identification
%server_online% Online player count Server status display
Configuration Examples
Using SagaRepair Placeholders in GUI Title
gui:
title: "&6Repair Interface - &e%player_name% &7| &bDurability: %ssr_durability_format%"
enable_papi: true

Using SagaRepair Placeholders in Messages
repair:
success: "&a %player_name% repair successful! Durability restored to %ssr_durability_format%"
status_check: "&7Item status: %ssr_status% &8| &7Protection: %ssr_protected%"

item_info:
ssr_examples:
current: "&7Current durability: &f%ssr_current%"
max: "&7Maximum durability: &f%ssr_max%"
percentage: "&7Durability percentage: &f%ssr_percentage%&7%"
full_format: "&7%ssr_durability_format% &8| %ssr_status%"

Actual Display Effects

• %ssr_current% → 85
• %ssr_max% → 100
• %ssr_percentage% → 85.0
• %ssr_durability_format% → 85/100 (85.0%)
• %ssr_status% → Normal
• %ssr_protected% → Protected

⚙️ Technical Implementation

• PlaceholderUtils Class: Unified management of PAPI functionality
• Dynamic Parsing: Real-time parsing of placeholder content
• ️ Compatibility Check: Automatic detection of PAPI plugin status
• Performance Optimization: Caching mechanism reduces repeated parsing

Technical Features
PDC Data-Driven Technology
PDC Key-Value Specifications
// Unified naming prefix: sagarepair_pdc_
public static final NamespacedKey DURABILITY = new NamespacedKey(plugin, "sagarepair_pdc_durability");
public static final NamespacedKey MAX_DURABILITY = new NamespacedKey(plugin, "sagarepair_pdc_max_durability");
public static final NamespacedKey PROTECTED = new NamespacedKey(plugin, "sagarepair_pdc_protected");
public static final NamespacedKey BROKEN = new NamespacedKey(plugin, "sagarepair_pdc_broken");
public static final NamespacedKey REPAIR_MATERIAL = new NamespacedKey(plugin, "sagarepair_pdc_repair_material");
public static final NamespacedKey REPAIR_COUNT = new NamespacedKey(plugin, "sagarepair_pdc_repair_count");

Data Management Advantages

• Data Persistence: PDC data permanently saved in items
• No Lore Dependency: Does not rely on traditional lore storage, avoiding conflicts
• ⚡ High Performance: Paper's officially recommended data storage method
• Easy to Extend: Unified key-value management facilitates feature expansion

Modern API Usage
Adventure API Integration
// Using Adventure API to handle text components
Component message = Component.text("Repair successful!")
.color(NamedTextColor.GREEN)
.decoration(TextDecoration.BOLD, true);
player.sendMessage(message);

Paper API Features

• PersistentDataContainer: Official data storage API
• Adventure Components: Modern text processing
• ⚡ Event System: Efficient event handling mechanism
• ️ Safety Features: Built-in safety checks and exception handling

⚠️ Important Notes
Item Requirements

• Only items containing PDC data can use repair functions
• Regular Minecraft items cannot use this plugin's repair functions
• Items must have durability data to display durability information
• Supports safe repair of zero-durability items

Repair Material Types

1. Traditional Repair Materials
   
   • Each item has specific repair material requirements
   • Material type and quantity can be viewed in item information
   • Corresponding amount of materials will be consumed during repair
2. Custom Repair Tools
   
   • Special repair items created by administrators
   • Have fixed repair points
   • Can repair any item that supports repair

Permission Instructions

• Regular players have basic usage permissions by default
• All players can use repair, view information, and other functions
• Administrators have additional management permissions (create repair tools, set durability, etc.)

Frequently Asked Questions
Q: Why can't my item be repaired?
A: Please check the following points:

• Does the item contain PDC durability data
• Do you have enough repair materials or repair tools
• Does the item really need repair (durability not full)

Q: What to do if repair interface won't open?
A: The new version repair interface can be opened directly without holding items:

• Use /srr repairgui directly to open
• Place items that need repair in the interface
• If still can't open, please check permission settings

Q: What to do if drag repair doesn't work?
A: Please confirm the following operations:

• Use right mouse button to drag (SWAP_WITH_CURSOR action)
• Ensure dragging valid repair materials or repair tools
• Target item must be PDC item that needs repair

Q: What to do if items disappear after closing GUI?
A: The new version has completely solved this problem:

• Items automatically return to inventory when closing GUI
• Items drop to ground with notification when inventory is full
• Items will not be lost under any circumstances

Q: How to obtain repair materials?
A: There are two types of repair materials:

1. Traditional Repair Materials: Regular Minecraft items
   • Mining and gathering
   • Trading with other players
   • Purchasing from shops
2. Custom Repair Tools: Created by administrators
   • Contact server administrators to obtain
   • Participate in server activities to get

Q: Will items disappear when damaged?
A: No! Protected items will not disappear when damaged:

• Zero-durability items will be marked as "broken"
• Cannot be used normally, but will not disappear
• Can be restored to normal use after repair

Q: What to do if zero-durability items cannot be operated?
A: The new version perfectly supports zero-durability items:

• Can be safely placed in repair GUI
• Supports drag repair operations
• Will not be forcibly moved during repair process

Usage Tips
Practical Suggestions

1. Regular Equipment Inspection
   
   • Use /srr info to regularly check equipment durability
   • Repair in time when durability is low
   • Pay attention to ActionBar low durability warnings
2. Prepare Repair Materials
   
   • Prepare commonly used repair materials in advance
   • Recommend storing some repair materials at base
   • Apply to administrators for custom repair tools
3. Reasonable Equipment Usage
   
   • Avoid unnecessary equipment wear
   • Perform repair operations in safe places
   • Zero-durability items can also be safely repaired

Repair Process Optimization
⚡ Quick Repair Tips

1. Drag Repair
   
   • Drag repair tools directly onto items in inventory
   • Drag repair in GUI without clicking confirm
   • Suitable for quick repair of single items
2. Batch Repair
   
   • Use repair GUI to repair multiple items one by one
   • Prepare sufficient repair materials
   • Use custom repair tools to improve efficiency

️ Safe Repair

1. Zero-Durability Item Repair
   
   • Open repair GUI directly without worrying about item movement
   • Supports drag repair of zero-durability items
   • Repair process is completely safe
2. Item Safety Guarantee
   
   • Items automatically return when closing GUI
   • Items drop with notification when inventory is full
   • Items are not lost in case of disconnection and other exceptions

Material Management

1. Traditional Materials
   
   • Understand repair material requirements for different items
   • Reasonably allocate and store repair materials
   • Use /srr info to check required materials
2. Custom Tools
   
   • Apply to administrators for high repair point tools
   • Use reasonably to avoid wasting repair points
   • Can repair any PDC items

Advanced Gameplay

1. Combined Repair Strategy
   
   • Use traditional materials for low-durability items
   • Use custom tools for high-value items
   • Use drag quick repair in emergency situations
2. Team Cooperation
   
   • Team sharing of repair materials
   • Administrators distribute repair tools uniformly
   • Establish team repair stations