RankAPIv3

RankAPIv3 is an advanced API for managing player ranks in a Minecraft server. It includes features such as dynamic rank management, temporary ranks, playtime-based promotions, rank persistence, and integration with both configuration files and databases.

This API is designed for flexibility, allowing extensive customization for ranks and efficient management of rank-based features.

---

Key Features

1. Dynamic Rank Management

   • Add, remove, and retrieve ranks dynamically.

   • Store ranks in both configuration files and databases.

2. Temporary Ranks

   • Assign ranks for a limited time.

   • Automatically remove expired temporary ranks.

3. Playtime-Based Promotions

   • Promote players based on their total playtime.

   • Customize playtime requirements for each rank.

4. Rank Persistence

   • Store player ranks per world in the database.

   • Retrieve ranks seamlessly for players across server restarts.

5. Economy Integration

   • Apply rank-based multipliers for economy payouts.

6. Chat Customization

   • Define rank-specific prefixes, suffixes, and chat colors.

---

Initialization

Singleton Pattern

RankAPIv3 uses a private constructor to enforce a singleton pattern:

private RankAPIv3() {
    if (system.getConfigHandler().connection.get().getBoolean("database.enabled")) {
        loadRanks();
        loadRanksFromDatabase();
    } else {
        loadRanks();
    }
}

To initialize and access RankAPIv3:

RankAPIv3 rankAPI = new RankAPIv3();

---

Rank Structure

Rank Class

Each rank is represented by the Rank class with the following attributes:

• Name: The rank identifier.

• Permission: Permission string required for the rank.

• Prefix: Chat prefix.

• Suffix: Chat suffix.

• Chat Color: Default chat color.

• Priority: Determines rank hierarchy.

• Playtime Required: Minimum playtime required for promotion to the rank.

• Economy Multiplier: Multiplier applied for economy-based rewards.

• Taxes Due: Tax deadlines for the rank.

• Taxes Amount: Tax amounts for the rank.

Example

Rank rank = new Rank("Rank1", "system.rank.1", "&6[Rank 1]", "&f", "&a", 10, 3600000, 1.5, 7, 500.0);

---

Public Methods

Rank Management

Add or Retrieve Ranks

• Add new rank:

rankAPI.saveRankToDatabase(rank);

• Get all ranks:

Collection<Rank> ranks = rankAPI.getRanks();

Temporary Ranks

• Assign a temporary rank:

rankAPI.assignTemporaryRank(player.getUniqueId(), "Rank1", TimeUnit.HOURS.toMillis(1));

• Remove a temporary rank:

rankAPI.removeTemporaryRank(player.getUniqueId());

• Check for expired ranks:

rankAPI.checkTemporaryRanks();

---

Playtime Management

Add and Get Playtime

• Add playtime:

rankAPI.addPlaytime(player.getUniqueId(), TimeUnit.HOURS.toMillis(2));

• Retrieve playtime:

long playtime = rankAPI.getPlaytimeFromDatabase(player.getUniqueId());

Promote by Playtime

Promote a player based on their playtime:

rankAPI.promotePlayerByPlaytime(player.getUniqueId());

---

Rank Persistence

Player Rank Management

• Assign rank to a player:

rankAPI.assignRank(player, rank);

• Save rank to a specific world:

rankAPI.savePlayerRank(player, world.getName(), rank.getName());

• Retrieve rank from a specific world:

String rankName = rankAPI.getRankFromDatabase(player, world.getName());

Delete Player Rank

rankAPI.removePlayerRank(player, world.getName());

---

Economy Integration

Get Economy Multiplier

Retrieve the economy multiplier for a rank:

double multiplier = rankAPI.getRankMultiplier("Rank1");

Apply Rank-Based Payout

rankAPI.applyRankPayout(player, 1000.0); // Base payout is 1000.0

---

Chat Customization

Get Chat Settings

• Prefix:

String prefix = rankAPI.getRankPrefix("Rank1");

• Suffix:

String suffix = rankAPI.getRankSuffix("Rank1");

• Chat Color:

String chatColor = rankAPI.getRankChatColor("Rank1");

AFK Prefix

String afkPrefix = rankAPI.setAFKPrefix();

---

Configuration Example

Ranks Configuration

chat:
  rank:
    Rank1:
      permission: "system.rank.1"
      prefix: "&6[Rank 1]"
      suffix: "&f[Admin]"
      chatcolor: "&a"
      priority: 10
      playtimeRequired: 3600000 # 1 hour in milliseconds
      economyMultiplier: 1.5
      taxes:
        due: 7
        amount: 500.0

---

Error Handling

Missing Rank

Logs a warning if a rank is missing during initialization:

[WARNING] Rank 'Rank1' does not exist.

Database Errors

Logs SQL exceptions during database operations:

[SEVERE] Error updating playtime for player <UUID>: <Error Message>

---

Advanced Usage

Promotions with Custom Criteria

Use Criteria to define custom promotion conditions:

Criteria criteria = player -> player.hasPlayedBefore();
rankAPI.promotePlayer(player, newRank, criteria);

---

Best Practices

1. Database and Configuration Sync:

   • Use both saveRankToDatabase and saveRankToConfig to ensure consistency.

2. Temporary Ranks:

   • Regularly invoke checkTemporaryRanks() to clean up expired ranks.

3. Playtime Promotions:

   • Set realistic playtime thresholds to encourage player progression.

4. Logging:

   • Monitor server logs for potential issues with missing ranks or configuration errors.

---