AdvancementSync

Real-time advancement synchronization across your Minecraft network using Redis and MySQL.

Overview

AdvancementSync is a Bukkit plugin that keeps player advancements in sync across multiple servers. When a player unlocks an advancement on one server, it instantly appears on all other servers in your network.

Features

• 🎯 Smart Rollback - Reset or rollback player advancements to a specific point in time
• ⚙️ Configurable - Extensive configuration options to customize behavior per server
• 🔐 Admin Tools - Powerful commands for server administrators to manage advancements
• 📊 Status Monitoring - Real-time status checks for Redis and MySQL connections

Requirements

• Bukkit/Spigot 1.21+
• Java 21+
• Redis server (primary)
• MySQL 8.0+ (fallback storage)

AdvancementSync - Quick Setup

1. Download & Install

Place the JAR in your plugins/ folder and restart the server.

2. Configure Redis

Edit plugins/AdvancementSync/config.yml:

redis:
  host: localhost
  port: 6379
  password: ""

3. Configure MySQL (Optional but Recommended)

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

features:
  teleport-on-join: true
  periodic-save: true
  sync-alerts: true
  use-mysql-fallback: true  # Enable MySQL backup

5. Restart Server

---

Commands

• /advsync reset <player> - Reset all advancements for a player
• /advsync rollback <player> <time> - Rollback to specific time (1h, 30m, 1d)
• /advsync reload - Reload configuration
• /advsync status - View database status
• /advsync help - Show help message

Permission: OP only by default

---

How It Works

1. Primary: Saves advancements 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
5. Network-Wide: All servers see updates instantly

---

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 saved location on join
• periodic-save - Auto-save advancements every 30 seconds
• sync-alerts - Show sync notifications to players
• use-mysql-fallback - Enable MySQL fallback when Redis unavailable

---

Multi-Server Network Example

Server 1 (Survival-1):

server-id: survival-1
redis:
  host: 192.168.1.100
database:
  host: 192.168.1.100

Server 2 (Survival-2):

server-id: survival-2
redis:
  host: 192.168.1.100
database:
  host: 192.168.1.100

Server 3 (Survival-3):

server-id: survival-3
redis:
  host: 192.168.1.100
database:
  host: 192.168.1.100

All servers connect to the same Redis and MySQL, advancements are shared automatically across your entire network.

---

Performance

• ⚡ Async Operations - Prevent server lag with non-blocking sync
• 🔄 Connection Pooling - Efficient resource usage
• 📊 Configurable Intervals - Customize save frequency
• 💾 Smart Caching - Minimize database queries
• 🚀 Scalable - 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
• Verify Redis password if set

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
• Check player has time to sync before switching

---

Support

Issues, suggestions, or questions?

• GitHub: AdvancementSync Repository
• Issues: GitHub Issues
• Discussions: GitHub Discussions