SyncAPI

com.astralrealms.sync.SyncAPI

The primary entry point for interacting with AstralSync from other plugins. All methods are static.

Methods

`findHolderById`

public static Optional<DataHolder> findHolderById(UUID playerId)

Returns the DataHolder for a currently online player. Returns an empty Optional if the player is not online or their data has not finished loading yet.

Parameters:

Name	Type	Description
`playerId`	`UUID`	The player's unique ID

Returns: Optional<DataHolder> — empty if not found

Example:

UUID uuid = player.getUniqueId();
SyncAPI.findHolderById(uuid).ifPresent(holder -> {
    // holder is guaranteed to be an OnlineSaveUser for online players
    if (holder instanceof OnlineSaveUser onlineUser && onlineUser.hasFinishedLoading()) {
        // safe to read data
    }
});

`findData(UUID, Class<T>)`

public static <T> Optional<T> findData(UUID playerId, Class<T> dataClass)

Retrieves a specific data object from a player's holder, matched by class type. Equivalent to calling holder.findByClass(dataClass).

Parameters:

Name	Type	Description
`playerId`	`UUID`	The player's unique ID
`dataClass`	`Class<T>`	The class of the data to retrieve

Returns: Optional<T> — empty if the player is not loaded or the data type is not stored

Example:

SyncAPI.findData(player.getUniqueId(), PlayerStateData.class)
    .ifPresent(state -> {
        int level = state.getLevel();
    });

`findData(UUID, Key)`

public static <T> Optional<T> findData(UUID playerId, Key key)

Retrieves a specific data object from a player's holder by adapter key. Equivalent to calling holder.findByKey(key).

Parameters:

Name	Type	Description
`playerId`	`UUID`	The player's unique ID
`key`	`net.kyori.adventure.key.Key`	The adapter's key

Returns: Optional<T> — empty if the player is not loaded or the key is not stored

Example:

Key key = Key.key("myplugin", "stats");
SyncAPI.<MyStats>findData(player.getUniqueId(), key)
    .ifPresent(stats -> {
        int kills = stats.getKills();
    });

`registerAdapter`

public static void registerAdapter(SnapshotAdapter<?> adapter)

Registers a SnapshotAdapter so that its data is included in all future snapshot save and load operations. Call this in your plugin's onEnable() method.

AstralSync detects whether the adapter implements VersionedSnapshotAdapter and stores it under the appropriate version slot automatically.

Parameters:

Name	Type	Description
`adapter`	`SnapshotAdapter<?>`	The adapter to register

Example:

@Override
public void onEnable() {
    SyncAPI.registerAdapter(new MyStatsAdapter());
}

`holders`

@Unmodifiable
public static Map<UUID, DataHolder> holders()

Returns an unmodifiable view of all currently loaded data holders, keyed by player UUID. Only includes players who are currently online (or whose data is still in memory during a save operation).

Returns: Map<UUID, DataHolder> — unmodifiable, never null

Example:

int loadedCount = SyncAPI.holders().size();

SyncAPI.holders().forEach((uuid, holder) -> {
    // iterate all online players' data
});

24 April 2026