Skip to content

Chat Components

Ayfri edited this page Sep 5, 2024 · 4 revisions

Chat Components

Chat Components are used to create rich text messages in Minecraft. They can include formatting, interactivity, and nested components. Kore has functions to create and manipulate Chat Components in a datapack.
Note that they always works by groups named ChatComponents, whenever you create a chat component, you actually create a ChatComponents, and you can chain multiple components together using the + operator.

Minecraft sometimes does not allow "complex" chat components with data resolving (score, nbt and entity chat components), if you use them, you'll get an empty text component. Simple chat components are inheriting the SimpleComponent interface, and you have a containsOnlySimpleComponents property to check if a ChatComponents only contains simple components.

You also have a containsOnlyText() function to check if a ChatComponents only contains plain text components with no formatting.

Common Properties

  • text - The text to display.
  • bold - Whether the text is bold.
  • clickEvent - The action to perform when the text is clicked.
  • color - The color of the text.
  • extra - Additional components to display after this one (prefer using the + operator).
  • font - The font to use.
  • hoverEvent - The action to perform when the text is hovered over.
  • insertion - The text to insert into the chat when the text is shift-clicked.
  • italic - Whether the text is italic.
  • obfuscated - Whether the text is obfuscated.
  • strikethrough - Whether the text is strikethrough.
  • underlined - Whether the text is underlined.

PlainTextComponent

The PlainTextComponent displays simple text with optional formatting such as color and bold.
To create a PlainTextComponent, use the textComponent function.

Example

val plainText = textComponent("Hello, world!") {
	color = Color.RED
	bold = true
}

In-game output:
Simple Hello World in bold red

Combined Components

Components can be combined using the + operator, use the text function to create a simple text component and not a ChatComponents.

val combinedComponents = textComponent("Hello, ") + text("world!") {
	color = Color.RED
	bold = true
}

In-game output:
Combined Hello World

(only the "world!" part is bold and red)

EntityComponent

The EntityComponent displays the name of an entity selected by a selector. If multiple entities are found, their names are displayed in the form Name1, Name2 etc.
The separator property can be used to change the separator between the names of the entities.
If no entities are found, the component displays nothing.

Example

val entityComponent = entityComponent(self())

In-game example:
Hello World of the player

KeybindComponent

The KeybindComponent displays a keybind. The keybind is displayed in the player's keybind settings.

Example

val keybindComponent = keybindComponent("key.sprint")

In-game example:
Keybind Component Example

NbtComponent

The NbtComponent displays NBT data from a block, an entity, or a storage. The interpret property can be used to interpret the NBT data as a text component, if the parsing fails, nothing is displayed.
The nbt property can be used to specify the path to the NBT data.
If nbt points to an array, then it will display all the elements joined in the form Element1, Element2 etc.
The separator property can be used to change the separator between the elements of the array.

Example

val nbtComponent = nbtComponent("Health", entity = nearestEntity {
	type = EntityType.CREEPER
})

In-game output:
NBT Component Example

ScoreComponent

The ScoreComponent displays the score of an entity for a specific objective. The name property can be used to specify the name of the entity whose score to display, it can be a selector or a literal name (will use the player with that name). It can also be * to select the entity seeing the text component.
The objective property can be used to specify the name of the objective to display the score of.
A value property can be used to specify a fixed value to display regardless of the score.

Example

val scoreComponent = scoreComponent("test")

In-game output:
Score Component Example

TranslatedTextComponent

The TranslatedTextComponent displays translated text using translation keys. You can also pass arguments to the translation key with the with argument, which should be a list of text components or strings.
A fallback property can be used to specify a fallback text if the translation key is not found.

Example

val translatedTextComponent = translatedTextComponent("chat.type.text", "Ayfri", "Hello !")

In-game example:
Translated Text Component Example

Hover Event

Hover events display extra information when the text is hovered over, it can be either text, an item, or an entity. Use showText to display text, showItem to display an item, and showEntity to display an entity.
Note that to show an entity, you have to have its UUID as a string.

Hover Event Example

val hoverEventComponent = textComponent("Hover over me!") {
	hoverEvent {
		showText("Hello, world!")
	}
}

In-game output:
Hover Event Example

Hover Item Example

val hoverItemComponent = textComponent("Hover over me!") {
	hoverEvent {
		showItem(Items.DIAMOND_SWORD {
			damage(5)
		})
	}
}

In-game output:
Hover Event with an Item Example

Click Event

Click events perform an action when the text is clicked. The action can be to:

  • Change the page of the book if reading a book
  • Copy some text to the clipboard
  • Open a file
  • Open a URL
  • Run a command
  • Suggest a command (insert the command in the chat but don't run it)

Click Event Example

val clickEventComponent = textComponent("Click me!") {
	clickEvent {
		runCommand {
			say("Hello, world!")
		}
	}
}