Utilities-OG

A collection of utilities and APIs used by TrueOG Network. Developed by christianniehaus & NotAlexNoyle.

Current Target: Purpur 1.19.4

Building:

./gradlew build

The resulting .jar file will be in build/libs

At the moment, any config change requires a server restart to take effect.

Features:

• Mock Bamboo: Enables crafting mock bamboo planks from 2x2 bamboo and mock bamboo wood from 2x2 mock bamboo planks.
• Chain Armor: Enables crafting chain armor from chains.
• Color Codes: Displays information to players about Bukkit's chat color codes and their syntax.
• MiniPlaceholderAPI: Enables a custom, easy-to-use MiniPlaceholders API (Note: May require additional configuration for specific placeholders).
• NoFlippy: Prevents trapdoors from being flipped in WorldGuard regions where the "can-flippy" flag is set to DENY (Requires WorldGuard plugin).
• TogglePhantoms: Allows players to use the /togglephantoms command to turn phantom spawning on or off for themselves.
• Ping: Provides two commands: /ping (displays real player ping) and /bing (replicates vanilla /ping functionality).
• Ranks Menu: Displays information to players about available ranks at the TrueOG Network Store.

Warning:

• DisableEntityCramming (Default: false): Disables entity cramming damage server-wide. This can cause lag if no other plugin manages entity limits. Enable this Module only if you have a separate plugin managing entity limitations.

Permissions:

• utilities.about
  • Description: Allows players to use the base /utilities command to get information about the plugin.
  • Default: op (Server Operator)
• utilities.colorcodes
  • Description: Grants permission to use the /colorcodes command to view Bukkit chat color code information.
  • Default: op (Server Operator)
• utilities.togglephantoms
  • Description: Allows players to use the /togglephantoms command to enable or disable phantom spawning for themselves.
  • Default: op (Server Operator)
• utilities.togglecramming
  • Description: Grants permission to use the /togglecramming command (if enabled) to manage entity cramming damage.
  • Default: op (Server Operator)
• utilities.ranks
  • Description: Allows players to use the /ranks command to view information about available ranks on the TrueOG Network Store.
  • Default: op (Server Operator)
• utilities.ping
  • Description: Grants permission to use the /ping (real ping) and /bing (mimics vanilla ping) commands.
  • Default: op (Server Operator)

Please note: These permissions can be modified in the Utilities-OG configuration file config.yml.

API Documentation:

[void] trueogMessage(Player player, String message)

Sends a message to the specified player with TrueOG formatting. Supports both modern color codes and legacy Bukkit color codes (case-insensitive). Automatically expands MiniPlaceholders within the message.

Kotlin:

val targetPlayer = Bukkit.getPlayer("USERNAME")
UtilitiesOG.trueogMessage(targetPlayer, "&6This is a &*message with <green>True&4OG <bold>formatting!")

Java:

Player targetPlayer = Bukkit.getPlayer("USERNAME");
UtilitiesOG.trueogMessage(targetPlayer, "&6This is a &*message with <green>True&4OG <bold>formatting!");

[void] trueogMessage(UUID playerUUID, String message)

Sends a message to a player identified by their UUID with TrueOG formatting. Useful when the Bukkit Player object is not available. Supports modern color codes and legacy Bukkit color codes (case-insensitive), and expands MiniPlaceholders within the message.

Kotlin:

UUID playerUUID = UUID.fromString("player_uuid");
UtilitiesOG.trueogMessage(playerUUID, "&6Hello there!");

Java:

UUID playerUUID = UUID.fromString("player_uuid");
UtilitiesOG.trueogMessage(playerUUID, "&6Hello there!");

[TextComponent] trueogExpand(String message)

Expands MiniPlaceholders within a message string without any player context. Supports color code processing via TrueOG's formatting.

Kotlin:

val message = "Welcome to the server, everyone!"
val expandedMessage = UtilitiesOG.trueogExpand(message)

Java:

String message = "Welcome to the server, everyone!";
TextComponent expandedMessage = UtilitiesOG.trueogExpand(message);

[TextComponent] trueogExpand(String message, Player player)

Expands MiniPlaceholders within a message string using the provided player's context. Supports color code processing.

Kotlin:

val targetPlayer = Bukkit.getPlayer("SomePlayer")
val message = "Welcome back, <player_display_name>!"
val expandedMessage = UtilitiesOG.trueogExpand(message, targetPlayer)
UtilitiesOG.trueogMessage(targetPlayer, expandedMessage)

Java:

Player targetPlayer = Bukkit.getPlayer("SomePlayer");
String message = "Welcome back, <player_display_name>!";
TextComponent expandedMessage = UtilitiesOG.trueogExpand(message, targetPlayer);
UtilitiesOG.trueogMessage(targetPlayer, expandedMessage);

[TextComponent] trueogExpand(String message, Player player, Player target)

Expands MiniPlaceholders within a message string using both the sender's and the target's player contexts, which is useful for relational placeholders. Supports color code processing.

Kotlin:

val player = Bukkit.getPlayer("Player")
val target = Bukkit.getPlayer("TargetPlayer")
val message = "<player_display_name> is sending a message to <target_display_name>"
val expandedMessage = UtilitiesOG.trueogExpand(message, player, target)
UtilitiesOG.trueogMessage(player, expandedMessage)

Java:

Player player = Bukkit.getPlayer("Player");
Player target = Bukkit.getPlayer("TargetPlayer");
String message = "<player_display_name> is sending a message to <target_display_name>";
TextComponent expandedMessage = UtilitiesOG.trueogExpand(message, player, target);
UtilitiesOG.trueogMessage(player, expandedMessage);

[TextComponent] trueogExpand(String message, UUID playerUUID)

Expands MiniPlaceholders within a message string using a player's UUID, useful when the Player object isn't available. Supports color code processing.

Kotlin:

val playerUUID = UUID.fromString("player_uuid")
val message = "Welcome back, <player_display_name>!"
val expandedMessage = UtilitiesOG.trueogExpand(message, playerUUID)
UtilitiesOG.trueogMessage(playerUUID, expandedMessage)

Java:

UUID playerUUID = UUID.fromString("player_uuid");
String message = "Welcome back, <player_display_name>!";
TextComponent expandedMessage = UtilitiesOG.trueogExpand(message, playerUUID);
UtilitiesOG.trueogMessage(playerUUID, expandedMessage);

[void] registerGlobalPlaceholder(String placeholderName, {String})

Registers a global MiniPlaceholder that can be used anywhere in your messages. The valueSupplier provides the placeholder's value at runtime. Prefixes are the values before the first underscore. For example, the prefix of server_name is server.

Examples Without Arguments:

Kotlin:

UtilitiesOG.registerGlobalPlaceholder("server_name") { "&aTrue&cOG &eNetwork" }

Java:

UtilitiesOG.registerGlobalPlaceholder("server_name", () -> "&aTrue&cOG &eNetwork");

Examples With Arguments:

Kotlin:

UtilitiesOG.registerGlobalPlaceholder("server_stat") { args ->
    val statName = args.getOrNull(0)?.lowercase() ?: return@registerGlobalPlaceholder "Invalid stat name"
    when (statName) {
        "uptime" -> "Up for 5 hours"
        "playercount" -> Bukkit.getOnlinePlayers().size.toString()
        else -> "Unknown stat"
    }
}

Java:

UtilitiesOG.registerGlobalPlaceholder("server_stat", args -> {
    if (args.isEmpty()) return "Invalid stat name";
    String statName = args.get(0).toLowerCase();
    switch (statName) {
        case "uptime":
            return "Up for 5 hours";
        case "playercount":
            return String.valueOf(Bukkit.getOnlinePlayers().size());
        default:
            return "Unknown stat";
    }
});

[void] registerAudiencePlaceholder(String name, player -> {String})

Registers an audience-specific MiniPlaceholder. The valueFunction uses the player's context to generate a dynamic value for the placeholder. Prefixes are the values before the first underscore. For example, the prefix of player_display_name is player.

Examples Without Arguments:

Kotlin:

UtilitiesOG.registerAudiencePlaceholder("player_display_name") { player ->
    val luckPerms = LuckPermsProvider.get()
    val user = luckPerms.getUserManager().getUser(player.uniqueId)
    val prefix = user?.cachedData?.metaData?.prefix ?: ""
    "$prefix ${player.name}"
}

Java:

UtilitiesOG.registerAudiencePlaceholder("player_display_name", player -> {
    LuckPerms luckPerms = LuckPermsProvider.get();
    User user = luckPerms.getUserManager().getUser(player.getUniqueId());
    String prefix = user != null ? user.getCachedData().getMetaData().getPrefix() : "";
    return prefix + " " + player.getName();
});

Examples With Arguments:

Kotlin:

UtilitiesOG.registerAudiencePlaceholder("essentials_kit_last_use") { player, args ->
    val kitName = args.getOrNull(0)?.lowercase() ?: return@registerAudiencePlaceholder "Invalid kit name"
    val kit = try {
        Kit(kitName, essentials) // Assume 'essentials' is properly initialized
    } catch (e: Exception) {
        return@registerAudiencePlaceholder "Invalid kit name"
    }
    val time = essentials.getUser(player.uniqueId).getKitTimestamp(kit.name)
    if (time <= 0) "Never used" else DateFormat.getDateInstance().format(Date(time))
}

Java:

UtilitiesOG.registerAudiencePlaceholder("essentials_kit_last_use", (player, args) -> {
    if (args.isEmpty()) return "Invalid kit name";
    String kitName = args.get(0).toLowerCase();
    Kit kit;
    try {
        kit = new Kit(kitName, essentials); // Assume 'essentials' is properly initialized
    } catch (Exception e) {
        return "Invalid kit name";
    }
    long time = essentials.getUser(player.getUniqueId()).getKitTimestamp(kit.getName());
    return time <= 0 ? "Never used" : DateFormat.getDateInstance().format(new Date(time));
});

[void] registerRelationalPlaceholder(String name, player, target -> {String})

Registers a relational MiniPlaceholder that depends on two players (e.g., viewer and target). The valueFunction provides a dynamic value based on both players' contexts. Prefixes are the values before the first underscore. For example, the prefix of distance_between is distance.

Examples Without Arguments:

Kotlin:

UtilitiesOG.registerRelationalPlaceholder("distance_between") { player, target ->
    val distance = player.location.distance(target.location)
    "Distance: ${distance.toInt()} blocks"
}

Java:

UtilitiesOG.registerRelationalPlaceholder("distance_between", (player, target) -> {
    double distance = player.getLocation().distance(target.getLocation());
    return "Distance: " + (int) distance + " blocks";
});

Examples With Arguments:

Kotlin:

UtilitiesOG.registerRelationalPlaceholder("relation_compare_stat") { player, target, args ->
    val stat = args.getOrNull(0)?.lowercase() ?: return@registerRelationalPlaceholder "No stat provided"
    when (stat) {
        "balance" -> {
            val playerBalance = getBalance(player) // Implement getBalance accordingly
            val targetBalance = getBalance(target) // Implement getBalance accordingly
            when {
                playerBalance > targetBalance -> "You have more money than ${target.name}"
                playerBalance < targetBalance -> "${target.name} has more money than you"
                else -> "You and ${target.name} have the same amount of money"
            }
        }
        else -> "Unknown stat"
    }
}

Java:

UtilitiesOG.registerRelationalPlaceholder("relation_compare_stat", (player, target, args) -> {
    if (args.isEmpty()) return "No stat provided";
    String stat = args.get(0).toLowerCase();
    switch (stat) {
        case "balance":
            double playerBalance = getBalance(player); // Implement getBalance accordingly
            double targetBalance = getBalance(target); // Implement getBalance accordingly
            if (playerBalance > targetBalance) {
                return "You have more money than " + target.getName();
            } else if (playerBalance < targetBalance) {
                return target.getName() + " has more money than you";
            } else {
                return "You and " + target.getName() + " have the same amount of money";
            }
        default:
            return "Unknown stat";
    }
});

[TextComponent] trueogColorize(String message)

Formats a String into a TextComponent. Supports modern and legacy color codes. Does not include custom MiniPlaceholder Expansion logic.

Kotlin:

val colorized = UtilitiesOG.trueogColorize(message)

Java:

TextComponent colorized = UtilitiesOG.trueogColorize(message);

[String] stripFormatting(String content)

Strips legacy and modern color codes and formatting from a String.

Kotlin:

val unformatted = UtilitiesOG.stripFormatting(content)

Java:

String unformatted = UtilitiesOG.stripFormatting(content);

[void] logToConsole(String prefix, String message)

Logs a message to the server console with a prefix. The message and prefix will have modern and legacy color codes and formatting stripped.

Kotlin:

UtilitiesOG.logToConsole("[MyPlugin-OG]", "&6This is a &*message with <green>color codes!")

Java:

UtilitiesOG.logToConsole("[MyPlugin-OG]", "&6This is a &*message with <green>color codes!");

[BukkitTask] runTaskAsynchronously(final Runnable run)

Schedules a task to run asynchronously using the Bukkit scheduler under the UtilitiesOG plugin.

Kotlin:

val asyncTask = UtilitiesOG.runTaskAsynchronously {
    // Your async code here
}

Java:

BukkitTask asyncTask = UtilitiesOG.runTaskAsynchronously(() -> {
    // Your async code here
});