player data api

The PlayerDataAPI provides methods to manage player data and caching.

Getting the API

ZelBountyAPI api = Bukkit.getServicesManager().load(ZelBountyAPI.class);
PlayerDataAPI playerDataAPI = api.getPlayerDataAPI();

Methods

getPlayer

Get cached player data synchronously.

@Nullable IBountyPlayer getPlayer(UUID uuid);

Parameters:

• uuid - Player's UUID

Returns: IBountyPlayer object or null if not cached

IBountyPlayer Interface:

public interface IBountyPlayer {
    UUID getUUID();
    String getName();
    IBountyData getBountyData();
    boolean isOnline();
}

Example:

IBountyPlayer bountyPlayer = playerDataAPI.getPlayer(playerUUID);
if (bountyPlayer != null) {
    sender.sendMessage("Player: " + bountyPlayer.getName());
    sender.sendMessage("Bounty: " + bountyPlayer.getBountyData().getFormattedBounty());
    sender.sendMessage("Online: " + bountyPlayer.isOnline());
}

---

loadPlayer

Load player data asynchronously from the database.

CompletableFuture<IBountyPlayer> loadPlayer(UUID uuid);

Parameters:

• uuid - Player's UUID

Returns: CompletableFuture<IBountyPlayer> - Loaded player data

Example:

playerDataAPI.loadPlayer(playerUUID)
    .thenAccept(bountyPlayer -> {
        if (bountyPlayer != null) {
            sender.sendMessage("Loaded: " + bountyPlayer.getName());
        } else {
            sender.sendMessage("Player not found in database.");
        }
    })
    .exceptionally(ex -> {
        sender.sendMessage("Error loading player: " + ex.getMessage());
        return null;
    });

---

savePlayer

Save player data asynchronously to the database.

CompletableFuture<Void> savePlayer(UUID uuid);

Parameters:

• uuid - Player's UUID

Returns: CompletableFuture<Void> - Completes when saved

Example:

playerDataAPI.savePlayer(playerUUID)
    .thenRun(() -> {
        sender.sendMessage("Player data saved!");
    });

---

isPlayerLoaded

Check if a player is currently loaded in the cache.

boolean isPlayerLoaded(UUID uuid);

Parameters:

• uuid - Player's UUID

Returns: true if player data is in memory cache

Example:

if (playerDataAPI.isPlayerLoaded(playerUUID)) {
    // Use synchronous getPlayer()
    IBountyPlayer player = playerDataAPI.getPlayer(playerUUID);
} else {
    // Load asynchronously
    playerDataAPI.loadPlayer(playerUUID).thenAccept(player -> {
        // Handle loaded player
    });
}

---

reloadAllData

Reload all player data from the database.

CompletableFuture<Void> reloadAllData();

Returns: CompletableFuture<Void> - Completes when all data is reloaded

Example:

playerDataAPI.reloadAllData()
    .thenRun(() -> {
        sender.sendMessage("All player data reloaded!");
    });

Data Models

IBountyPlayer

Represents a player with bounty data.

public interface IBountyPlayer {
    /**
     * Get the player's UUID
     */
    UUID getUUID();

    /**
     * Get the player's name
     */
    String getName();

    /**
     * Get the player's bounty data
     */
    IBountyData getBountyData();

    /**
     * Check if the player is currently online
     */
    boolean isOnline();
}

IBountyData

Contains bounty statistics for a player.

public interface IBountyData {
    /**
     * Get the player's UUID
     */
    UUID getPlayerUUID();

    /**
     * Get current bounty amount
     */
    double getBountyAmount();

    /**
     * Get formatted bounty string (e.g., "$1,000.00")
     */
    String getFormattedBounty();

    /**
     * Get total number of bounties this player has set
     */
    int getTotalBountiesSet();

    /**
     * Get total number of bounties this player has claimed
     */
    int getTotalBountiesClaimed();

    /**
     * Get timestamp of last update
     */
    long getLastUpdated();
}

Caching Behavior

• Players are automatically loaded when they join the server

• Players are saved and unloaded when they leave

• Use isPlayerLoaded() to check if data is available synchronously

• Always use loadPlayer() for offline players

Complete Example

public class PlayerStatsCommand implements CommandExecutor {

    private final PlayerDataAPI playerDataAPI;

    public PlayerStatsCommand(PlayerDataAPI playerDataAPI) {
        this.playerDataAPI = playerDataAPI;
    }

    @Override
    public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
        if (args.length == 0) {
            sender.sendMessage("Usage: /bountystats <player>");
            return true;
        }

        String playerName = args[0];
        Player onlinePlayer = Bukkit.getPlayer(playerName);

        if (onlinePlayer != null) {
            // Player is online - data should be cached
            displayStats(sender, playerDataAPI.getPlayer(onlinePlayer.getUniqueId()));
        } else {
            // Player is offline - need to load from database
            OfflinePlayer offlinePlayer = Bukkit.getOfflinePlayer(playerName);
            if (offlinePlayer.hasPlayedBefore()) {
                playerDataAPI.loadPlayer(offlinePlayer.getUniqueId())
                    .thenAccept(data -> displayStats(sender, data))
                    .exceptionally(ex -> {
                        sender.sendMessage("Error: " + ex.getMessage());
                        return null;
                    });
            } else {
                sender.sendMessage("Player has never joined the server.");
            }
        }

        return true;
    }

    private void displayStats(CommandSender sender, IBountyPlayer player) {
        if (player == null) {
            sender.sendMessage("No data found for this player.");
            return;
        }

        IBountyData data = player.getBountyData();
        sender.sendMessage("=== Stats for " + player.getName() + " ===");
        sender.sendMessage("Current Bounty: " + data.getFormattedBounty());
        sender.sendMessage("Bounties Set: " + data.getTotalBountiesSet());
        sender.sendMessage("Bounties Claimed: " + data.getTotalBountiesClaimed());
        sender.sendMessage("Online: " + (player.isOnline() ? "Yes" : "No"));
    }
}