InventoryBackup Plugin Description

Overview

InventoryBackup is a robust and secure Minecraft Spigot plugin designed to automatically save player inventories upon death and provide comprehensive restore functionality. Built with server administrators in mind, it offers a complete solution for inventory management with focus on security, performance, and ease of use.

Why Use InventoryBackup?

Protect Your Players

Players invest countless hours gathering resources, building, and progressing. Unexpected deaths, server crashes, or bugs can wipe out all that progress in seconds. InventoryBackup ensures that no player ever permanently loses their valuable items.

Easy to Use

Simple commands make inventory management accessible to any administrator. No complex configuration required - just install and go.

Peace of Mind

Automatic backups mean you don't have to worry about manually saving inventories. The plugin handles everything in the background.

Key Features

Automatic Death Backups

The plugin features an intelligent two-stage caching system:

• Damage Detection: When a player takes damage that would bring them to 4 hearts or less, their inventory is cached synchronously
• Death Event: When the player actually dies, the cached inventory is saved to disk asynchronously

This dual-stage approach ensures reliable inventory capture even in one-shot death scenarios, such as fall damage or instant-kill effects.

Manual Backup Control

Administrators can create manual backups for any online player using the /inv backup command. This is useful for:

• Creating backups before risky activities (raids, PvP events)
• Taking snapshots of player inventories for investigation
• Ensuring backups exist before server maintenance

Flexible Restore Options

Multiple restore methods cater to different scenarios:

• Full Restore: Completely replace a player's current inventory with a saved backup
• Inventory Preview: View saved inventories in a GUI before restoring
• Missing Items Only: Give only items that are missing from the player's current inventory

Backup Management

Comprehensive management tools allow administrators to:

• List all backups for a specific player with timestamps
• Delete individual backup files
• Delete all backups for a player in one command
• Configure automatic cleanup of old backups

Security & Reliability

• Path Traversal Protection: Filename validation and path canonicalization prevent directory traversal attacks
• Thread-Safe Design: Uses thread-safe date formatting and proper synchronization for multi-threaded environments
• Race Condition Prevention: Critical operations are synchronized to prevent timing issues
• Error Handling: Comprehensive error logging with Bukkit Logger for easy debugging

Performance Optimizations

• Async Operations: File I/O operations run asynchronously to prevent server lag
• Efficient Cleanup: Timestamp parsing from filenames instead of loading YAML files for faster cleanup
• Configurable Intervals: Cleanup and cache intervals can be tuned for server performance

How to Use the Commands

Creating Backups

Backup all online players at once:

/inv backup all

Perfect for creating server-wide snapshots before events or maintenance.

Backup a specific player:

/inv backup Steve

Useful when a player is about to do something risky and wants a safety net.

Restoring Inventories

Restore a player's inventory from a backup:

/inv Steve restore 2024-05-24_15-30-45_death.yml

This completely replaces Steve's current inventory with the saved backup. The filename can be obtained using the list command.

View a backup before restoring:

/inv Steve show 2024-05-24_15-30-45_death.yml

Opens a GUI showing the saved inventory. This is perfect for verifying what items were in the backup before restoring.

Give only missing items:

/inv Steve givemissing 2024-05-24_15-30-45_death.yml

Compares the saved backup with Steve's current inventory and only gives back items that are missing. This is ideal when a player has already recovered some items but needs the rest.

Managing Backups

List all backups for a player:

/inv Steve list

Shows all available backup files for Steve with their timestamps. Use this to find the right backup filename for restore operations.

Delete a specific backup:

/inv Steve delete 2024-05-24_15-30-45_death.yml

Removes a single backup file. Useful for cleaning up accidental or unwanted backups.

Delete all backups for a player:

/inv Steve delete all

Removes all backup files for a player. Use with caution - this cannot be undone.

Command Aliases

The /inv command has two aliases for convenience:

• /inventory
• /invbackup

You can use any of these interchangeably.

Permissions

All commands require specific permissions. By default, only OPs have access:

• inventorybackup.use - Use all inventory backup commands
• inventorybackup.restore - Restore inventories and delete backups
• inventorybackup.show - Show saved inventories and list backups
• inventorybackup.givemissing - Give missing items
• inventorybackup.backup - Create manual backups
• inventorybackup.notify - Receive backup notification messages

Configure these in your permission plugin (like LuckPerms) to grant access to moderators or trusted players.

Configuration

The plugin creates a config.yml file with these important settings:

Auto-Deletion

auto-delete-days: 30
cleanup-interval-hours: 24

Backups older than 30 days are automatically deleted every 24 hours. Set auto-delete-days to 0 to disable automatic cleanup.

Death Backup

save-on-death: true

Enable or disable automatic death backups. Set to false if you only want manual backups.

Performance

cache-cleanup-interval: 30

How often (in seconds) the internal cache is cleaned up. Lower values use more CPU but free memory faster.

Notifications

notify-on-backup: true
notify-ops-only: true

Control who receives backup notifications. Set notify-ops-only to false to allow anyone with the inventorybackup.notify permission to receive notifications.

Common Use Cases

Scenario 1: Player Died Unexpectedly

A player fell into the void and lost all their items. As an admin, you can:

1. Use /inv PlayerName list to see available backups
2. Use /inv PlayerName show <filename> to verify the backup contains their items
3. Use /inv PlayerName restore <filename> to restore their inventory

Scenario 2: Server Crash During Raid

Your server crashed during a raid event and players lost their items:

1. Use /inv backup all to create a fresh backup of everyone's current state
2. Use /inv PlayerName restore <filename> for each affected player
3. Or use /inv PlayerName givemissing <filename> if they've already recovered some items

Scenario 3: Investigation

A player is suspected of having illegal items:

1. Use /inv PlayerName list to see all their backups
2. Use /inv PlayerName show <filename> to inspect inventories at different times
3. Delete suspicious backups with /inv PlayerName delete <filename>

Scenario 4: Pre-Event Backup

Before a major PvP event or raid:

1. Use /inv backup all to save everyone's inventory
2. After the event, players can restore if needed
3. Clean up with /inv PlayerName delete all once everyone is satisfied

Tips for Best Results

• Regular Backups: Use /inv backup all before major events or maintenance
• Verify Before Restore: Always use the show command to verify backup contents before restoring
• Use Missing Items: The givemissing command is often better than full restore when players have already recovered some items
• Configure Cleanup: Set auto-delete-days to match your server's needs - 30 days is a good starting point
• Monitor Disk Space: If you have many players, consider reducing the auto-delete interval
• Test Permissions: Make sure your moderators have the right permissions for their role

Integration

The plugin integrates seamlessly with existing server infrastructure:

• Uses standard Spigot API
• No external dependencies beyond Spigot
• Compatible with most other plugins
• Minimal performance impact when configured properly

Support

For issues, questions, or suggestions:

• Website: https://sterra.online
• Email: [email protected]
• License: MIT (see LICENSE file)