Moderation Module

How to use the Mineplex Studio Moderation Module to enforce rules on your projects.

The Moderation Module is one of the built-in Studio Modules that allows you to manage and enforce player behavior within your projects. With this module, you can punish specific players through various means such as bans, mutes, or other restrictions. These punishments can be managed by your project's moderation team and tailored to fit the needs of your community.

Important Note:

If you'd like to make your own punishment system, all punishments must go through this Module, this helps us track punishments, handle appeals and ensure accountability. Please do not create your own Punishment table / Punishment database, this will result in your project being rejected. You can create your own user interface / systems.

How everything connects 🔗

The Moderation Module integrates seamlessly with your project, ensuring a consistent approach to managing player behavior. By utilizing the provided methods, you can automate and customize moderation tasks to create a fair and enjoyable experience for all users.

The Punishment Object: The Punishment object is central to the Moderation Module and contains the following fields:

  • Identifier: Unique ID for the punishment.
  • Player Identifier: UUID of the punished player.
  • Moderator Identifier: UUID of the moderator who applied the punishment.
  • Start Timestamp: When the punishment started.
  • Applicable Projects: Set of projects where the punishment applies.
  • Reason: Pre-defined reason for the punishment.
  • Notes: Additional information about the punishment.
  • Removal Information: Details about the removal of the punishment, if applicable.

For a full breakdown of the punishment object, see the punishment object documentation

Reasons 🔗

Instead of allowing arbitrary text, the module uses a pre-defined list of reasons for consistency and clarity.

The PunishmentReason object includes:

  • Punishment type: Specifies the type of punishment (e.g., mute, ban).
  • Display reason: User-friendly explanation of the reason.
  • Priority: Importance level of the reason (important if they have multiple at once).
  • Identifier: Unique ID for the reason.
  • Duration: Length of time the punishment lasts.

For a full breakdown of the reasons and some defaults we've added for you, check out the punishment reason documentation

Method overview 🔗

Below is an overview of the key methods available in the Moderation Module:

listActivePunishments 🔗

@NonNull CompletableFuture<@NonNull List<@NonNull Punishment>> listActivePunishments(
            @NonNull UUID playerUUID, boolean includeGlobal);

Retrieves a list of active punishments for a specific player. You can include global punishments by setting includeGlobal to true.

Example Usage: 🔗

final UUID playerUUID = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
moderationModule.listActivePunishments(playerUUID, true).thenAccept(punishments -> {
    punishments.forEach(punishment -> {
        System.out.println("Active Punishment: " + punishment);
    });
});

listAllPunishments 🔗

@NonNull CompletableFuture<@NonNull List<@NonNull Punishment>> listAllPunishments(@NonNull UUID playerUUID, boolean includeGlobal);

Retrieves a complete list of punishments for a player, both active and inactive. Use includeGlobal to fetch global punishments.

applyPunishment 🔗

@NonNull CompletableFuture<Punishment> applyPunishment(@NonNull Punishment punishment);

Applies a new punishment to a player. Returns the created punishment object.

Example Usage: 🔗

final PunishmentImpl punishment = PunishmentImpl.builder()
    .playerId(UUID.fromString("123e4567-e89b-12d3-a456-426614174000"))
    .moderatorId(UUID.fromString("223e4567-e89b-12d3-a456-426614174000"))
    .startTimestamp(Instant.now())
    .applicableProjects(Set.of(Objects.requireNonNull(System.getenv("MINEPLEX_PROJECT_ID"))))
    .punishmentReason(BuiltInReason.HACKING_ESCALATION)
    .notes("https://evidence.com")
    .build();

moderationModule.applyPunishment(punishment).thenAccept(appliedPunishment -> {
    System.out.println("Punishment applied: " + appliedPunishment);
});

updatePunishment 🔗

@NonNull CompletableFuture<Punishment> updatePunishment(@NonNull Punishment punishment);

Updates an existing punishment with new information, such as adding notes or updating the removal information.

isMuted 🔗

@NonNull CompletableFuture<@NonNull Boolean> isMuted(@NonNull UUID playerUUID);

Checks if a player is currently muted.

Example Usage: 🔗

moderationModule.isMuted(playerUUID).thenAccept(isMuted -> {
    if (isMuted) {
        System.out.println("Player is muted.");
    } else {
        System.out.println("Player is not muted.");
    }
});

isBanned 🔗

@NonNull CompletableFuture<@NonNull Boolean> isBanned(@NonNull UUID playerUUID);

Checks if a player is currently banned.

hasActivePunishment 🔗

@NonNull CompletableFuture<@NonNull Boolean> hasActivePunishment(@NonNull UUID playerUUID);

Determines whether a player has any active punishment.

disableDefaultPunishmentCommand 🔗

void disableDefaultPunishmentCommand();

Disables the default punishment command, allowing you to implement custom commands tailored to your project. See more information in the punishment command guide

Examples 🔗

Applying a Temporary Ban 🔗

final PunishmentReasonImpl banReason = PunishmentReasonImpl.builder()
    .type(PunishmentType.TEMP_BAN)
    .displayReason("Excessive Toxicity")
    .priority(1)
    .reasonIdentifier("toxicity")
    .duration(Duration.ofSeconds(3600 * 24));

final PunishmentImpl punishment = PunishmentImpl.builder()
    .playerId(UUID.fromString("123e4567-e89b-12d3-a456-426614174000"))
    .moderatorId(UUID.fromString("223e4567-e89b-12d3-a456-426614174000"))
    .startTimestamp(Instant.now())
    .applicableProjects(Set.of(Objects.requireNonNull(System.getenv("MINEPLEX_PROJECT_ID"))))
    .punishmentReason(banReason)
    .notes("https://evidence.com")
    .build();

moderationModule.applyPunishment(punishment).thenAccept(appliedPunishment -> {
    System.out.println("Ban applied: " + appliedPunishment);
});

Checking and Removing a Punishment 🔗

final ModerationModule moderationModule = MineplexModuleManager.getRegisteredModule(ModerationModule.class);
moderationModule.listActivePunishments(playerUUID, false).thenAccept(punishments -> {
    if (!punishments.isEmpty()) {
        Punishment punishment = punishments.get(0);

        final PunishmentRemovalImpl removalInformation = PunishmentRemovalImpl.builder()
            .removeFromHistory(false)
            .removalReason("Forgiven")
            .removalTimestamp(Instant.now())
            .removalModerator(UUID.fromString("223e4567-e89b-12d3-a456-426614174000"))

        punishment.setRemovalInformation(removalInformation);
        moderationModule.updatePunishment(punishment).thenAccept(updated -> {
            System.out.println("Punishment updated: " + updated);
        });
    } else {
        System.out.println("No active punishments found.");
    }
});