Crate kyori_component_json

Source
Expand description

§kyori-component-json

A library for serialising and deserialising Minecraft’s JSON component format, also known as ‘raw JSON text’. Minecraft uses this format to display rich text throughout the game, including in commands such as /tellraw and in elements such as books, signs, scoreboards and entity names.

§Features

  • Full support for Minecraft’s component specification (as of Java Edition 1.21.5+)
  • Serialization and deserialization using Serde
  • Builder-style API for constructing components
  • Style inheritance and component nesting
  • Comprehensive type safety for all component elements

§When to Use

This library is useful when:

  • Generating complex chat messages with formatting and interactivity
  • Creating custom books or signs with rich text
  • Building command generators that use /tellraw or /title
  • Processing component data from Minecraft APIs or data packs

§Getting Started

Add to your Cargo.toml:

[dependencies]
kyori-component-json = "0.1"
serde-json = "1.0"

§Basic Example

use kyori_component_json::*;
use serde_json::json;

// Create a formatted chat message
let message = Component::text("Hello ")
    .color(Some(Color::Named(NamedColor::Yellow)))
    .append(
        Component::text("World!")
            .color(Some(Color::Named(NamedColor::White)))
            .decoration(TextDecoration::Bold, Some(true))
    )
    .append_newline()
    .append(
        Component::text("Click here")
            .click_event(Some(ClickEvent::RunCommand {
                command: "/say I was clicked!".into()
            }))
            .hover_event(Some(HoverEvent::ShowText {
                value: Component::text("Run a command!")
            }))
    );

// Serialize to JSON
let json = serde_json::to_value(&message).unwrap();
assert_eq!(json, json!({
    "text": "Hello ",
    "color": "yellow",
    "extra": [
        {
            "text": "World!",
            "color": "white",
            "bold": true
        },
        {"text": "\n"},
        {
            "text": "Click here",
            "click_event": {
                "action": "run_command",
                "command": "/say I was clicked!"
            },
            "hover_event": {
                "action": "show_text",
                "value": {"text": "Run a command!"}
            }
        }
    ]
}));

§Key Concepts

  1. Components - The building blocks of Minecraft text:
    • String: Plain text shorthand
    • Array: List of components
    • Object: Full component with properties
  2. Content Types - Special content like translations or scores
  3. Formatting - Colors, styles, and fonts
  4. Interactivity - Click and hover events

See Minecraft Wiki for full specification.

Modules§

minimessage
MiniMessage format parser and serializer for Minecraft components.
parsing
Provides traits for parsing and serializing Minecraft text Components.

Structs§

ComponentObject
Core component structure containing all properties
ParseColorError
Error type for color parsing
ScoreContent
Scoreboard value content
Style
Style properties for components

Enums§

ClickEvent
Actions triggered when clicking text
Color
Text color representation (either named or hex)
Component
Represents a Minecraft text component. Allows de/serialization using Serde with JSON.
ContentType
Content type of a component object
HoverEvent
Information shown when hovering over text
NamedColor
Named text colors from Minecraft
NbtSource
Source for NBT data
ShadowColor
Shadow color representation (integer or float array)
StyleMerge
Style properties for merging (unused in current implementation)
TextDecoration
Text decoration styles
UuidRepr
UUID representation for entity hover events