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 <br> redis: <br> host: localhost <br> port: 6379 <br> password: "" <br>

### 3. Configure MySQL (Optional but Recommended)

yaml <br> database: <br> enabled: true <br> host: localhost <br> port: 3306 <br> database: advancementsync <br> username: root <br> password: "" <br> <br> pool: <br> max-connections: 10 <br> min-idle: 2 <br> connection-timeout: 5000 <br>

### 4. Enable Features

yaml <br> features: <br> teleport-on-join: true <br> periodic-save: true <br> sync-alerts: true <br> use-mysql-fallback: true <br>

### 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 <br> server-id: hub-1 <br> redis: <br> host: 192.168.1.100 <br> database: <br> host: 192.168.1.100 <br>

Server 2 (Survival):

yaml <br> server-id: survival-1 <br> redis: <br> host: 192.168.1.100 <br> database: <br> host: 192.168.1.100 <br>

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