Interface VersionedComponent

public interface VersionedComponent
A multi-version wrapper that supports Kyori Adventure Components and the MiniMessage format.

This wrapper facilitates sending this wrapped component despite server version differences. (See sendTo(CommandSender))
On older servers, it likely sends via BaseComponents, while on newer servers it can use the native adventure api.

This wrapper attempts to use the native adventure api on newer servers, but falls back to using an internal shaded copy of adventure if the server does not support it natively.

  • Method Details

    • sendTo

      void sendTo(@NotNull @NotNull CommandSender sender)
      Sends the current message component to a sender.

    • serializeMiniMessage

      @NotNull @NotNull String serializeMiniMessage()
      Serializes the current message component to a MiniMessage string.

    • serializePlainText

      @NotNull @NotNull String serializePlainText()
      Serializes the current message component to a plain text string using the PlainTextComponentSerializer on the current platform.

    • serializeLegacyAmpersand

      @NotNull @NotNull String serializeLegacyAmpersand()
      Serializes the current message component to a string formatted using legacy ampersand (&) color codes.

    • serializeLegacySection

      @NotNull @NotNull String serializeLegacySection()
      Serializes the current message component to a string formatted using legacy section (§) color codes.

    • plainText

      @Deprecated @NotNull default @NotNull String plainText()
      Deprecated.
      Replace with serializePlainText().
      Serializes the current message component to a plain text string using the PlainTextComponentSerializer on the current platform.

    • createInventory

      @NotNull @NotNull Inventory createInventory(@NotNull @NotNull InventoryHolder owner, int size)
      Create a new menu with the current message as the title, other arguments are passed as normal.
      Parameters:
      owner - The inventory holder for this inventory. (inherited from Bukkit.createInventory)
      size - The size of the inventory. (inherited from Bukkit.createInventory)

    • createInventory

      @NotNull @NotNull Inventory createInventory(@NotNull @NotNull InventoryHolder owner, @NotNull @NotNull InventoryType type)
      Create a new menu with the current message as the title, other arguments are passed as normal.
      Parameters:
      owner - The inventory holder for this inventory. (inherited from Bukkit.createInventory)
      type - The type of the inventory. (inherited from Bukkit.createInventory)

    • serializeJson

      @NotNull @NotNull String serializeJson()
      Serializes to the JSON representation Minecraft itself uses for components.

      This replaced asInternalComponent(), removed 2026-08-30. That method handed back the relocated Adventure component, and once the relocated package is hidden from consumers it was unusable by construction: a caller cannot name the type, cannot declare a variable for it, and cannot cast it to anything. Assuming it is the server's own Adventure is wrong even on modern versions, because it is the shaded copy.

      JSON and MiniMessage carry the same information in a form callers can actually hold. On 1.21.4 and up, ModernVersionedComponent#asNativeComponent() returns the server's real Adventure component, which is nameable and is the right escape hatch there.

    • append

      @NotNull @NotNull VersionedComponent append(@NotNull @NotNull VersionedComponent other)
      Appends another VersionedComponent to this one, returning a new instance.
      The original instances are not modified.

    • click

      @NotNull default @NotNull VersionedComponent click(@NotNull @NotNull ClickAction action, @NotNull @NotNull String value)
      Returns a copy of this component with a click behaviour attached.

      Use this rather than reaching for Adventure directly to call its clickEvent. Anything outside the versions/* modules that names the shaded Adventure copy pins it onto every server, including the modern ones that have Adventure natively and do not need it.

      Parameters:
      action - what the click does
      value - the command or URL the action applies to, without a leading slash for commands
      Throws:
      UnsupportedOperationException - if this server version cannot express the action; see ClickAction.COPY_TO_CLIPBOARD

    • hover

      @NotNull default @NotNull VersionedComponent hover(@NotNull @NotNull VersionedComponent tooltip)
      Returns a copy of this component with hover text attached.
      Parameters:
      tooltip - the component shown on hover

    • hoverItem

      @NotNull default @NotNull VersionedComponent hoverItem(@NotNull @NotNull ItemStack item)
      Returns a copy of this component whose hover shows the given item, with its name, lore and enchantments as a player would see them in an inventory.

      Supported on every version from 1.8. Servers from 1.18.2 build the hover from their own Adventure; below that the item's id, count and tag compound are read from NMS and assembled into the same hover.

      On 1.8 through 1.12 the hover carries the item's tag compound, so the name, lore and enchantments survive while the top-level Damage field does not. An item whose variant or durability lives in Damage, such as coloured wool or a worn tool, therefore hovers as the undamaged base item. This is the shape of Adventure's item hover, which holds an id, a count and a tag and has nowhere to put Damage. From 1.13 onward the variant is part of the id and durability moved into tag, so nothing is lost.

      Parameters:
      item - the item shown on hover
      Throws:
      IllegalArgumentException - if the item is air, which has no item to show

    • decorate

      @NotNull default @NotNull VersionedComponent decorate(@NotNull @NotNull TextDecoration decoration, boolean value)
      Returns a copy of this component with a style flag explicitly set.

      Minecraft italicises custom item names and lore by default, and this library suppresses that where the caller left italic unset, so no call is needed before writing a component into ItemMeta. Pass ITALIC with true to ask for italics there anyway.

    • sendTo

      default void sendTo(@NotNull @NotNull CommandSender... senders)
      Sends the current message component to multiple senders.

    • sendTo

      default void sendTo(@NotNull @NotNull Collection<CommandSender> senders)
      Sends the current message component to multiple senders.