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.