> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.z-craft.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin Setup & Management

> Basic guide for installing and managing Z-Craft server plugins.

# Plugin Setup & Management

Basic guide for installing and managing server plugins.

## Plugin Installation

### Basic Installation Steps

<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
</Steps>

### 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*

```yaml theme={null}
# 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 Size                 | Thread Pool | Cache Size | Memory Optimization |
| --------------------------- | ----------- | ---------- | ------------------- |
| **Small (1-50 players)**    | 4           | 500        | Basic               |
| **Medium (51-200 players)** | 8           | 1000       | Advanced            |
| **Large (201-500 players)** | 12          | 2000       | Aggressive          |
| **Mega (500+ players)**     | 16          | 5000       | Maximum             |

### Z-Lifesteal: Heart Mechanics

#### Configuration Deep Dive

**File:** `plugins/Z-Lifesteal/config.yml`

**Core Mechanics:**

```yaml theme={null}
# 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:**

```yaml theme={null}
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:**

```yaml theme={null}
# 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:**

```yaml theme={null}
inflation-control:
  enabled: true
  target-circulation: 1000000
  adjustment-rate: 0.001
  monitoring-period: 604800  # 1 week
```

**Wealth Distribution:**

```yaml theme={null}
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:**

```yaml theme={null}
# 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:**

```yaml theme={null}
subdivision:
  enabled: true
  min-size: 10
  cost-multiplier: 0.5
  permission-inheritance: true
```

**Integration Settings:**

```yaml theme={null}
integrations:
  worldguard: true
  griefprevention: false
  towny: false
  factions: false
```

## 🔗 Plugin Integration & Compatibility

### Cross-Plugin Communication

#### API Integration Standards

**Z-Craft Plugin API:**

```java theme={null}
// 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:**

```yaml theme={null}
load-balancing:
  economy-threads: 2
  combat-threads: 4
  event-threads: 1
  database-threads: 3
```

**Memory Management:**

```yaml theme={null}
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:**

```yaml theme={null}
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

<Steps>
  ### Step 1: Pre-Update Assessment

  * **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

  ### Step 2: Update Execution

  * **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

  ### Step 3: Post-Update Verification

  * **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

  ### Step 4: Rollback Preparation

  * **Backup Retention:** Keep previous version available
  * **Configuration Backup:** Save old configs
  * **Documentation Update:** Record update details
  * **Monitoring Period:** 24-hour observation period
</Steps>

### 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:**

```yaml theme={null}
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:**

```yaml theme={null}
permissions:
  admin-only-commands: true
  op-required: false
  permission-nodes:
    - "zcraft.admin"
    - "zcraft.moderator"
    - "zcraft.staff"
```

#### Audit Logging

**Security Events:**

```yaml theme={null}
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:**

```yaml theme={null}
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:**

```java theme={null}
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:**

```yaml theme={null}
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:

```bash theme={null}
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

```yaml theme={null}
# 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

```yaml theme={null}
# 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?**

* [Admin Commands](/staff/admin-commands)
* [Plugin Documentation](/support/modmail)
* Discord #staff-help
* Plugin Developer Docs

***

**Plugin issues?** [Contact tech support](/support/modmail) 🔧