Skip to main content

Plugin Setup & Management

Basic guide for installing and managing server plugins.

Plugin Installation

Basic Installation Steps

  1. Download Plugin - Get the plugin JAR file from trusted sources
  2. Stop Server - Use /stop command to safely shut down
  3. Place File - Put JAR file in the /plugins/ folder
  4. Start Server - Restart server and check console for errors
  5. Configure - Edit config files if needed

Common Plugins Used

  • Essentials - Basic server commands and features
  • WorldGuard - Region protection and management
  • LuckPerms - Permission management
  • Vault - Economy integration
  • Lifesteal Plugin - Core heart-stealing mechanics

Plugin Management

Checking Plugin Status

  • Use /plugins to see loaded plugins
  • Check console for error messages
  • Monitor server performance after installation

Updating Plugins

  • Backup server before updates
  • Download new version
  • Replace old JAR file
  • Restart server
  • Test functionality

Troubleshooting

  • Check plugin compatibility with server version
  • Ensure dependencies are installed
  • Review error logs in console
  • Disable conflicting plugins

Configuration

Basic Config Files

Most plugins create config files in /plugins/pluginname/config.yml
  • Edit with text editor
  • Follow YAML formatting
  • Restart server after changes
  • Backup configs before editing

Common Settings

  • Permission nodes
  • Command aliases
  • Feature toggles
  • Performance options

Need help? Contact technical staff for plugin issues.
Last updated: December 2024
# Server performance tuning
performance:
  async-tasks: true
  thread-pool-size: 8
  cache-size: 1000
  memory-optimization: true

# Database connection
database:
  type: mysql
  host: localhost
  port: 3306
  database: zcraft
  username: zcraft_user
  password: "${DB_PASSWORD}"
  connection-pool: 10

# Security settings
security:
  encryption-enabled: true
  session-timeout: 3600
  rate-limiting: true
  ip-whitelisting: false

# Monitoring and logging
monitoring:
  metrics-enabled: true
  log-level: INFO
  performance-tracking: true
  error-reporting: true

Performance Tuning Guide

Server SizeThread PoolCache SizeMemory Optimization
Small (1-50 players)4500Basic
Medium (51-200 players)81000Advanced
Large (201-500 players)122000Aggressive
Mega (500+ players)165000Maximum

Z-Lifesteal: Heart Mechanics

Configuration Deep Dive

File: plugins/Z-Lifesteal/config.yml Core Mechanics:
# Heart system configuration
hearts:
  max-hearts: 20
  default-hearts: 10
  heart-item: PLAYER_HEAD
  heart-lore:
    - "&cLifesteal Heart"
    - "&7Consume to gain an extra heart"
  drop-on-death: true
  drop-chance: 0.25

# Combat mechanics
combat:
  heart-steal-chance: 0.15
  heart-steal-amount: 1
  minimum-hearts: 1
  death-protection: true
  pvp-only: true

# Visual effects
effects:
  heart-drop-particle: HEART
  heart-consume-sound: ENTITY_PLAYER_LEVELUP
  death-effect: true
  heal-effect: true

# Balance settings
balance:
  heart-value: 1000  # Credits to buy heart
  max-hearts-shop: 15
  prestige-multiplier: 1.5

Advanced Balance Tuning

Heart Drop Rate Balancing:
  • Casual: 35% drop chance, 0.1 steal chance
  • Competitive: 25% drop chance, 0.15 steal chance
  • Hardcore: 20% drop chance, 0.2 steal chance
Prestige System:
prestige:
  enabled: true
  max-level: 10
  heart-bonus: 2  # Extra hearts per prestige
  requirement-multiplier: 1.5  # Hearts needed multiplier
  reset-penalty: 0.5  # Heart loss on prestige

Z-Economy: Currency System

Comprehensive Configuration

File: plugins/Z-Economy/config.yml Economic Parameters:
# Currency settings
currency:
  name: "Credits"
  symbol: "ยข"
  starting-balance: 1000
  max-balance: 10000000
  decimal-places: 0

# Banking system
banking:
  enabled: true
  interest-rate: 0.005  # 0.5% daily
  interest-interval: 86400  # 24 hours
  minimum-balance: 100
  withdrawal-fee: 0.01  # 1%

# Transaction settings
transactions:
  log-all: true
  max-transaction-size: 1000000
  daily-transfer-limit: 50000
  confirmation-required: 10000  # Over this amount

# Shop integration
shops:
  commission-rate: 0.05  # 5%
  minimum-price: 1
  maximum-price: 100000
  price-fluctuation: true
  dynamic-pricing: true

# Anti-cheat measures
security:
  transaction-logging: true
  duplication-detection: true
  anomaly-detection: true
  fraud-prevention: true

Economic Balance Tools

Inflation Control:
inflation-control:
  enabled: true
  target-circulation: 1000000
  adjustment-rate: 0.001
  monitoring-period: 604800  # 1 week
Wealth Distribution:
wealth-redistribution:
  enabled: true
  tax-threshold: 50000
  tax-rate: 0.02  # 2%
  redistribution-target: "server-fund"

Z-Claims: Territory Protection

Protection System Configuration

File: plugins/Z-Claims/config.yml Claim Mechanics:
# Basic claim settings
claims:
  default-size: 100  # Blocks
  max-claims: 5
  claim-cost: 1000   # Credits
  expansion-cost: 500  # Per 100 blocks
  max-size: 1000

# Protection rules
protection:
  block-breaking: true
  block-placing: true
  entity-interaction: true
  pvp-allowed: false
  mob-spawning: false
  fire-spread: true
  tnt-damage: true

# Permission system
permissions:
  allow-trusted: true
  public-access: false
  admin-override: true
  inheritance: true

# Visual indicators
visualization:
  show-borders: true
  border-particle: BARRIER
  corner-markers: true
  info-holograms: true

Advanced Protection Features

Subdivision System:
subdivision:
  enabled: true
  min-size: 10
  cost-multiplier: 0.5
  permission-inheritance: true
Integration Settings:
integrations:
  worldguard: true
  griefprevention: false
  towny: false
  factions: false

๐Ÿ”— Plugin Integration & Compatibility

Cross-Plugin Communication

API Integration Standards

Z-Craft Plugin API:
// Example integration
public class CustomPlugin extends ZPlugin {
    @Override
    public void onEnable() {
        ZAPI api = getZAPI();
        
        // Register economy listener
        api.getEconomy().registerListener(this);
        
        // Access lifesteal data
        HeartManager hearts = api.getHeartManager();
        
        // Claim system integration
        ClaimManager claims = api.getClaimManager();
    }
}

Event-Driven Architecture

Supported Events:
  • PlayerHeartChangeEvent - Heart gain/loss tracking
  • EconomyTransactionEvent - Financial activity monitoring
  • ClaimProtectionEvent - Territory access control
  • TournamentStartEvent - Competition lifecycle
  • PlayerRankChangeEvent - Progression tracking

Performance Optimization

Plugin Load Balancing

Resource Allocation:
load-balancing:
  economy-threads: 2
  combat-threads: 4
  event-threads: 1
  database-threads: 3
Memory Management:
memory:
  cache-cleanup-interval: 300000  # 5 minutes
  max-cache-size: 10000
  garbage-collection: true
  memory-monitoring: true

๐Ÿ› ๏ธ Troubleshooting & Maintenance

Common Plugin Issues

Startup Failures

Console Error Patterns:
[SEVERE] [Z-Core] Failed to load configuration!
Cause: YAML syntax error on line 42
Resolution Steps:
  1. Check YAML syntax with online validator
  2. Verify file permissions
  3. Check for missing dependencies
  4. Review server logs for detailed error

Performance Degradation

Performance Monitoring:
performance-monitoring:
  tps-threshold: 18.0
  memory-threshold: 85
  plugin-response-time: 100  # ms
  automatic-restart: true
Optimization Commands:
/plugin performance Z-Lifesteal  # Check plugin performance
/plugin memory Z-Economy         # Memory usage analysis
/plugin threads                  # Thread utilization

Plugin Update Procedures

Safe Update Process

1
Step 1: Pre-Update Assessment
2
  • Compatibility Check: Verify update compatibility
  • Backup Creation: Full server and database backup
  • Changelog Review: Check for breaking changes
  • Testing Environment: Test update on development server
  • 3
    Step 2: Update Execution
    4
  • Server Shutdown: Graceful shutdown with data saving
  • File Replacement: Replace JAR files with new versions
  • Configuration Migration: Update config files as needed
  • Dependency Updates: Install any new required plugins
  • 5
    Step 3: Post-Update Verification
    6
  • Startup Testing: Monitor console for errors
  • Functionality Testing: Test all plugin features
  • Performance Monitoring: Check TPS and memory usage
  • Player Feedback: Monitor for gameplay issues
  • 7
    Step 4: Rollback Preparation
    8
  • Backup Retention: Keep previous version available
  • Configuration Backup: Save old configs
  • Documentation Update: Record update details
  • Monitoring Period: 24-hour observation period
  • Emergency Procedures

    Plugin Failure Response

    Immediate Actions:
    1. Isolate Plugin: Disable failing plugin with /plugin disable PluginName
    2. Server Stability: Check TPS and player impact
    3. Alternative Systems: Activate backup systems if available
    4. Player Communication: Inform players of temporary issues
    Recovery Process:
    1. Log Analysis: Review error logs for root cause
    2. Configuration Check: Verify config file integrity
    3. Dependency Verification: Check required plugins
    4. Gradual Restart: Re-enable plugin with monitoring

    ๐Ÿ“Š Monitoring & Analytics

    Plugin Performance Dashboard

    Real-Time Metrics

    Performance Indicators:
    • Response Time: Average command execution time
    • Memory Usage: RAM consumption per plugin
    • CPU Utilization: Thread usage and processing load
    • Database Queries: Query performance and frequency
    • Error Rate: Exception frequency and types

    Automated Reporting

    Daily Plugin Report:
    plugin-report:
      enabled: true
      recipients: [admin1, admin2]
      include-metrics: true
      include-errors: true
      performance-thresholds: true
    
    Weekly Comprehensive Analysis:
    • Plugin efficiency rankings
    • Resource utilization trends
    • Error pattern analysis
    • Performance optimization recommendations

    ๐Ÿ”’ Security & Access Control

    Plugin Security Measures

    Access Control Configuration

    Permission System:
    permissions:
      admin-only-commands: true
      op-required: false
      permission-nodes:
        - "zcraft.admin"
        - "zcraft.moderator"
        - "zcraft.staff"
    

    Audit Logging

    Security Events:
    audit-logging:
      enabled: true
      log-level: ALL
      include-commands: true
      include-config-changes: true
      retention-period: 90  # days
    

    Backup & Recovery

    Automated Backup System

    Backup Schedule:
    backups:
      plugin-configs: "0 3 * * *"    # Daily at 3 AM
      plugin-data: "0 4 * * *"       # Daily at 4 AM
      full-server: "0 5 * * 0"       # Weekly on Sunday
      retention: 30                  # Days to keep
    
    Recovery Testing:
    • Monthly backup integrity verification
    • Quarterly full recovery testing
    • Automated checksum validation
    • Offsite backup synchronization

    ๐Ÿ“š Advanced Configuration

    Custom Plugin Development

    Z-Craft Plugin Template

    Required Structure:
    public class CustomPlugin extends ZPlugin {
        
        @Override
        public void onEnable() {
            // Plugin initialization
            saveDefaultConfig();
            registerCommands();
            registerListeners();
            
            // API integration
            ZAPI api = getZAPI();
            api.registerCustomFeature(this);
        }
        
        @Override
        public void onDisable() {
            // Cleanup operations
            saveData();
            unregisterListeners();
        }
    }
    

    Configuration Management

    Dynamic Configuration:
    dynamic-config:
      reload-on-change: true
      hot-reload: true
      validation: true
      backup-on-change: true
    

    Plugin management is both an art and a science. This guide provides the technical foundation, but experience and careful testing are essential for optimal server performance. โš™๏ธ๐Ÿ”ง๐Ÿ’š Remember: Always test plugin changes on a development server before deploying to production. Regular backups and monitoring are your best friends in plugin administration. ๐Ÿ›ก๏ธ๐Ÿ“Š Solutions:
    1. Verify Java version compatible
    2. Check plugin JAR name
    3. Ensure dependencies installed
    4. Review error message
    5. Check file permissions

    Configuration Wonโ€™t Apply

    Steps:
    1. Verify syntax is valid YAML
    2. Use /plugin reload PluginName
    3. Check for typos
    4. Verify permission level
    5. Restart if reload fails

    Commands Not Working

    Debug:
    /plugin reload PluginName
    Check if command registered
    Test with different player
    Review permissions
    

    Data Corruption

    Recovery:
    1. Stop server
    2. Restore from backup
    3. Check plugin logs
    4. Report to developers

    Performance Optimization

    Plugin Load Order

    Priority (in order):
    1. Database plugins
    2. Core plugins
    3. Feature plugins
    4. Optional plugins

    Memory Management

    Monitor:
    /mem                - Check memory
    /gc                 - Garbage collection
    /entities           - Entity count
    
    Optimize:
    • Remove unused plugins
    • Adjust cache sizes
    • Tune database connections
    • Monitor heap usage

    Backup & Recovery

    Backup Locations

    backups/
    โ”œโ”€โ”€ economy/         (Economy data)
    โ”œโ”€โ”€ claims/          (Land claims)
    โ”œโ”€โ”€ jobs/            (Job data)
    โ””โ”€โ”€ shops/           (Shop inventory)
    

    Manual Backup

    /economy backup
    /claims backup
    /shops backup
    /jobs backup
    

    Automated Backups

    Schedule via cron or plugin:
    0 3 * * * /server/backup.sh
    

    Plugin Updates

    Update Process

    1. Backup current version
      cp plugins/Plugin.jar plugins/Plugin.jar.bak
      
    2. Download new version
      • Verify compatibility
      • Check changelog
    3. Stop server
      /stop
      
    4. Replace JAR
      cp NewPlugin.jar plugins/Plugin.jar
      
    5. Start and test
      • Check console for errors
      • Verify features work
      • Monitor performance

    Version Management

    Keep backup of previous versions:
    plugins/
    โ”œโ”€โ”€ Plugin-1.0.jar
    โ”œโ”€โ”€ Plugin-1.1.jar  (current)
    โ””โ”€โ”€ Plugin-1.1.jar.bak
    

    Development Setup

    Plugin Development

    Requirements:
    • Java JDK 11+
    • Spigot/Paper API
    • IDE (IntelliJ IDEA)
    • Maven or Gradle
    Basic Structure:
    MyPlugin/
    โ”œโ”€โ”€ src/
    โ”‚   โ””โ”€โ”€ com/zcraft/myplugin/
    โ”‚       โ”œโ”€โ”€ MyPlugin.java
    โ”‚       โ”œโ”€โ”€ listeners/
    โ”‚       โ””โ”€โ”€ commands/
    โ”œโ”€โ”€ resources/
    โ”‚   โ””โ”€โ”€ plugin.yml
    โ””โ”€โ”€ pom.xml
    

    Testing

    1. Compile:
      mvn clean package
      
    2. Deploy:
      cp target/MyPlugin-1.0.jar server/plugins/
      
    3. Test:
      • Join test server
      • Verify functionality
      • Check logs
      • Monitor performance

    Configuration Examples

    Full Economy Config

    # Z-Economy Configuration
    economy:
      # Starting balance
      starting-balance: 1000
      
      # Max balance cap
      max-balance: 9999999
      
      # Bank system
      bank:
        enabled: true
        interest: 0.005
        compound: daily
    
    # Log all transactions
    logging:
      enabled: true
      file: logs/economy.log
    

    Full Claims Config

    # Z-Claims Configuration
    claims:
      # Default claim size
      default-size: 100
      
      # Expansion
      expansion:
        enabled: true
        cost-per-block: 1
      
      # Limits per rank
      limits:
        member: 1
        veteran: 3
        elite: 5
        legend: 10
    

    Support & Resources

    Need Help?
    Plugin issues? Contact tech support ๐Ÿ”ง