Skip to content
A text library for Minecraft.
Java Shell
Branch: master
Clone or download
kashike Merge pull request #52 from KyoriPowered/cleanup
general cleanup and improvement
Latest commit 934e5ea Oct 22, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
api general cleanup and improvement Oct 20, 2019
feature-pagination general cleanup and improvement Oct 20, 2019
gradle/wrapper Update gradle wrapper Sep 19, 2018
serializer-gson general cleanup and improvement Oct 20, 2019
serializer-legacy general cleanup and improvement Oct 20, 2019
serializer-plain general cleanup and improvement Oct 20, 2019
.gitignore Pagination Jul 15, 2019
.travis.sh
.travis.yml Refactor into separate projects - this is 2.0.0-SNAPSHOT Jan 20, 2019
build.gradle build: version to 3.0.3-SNAPSHOT Aug 25, 2019
gradlew Update gradle wrapper Sep 19, 2018
gradlew.bat Create skeleton project May 22, 2017
header.txt 2019 Jan 20, 2019
license.txt 2019 Jan 20, 2019
readme.md Update readme for 3.0.0 release May 7, 2019
settings.gradle Pagination Jul 15, 2019

readme.md

text License Build Status

A text library for Minecraft.

Artifacts

There are various artifacts:

  • text-api is the core project - you will always want to import this.
  • text-serializer-gson is a GSON-based JSON serializer.
  • text-serializer-legacy is a legacy character text serializer.
  • text-serializer-plain is a plain text serializer.

Importing text into your project

  • Maven
<dependency>
  <groupId>net.kyori</groupId>
  <artifactId>text-api</artifactId>
  <version>3.0.0</version>
</dependency>
  • Gradle
repositories {
  mavenCentral()
}

dependencies {
  compile 'net.kyori:text-api:3.0.0'
}

Example usage

Creating components

// Creates a line of text saying "You're a Bunny! Press <key> to jump!", with some colouring and styling.
final TextComponent textComponent = TextComponent.of("You're a ")
  .color(TextColor.GRAY)
  .append(TextComponent.of("Bunny").color(TextColor.LIGHT_PURPLE))
  .append(TextComponent.of("! Press "))
  .append(
    KeybindComponent.of("key.jump")
      .color(TextColor.LIGHT_PURPLE)
      .decoration(TextDecoration.BOLD, true)
  )
  .append(TextComponent.of(" to jump!"));
// now you can send `textComponent` to something, such as a client

You can also use a builder, which is mutable, and creates one final component with the children.

// Creates a line of text saying "You're a Bunny! Press <key> to jump!", with some colouring and styling.
final TextComponent textComponent2 = TextComponent.builder().content("You're a ")
  .color(TextColor.GRAY)
  .append(TextComponent.builder("Bunny").color(TextColor.LIGHT_PURPLE).build())
  .append(TextComponent.of("! Press "))
  .append(
    KeybindComponent.builder("key.jump")
      .color(TextColor.LIGHT_PURPLE)
      .decoration(TextDecoration.BOLD, true)
      .build()
  )
  .append(TextComponent.of(" to jump!"))
  .build();
// now you can send `textComponent2` to something, such as a client

Serializing and deserializing components

Serialization to JSON, legacy and plain representations is also supported.

// Creates a text component
final TextComponent textComponent = TextComponent.of("Hello ")
  .color(TextColor.GOLD)
  .append(
    TextComponent.of("world")
      .color(TextColor.AQUA).
      decoration(TextDecoration.BOLD, true)
  )
  .append(TextComponent.of("!").color(TextColor.RED));

// Converts textComponent to the JSON form used for serialization by Minecraft.
String json = GsonComponentSerializer.INSTANCE.serialize(textComponent);

// Converts textComponent to a legacy string - "&6Hello &b&lworld&c!"
String legacy = LegacyComponentSerializer.INSTANCE.serialize(textComponent, '&');

// Converts textComponent to a plain string - "Hello world!"
String plain = PlainComponentSerializer.INSTANCE.serialize(textComponent);

The same is of course also possible in reverse for deserialization.

// Converts JSON in the form used for serialization by Minecraft to a Component
Component component = GsonComponentSerializer.INSTANCE.deserialize(json);

// Converts a legacy string (using formatting codes) to a TextComponent
TextComponent component = LegacyComponentSerializer.INSTANCE.deserialize("&6Hello &b&lworld&c!", '&');

// Converts a plain string to a TextComponent
TextComponent component = PlainComponentSerializer.INSTANCE.deserialize("Hello world!");

Using components within your application

The way you use components within your application will of course vary depending on what you're aiming to achieve.

However, the most common task is likely to be sending a component to some sort of Minecraft client. The method for doing this will depend on the platform your program is running on, however it is likely to involve serializing the component to Minecraft's JSON format, and then sending the JSON through another method provided by the platform.

The text library is platform agnostic and therefore doesn't provide any way to send components to clients. However, some platform adapters (which make this easy!) can be found in the text-extras project.

You can’t perform that action at this time.