0
# Adventure Text Serializer Gson
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: adventure-text-serializer-gson
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `net.kyori:adventure-text-serializer-gson:4.23.0`
10

11
## Core Imports
12

13
```java
14
import net.kyori.adventure.text.serializer.gson.GsonComponentSerializer;
15
import net.kyori.adventure.text.Component;
16
import com.google.gson.JsonElement;
17
```
18

19
## Basic Usage
20

21
```java
22
import net.kyori.adventure.text.serializer.gson.GsonComponentSerializer;
23
import net.kyori.adventure.text.Component;
24

25
// Get standard serializer
26
GsonComponentSerializer serializer = GsonComponentSerializer.gson();
27

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

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

35
// Work with JsonElement directly
36
JsonElement jsonElement = serializer.serializeToTree(component);
37
Component fromTree = serializer.deserializeFromTree(jsonElement);
38
```
39

40
## Architecture
41

42
The library is built around several key components:
43

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

50
## Capabilities
51

52
### Component Serialization
53

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

56
```java { .api }
57
/**
58
 * Main interface for Gson-based Adventure text component serialization
59
 */
60
public interface GsonComponentSerializer extends JSONComponentSerializer, 
61
    Buildable<GsonComponentSerializer, GsonComponentSerializer.Builder> {
62
    
63
    /**
64
     * Gets a standard gson component serializer
65
     * @return Standard GsonComponentSerializer instance
66
     */
67
    static GsonComponentSerializer gson();
68
    
69
    /**
70
     * Gets a legacy gson component serializer with color downsampling
71
     * @return Legacy GsonComponentSerializer with color downsampling enabled
72
     */
73
    static GsonComponentSerializer colorDownsamplingGson();
74
    
75
    /**
76
     * Creates a new builder for custom configuration
77
     * @return New Builder instance
78
     */
79
    static Builder builder();
80
    
81
    /**
82
     * Gets the underlying gson serializer
83
     * @return Gson instance used for serialization
84
     */
85
    Gson serializer();
86
    
87
    /**
88
     * Gets the underlying gson populator
89
     * @return UnaryOperator that configures GsonBuilder
90
     */
91
    UnaryOperator<GsonBuilder> populator();
92
    
93
    /**
94
     * Deserialize a component from a JsonElement
95
     * @param input JsonElement to deserialize
96
     * @return Deserialized Component
97
     */
98
    Component deserializeFromTree(JsonElement input);
99
    
100
    /**
101
     * Serialize a component to a JsonElement
102
     * @param component Component to serialize
103
     * @return Serialized JsonElement
104
     */
105
    JsonElement serializeToTree(Component component);
106
}
107
```
108

109
**Usage Examples:**
110

111
```java
112
// Standard serialization
113
GsonComponentSerializer serializer = GsonComponentSerializer.gson();
114
String json = serializer.serialize(component);
115

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

120
// JsonElement integration
121
JsonElement element = serializer.serializeToTree(component);
122
Component restored = serializer.deserializeFromTree(element);
123
```
124

125
### Serializer Configuration
126

127
Builder pattern for creating customized serializers with specific options.
128

129
```java { .api }
130
/**
131
 * Builder interface for configuring GsonComponentSerializer instances
132
 */
133
public interface Builder extends AbstractBuilder<GsonComponentSerializer>, 
134
    Buildable.Builder<GsonComponentSerializer>, JSONComponentSerializer.Builder {
135
    
136
    /**
137
     * Sets serialization options
138
     * @param flags OptionState containing serialization options
139
     * @return This builder for chaining
140
     */
141
    Builder options(OptionState flags);
142
    
143
    /**
144
     * Edit options using a consumer
145
     * @param optionEditor Consumer to edit options
146
     * @return This builder for chaining
147
     */
148
    Builder editOptions(Consumer<OptionState.Builder> optionEditor);
149
    
150
    /**
151
     * Enables downsampling of hex colors to named colors for legacy compatibility
152
     * @return This builder for chaining
153
     */
154
    Builder downsampleColors();
155
    
156
    /**
157
     * Sets legacy hover event serializer (deprecated)
158
     * @param serializer Legacy hover event serializer
159
     * @return This builder for chaining
160
     * @deprecated Use the non-deprecated version
161
     */
162
    @Deprecated
163
    Builder legacyHoverEventSerializer(LegacyHoverEventSerializer serializer);
164
    
165
    /**
166
     * Sets legacy hover event serializer
167
     * @param serializer Legacy hover event serializer from json package
168
     * @return This builder for chaining
169
     */
170
    Builder legacyHoverEventSerializer(
171
        net.kyori.adventure.text.serializer.json.LegacyHoverEventSerializer serializer);
172
    
173
    /**
174
     * Enables legacy hover event emission (deprecated)
175
     * @return This builder for chaining
176
     * @deprecated Use legacyHoverEventSerializer instead
177
     */
178
    @Deprecated
179
    Builder emitLegacyHoverEvent();
180
    
181
    /**
182
     * Builds the configured serializer
183
     * @return Configured GsonComponentSerializer instance
184
     */
185
    GsonComponentSerializer build();
186
}
187
```
188

189
**Usage Examples:**
190

191
```java
192
// Custom serializer with color downsampling
193
GsonComponentSerializer customSerializer = GsonComponentSerializer.builder()
194
    .downsampleColors()
195
    .build();
196

197
// Advanced configuration with options
198
GsonComponentSerializer advancedSerializer = GsonComponentSerializer.builder()
199
    .editOptions(options -> options
200
        .emitLegacyHoverEvent(true)
201
        .downsampleColors(true))
202
    .build();
203
```
204

205
### Data Component Values
206

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

209
```java { .api }
210
/**
211
 * DataComponentValue implementation that holds a JsonElement for item data
212
 */
213
@ApiStatus.NonExtendable
214
public interface GsonDataComponentValue extends DataComponentValue {
215
    
216
    /**
217
     * Creates a data component value from a JsonElement
218
     * @param data JsonElement containing the data
219
     * @return GsonDataComponentValue wrapping the JsonElement
220
     */
221
    static GsonDataComponentValue gsonDataComponentValue(JsonElement data);
222
    
223
    /**
224
     * Gets the contained JsonElement
225
     * @return JsonElement containing the component data
226
     */
227
    JsonElement element();
228
}
229
```
230

231
**Usage Examples:**
232

233
```java
234
// Create data component value from JsonElement
235
JsonElement itemData = new JsonObject();
236
itemData.addProperty("custom_name", "My Item");
237
GsonDataComponentValue dataValue = GsonDataComponentValue.gsonDataComponentValue(itemData);
238

239
// Extract JsonElement from data component value
240
JsonElement extracted = dataValue.element();
241
```
242

243

244
## Types
245

246
```java { .api }
247
/**
248
 * Legacy hover event serializer interface (deprecated)
249
 */
250
@Deprecated
251
@ApiStatus.ScheduledForRemoval(inVersion = "5.0.0")
252
public interface LegacyHoverEventSerializer 
253
    extends net.kyori.adventure.text.serializer.json.LegacyHoverEventSerializer {
254
    // Empty interface extending base functionality
255
}
256

257
/**
258
 * Service provider interface for GsonComponentSerializer (internal)
259
 */
260
@ApiStatus.Internal
261
@PlatformAPI
262
public interface Provider {
263
    GsonComponentSerializer gson();
264
    GsonComponentSerializer gsonLegacy();
265
    Consumer<Builder> builder();
266
}
267
```
268

269
## Error Handling
270

271
The library follows Adventure's standard error handling patterns:
272

273
- **Deserialization Errors**: Invalid JSON or malformed component data throws `JsonParseException`
274
- **Serialization Errors**: Components with invalid state may throw `IllegalStateException`
275
- **Configuration Errors**: Invalid builder configurations throw `IllegalArgumentException`
276

277
Common error scenarios:
278
- Malformed JSON input during deserialization
279
- Unsupported component types in legacy mode
280
- Invalid hover event data in legacy formats
281

282
## Legacy Compatibility
283

284
The library provides extensive support for legacy Minecraft versions:
285

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

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