Developer API Overview

AstralSync exposes a public API that allows other plugins to:

Read and write player snapshot data via SyncAPI
Register custom SnapshotAdapter implementations to include plugin-specific data in snapshots
React to data lifecycle events (PlayerDataLoadedEvent, SnapshotCreatedEvent)

Package

All public API types live under:

com.astralrealms.sync

Key packages:

Package	Contents
`com.astralrealms.sync`	`SyncAPI` entry point
`com.astralrealms.sync.adapter`	`SnapshotAdapter`, `VersionedSnapshotAdapter`, `UnloadableSnapshotAdapter`
`com.astralrealms.sync.container`	`AdapterContainer` singleton
`com.astralrealms.sync.event`	`PlayerDataLoadedEvent`, `SnapshotCreatedEvent`
`com.astralrealms.sync.model.holder`	`DataHolder`, `OnlineSaveUser`, `OfflineSaveUser`
`com.astralrealms.sync.model.snapshot`	`SnapshotCause`

Entry Points

Static API

SyncAPI is the primary entry point. All methods are static utility methods.

// Get a player's data holder
Optional<DataHolder> holder = SyncAPI.findHolderById(player.getUniqueId());

// Get a specific data type
Optional<MyData> data = SyncAPI.findData(player.getUniqueId(), MyData.class);

// Register a custom adapter
SyncAPI.registerAdapter(new MyAdapter());

Adapter Registry

AdapterContainer.INSTANCE provides direct access to the adapter registry, including version-aware lookups.

Events

Listen to Bukkit events on the plugin's event bus:

@EventHandler
public void onDataLoaded(PlayerDataLoadedEvent event) {
    // ...
}

Thread Safety

All database operations return CompletableFuture — they execute on a virtual thread pool.
adapter.apply(player, data) is always scheduled on the main server thread.
DataHolder implementations use ConcurrentHashMap internally.
Do not call SyncAPI.findData() or DataHolder.findByKey() from a thread that may race with the load/save cycle without external synchronization. In practice, after PlayerDataLoadedEvent fires, data is safe to read from the main thread.

Compatibility

AstralSync depends on:

AstralCore for BinaryMessage, database utilities, and packet handling
Paper 1.21+ API
PacketEvents for distributed lock packet handling

Your plugin must declare AstralSync in its depend or softdepend list in plugin.yml to ensure correct load order.

24 April 2026