AstralSync

AstralSync is a Paper plugin that provides real-time player data synchronization across server instances. It snapshots a player's entire game state — inventory, attributes, advancements, potion effects, and more — into a compressed, checksummed binary record stored in a relational database. On the next login (to any server sharing the same database and Redis instance), that state is restored transparently.

Key Features

Modular adapter system — any plugin can register its own SnapshotAdapter to include custom data in snapshots
Binary serialization — compact chunked binary format with Deflate compression
Checksum validation — MD5/SHA-256 integrity check on every load to detect corruption
Distributed locking — Redis locks prevent concurrent save/load races in multi-server setups
Caffeine caching — 10,000-entry, 15-minute in-process cache for snapshot reads
Read-only mode — disable saves for maintenance or read-replica servers
Graceful shutdown — waits for all in-flight saves before the JVM exits

Architecture

Player Join → Load

PlayerJoinEvent (LOWEST priority)
  └─ SnapshotService.load()
       ├─ Acquire Redis lock  (30 s TTL)
       ├─ SnapshotRepository.findLatestByPlayer()  ← Caffeine cache
       ├─ ChecksumUtils.validate()
       ├─ FastDeflateUtils.decompress()
       ├─ SnapshotSerializer.deserialize()  ← calls each adapter
       │    └─ adapter.apply(player, data)  (scheduled on main thread)
       ├─ OnlineSaveUser.hasFinishedLoading(true)
       └─ fire PlayerDataLoadedEvent

Save Flow

Trigger event  (disconnect / death / world save / shutdown / manual)
  └─ SnapshotService.save()
       ├─ Skip if read-only mode
       ├─ Acquire Redis lock
       ├─ Validate OnlineSaveUser.hasFinishedLoading()
       ├─ SnapshotSerializer.serialize()  ← calls each adapter.update() then serialize()
       ├─ FastDeflateUtils.compress()
       ├─ ChecksumUtils.compute()
       ├─ SnapshotRepository.save()  ← updates Caffeine cache
       └─ fire SnapshotCreatedEvent

Save triggers and their behavior:

Trigger	Cause	Unloads data?
Player disconnects	`DISCONNECT`	Yes
Player dies	`DEATH`	No
World save	`WORLD_SAVE`	No
Server shutdown	`SERVER_SHUTDOWN`	Yes
Admin rollback	`MANUAL`	No
First join (new player)	`INITIALIZATION`	No

Plugin Info

Property	Value
Version	3.0-SNAPSHOT
API	Paper 1.21
Java	25
Required plugins	AstralCore, PacketEvents
Database	MariaDB
Cache	Redis (distributed locks) + Caffeine (read cache)

24 April 2026