0
# Adventure API
1

2
Adventure API is a comprehensive serverside user interface library for Minecraft: Java Edition servers. It provides type-safe, immutable component-based text handling with support for rich formatting, colors, hover events, click actions, and translations. The library includes audience management for targeting messages to players or groups, sound and boss bar APIs, inventory book creation, chat signing support, and resource pack management.
3

4
## Package Information
5

6
- **Package Name**: net.kyori:adventure-api
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your `build.gradle` or `pom.xml`:
10

11
```gradle
12
implementation 'net.kyori:adventure-api:4.23.0'
13
```
14

15
```xml
16
<dependency>
17
  <groupId>net.kyori</groupId>
18
  <artifactId>adventure-api</artifactId>
19
  <version>4.23.0</version>
20
</dependency>
21
```
22

23
## Core Imports
24

25
The most commonly used classes and interfaces:
26

27
```java
28
import net.kyori.adventure.text.Component;
29
import net.kyori.adventure.audience.Audience;
30
import net.kyori.adventure.text.format.NamedTextColor;
31
import net.kyori.adventure.text.format.TextDecoration;
32
import net.kyori.adventure.text.event.ClickEvent;
33
import net.kyori.adventure.text.event.HoverEvent;
34
```
35

36
For specific functionality:
37

38
```java
39
// Text components and formatting
40
import net.kyori.adventure.text.Component;
41
import net.kyori.adventure.text.TextComponent;
42
import net.kyori.adventure.text.format.Style;
43
import net.kyori.adventure.text.format.TextColor;
44

45
// Audience system
46
import net.kyori.adventure.audience.Audience;
47
import net.kyori.adventure.audience.Audiences;
48

49
// Sound and media
50
import net.kyori.adventure.sound.Sound;
51
import net.kyori.adventure.bossbar.BossBar;
52
import net.kyori.adventure.title.Title;
53
```
54

55
## Basic Usage
56

57
```java
58
import net.kyori.adventure.text.Component;
59
import net.kyori.adventure.text.format.NamedTextColor;
60
import net.kyori.adventure.text.format.TextDecoration;
61
import net.kyori.adventure.text.event.ClickEvent;
62
import net.kyori.adventure.audience.Audience;
63

64
// Create text components with formatting
65
Component message = Component.text("Hello World!")
66
    .color(NamedTextColor.GOLD)
67
    .decorate(TextDecoration.BOLD);
68

69
// Create interactive text with click events
70
Component clickableText = Component.text("Click me!")
71
    .color(NamedTextColor.GREEN)
72
    .clickEvent(ClickEvent.runCommand("/help"));
73

74
// Send to an audience (player, console, etc.)
75
audience.sendMessage(message);
76
audience.sendMessage(clickableText);
77

78
// Create complex text with multiple components
79
Component complex = Component.text()
80
    .append(Component.text("[SERVER] ", NamedTextColor.BLUE))
81
    .append(Component.text("Welcome ", NamedTextColor.WHITE))
82
    .append(Component.text("Player123", NamedTextColor.YELLOW, TextDecoration.BOLD))
83
    .append(Component.text("!", NamedTextColor.WHITE))
84
    .build();
85
```
86

87
## Architecture
88

89
Adventure API is built around several key systems:
90

91
- **Component System**: Immutable text components with rich formatting, styling, and interactivity
92
- **Audience System**: Universal interface for sending messages and media to players, consoles, and groups
93
- **Style System**: Comprehensive text formatting including colors, decorations, and events
94
- **Media System**: Sound playback, boss bars, titles, and resource pack management
95
- **Translation System**: Internationalization support with locale-based text rendering
96
- **Builder Pattern**: Fluent APIs throughout for creating components, styles, and configurations
97

98
## Capabilities
99

100
### Text Components
101

102
Core text component system providing immutable, type-safe text objects with rich formatting, events, and styling capabilities.
103

104
```java { .api }
105
// Main component interface
106
interface Component extends ComponentLike, Examinable, HoverEventSource<Component>, StyleGetter, StyleSetter<Component> {
107
    // Factory methods
108
    static Component empty();
109
    static Component newline();
110
    static Component space();
111
    static TextComponent text(String content);
112
    static TranslatableComponent translatable(String key);
113
    static Component join(ComponentLike separator, ComponentLike... components);
114
}
115

116
// Text component with string content
117
interface TextComponent extends BuildableComponent<TextComponent, TextComponent.Builder> {
118
    String content();
119
    TextComponent content(String content);
120
}
121

122
// Component builder interface
123
interface ComponentBuilder<C extends Component, B extends ComponentBuilder<C, B>> 
124
    extends AbstractBuilder<C>, ComponentBuilderApplicable, StyleSetter<B> {
125
    B append(Component component);
126
    B append(ComponentLike component);
127
    C build();
128
}
129
```
130

131
[Text Components](./text-components.md)
132

133
### Audience System
134

135
Universal messaging system for sending text, media, and interactive content to players, consoles, and groups of recipients.
136

137
```java { .api }
138
interface Audience extends Pointered {
139
    // Message sending
140
    void sendMessage(ComponentLike message);
141
    void sendActionBar(ComponentLike message);
142
    
143
    // Title display
144
    void showTitle(Title title);
145
    void clearTitle();
146
    
147
    // Boss bars
148
    void showBossBar(BossBar bar);
149
    void hideBossBar(BossBar bar);
150
    
151
    // Sound playback
152
    void playSound(Sound sound);
153
    void stopSound(SoundStop stop);
154
    
155
    // Books and UI
156
    void openBook(Book book);
157
    
158
    // Resource packs
159
    void sendResourcePacks(ResourcePackRequest request);
160
}
161

162
// Audience utilities
163
class Audiences {
164
    static Audience empty();
165
    static Audience audience(Collection<? extends Audience> audiences);
166
    static Collector<Audience, ?, ForwardingAudience> toAudience();
167
}
168
```
169

170
[Audience System](./audience-system.md)
171

172
### Text Formatting and Styling
173

174
Comprehensive formatting system with colors, decorations, events, and complete style management.
175

176
```java { .api }
177
// Style interface
178
interface Style extends StyleGetter, StyleSetter<Style>, StyleBuilderApplicable, Buildable<Style, Style.Builder> {
179
    // Style properties
180
    @Nullable TextColor color();
181
    TextDecoration.State decoration(TextDecoration decoration);
182
    @Nullable ClickEvent clickEvent();
183
    @Nullable HoverEvent<?> hoverEvent();
184
    
185
    // Style creation
186
    static Style empty();
187
    static Style style(TextColor color);
188
    static Style style(TextDecoration... decorations);
189
}
190

191
// Text colors
192
interface TextColor extends Examinable, StyleBuilderApplicable, TextFormat {
193
    int value();
194
    static TextColor color(int value);
195
    static TextColor fromHexString(String string);
196
}
197

198
// Named colors
199
enum NamedTextColor implements TextColor {
200
    BLACK, DARK_BLUE, DARK_GREEN, DARK_AQUA, DARK_RED, DARK_PURPLE, 
201
    GOLD, GRAY, DARK_GRAY, BLUE, GREEN, AQUA, RED, LIGHT_PURPLE, YELLOW, WHITE
202
}
203

204
// Text decorations
205
enum TextDecoration implements StyleBuilderApplicable, TextFormat {
206
    OBFUSCATED, BOLD, STRIKETHROUGH, UNDERLINED, ITALIC;
207
    
208
    enum State { NOT_SET, FALSE, TRUE }
209
}
210
```
211

212
[Text Formatting](./text-formatting.md)
213

214
### Events and Interactivity
215

216
Click and hover event system for creating interactive text with commands, URLs, and rich tooltips.
217

218
```java { .api }
219
// Click events
220
class ClickEvent implements ComponentBuilderApplicable, StyleBuilderApplicable, Examinable {
221
    Action action();
222
    String value();
223
    
224
    static ClickEvent openUrl(String url);
225
    static ClickEvent runCommand(String command);
226
    static ClickEvent suggestCommand(String command);
227
    static ClickEvent copyToClipboard(String text);
228
    
229
    enum Action { OPEN_URL, OPEN_FILE, RUN_COMMAND, SUGGEST_COMMAND, CHANGE_PAGE, COPY_TO_CLIPBOARD, CALLBACK }
230
}
231

232
// Hover events
233
class HoverEvent<V> implements ComponentBuilderApplicable, StyleBuilderApplicable, Examinable {
234
    Action<V> action();
235
    V value();
236
    
237
    static HoverEvent<Component> showText(ComponentLike text);
238
    static HoverEvent<ShowItem> showItem(ShowItem item);
239
    static HoverEvent<ShowEntity> showEntity(ShowEntity entity);
240
}
241
```
242

243
[Events and Interactivity](./events-and-interactivity.md)
244

245
### Sound System
246

247
Sound playback and management with support for different sources, volumes, and positional audio.
248

249
```java { .api }
250
// Sound interface
251
interface Sound extends Examinable {
252
    Key name();
253
    Source source();
254
    float volume();
255
    float pitch();
256
    
257
    static Sound sound(Key name, Source source, float volume, float pitch);
258
    static Builder sound();
259
    
260
    enum Source { MASTER, MUSIC, RECORD, WEATHER, BLOCK, HOSTILE, NEUTRAL, PLAYER, AMBIENT, VOICE }
261
}
262

263
// Sound stopping
264
interface SoundStop extends Examinable {
265
    @Nullable Key sound();
266
    @Nullable Sound.Source source();
267
    
268
    static SoundStop all();
269
    static SoundStop named(Key sound);
270
    static SoundStop source(Sound.Source source);
271
}
272
```
273

274
[Sound System](./sound-system.md)
275

276
### Boss Bars
277

278
Boss bar display system with customizable appearance, progress tracking, and viewer management.
279

280
```java { .api }
281
interface BossBar extends Examinable {
282
    Component name();
283
    float progress();
284
    Color color();
285
    Overlay overlay();
286
    Set<Flag> flags();
287
    
288
    // Modification methods
289
    BossBar name(ComponentLike name);
290
    BossBar progress(float progress);
291
    BossBar color(Color color);
292
    BossBar overlay(Overlay overlay);
293
    BossBar flags(Set<Flag> flags);
294
    
295
    static BossBar bossBar(ComponentLike name, float progress, Color color, Overlay overlay);
296
    
297
    enum Color { PINK, BLUE, RED, GREEN, YELLOW, PURPLE, WHITE }
298
    enum Overlay { PROGRESS, NOTCHED_6, NOTCHED_10, NOTCHED_12, NOTCHED_20 }
299
    enum Flag { DARKEN_SCREEN, PLAY_BOSS_MUSIC, CREATE_WORLD_FOG }
300
}
301
```
302

303
[Boss Bars](./boss-bars.md)
304

305
### Titles and Subtitles
306

307
Title display system with customizable timing, main titles, subtitles, and action bar text.
308

309
```java { .api }
310
interface Title extends Examinable {
311
    Component title();
312
    Component subtitle();
313
    @Nullable Times times(); 
314
    
315
    static Title title(ComponentLike title, ComponentLike subtitle);
316
    static Title title(ComponentLike title, ComponentLike subtitle, Times times);
317
    
318
    // Title timing configuration
319
    class Times implements Examinable {
320
        Duration fadeIn();
321
        Duration stay();
322
        Duration fadeOut();
323
        
324
        static Times times(Duration fadeIn, Duration stay, Duration fadeOut);
325
    }
326
}
327

328
// Title parts for individual updates
329
interface TitlePart<T> {
330
    T value();
331
    
332
    static TitlePart<Component> title(ComponentLike title);
333
    static TitlePart<Component> subtitle(ComponentLike subtitle);
334
    static TitlePart<Title.Times> times(Title.Times times);
335
}
336
```
337

338
[Titles and Subtitles](./titles-and-subtitles.md)
339

340
### Translation System
341

342
Internationalization support with locale-based rendering, translation registries, and global translation management.
343

344
```java { .api }
345
// Translatable components
346
interface TranslatableComponent extends BuildableComponent<TranslatableComponent, TranslatableComponent.Builder> {
347
    String key();
348
    List<TranslationArgument> arguments();
349
    
350
    TranslatableComponent key(String key);
351
    TranslatableComponent arguments(TranslationArgument... arguments);
352
}
353

354
// Translation system
355
interface Translator {
356
    @Nullable MessageFormat translate(String key, Locale locale);
357
    static Translator translator();
358
}
359

360
interface GlobalTranslator extends Translator {
361
    void addSource(Translator translator);
362
    void removeSource(Translator translator);
363
}
364

365
// Translation arguments
366
interface TranslationArgument {
367
    Component asComponent();
368
    String asString();
369
    
370
    static TranslationArgument component(ComponentLike component);
371
    static TranslationArgument string(String string);
372
}
373
```
374

375
[Translation System](./translation-system.md)
376

377
### Resource Packs
378

379
Resource pack management system for sending, tracking, and handling resource pack requests with callback support.
380

381
```java { .api }
382
interface ResourcePackRequest extends Examinable {
383
    ResourcePackInfo packs();
384
    boolean replace();
385
    @Nullable Component prompt();
386
    @Nullable ResourcePackCallback callback();
387
    
388
    static ResourcePackRequest resourcePackRequest(ResourcePackInfo pack);
389
    static Builder resourcePackRequest();
390
}
391

392
interface ResourcePackInfo extends Examinable {
393
    String id();
394
    String uri();
395
    String hash();
396
    
397
    static ResourcePackInfo resourcePackInfo(String id, String uri, String hash);
398
}
399

400
enum ResourcePackStatus {
401
    SUCCESSFULLY_LOADED, DECLINED, FAILED_DOWNLOAD, ACCEPTED, 
402
    DOWNLOADED, INVALID_URL, FAILED_TO_RELOAD, DISCARDED
403
}
404

405
interface ResourcePackCallback {
406
    void packEventReceived(String id, ResourcePackStatus status, Audience audience);
407
}
408
```
409

410
[Resource Packs](./resource-packs.md)
411

412
### Books and Inventory
413

414
Book creation and management for opening written books with multiple pages, authors, and titles.
415

416
```java { .api }
417
interface Book extends Examinable {
418
    Component title();
419
    Component author();
420
    List<Component> pages();
421
    
422
    Book title(ComponentLike title);
423
    Book author(ComponentLike author);
424
    Book pages(List<? extends ComponentLike> pages);
425
    
426
    static Book book(ComponentLike title, ComponentLike author, ComponentLike... pages);
427
    static Builder book();
428
}
429
```
430

431
[Books and Inventory](./books-and-inventory.md)
432

433
### NBT and Data Components
434

435
NBT (Named Binary Tag) data handling with serialization support and integration with Minecraft's data component system.
436

437
```java { .api }
438
interface BinaryTagHolder extends Examinable {
439
    @NotNull BinaryTag get() throws IOException;
440
    String string();
441
    
442
    static BinaryTagHolder encode(BinaryTag nbt);
443
    static BinaryTagHolder of(String string);
444
}
445

446
// NBT components
447
interface NBTComponent<C extends NBTComponent<C, B>, B extends NBTComponentBuilder<C, B>> 
448
    extends BuildableComponent<C, B> {
449
    String nbtPath();
450
    boolean interpret();
451
    @Nullable Component separator();
452
    
453
    C nbtPath(String nbtPath);
454
    C interpret(boolean interpret);
455
    C separator(@Nullable ComponentLike separator);
456
}
457

458
interface BlockNBTComponent extends NBTComponent<BlockNBTComponent, BlockNBTComponent.Builder> {
459
    BlockNBTComponent.Pos pos();
460
}
461

462
interface EntityNBTComponent extends NBTComponent<EntityNBTComponent, EntityNBTComponent.Builder> {
463
    String selector();
464
}
465

466
interface StorageNBTComponent extends NBTComponent<StorageNBTComponent, StorageNBTComponent.Builder> {
467
    Key storage();
468
}
469
```
470

471
[NBT and Data Components](./nbt-data-components.md)
472

473
## Common Patterns and Best Practices
474

475
### Component Creation
476
- Use factory methods like `Component.text()`, `Component.translatable()` for basic components
477
- Use builders for complex components with multiple properties
478
- Prefer immutable operations - methods return new instances rather than modifying existing ones
479

480
### Style Application
481
- Chain style methods for fluent API usage: `component.color(RED).decorate(BOLD)`
482
- Use `Style.style()` factory methods for reusable styles
483
- Apply styles to components using `.style()` method
484

485
### Audience Management
486
- Use `Audiences.audience()` to create composite audiences for broadcasting
487
- Check audience properties using pointer system for conditional logic
488
- Handle audience-specific capabilities gracefully
489

490
### Performance Considerations
491
- Components are immutable - cache frequently used components
492
- Use `Component.empty()` instead of creating empty text components
493
- Prefer `Component.join()` for combining multiple components efficiently