The Chat Component API - Historical

Applied By MinecraftDorado: Nov 11, 2019 at 4:26 AM

The Chat Component API

The Chat Component API

Using the BungeeCord chat API to construct messages




Basics(top)

The simplest component is the TextComponent, which can be used as follows:
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.spigot().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.spigot().sendMessage( message );
will display "Hello world!"

Events(top)

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 "http://spigotmc.org".
Code (Java):
TextComponent message = new TextComponent( "Click me" );
message.setClickEvent( new ClickEvent( ClickEvent.Action.OPEN_URL, "http://spigotmc.org" ) );
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.swordDiamond.name" );
item.setColor( ChatColor.GOLD );
giveMessage.addWith( item );
giveMessage.addWith( "32" );
TextComponent username = new TextComponent( "Thinkofdeath" );
username.setColor( ChatColor.AQUA );
giveMessage.addWith( username );
player.spigot().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.spigot().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().