or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/maven-net-kyori--adventure-text-serializer-gson

A Gson-based JSON serializer for Adventure text components, providing serialization and deserialization of Minecraft text components to/from JSON format using Google's Gson library

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/net.kyori/adventure-text-serializer-gson@4.23.x

To install, run

npx @tessl/cli install tessl/maven-net-kyori--adventure-text-serializer-gson@4.23.0

index.mddocs/

Adventure Text Serializer Gson

Adventure Text Serializer Gson is a Gson-based JSON serialization library for Adventure text components. It provides high-performance serialization and deserialization of Minecraft text components to/from JSON format using Google's Gson library, with support for advanced features like hex colors, hover events, click events, and legacy compatibility.

Package Information

  • Package Name: adventure-text-serializer-gson
  • Package Type: maven
  • Language: Java
  • Installation: net.kyori:adventure-text-serializer-gson:4.23.0

Core Imports

import net.kyori.adventure.text.serializer.gson.GsonComponentSerializer;
import net.kyori.adventure.text.Component;
import com.google.gson.JsonElement;

Basic Usage

import net.kyori.adventure.text.serializer.gson.GsonComponentSerializer;
import net.kyori.adventure.text.Component;

// Get standard serializer
GsonComponentSerializer serializer = GsonComponentSerializer.gson();

// Serialize component to JSON string
Component component = Component.text("Hello World");
String json = serializer.serialize(component);

// Deserialize JSON string to component
Component parsed = serializer.deserialize(json);

// Work with JsonElement directly
JsonElement jsonElement = serializer.serializeToTree(component);
Component fromTree = serializer.deserializeFromTree(jsonElement);

Architecture

The library is built around several key components:

  • GsonComponentSerializer: Main entry point providing standard and legacy serializers
  • Builder Pattern: Configurable serializer creation with options for color downsampling and legacy compatibility
  • JsonElement Integration: Direct integration with Gson's JsonElement API for advanced use cases
  • Data Component Support: Specialized handling of item data components through GsonDataComponentValue
  • Legacy Compatibility: Support for older Minecraft versions through color downsampling and legacy hover events

Capabilities

Component Serialization

Core functionality for serializing Adventure text components to/from JSON using Gson.

/**
 * Main interface for Gson-based Adventure text component serialization
 */
public interface GsonComponentSerializer extends JSONComponentSerializer, 
    Buildable<GsonComponentSerializer, GsonComponentSerializer.Builder> {
    
    /**
     * Gets a standard gson component serializer
     * @return Standard GsonComponentSerializer instance
     */
    static GsonComponentSerializer gson();
    
    /**
     * Gets a legacy gson component serializer with color downsampling
     * @return Legacy GsonComponentSerializer with color downsampling enabled
     */
    static GsonComponentSerializer colorDownsamplingGson();
    
    /**
     * Creates a new builder for custom configuration
     * @return New Builder instance
     */
    static Builder builder();
    
    /**
     * Gets the underlying gson serializer
     * @return Gson instance used for serialization
     */
    Gson serializer();
    
    /**
     * Gets the underlying gson populator
     * @return UnaryOperator that configures GsonBuilder
     */
    UnaryOperator<GsonBuilder> populator();
    
    /**
     * Deserialize a component from a JsonElement
     * @param input JsonElement to deserialize
     * @return Deserialized Component
     */
    Component deserializeFromTree(JsonElement input);
    
    /**
     * Serialize a component to a JsonElement
     * @param component Component to serialize
     * @return Serialized JsonElement
     */
    JsonElement serializeToTree(Component component);
}

Usage Examples:

// Standard serialization
GsonComponentSerializer serializer = GsonComponentSerializer.gson();
String json = serializer.serialize(component);

// Legacy compatibility (downsamples hex colors to named colors)
GsonComponentSerializer legacySerializer = GsonComponentSerializer.colorDownsamplingGson();
String legacyJson = legacySerializer.serialize(component);

// JsonElement integration
JsonElement element = serializer.serializeToTree(component);
Component restored = serializer.deserializeFromTree(element);

Serializer Configuration

Builder pattern for creating customized serializers with specific options.

/**
 * Builder interface for configuring GsonComponentSerializer instances
 */
public interface Builder extends AbstractBuilder<GsonComponentSerializer>, 
    Buildable.Builder<GsonComponentSerializer>, JSONComponentSerializer.Builder {
    
    /**
     * Sets serialization options
     * @param flags OptionState containing serialization options
     * @return This builder for chaining
     */
    Builder options(OptionState flags);
    
    /**
     * Edit options using a consumer
     * @param optionEditor Consumer to edit options
     * @return This builder for chaining
     */
    Builder editOptions(Consumer<OptionState.Builder> optionEditor);
    
    /**
     * Enables downsampling of hex colors to named colors for legacy compatibility
     * @return This builder for chaining
     */
    Builder downsampleColors();
    
    /**
     * Sets legacy hover event serializer (deprecated)
     * @param serializer Legacy hover event serializer
     * @return This builder for chaining
     * @deprecated Use the non-deprecated version
     */
    @Deprecated
    Builder legacyHoverEventSerializer(LegacyHoverEventSerializer serializer);
    
    /**
     * Sets legacy hover event serializer
     * @param serializer Legacy hover event serializer from json package
     * @return This builder for chaining
     */
    Builder legacyHoverEventSerializer(
        net.kyori.adventure.text.serializer.json.LegacyHoverEventSerializer serializer);
    
    /**
     * Enables legacy hover event emission (deprecated)
     * @return This builder for chaining
     * @deprecated Use legacyHoverEventSerializer instead
     */
    @Deprecated
    Builder emitLegacyHoverEvent();
    
    /**
     * Builds the configured serializer
     * @return Configured GsonComponentSerializer instance
     */
    GsonComponentSerializer build();
}

Usage Examples:

// Custom serializer with color downsampling
GsonComponentSerializer customSerializer = GsonComponentSerializer.builder()
    .downsampleColors()
    .build();

// Advanced configuration with options
GsonComponentSerializer advancedSerializer = GsonComponentSerializer.builder()
    .editOptions(options -> options
        .emitLegacyHoverEvent(true)
        .downsampleColors(true))
    .build();

Data Component Values

Specialized handling of item data components that can be serialized with Gson.

/**
 * DataComponentValue implementation that holds a JsonElement for item data
 */
@ApiStatus.NonExtendable
public interface GsonDataComponentValue extends DataComponentValue {
    
    /**
     * Creates a data component value from a JsonElement
     * @param data JsonElement containing the data
     * @return GsonDataComponentValue wrapping the JsonElement
     */
    static GsonDataComponentValue gsonDataComponentValue(JsonElement data);
    
    /**
     * Gets the contained JsonElement
     * @return JsonElement containing the component data
     */
    JsonElement element();
}

Usage Examples:

// Create data component value from JsonElement
JsonElement itemData = new JsonObject();
itemData.addProperty("custom_name", "My Item");
GsonDataComponentValue dataValue = GsonDataComponentValue.gsonDataComponentValue(itemData);

// Extract JsonElement from data component value
JsonElement extracted = dataValue.element();

Types

/**
 * Legacy hover event serializer interface (deprecated)
 */
@Deprecated
@ApiStatus.ScheduledForRemoval(inVersion = "5.0.0")
public interface LegacyHoverEventSerializer 
    extends net.kyori.adventure.text.serializer.json.LegacyHoverEventSerializer {
    // Empty interface extending base functionality
}

/**
 * Service provider interface for GsonComponentSerializer (internal)
 */
@ApiStatus.Internal
@PlatformAPI
public interface Provider {
    GsonComponentSerializer gson();
    GsonComponentSerializer gsonLegacy();
    Consumer<Builder> builder();
}

Error Handling

The library follows Adventure's standard error handling patterns:

  • Deserialization Errors: Invalid JSON or malformed component data throws JsonParseException
  • Serialization Errors: Components with invalid state may throw IllegalStateException
  • Configuration Errors: Invalid builder configurations throw IllegalArgumentException

Common error scenarios:

  • Malformed JSON input during deserialization
  • Unsupported component types in legacy mode
  • Invalid hover event data in legacy formats

Legacy Compatibility

The library provides extensive support for legacy Minecraft versions:

  • Color Downsampling: Automatically converts hex colors to named colors for pre-1.16 compatibility
  • Legacy Hover Events: Supports older hover event formats with automatic conversion
  • Backward Compatibility: Maintains compatibility with older Adventure versions through configuration options

Use GsonComponentSerializer.colorDownsamplingGson() for maximum compatibility with legacy platforms.