Bukkit Utilities

Bukkit utilities

platform-commons ships a handful of Bukkit-side helpers that take the friction out of building items, translating colors, and reading or writing NBT/PDC data on items. They are static or constructor-based utilities you import and use directly.

ColorTranslator

com.github.frosxt.prisoncore.commons.bukkit.color.ColorTranslator

Converts ampersand color codes. Supports both standard codes (&a, &l) and hex codes (&#rrggbb).

public static String colorize(String text);
public static String stripColor(String text);

colorize(text) is what you'll use 99% of the time. Pass it any string with & color codes and it returns a string Bukkit will render with the right colors.

final String name = ColorTranslator.colorize("&aGreen &#FF8800Orange");
player.sendMessage(name);

A few rules to keep in mind:

• colorize(null) returns an empty string, not null. Safe to chain.
• The translator is the same one BukkitItemBuilder uses internally for item names and lore, and the same one BukkitMessageService uses for chat lines, so you usually don't need to call it directly. The places you do are: menu titles you build by hand, raw player.sendMessage calls, and any other Bukkit API that takes a colored string.

stripColor(text) returns the input with all colors removed. Useful for log lines or when you want to compare two colored strings ignoring color.

BukkitItemBuilder

com.github.frosxt.prisoncore.commons.bukkit.item.BukkitItemBuilder

Fluent ItemStack builder. Handles names, lore, enchantments, flags, custom model data, durability, skull textures, persistent data, and potion meta in a single chain.

final ItemStack item = BukkitItemBuilder.of(Material.DIAMOND_SWORD)
    .name("&bExcalibur")
    .lore("&7A blade of legend", "&7Damage: &f+10")
    .enchant(Enchantment.DAMAGE_ALL, 5)
    .glow()
    .hideFlags()
    .build();

Construction:

• BukkitItemBuilder.of(Material) — fresh stack of the given material.
• BukkitItemBuilder.of(ItemStack) — clone of an existing stack so the original isn't mutated.

Common methods:

• name(String) — set display name. Auto-colorized.
• lore(String...) / lore(List<String>) — set lore lines. Auto-colorized. Replaces existing lore.
• addLore(String...) / addLore(List<String>) — append to existing lore. Auto-colorized.
• amount(int) — set stack size.
• enchant(Enchantment, int) / enchant(Enchantment) — add an enchantment (level defaults to 1).
• glow() — apply the standard "glowing item" effect (unbreaking 1 + hide enchants).
• flags(ItemFlag...) — add item flags.
• hideFlags() — apply every item flag, hiding all metadata in the tooltip.
• customModelData(int) — set custom model data.
• unbreakable(boolean) — toggle the unbreakable flag.
• durability(short) — set damage on a Damageable item.
• skullOwner(String) — set a player head's skull owner. Only meaningful for PLAYER_HEAD items.

There are more methods for potions and PDC writes. Read the source if you need them.

build() finalizes the meta and returns the ItemStack.

The same builder instance can be reused by calling build() more than once if you want; each call snapshots the current state.

PersistentDataAdapter

com.github.frosxt.prisoncore.commons.bukkit.item.PersistentDataAdapter

Typed read/write helpers over Bukkit's PersistentDataContainer. All keys are namespaced under a single value set once at boot.

The platform sets the namespace during kernel initialization. As a module author, you don't call setNamespace — you just use the read/write methods.

public static void setString(PersistentDataContainer pdc, String key, String value);
public static Optional<String> getString(PersistentDataContainer pdc, String key);
public static void setInt(PersistentDataContainer pdc, String key, int value);
public static Optional<Integer> getInt(PersistentDataContainer pdc, String key);
public static void setLong(PersistentDataContainer pdc, String key, long value);
public static Optional<Long> getLong(PersistentDataContainer pdc, String key);
public static void setDouble(PersistentDataContainer pdc, String key, double value);
public static Optional<Double> getDouble(PersistentDataContainer pdc, String key);
public static void setBoolean(PersistentDataContainer pdc, String key, boolean value);
public static Optional<Boolean> getBoolean(PersistentDataContainer pdc, String key);
public static boolean hasKey(PersistentDataContainer pdc, String key);
public static void removeKey(PersistentDataContainer pdc, String key);

Typical use is on item meta:

final ItemMeta meta = item.getItemMeta();
final PersistentDataContainer pdc = meta.getPersistentDataContainer();

PersistentDataAdapter.setString(pdc, "currency", "money");
PersistentDataAdapter.setLong(pdc, "amount", 1000L);
item.setItemMeta(meta);

Reading later:

final Optional<String> currency = PersistentDataAdapter.getString(pdc, "currency");
if (currency.isPresent() && currency.get().equals("money")) {
    // ...
}

hasKey checks whether the key exists under any of the supported types. removeKey removes the key entirely.

The read methods return Optional rather than nullable values, so you can chain .orElse(...) or .ifPresent(...) without manual null checks.

A note on ComponentFactory

com.github.frosxt.prisoncore.commons.bukkit.component.BukkitComponentFactory exists for building BaseComponent instances when you want hover/click events on chat messages. Most modules don't need it because the message service handles delivery for keyed messages. Reach for it only when you're building rich text outside the catalog.

A note on experience

com.github.frosxt.prisoncore.commons.bukkit.experience.PlayerExperience and ExperienceCalculator provide level/experience math. Most modules won't need them, but they are there if you do.