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.
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.
The text builder interface allows for the creation of formatted text in a „building-block” style.
Read this Wikipedia article for help understanding the purpose of the builder pattern in software design.
One usage of the text builder is the addition of colors to text, as illustrated below.
Example: Colored Text¶
import org.spongepowered.api.text.format.TextColors; Text coloredText = Text.builder("Woot! Golden text is golden.").color(TextColors.GOLD).build();
Any color specified within the TextColors class can be used when coloring text. Multiple colors can be used in text by appending additional texts with different colors:
Example: Multi-colored Text¶
Text multiColoredText = Text.builder("Sponges are ").color(TextColors.YELLOW).append( Text.builder("invincible!").color(TextColors.RED).build()).build();
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 colors, 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();
Coloring & Styling Shortcut¶
The Text#of(Object…) method provides a simple way to add color and styling to your text in a much more concise way.
Example: Color & Style Shortcut¶
Text colorAndStyleText = Text.of(TextColors.RED, TextStyles.ITALIC, "Shortcuts for the win!");
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.
Some text actions, such as TextActions#changePage(int), can only be used with book items.
Just like with colors, multiple actions can be appended to text. Text actions can even be used in tandem with colors because of the builder pattern interface.
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.
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.