The Chat Component API

Feb 21, 2017
The Chat Component API
  • The Chat Component API

    Using the BungeeCord chat API to construct messages


    The simplest component is the TextComponent, which can be used as follows in BungeeCord:
    Code (Java):
    player.sendMessage( new TextComponent( "Hello world" ) );
    Or if you're using Spigot:
    Code (Java):
    player.spigot().sendMessage( new TextComponent( "Hello world" ) );
    This is a simple component with no formatting or colors.

    Colors and formatting(top)

    Every component supports the following:
    • Color
    • Bold
    • Italic
    • Underline
    • Strikethrough
    • Obfuscate
    • Events (More about these later)

    For example:
    Code (Java):
    TextComponent message = new TextComponent( "Hello world" );
    message.setColor( ChatColor.RED );
    message.setBold( true );
    player.sendMessage( message );
    This will display "Hello World". Any formatting and events also apply to any sub-components unless the component overrides it. For example:
    Code (Java):
    TextComponent message = new TextComponent( "Hello " );
    message.setColor( ChatColor.RED );
    message.setBold( true );
    TextComponent world = new TextComponent( "world" );
    world.setColor( ChatColor.BLUE );
    message.addExtra( world );
    message.addExtra( "!" );
    player.sendMessage( message );
    will display "Hello world!"


    Events allow for actions to be performed upon actions being done on text. The two events currently supported in minecraft are HoverEvent and ClickEvent. Both events have an action (what to perform upon executing the event) and a value (the argument for the action). For example on with a click event if the action is OPEN_URL then the value must be a valid url e.g "".
    Code (Java):
    TextComponent message = new TextComponent( "Click me" );
    message.setClickEvent( new ClickEvent( ClickEvent.Action.OPEN_URL, "" ) );
    message.setHoverEvent( new HoverEvent( HoverEvent.Action.SHOW_TEXT, new ComponentBuilder("Goto the Spigot website!").create() ) );
    player.spigot().sendMessage( message );

    Client-side translations(top)

    TranslatableComponent can used to send translation keys for the client translate client side, this means you are limited to the text provided by Minecraft (see here) unless a resource pack is used to add more. Some translations support arguments with can also be TranslatableComponents (or just TextComponents).
    Code (Java):
    TranslatableComponent giveMessage = new TranslatableComponent( "commands.give.success" );
    TranslatableComponent item = new TranslatableComponent( "" );
    item.setColor( ChatColor.GOLD );
    giveMessage.addWith( item );
    giveMessage.addWith( "32" );
    TextComponent username = new TextComponent( "Thinkofdeath" );
    username.setColor( ChatColor.AQUA );
    giveMessage.addWith( username );
    player.sendMessage( giveMessage );
    This will display "Given Diamond Sword * 32 to Thinkofdeath" for a client using en_US but a client using zh_CN will see "成功将 钻石剑 * 32 给予 Thinkofdeath"

    The Component Builder(top)

    For simple messages the above is a lot of work so a ComponentBuilder can be used. The ComponentBuilder is a chainable object allowing quick creation of messages.
    Code (Java):
    player.sendMessage( new ComponentBuilder( "Hello " ).color( ChatColor.RED ).bold( true ).append( "world" ).color( ChatColor.BLUE ).append( "!" ).color( ChatColor.RED ).create() );
    will display "Hello world!"

    Common pitfalls(top)

    • Creating a direct instance of BaseComponent will not work (i.e. player.sendMessage( new BaseComponent(){} );). Use TextComponent or TranslatableComponent.
    • Using the old style color codes with components (i.e player.sendMessage( new TextComponent( ChatColor.RED + ":-(" ) );) does not work well and can cause client-side issues. Always run legacy text through TextComponent.fromLegacyText().


    All the actions for the ClickEvent and HoverEvent can be found below.

    ClickEvent actions(top)

    These will be run when a user click on a message in the chat!
    Code (Java):
    Action.OPEN_URL //Open an url in the users browser.

    Action.OPEN_FILE //Open a file at the user's computer.

    Action.RUN_COMMAND //Run a command by the user.

    Action.SUGGEST_COMMAND //Place a text in the user's chat.

    Action.CHANGE_PAGE //Change the page number of a book

    HoverEvent actions(top)

    There will be run when a user hover over a message!
    Code (Java):
    Action.SHOW_TEXT //Shows a text to the user.

    Action.SHOW_ACHIEVEMENT //Shows an achievement and its description

    Action.SHOW_ITEM //Shows an item with name and other information

    Action.SHOW_ENTITY //Shows an entity with name, id and other information
  • Loading...
  • Loading...