The Chat Component API

Jul 24, 2020
The Chat Component API
  • The Chat Component API

    Using the BungeeCord chat API to construct messages


    The components provided by the API are KeybindComponent, SelectorComponent, ScoreComponent, TextComponent, and TranslatableComponent. The simplest component to use is the TextComponent. All of these are subclasses under BaseComponent.




    TextComponents are used to create plain messages.

    You would create a TextComponent as follows:
    Code (Java):
    new TextComponent( "Hello world!" )

    TranslatableComponents are used for client side translations. It can be 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( net.md_5.bungee.api.ChatColor.GOLD );
    giveMessage.addWith( item );
    giveMessage.addWith( "32" );
    TextComponent username = new TextComponent( "Thinkofdeath" );
    username.setColor( net.md_5.bungee.api.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"

    To send any component to a player, the following code is used:

    Initialise your component:
    Code (Java):
    BaseComponent component = ...
    Send message in BungeeCord:
    Code (Java):
    player.sendMessage( component );
    Send message in Spigot:
    Code (Java):
    player.spigot().sendMessage( component );

    Colors and Formatting Styles(top)

    The appearance of components may be modified by applying format styles such as Color, Bold, Italic, Underline, Strikethrough, Obfuscate, and Insertion.

    Here is an example, using a TextComponent;
    Code (Java):
    TextComponent message = new TextComponent( "Hello world" );
    message.setColor( net.md_5.bungee.api.ChatColor.RED );
    message.setBold( true );
    If this component is sent to a player it would display as "Hello world".

    Any formatting and events also apply to any sub-components unless the component overrides it. For example, amending our above example:
    Code (Java):
    TextComponent message = new TextComponent( "Hello " );
    message.setColor( net.md_5.bungee.api.ChatColor.RED );
    message.setBold( true );
    TextComponent world = new TextComponent( "world" );
    world.setColor( net.md_5.bungee.api.ChatColor.DARK_RED );
    message.addExtra( world );
    message.addExtra( "!" );
    our component would display "Hello world!"


    There are two chat events currently in Minecraft. ClickEvent and HoverEvent. As you can expect, hovering over text supplied by a component with a HoverEvent would show a tooltip based on an action and clicking whereas clicking on text with a ClickEvent would perform a certain action.

    Here's an example for a component with a ClickEvent with action OPEN_URL attached:
    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 Text( "Visit the Spigot website!" ) ) );
    ClickEvent actions.
    HoverEvent actions.

    The Component Builder API (WIP)(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( net.md_5.bungee.api.ChatColor.RED ).bold( true ).append( "world" )
    .color( net.md_5.bungee.api.ChatColor.DARK_RED ).append( "!" )
    .color( net.md_5.bungee.api.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 one of the components listed in Basics section.
    • Using the old style color codes with components (i.e player.sendMessage( new TextComponent( net.md_5.bungee.api.ChatColor.RED + ":-(" ) );) does not work well and can cause client-side issues. Always run legacy text through TextComponent.fromLegacyText().
  • Loading...
  • Loading...