Level Module

How to use the Mineplex Studio Level Module.

The MineplexLevelModule is a module for managing player leveling and experience in the Mineplex system. It provides methods for retrieving, updating, and managing player experience data. This module supports both online and offline players, allowing asynchronous access to player data and rewarding players with experience.

Key Features 🔗

  • Retrieve Player Experience: Fetch experience data for individual or multiple players.
  • Cache Support: Access experience data for online players directly from the cache.
  • Asynchronous Operations: All retrieval and update operations are non-blocking, using CompletableFuture for concurrency.
  • Experience Rewarding: Grant experience to players via predefined sessions.

Rewarding players 🔗

We have designed our system to allow partners to add weights to each action. Rather than directly awarding xp, you report a game session and the players' total action values. This allows us to calculate how much xp to award them based on their own player profile, and network conditions.

To award, we use the Module's rewardGame method:

@NonNull CompletableFuture<@NonNull Map<@NonNull UUID, @NonNull ExperienceAwardResult>>
rewardGame(@NonNull MineplexExperienceSession levelSession)

In-built Example 🔗

We have an in-built MineplexExperienceSessionImpl which implements the MineplexExperienceSession to provide session functionality.

Note:

You need to construct this premade implementation of the session at the START of each game (when your game starts & becomes playable), as we take into account the time you start the session for determining the amount of experience to give to players.

Do not start the session at the end of your game, or before players join, as this will give an innacurate amount of experience.

1

Construct the session

final MineplexExperienceSessionImpl experienceSession = MineplexExperienceSessionImpl.start();

This example will use this class, but you are welcome to create your own implementing class. This is the session we'll be using to award player's with points, which will be converted into experience by our backend system.

2

Award your points

So, the player did something cool, like getting a kill, or claiming a beacon, reward them!

final Player player = event.getPlayer();
final int points = 5;
experienceSession.addPoints(player, points);
3

Apply the session

Once your game comes to an end (and only when this happens!), apply the session's results to the players.

final MineplexLevelModule levelModule = MineplexModuleManager.getRegisteredModule(MineplexLevelModule.class);
// I'm using get here on the future, make sure you're handling the thread safety properly
final CompletableFuture<Map<UUID, ExperienceAwardResult>> awardFuture = levelModule.rewardGame(experienceSession);
4

Inform the players

Once you've told our backend about your session, now we'll tell you how much each player earned!

// Handle the Future asynchronously to avoid blocking the main thread
awardFuture.thenAcceptAsync(result -> {
    // Inform the players inside the callback
    result.forEach((uuid, awarded) -> {
        // Use Bukkit or your game player store API to get the player
        final Player player = Bukkit.getPlayer(uuid);
        // remember to null check awarded, this will happen if nothing is given.
        if (player != null && awarded != null) {
            player.sendMessage(Component.text("You have earned " + awarded.getAwardedExperience() + " Mineplex Network exp!"));
            // Send level-up message
            if (awarded.hasLevelIncreased()) {
                player.sendMessage(Component.text("You have increased in Mineplex Network Level!")); // Add your styling, perhaps include the level!
            }
        }
    });
}).exceptionally(ex -> {
    // Handle any errors during the reward process
    ex.printStackTrace();
    return null; // Return null to satisfy the exceptionally handler
});

Other Methods 🔗

Retrieve Player Experience by OfflinePlayer 🔗

@NonNull CompletableFuture<@NonNull MineplexPlayerExperience> getPlayerExperience(@NonNull OfflinePlayer player)

Example Usage: 🔗

OfflinePlayer player = Bukkit.getOfflinePlayer("playerName");
mineplexLevelModule.getPlayerExperience(player).thenAccept(experience -> {
    System.out.println("Player Level: " + experience.getLevel());
});

Retrieve Player Experience by UUID 🔗

@NonNull CompletableFuture<@NonNull MineplexPlayerExperience> getPlayerExperience(@NonNull UUID playerId)

Example Usage: 🔗

UUID playerId = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
mineplexLevelModule.getPlayerExperience(playerId).thenAccept(experience -> {
    System.out.println("Player XP: " + experience.getExperience());
});