Package me.croabeast.prismatic

Class PrismaticAPI

java.lang.Object
me.croabeast.prismatic.PrismaticAPI
public final class PrismaticAPI extends Object
Main entry point for the PrismaticAPI formatting pipeline.

This class exposes two facades backed by the same parser and color engine: legacy() returns plain strings containing Bukkit-compatible color codes and is always safe to use, while adventure() returns Adventure components when the Adventure runtime is available.

The top-level methods on this class are retained for source compatibility with older PrismaticAPI versions and delegate to legacy().

The shared pipeline understands legacy color codes, multiple RGB syntaxes, gradients, rainbows and, when Adventure MiniMessage is present at runtime, MiniMessage tags that coexist with Prismatic tags.

  • Method Summary

    Modifier and Type
    Method
    Description
    static Formatter<net.kyori.adventure.text.Component>
    adventure()
    Returns the Adventure formatter facade when the required Adventure classes are present at runtime.
    static String
    applyColor(Color color, String string, boolean legacy)
    Applies a single color to the beginning of a string.
    static String
    applyGradient(String string, Color start, Color end, boolean legacy)
    Applies a per-character gradient between two colors.
    static String
    applyRainbow(String string, float saturation, boolean legacy)
    Applies a per-character rainbow effect.
    static ChatComponent<?>
    chatComponent(String message)
    Creates a mutable interactive chat component.
    static String
    colorize(String string)
    Parses and colorizes a string using the conservative no-player fallback.
    static String
    colorize(@Nullable org.bukkit.entity.Player player, String string)
    Parses and colorizes a string using the full Prismatic pipeline for a specific player context.
    static net.md_5.bungee.api.ChatColor
    fromString(String string)
    Parses a color token into a ChatColor.
    static net.md_5.bungee.api.ChatColor
    fromString(String string, boolean legacy)
    Converts a bare six-digit hexadecimal RGB value into a ChatColor.
    static @Nullable String
    getEndColor(String string)
    Returns the last color code found in the formatted representation of a string.
    static @Nullable String
    getStartColor(String string)
    Returns the first color code found in the formatted representation of a string.
    static boolean
    isAdventureAvailable()
    Checks whether the Adventure facade can be used safely at runtime.
    static Formatter<String>
    legacy()
    Returns the always-safe legacy formatter facade.
    static MultiComponent
    multiComponent(String message)
    Creates a mutable multi-component that can parse click and hover markup.
    static boolean
    startsWithColor(String string)
    Determines whether the formatted representation of a string starts with a color code.
    static String
    stripAll(String string)
    Removes Bukkit colors, Bukkit special formatting, MiniMessage tags and Prismatic RGB syntax from a string.
    static String
    stripBukkit(String string)
    Removes standard Bukkit color codes from a string.
    static String
    stripMiniMessage(String string)
    Removes MiniMessage formatting tags from a string.
    static String
    stripRGB(String string)
    Removes Prismatic RGB, gradient and rainbow syntax from a string while leaving legacy Bukkit codes untouched.
    static String
    stripSpecial(String string)
    Removes Bukkit special formatting codes from a string.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • legacy

      public static Formatter<String> legacy()
      Returns the always-safe legacy formatter facade.

      The returned formatter produces strings containing Bukkit/Bungee color codes and does not require Adventure to exist at runtime.

      Returns:
      formatter that produces legacy strings
      Since:
      1.4.0

    • adventure

      public static Formatter<net.kyori.adventure.text.Component> adventure()
      Returns the Adventure formatter facade when the required Adventure classes are present at runtime.

      This facade produces components from the same Prismatic parsing pipeline used by legacy(). Call isAdventureAvailable() before invoking this method when Adventure is an optional dependency in the consuming plugin.

      Returns:
      formatter that produces Adventure components
      Throws:
      IllegalStateException - if Adventure or MiniMessage is not available at runtime
      Since:
      1.4.0

    • isAdventureAvailable

      public static boolean isAdventureAvailable()
      Checks whether the Adventure facade can be used safely at runtime.

      The check validates the presence of the Adventure component API, MiniMessage and the legacy serializer classes required by PrismaticAPI's Adventure bridge.

      Returns:
      true when the Adventure formatter can be created safely
      Since:
      1.4.0

    • chatComponent

      public static ChatComponent<?> chatComponent(String message)
      Creates a mutable interactive chat component.

      The component compiles to Bungee/Spigot BaseComponent output and uses the Prismatic legacy formatter by default.

      Parameters:
      message - raw message
      Returns:
      new chat component
      Since:
      1.5.0

    • multiComponent

      public static MultiComponent multiComponent(String message)
      Creates a mutable multi-component that can parse click and hover markup.

      The supported markup is <action:"argument">text</text> or <action:"argument"|action:"argument">text</text>.

      Parameters:
      message - raw or formatted message
      Returns:
      new multi-component
      Since:
      1.5.0

    • fromString

      public static net.md_5.bungee.api.ChatColor fromString(String string, boolean legacy)
      Converts a bare six-digit hexadecimal RGB value into a ChatColor.

      When legacy is false, the returned color preserves the exact RGB value. When legacy is true, the value is downsampled to the nearest legacy Bukkit color.

      Parameters:
      string - six-digit hexadecimal RGB value without a leading #
      legacy - whether to downsample the result to the legacy Bukkit palette
      Returns:
      the resulting chat color
      Throws:
      NumberFormatException - if string is not a valid six-digit hexadecimal RGB value

    • fromString

      public static net.md_5.bungee.api.ChatColor fromString(String string)
      Parses a color token into a ChatColor.

      This overload accepts plain legacy codes such as a, prefixed legacy codes such as &a or §a, exact RGB values such as ff8800, and compact hex tokens such as &xff8800. Blank input falls back to ChatColor.WHITE.

      Parameters:
      string - color token to parse
      Returns:
      the parsed chat color, or white when the input is blank or unrecognized

    • applyColor

      public static String applyColor(Color color, String string, boolean legacy)
      Applies a single color to the beginning of a string.
      Parameters:
      color - color to prepend
      string - text to receive the color
      legacy - whether to use the nearest legacy Bukkit color instead of exact RGB
      Returns:
      the colorized string

    • applyGradient

      public static String applyGradient(String string, Color start, Color end, boolean legacy)
      Applies a per-character gradient between two colors.

      Existing special format codes such as bold or italic are preserved while visible characters are recolored across the gradient.

      Parameters:
      string - text to colorize
      start - gradient start color
      end - gradient end color
      legacy - whether to downsample each generated step to the legacy Bukkit palette
      Returns:
      the gradient-colored string

    • applyRainbow

      public static String applyRainbow(String string, float saturation, boolean legacy)
      Applies a per-character rainbow effect.
      Parameters:
      string - text to colorize
      saturation - rainbow saturation/brightness factor used to generate the palette
      legacy - whether to downsample each generated step to the legacy Bukkit palette
      Returns:
      the rainbow-colored string

    • colorize

      public static String colorize(@Nullable @Nullable org.bukkit.entity.Player player, String string)
      Parses and colorizes a string using the full Prismatic pipeline for a specific player context.

      If the player supports hex colors, RGB output is preserved. Otherwise the result is converted to legacy-safe colors. When Adventure MiniMessage is available at runtime, MiniMessage tags are handled before Prismatic tags are restored into the final output.

      Parameters:
      player - player used to resolve runtime color capabilities, or null to force the conservative legacy fallback
      string - text to parse and colorize
      Returns:
      the final formatted string

    • colorize

      public static String colorize(String string)
      Parses and colorizes a string using the conservative no-player fallback.

      This overload delegates to colorize(Player, String) with a null player, which means the result is treated as legacy-safe output because no player capability information is available.

      Parameters:
      string - text to parse and colorize
      Returns:
      the formatted legacy-safe string

    • stripBukkit

      public static String stripBukkit(String string)
      Removes standard Bukkit color codes from a string.

      This targets color codes such as &a, §c and the compact x hex prefix. It does not remove Prismatic gradient/rainbow tags.

      Parameters:
      string - text to clean
      Returns:
      the string without standard Bukkit color codes

    • stripSpecial

      public static String stripSpecial(String string)
      Removes Bukkit special formatting codes from a string.

      This includes styles such as bold, italic, underline, obfuscated and reset markers.

      Parameters:
      string - text to clean
      Returns:
      the string without Bukkit special formatting codes

    • stripRGB

      public static String stripRGB(String string)
      Removes Prismatic RGB, gradient and rainbow syntax from a string while leaving legacy Bukkit codes untouched.
      Parameters:
      string - text to clean
      Returns:
      the string without Prismatic RGB syntax

    • stripMiniMessage

      public static String stripMiniMessage(String string)
      Removes MiniMessage formatting tags from a string.
      Parameters:
      string - text to clean
      Returns:
      the string without MiniMessage tags

    • stripAll

      public static String stripAll(String string)
      Removes Bukkit colors, Bukkit special formatting, MiniMessage tags and Prismatic RGB syntax from a string.
      Parameters:
      string - text to clean
      Returns:
      the fully stripped plain-text string

    • startsWithColor

      public static boolean startsWithColor(String string)
      Determines whether the formatted representation of a string starts with a color code.

      The inspection is performed against the conservative legacy rendering used by colorize(String).

      Parameters:
      string - text to inspect
      Returns:
      true if the formatted output begins with a color code

    • getStartColor

      @Nullable public static @Nullable String getStartColor(String string)
      Returns the first color code found in the formatted representation of a string.

      The returned value is based on the conservative legacy rendering used by colorize(String) and is typically a section-sign color code such as §a.

      Parameters:
      string - text to inspect
      Returns:
      the first detected color code, or null if none is present

    • getEndColor

      @Nullable public static @Nullable String getEndColor(String string)
      Returns the last color code found in the formatted representation of a string.

      The returned value is based on the conservative legacy rendering used by colorize(String) and is typically a section-sign color code such as §a.

      Parameters:
      string - text to inspect
      Returns:
      the last detected color code, or null if none is present