# AdvancementSync
**Multi-server player advancement synchronization for Minecraft Spigot/Bukkit servers**
## Overview
AdvancementSync is a lightweight plugin that keeps player advancements synchronized across multiple Spigot/Bukkit servers using Redis. With automatic MySQL fallback, your player progress is never lost even if Redis goes down.
## Features
✨ **Real-time Synchronization** - Player advancements instantly synced across servers via Redis
**Smart Rollback** - Reset or rollback player advancements to a specific time
**Automatic Backup** - MySQL fallback when Redis is unavailable
**Sync Notifications** - Optional chat alerts for advancement updates
⚙️ **Easy Configuration** - Simple YAML setup for Redis and MySQL
️ **Admin Commands** - Built-in reset, rollback, reload, and status commands
**Async Operations** - Non-blocking database calls prevent server lag
## Requirements
- **Minecraft**: 1.21+
- **Server Software**: Paper, Spigot, CraftBukkit, or compatible
- **Java**: 21 or higher
- **Redis**: 5.0+ (primary database)
- **MySQL**: 5.7+ (optional fallback, recommended)
## Quick Setup
### 1. Download & Install
Place the JAR in your `plugins/` folder and restart the server.
### 2. Configure Redis
Edit `plugins/AdvancementSync/config.yml`:
```yaml
redis:
host: localhost
port: 6379
password: ""
```
### 3. Configure MySQL (Optional but Recommended)
```yaml
database:
enabled: true
host: localhost
port: 3306
database: advancementsync
username: root
password: ""

pool:
max-connections: 10
min-idle: 2
connection-timeout: 5000
```
### 4. Enable Features
```yaml
features:
teleport-on-join: true
periodic-save: true
sync-alerts: true
use-mysql-fallback: true
```
### 5. Restart Server
## Commands
- `/advsync reset <player>` - Reset all advancements for a player
- `/advsync rollback <player> <time>` - Rollback advancements (1h, 30m, 1d, etc)
- `/advsync reload` - Reload configuration
- `/advsync status` - View database status
- `/advsync help` - Show help message
**Permission**: `advancementsync.admin` (OP only by default)
## How It Works
1. **Primary**: Saves to Redis (fast, real-time sync)
2. **Fallback**: Automatically uses MySQL if Redis fails
3. **Redundancy**: Data saved to both databases when available
4. **Recovery**: Retrieves from MySQL if Redis is unavailable
## Configuration
### Redis Section
- `host` - Redis server IP/hostname
- `port` - Redis port (default: 6379)
- `password` - Redis authentication (leave empty if none)
### MySQL Section
- `host` - MySQL server IP/hostname
- `port` - MySQL port (default: 3306)
- `database` - Database name (will be created if needed)
- `username` - MySQL user
- `password` - MySQL password
- `pool.max-connections` - Connection pool size
- `pool.min-idle` - Minimum idle connections
- `pool.connection-timeout` - Connection timeout in ms
### Features
- `teleport-on-join` - Teleport players to their last location
- `periodic-save` - Auto-save advancements every 30 seconds
- `sync-alerts` - Show sync notifications
- `use-mysql-fallback` - Enable MySQL fallback
## Multi-Server Network Example
**Server 1 (Hub):**
```yaml
server-id: hub-1
redis:
host: 192.168.1.100
database:
host: 192.168.1.100
```
**Server 2 (Survival):**
```yaml
server-id: survival-1
redis:
host: 192.168.1.100
database:
host: 192.168.1.100
```
Both servers connect to the same Redis and MySQL, advancements are shared automatically.
## Performance
- ⚡ Async operations prevent server lag
- Connection pooling for efficient resource use
- Configurable save intervals
- Handles 1000+ concurrent players
## Troubleshooting
**Redis connection fails**
- Check Redis is running: `redis-cli ping`
- Verify host/port in config
- Check firewall allows Redis port
**MySQL connection fails**
- Verify MySQL is running
- Check credentials in config
- Ensure database user has proper permissions
- Run schema.sql to create tables
**Advancements not syncing**
- Check `/advsync status`
- Verify at least one database is connected
- Check server logs for errors
- Reload with `/advsync reload`
**Players losing advancements on server switch**
- Enable `use-mysql-fallback` in config
- Verify both Redis and MySQL are configured
- Ensure players have time to sync before switching
## Support
Issues, suggestions, or questions? Visit the [GitHub repository]( https://github.com/expo-sitory/AdvancementSync).
## Links
- **GitHub**: https://github.com/expo-sitory/AdvancementSync
- **Issues**: https://github.com/expo-sitory/AdvancementSync/issues
- **Discord**: [Join our Discord community]( https://discord.gg/example)
## Changelog
**v1.1.0** - Database Fallback & MySQL Support
- Added MySQL database as fallback to Redis
- HikariCP connection pooling for efficiency
- Automatic failover on Redis failure
- Smart advancement rollback system
- Database status monitoring and health checks
- Improved error handling and logging
**v1.0.0** - Initial Release
- Real-time advancement synchronization via Redis
- Automatic MySQL fallback for reliability
- Reset and rollback commands
- Admin commands (reload, status)
- Async database operations
- Cross-server advancement sharing