Player Management

This guide covers player-specific operations including adding players to clans, setting ranks, and managing player data.

Adding Players to Clans

Basic Addition

The simplest way to add a player to a clan:

ClanPlus clansPlusAPI = Bukkit.getServicesManager().getRegistration(ClanPlus.class).getProvider();
ClanPlus.ClanManagerUtil clanManager = clansPlusAPI.getClanManager();

String playerName = "Cortez_Romeo";
String clanName = "HelloClan";

clanManager.addPlayerToAClan(playerName, clanName, false);

The third parameter forceToLeaveOldClan determines whether the player should be removed from their current clan first.

Force Transfer from Another Clan

If a player is already in a clan and you want to transfer them:

String playerName = "Cortez_Romeo";
String newClanName = "NewClan";

// Force player to leave their current clan and join the new one
clanManager.addPlayerToAClan(playerName, newClanName, true);

Safe Addition with Checks

Check if player exists

ClanPlus.PluginDataManagerUtil dataManager = clansPlusAPI.getPluginDataManager();

String playerName = "Cortez_Romeo";

if (!dataManager.getPlayerDatabase().containsKey(playerName)) {
    // Load player data if not in memory
    dataManager.loadPlayerDatabase(playerName);
}

Check if player is already in a clan

if (clanManager.isPlayerInClan(playerName)) {
    IPlayerData playerData = dataManager.getPlayerDatabase(playerName);
    getLogger().warning(playerName + " is already in clan: " + playerData.getClan());
    return;
}

Verify clan exists

String clanName = "HelloClan";

if (!clanManager.isClanExisted(clanName)) {
    getLogger().warning("Clan " + clanName + " does not exist!");
    return;
}

Add player to clan

clanManager.addPlayerToAClan(playerName, clanName, false);
getLogger().info("Successfully added " + playerName + " to " + clanName);

Complete Example: Adding a Player

Here’s a comprehensive method that safely adds a player to a clan:

public boolean addPlayerToClan(String playerName, String clanName) {
    ClanPlus clansPlusAPI = Bukkit.getServicesManager().getRegistration(ClanPlus.class).getProvider();
    ClanPlus.PluginDataManagerUtil dataManager = clansPlusAPI.getPluginDataManager();
    ClanPlus.ClanManagerUtil clanManager = clansPlusAPI.getClanManager();
    
    // Verify player data exists
    if (!dataManager.getPlayerDatabase().containsKey(playerName)) {
        dataManager.loadPlayerDatabase(playerName);
    }
    
    // Check if clan exists
    if (!clanManager.isClanExisted(clanName)) {
        getLogger().severe("Clan " + clanName + " does not exist!");
        return false;
    }
    
    // Check if player is already in a clan
    if (clanManager.isPlayerInClan(playerName)) {
        IPlayerData playerData = dataManager.getPlayerDatabase(playerName);
        getLogger().warning(playerName + " is already in clan: " + playerData.getClan());
        return false;
    }
    
    // Add player to clan
    clanManager.addPlayerToAClan(playerName, clanName, false);
    
    getLogger().info("Successfully added " + playerName + " to " + clanName);
    return true;
}

Setting Player Ranks

Available Ranks

ClansPlus has three rank levels:

Rank.LEADER - Clan owner with full permissions
Rank.MANAGER - Trusted member with elevated permissions
Rank.MEMBER - Regular clan member

Promoting to Leader

String playerName = "Cortez_Romeo";
String clanName = "HelloClan";

IPlayerData playerData = dataManager.getPlayerDatabase(playerName);
IClanData clanData = dataManager.getClanDatabase(clanName);

if (playerData != null && clanData != null) {
    // Set player rank to leader
    playerData.setRank(Rank.LEADER);
    
    // Update clan owner
    clanData.setOwner(playerName);
    
    // Save changes
    dataManager.savePlayerDatabaseToStorage(playerName, playerData);
    dataManager.saveClanDatabaseToStorage(clanName, clanData);
}

Promoting to Manager

IPlayerData playerData = dataManager.getPlayerDatabase("Cortez_Romeo");

if (playerData != null && playerData.getClan() != null) {
    playerData.setRank(Rank.MANAGER);
    dataManager.savePlayerDatabaseToStorage("Cortez_Romeo", playerData);
}

Demoting to Member

IPlayerData playerData = dataManager.getPlayerDatabase("Cortez_Romeo");

if (playerData != null && playerData.getClan() != null) {
    playerData.setRank(Rank.MEMBER);
    dataManager.savePlayerDatabaseToStorage("Cortez_Romeo", playerData);
}

Checking Player Rank Permissions

Verify if a player has sufficient rank for an operation:

String playerName = "Cortez_Romeo";
Rank requiredRank = Rank.MANAGER;

if (clanManager.isPlayerRankSatisfied(playerName, requiredRank)) {
    getLogger().info(playerName + " has sufficient rank!");
} else {
    getLogger().warning(playerName + " does not have required rank: " + requiredRank);
}

Leaders automatically satisfy all rank requirements. Managers satisfy Member requirements.

Updating Player Data

Setting Score Collected

IPlayerData playerData = dataManager.getPlayerDatabase("Cortez_Romeo");

if (playerData != null) {
    long currentScore = playerData.getScoreCollected();
    playerData.setScoreCollected(currentScore + 50L);
    
    dataManager.savePlayerDatabaseToStorage("Cortez_Romeo", playerData);
}

Updating Last Activated

IPlayerData playerData = dataManager.getPlayerDatabase("Cortez_Romeo");

if (playerData != null) {
    playerData.setLastActivated(System.currentTimeMillis());
    dataManager.savePlayerDatabaseToStorage("Cortez_Romeo", playerData);
}

Setting Join Date

IPlayerData playerData = dataManager.getPlayerDatabase("Cortez_Romeo");

if (playerData != null) {
    playerData.setJoinDate(System.currentTimeMillis());
    dataManager.savePlayerDatabaseToStorage("Cortez_Romeo", playerData);
}

Querying Player Information

Getting All Player Data

public void displayPlayerInfo(String playerName) {
    IPlayerData playerData = dataManager.getPlayerDatabase(playerName);
    
    if (playerData == null) {
        getLogger().warning("Player " + playerName + " not found!");
        return;
    }
    
    getLogger().info("=== Player Info: " + playerName + " ===");
    getLogger().info("UUID: " + playerData.getUUID());
    getLogger().info("Clan: " + (playerData.getClan() != null ? playerData.getClan() : "None"));
    getLogger().info("Rank: " + (playerData.getRank() != null ? playerData.getRank() : "None"));
    getLogger().info("Join Date: " + playerData.getJoinDate());
    getLogger().info("Score Collected: " + playerData.getScoreCollected());
    getLogger().info("Last Activated: " + playerData.getLastActivated());
}

Listing All Players in a Clan

public void listClanMembers(String clanName) {
    IClanData clanData = dataManager.getClanDatabase(clanName);
    
    if (clanData == null) {
        getLogger().warning("Clan " + clanName + " not found!");
        return;
    }
    
    List<String> members = clanData.getMembers();
    getLogger().info("=== Members of " + clanName + " ===");
    
    for (String memberName : members) {
        IPlayerData playerData = dataManager.getPlayerDatabase(memberName);
        
        if (playerData != null) {
            String rank = playerData.getRank() != null ? playerData.getRank().toString() : "UNKNOWN";
            getLogger().info("- " + memberName + " (" + rank + ")");
        }
    }
}

Finding Players by Rank

public List<String> getPlayersByRank(String clanName, Rank rank) {
    List<String> playersWithRank = new ArrayList<>();
    
    IClanData clanData = dataManager.getClanDatabase(clanName);
    if (clanData == null) return playersWithRank;
    
    for (String memberName : clanData.getMembers()) {
        IPlayerData playerData = dataManager.getPlayerDatabase(memberName);
        
        if (playerData != null && playerData.getRank() == rank) {
            playersWithRank.add(memberName);
        }
    }
    
    return playersWithRank;
}

// Usage
List<String> managers = getPlayersByRank("HelloClan", Rank.MANAGER);
getLogger().info("Managers: " + String.join(", ", managers));

Removing Players from Clans

Safe Removal

public boolean removePlayerFromClan(String playerName) {
    IPlayerData playerData = dataManager.getPlayerDatabase(playerName);
    
    if (playerData == null || playerData.getClan() == null) {
        getLogger().warning(playerName + " is not in a clan!");
        return false;
    }
    
    String clanName = playerData.getClan();
    IClanData clanData = dataManager.getClanDatabase(clanName);
    
    if (clanData == null) {
        getLogger().severe("Data inconsistency for player " + playerName);
        return false;
    }
    
    // Remove from clan members list
    clanData.getMembers().remove(playerName);
    
    // Clear player data
    dataManager.clearPlayerDatabase(playerName);
    
    // Save changes
    dataManager.saveClanDatabaseToStorage(clanName, clanData);
    dataManager.savePlayerDatabaseToStorage(playerName);
    
    getLogger().info("Removed " + playerName + " from " + clanName);
    return true;
}

Always remove the player from the clan’s member list AND clear their player data to maintain database consistency.

Complete Example: Player Lifecycle

Here’s a complete example showing a player’s lifecycle from joining to leaving:

public void playerLifecycleExample() {
    // Initialize API
    ClanPlus clansPlusAPI = Bukkit.getServicesManager().getRegistration(ClanPlus.class).getProvider();
    ClanPlus.PluginDataManagerUtil dataManager = clansPlusAPI.getPluginDataManager();
    ClanPlus.ClanManagerUtil clanManager = clansPlusAPI.getClanManager();
    
    String playerName = "Cortez_Romeo";
    String clanName = "HelloClan";
    
    // 1. Add player to clan
    clanManager.addPlayerToAClan(playerName, clanName, false);
    
    // 2. Player starts as MEMBER (automatically set by addPlayerToAClan)
    IPlayerData playerData = dataManager.getPlayerDatabase(playerName);
    getLogger().info("Initial rank: " + playerData.getRank()); // MEMBER
    
    // 3. Promote to manager after some time
    playerData.setRank(Rank.MANAGER);
    dataManager.savePlayerDatabaseToStorage(playerName, playerData);
    
    // 4. Update player's score
    playerData.setScoreCollected(playerData.getScoreCollected() + 100L);
    dataManager.savePlayerDatabaseToStorage(playerName, playerData);
    
    // 5. Update last activated
    playerData.setLastActivated(System.currentTimeMillis());
    dataManager.savePlayerDatabaseToStorage(playerName, playerData);
    
    // 6. Check permissions
    if (clanManager.isPlayerRankSatisfied(playerName, Rank.MEMBER)) {
        getLogger().info(playerName + " can perform member actions");
    }
    
    // 7. Eventually promote to leader
    playerData.setRank(Rank.LEADER);
    IClanData clanData = dataManager.getClanDatabase(clanName);
    clanData.setOwner(playerName);
    
    dataManager.savePlayerDatabaseToStorage(playerName, playerData);
    dataManager.saveClanDatabaseToStorage(clanName, clanData);
    
    // 8. Later, player leaves clan
    clanData.getMembers().remove(playerName);
    dataManager.clearPlayerDatabase(playerName);
    
    dataManager.saveClanDatabaseToStorage(clanName, clanData);
    dataManager.savePlayerDatabaseToStorage(playerName);
}

Working with Online Players

You can also work with online Player objects:

Player player = Bukkit.getPlayer("Cortez_Romeo");

if (player != null) {
    // Check if online player is in a clan
    if (clanManager.isPlayerInClan(player)) {
        IClanData clanData = dataManager.getClanDatabaseByPlayerName(player.getName());
        
        if (clanData != null) {
            player.sendMessage("You are in clan: " + clanData.getName());
        }
    } else {
        player.sendMessage("You are not in a clan!");
    }
}

Getting Started

Core API

Data Models

Examples

Adding Players to Clans

Basic Addition

Force Transfer from Another Clan

Safe Addition with Checks

Complete Example: Adding a Player

Setting Player Ranks

Available Ranks

Promoting to Leader

Promoting to Manager

Demoting to Member

Checking Player Rank Permissions

Updating Player Data

Setting Score Collected

Updating Last Activated

Setting Join Date

Querying Player Information

Getting All Player Data

Listing All Players in a Clan

Finding Players by Rank

Removing Players from Clans

Safe Removal

Complete Example: Player Lifecycle

Working with Online Players

Next Steps

Clan Operations

API Reference

Build docs developers (and LLMs) love

Getting Started

Core API

Data Models

Examples

​Adding Players to Clans

​Basic Addition

​Force Transfer from Another Clan

​Safe Addition with Checks

​Complete Example: Adding a Player

​Setting Player Ranks

​Available Ranks

​Promoting to Leader

​Promoting to Manager

​Demoting to Member

​Checking Player Rank Permissions

​Updating Player Data

​Setting Score Collected

​Updating Last Activated

​Setting Join Date

​Querying Player Information

​Getting All Player Data

​Listing All Players in a Clan

​Finding Players by Rank

​Removing Players from Clans

​Safe Removal

​Complete Example: Player Lifecycle

​Working with Online Players

​Next Steps

Clan Operations

API Reference

Build docs developers (and LLMs) love

Adding Players to Clans

Basic Addition

Force Transfer from Another Clan

Safe Addition with Checks

Complete Example: Adding a Player

Setting Player Ranks

Available Ranks

Promoting to Leader

Promoting to Manager

Demoting to Member

Checking Player Rank Permissions

Updating Player Data

Setting Score Collected

Updating Last Activated

Setting Join Date

Querying Player Information

Getting All Player Data

Listing All Players in a Clan

Finding Players by Rank

Removing Players from Clans

Safe Removal

Complete Example: Player Lifecycle

Working with Online Players

Next Steps