Creating Text

The Text API is used to create formatted text, which can be sent to players in chat messages, and can also be used in places such as books and signs.

Unformatted Text

Oftentimes, all you need is unformatted text. Unformatted text does not require the use of a text builder, and is the simplest form of text to create.

Example:

import org.spongepowered.api.text.Text;

Text unformattedText = Text.of("Hey! This is unformatted text!");

The code excerpt illustrated above will return uncoloured, unformatted text with no text actions configured.

Text Builder

The text builder interface allows for the creation of formatted text in a “building-block” style.

Tip

Read this Wikipedia article for help understanding the purpose of the builder pattern in software design.

Colours

One usage of the text builder is the addition of colours to text, as illustrated below.

Example: Coloured Text

import org.spongepowered.api.text.format.TextColors;

Text coloredText = Text.builder("Woot! Golden text is golden.").color(TextColors.GOLD).build();

Any colour specified within the TextColors class can be used when colouring text. Multiple colours can be used in text by appending additional texts with different colours:

Example: Multi-coloured Text

Text multiColoredText = Text.builder("Sponges are ").color(TextColors.YELLOW).append(
        Text.builder("invincible!").color(TextColors.RED).build()).build();

Styling

The builder can also be used to style text, including underlining, italicizing, etc.

Example: Styled Text

import org.spongepowered.api.text.format.TextStyles;

Text styledText = Text.builder("Yay! Styled text!").style(TextStyles.ITALIC).build();

Just like with colours, multiple styles can be used by chaining together separately styled texts.

Example: Multi-styled Text

Text multiStyledText = Text.builder("I'm italicized! ").style(TextStyles.ITALIC)
        .append(Text.builder("I'm bold!").style(TextStyles.BOLD).build()).build();

Colouring & Styling Shortcut

The Text#of(Object…) method provides a simple way to add colour and styling to your text in a much more concise way.

Example: Colour & Style Shortcut

Text colorAndStyleText = Text.of(TextColors.RED, TextStyles.ITALIC, "Shortcuts for the win!");

Text Actions

The text builder also offers the ability to create actions for text. Any action specified within the TextActions class can be used when creating text actions for text. The method below is a small example of what text actions can do.

Example: Text with an Action

import org.spongepowered.api.text.action.TextActions;

Text clickableText = Text.builder("Click here!").onClick(TextActions.runCommand("tell Spongesquad I'm ready!")).build();

In the method above, players can click the “Click here!” text to run the specified command.

Note

Some text actions, such as TextActions#changePage(int), can only be used with book items.

Tip

Just like with colours, multiple actions can be appended to text. Text actions can even be used in tandem with colours because of the builder pattern interface.

Selectors

Target selectors are used to target players or entities that meet a specific criteria. Target selectors are particularly useful when creating minigame plugins, but have a broad range of applications.

Tip

Read this Minecraft wiki article for help understanding what target selectors are in Minecraft, and how to use them.

To use selectors in text, you must use the Selector.Builder interface. This is illustrated in the example below.

Example: Selector-generated Text

import org.spongepowered.api.text.selector.Selector;

Text adventurers = Text.builder("These players are in adventure mode: ").append(
        Text.of(Selector.parse("@a[m=2]"))
).build();

In this example, the target selector @a[m=2] is targeting every online player who is in adventure mode. When the method is called, a Text will be returned containing the usernames of every online player who is in adventure mode.