AstralSync fires two custom Bukkit events during the player data lifecycle. Both extend org.bukkit.event.Event and can be listened to with standard @EventHandler annotations.
PlayerDataLoadedEvent
com.astralrealms.sync.event.PlayerDataLoadedEvent
Fired on the main server thread after a player's snapshot has been fully deserialized and applied. This is the earliest point at which player data is guaranteed to be available via SyncAPI.
Fields
Method
Return Type
Description
getPlayer()
Player
The player whose data was loaded
getSaveUser()
OnlineSaveUser
The data holder for this player
isFirstLoad()
boolean
true if this is the player's first ever snapshot (new player)
Example
@EventHandler
public void onDataLoaded(PlayerDataLoadedEvent event) {
Player player = event.getPlayer();
if (event.isFirstLoad()) {
// New player — apply welcome kit, send tutorial, etc.
player.sendMessage("Welcome! Setting up your profile...");
return;
}
// Existing player — data is ready to read
SyncAPI.findData(player.getUniqueId(), MyData.class).ifPresent(data -> {
player.sendMessage("Welcome back! You have " + data.getPoints() + " points.");
});
}
SnapshotCreatedEvent
com.astralrealms.sync.event.SnapshotCreatedEvent
Fired after a player snapshot has been successfully written to the database. The async status of this event mirrors the calling context — it may fire on a virtual thread.
Fields
Method
Return Type
Description
getPlayer()
Player
The player whose snapshot was saved
getCause()
SnapshotCause
The reason the snapshot was created
Example
@EventHandler
public void onSnapshotCreated(SnapshotCreatedEvent event) {
if (event.getCause() == SnapshotCause.DEATH) {
// React to a death snapshot — e.g. log, audit, etc.
getLogger().info(event.getPlayer().getName() + " death snapshot saved.");
}
}