or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

audience-system.mdbooks-and-inventory.mdboss-bars.mdevents-and-interactivity.mdindex.mdnbt-data-components.mdresource-packs.mdsound-system.mdtext-components.mdtext-formatting.mdtitles-and-subtitles.mdtranslation-system.md
tile.json

tessl/maven-net-kyori--adventure-api

A serverside user interface library for Minecraft: Java Edition

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

To install, run

npx @tessl/cli install tessl/maven-net-kyori--adventure-api@4.23.0

index.mddocs/

Adventure API

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.

Package Information

  • Package Name: net.kyori:adventure-api
  • Package Type: maven
  • Language: Java
  • Installation: Add to your build.gradle or pom.xml:
implementation 'net.kyori:adventure-api:4.23.0'
<dependency>
  <groupId>net.kyori</groupId>
  <artifactId>adventure-api</artifactId>
  <version>4.23.0</version>
</dependency>

Core Imports

The most commonly used classes and interfaces:

import net.kyori.adventure.text.Component;
import net.kyori.adventure.audience.Audience;
import net.kyori.adventure.text.format.NamedTextColor;
import net.kyori.adventure.text.format.TextDecoration;
import net.kyori.adventure.text.event.ClickEvent;
import net.kyori.adventure.text.event.HoverEvent;

For specific functionality:

// Text components and formatting
import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.TextComponent;
import net.kyori.adventure.text.format.Style;
import net.kyori.adventure.text.format.TextColor;

// Audience system
import net.kyori.adventure.audience.Audience;
import net.kyori.adventure.audience.Audiences;

// Sound and media
import net.kyori.adventure.sound.Sound;
import net.kyori.adventure.bossbar.BossBar;
import net.kyori.adventure.title.Title;

Basic Usage

import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.format.NamedTextColor;
import net.kyori.adventure.text.format.TextDecoration;
import net.kyori.adventure.text.event.ClickEvent;
import net.kyori.adventure.audience.Audience;

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

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

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

// Create complex text with multiple components
Component complex = Component.text()
    .append(Component.text("[SERVER] ", NamedTextColor.BLUE))
    .append(Component.text("Welcome ", NamedTextColor.WHITE))
    .append(Component.text("Player123", NamedTextColor.YELLOW, TextDecoration.BOLD))
    .append(Component.text("!", NamedTextColor.WHITE))
    .build();

Architecture

Adventure API is built around several key systems:

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

Capabilities

Text Components

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

// Main component interface
interface Component extends ComponentLike, Examinable, HoverEventSource<Component>, StyleGetter, StyleSetter<Component> {
    // Factory methods
    static Component empty();
    static Component newline();
    static Component space();
    static TextComponent text(String content);
    static TranslatableComponent translatable(String key);
    static Component join(ComponentLike separator, ComponentLike... components);
}

// Text component with string content
interface TextComponent extends BuildableComponent<TextComponent, TextComponent.Builder> {
    String content();
    TextComponent content(String content);
}

// Component builder interface
interface ComponentBuilder<C extends Component, B extends ComponentBuilder<C, B>> 
    extends AbstractBuilder<C>, ComponentBuilderApplicable, StyleSetter<B> {
    B append(Component component);
    B append(ComponentLike component);
    C build();
}

Text Components

Audience System

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

interface Audience extends Pointered {
    // Message sending
    void sendMessage(ComponentLike message);
    void sendActionBar(ComponentLike message);
    
    // Title display
    void showTitle(Title title);
    void clearTitle();
    
    // Boss bars
    void showBossBar(BossBar bar);
    void hideBossBar(BossBar bar);
    
    // Sound playback
    void playSound(Sound sound);
    void stopSound(SoundStop stop);
    
    // Books and UI
    void openBook(Book book);
    
    // Resource packs
    void sendResourcePacks(ResourcePackRequest request);
}

// Audience utilities
class Audiences {
    static Audience empty();
    static Audience audience(Collection<? extends Audience> audiences);
    static Collector<Audience, ?, ForwardingAudience> toAudience();
}

Audience System

Text Formatting and Styling

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

// Style interface
interface Style extends StyleGetter, StyleSetter<Style>, StyleBuilderApplicable, Buildable<Style, Style.Builder> {
    // Style properties
    @Nullable TextColor color();
    TextDecoration.State decoration(TextDecoration decoration);
    @Nullable ClickEvent clickEvent();
    @Nullable HoverEvent<?> hoverEvent();
    
    // Style creation
    static Style empty();
    static Style style(TextColor color);
    static Style style(TextDecoration... decorations);
}

// Text colors
interface TextColor extends Examinable, StyleBuilderApplicable, TextFormat {
    int value();
    static TextColor color(int value);
    static TextColor fromHexString(String string);
}

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

// Text decorations
enum TextDecoration implements StyleBuilderApplicable, TextFormat {
    OBFUSCATED, BOLD, STRIKETHROUGH, UNDERLINED, ITALIC;
    
    enum State { NOT_SET, FALSE, TRUE }
}

Text Formatting

Events and Interactivity

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

// Click events
class ClickEvent implements ComponentBuilderApplicable, StyleBuilderApplicable, Examinable {
    Action action();
    String value();
    
    static ClickEvent openUrl(String url);
    static ClickEvent runCommand(String command);
    static ClickEvent suggestCommand(String command);
    static ClickEvent copyToClipboard(String text);
    
    enum Action { OPEN_URL, OPEN_FILE, RUN_COMMAND, SUGGEST_COMMAND, CHANGE_PAGE, COPY_TO_CLIPBOARD, CALLBACK }
}

// Hover events
class HoverEvent<V> implements ComponentBuilderApplicable, StyleBuilderApplicable, Examinable {
    Action<V> action();
    V value();
    
    static HoverEvent<Component> showText(ComponentLike text);
    static HoverEvent<ShowItem> showItem(ShowItem item);
    static HoverEvent<ShowEntity> showEntity(ShowEntity entity);
}

Events and Interactivity

Sound System

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

// Sound interface
interface Sound extends Examinable {
    Key name();
    Source source();
    float volume();
    float pitch();
    
    static Sound sound(Key name, Source source, float volume, float pitch);
    static Builder sound();
    
    enum Source { MASTER, MUSIC, RECORD, WEATHER, BLOCK, HOSTILE, NEUTRAL, PLAYER, AMBIENT, VOICE }
}

// Sound stopping
interface SoundStop extends Examinable {
    @Nullable Key sound();
    @Nullable Sound.Source source();
    
    static SoundStop all();
    static SoundStop named(Key sound);
    static SoundStop source(Sound.Source source);
}

Sound System

Boss Bars

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

interface BossBar extends Examinable {
    Component name();
    float progress();
    Color color();
    Overlay overlay();
    Set<Flag> flags();
    
    // Modification methods
    BossBar name(ComponentLike name);
    BossBar progress(float progress);
    BossBar color(Color color);
    BossBar overlay(Overlay overlay);
    BossBar flags(Set<Flag> flags);
    
    static BossBar bossBar(ComponentLike name, float progress, Color color, Overlay overlay);
    
    enum Color { PINK, BLUE, RED, GREEN, YELLOW, PURPLE, WHITE }
    enum Overlay { PROGRESS, NOTCHED_6, NOTCHED_10, NOTCHED_12, NOTCHED_20 }
    enum Flag { DARKEN_SCREEN, PLAY_BOSS_MUSIC, CREATE_WORLD_FOG }
}

Boss Bars

Titles and Subtitles

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

interface Title extends Examinable {
    Component title();
    Component subtitle();
    @Nullable Times times(); 
    
    static Title title(ComponentLike title, ComponentLike subtitle);
    static Title title(ComponentLike title, ComponentLike subtitle, Times times);
    
    // Title timing configuration
    class Times implements Examinable {
        Duration fadeIn();
        Duration stay();
        Duration fadeOut();
        
        static Times times(Duration fadeIn, Duration stay, Duration fadeOut);
    }
}

// Title parts for individual updates
interface TitlePart<T> {
    T value();
    
    static TitlePart<Component> title(ComponentLike title);
    static TitlePart<Component> subtitle(ComponentLike subtitle);
    static TitlePart<Title.Times> times(Title.Times times);
}

Titles and Subtitles

Translation System

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

// Translatable components
interface TranslatableComponent extends BuildableComponent<TranslatableComponent, TranslatableComponent.Builder> {
    String key();
    List<TranslationArgument> arguments();
    
    TranslatableComponent key(String key);
    TranslatableComponent arguments(TranslationArgument... arguments);
}

// Translation system
interface Translator {
    @Nullable MessageFormat translate(String key, Locale locale);
    static Translator translator();
}

interface GlobalTranslator extends Translator {
    void addSource(Translator translator);
    void removeSource(Translator translator);
}

// Translation arguments
interface TranslationArgument {
    Component asComponent();
    String asString();
    
    static TranslationArgument component(ComponentLike component);
    static TranslationArgument string(String string);
}

Translation System

Resource Packs

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

interface ResourcePackRequest extends Examinable {
    ResourcePackInfo packs();
    boolean replace();
    @Nullable Component prompt();
    @Nullable ResourcePackCallback callback();
    
    static ResourcePackRequest resourcePackRequest(ResourcePackInfo pack);
    static Builder resourcePackRequest();
}

interface ResourcePackInfo extends Examinable {
    String id();
    String uri();
    String hash();
    
    static ResourcePackInfo resourcePackInfo(String id, String uri, String hash);
}

enum ResourcePackStatus {
    SUCCESSFULLY_LOADED, DECLINED, FAILED_DOWNLOAD, ACCEPTED, 
    DOWNLOADED, INVALID_URL, FAILED_TO_RELOAD, DISCARDED
}

interface ResourcePackCallback {
    void packEventReceived(String id, ResourcePackStatus status, Audience audience);
}

Resource Packs

Books and Inventory

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

interface Book extends Examinable {
    Component title();
    Component author();
    List<Component> pages();
    
    Book title(ComponentLike title);
    Book author(ComponentLike author);
    Book pages(List<? extends ComponentLike> pages);
    
    static Book book(ComponentLike title, ComponentLike author, ComponentLike... pages);
    static Builder book();
}

Books and Inventory

NBT and Data Components

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

interface BinaryTagHolder extends Examinable {
    @NotNull BinaryTag get() throws IOException;
    String string();
    
    static BinaryTagHolder encode(BinaryTag nbt);
    static BinaryTagHolder of(String string);
}

// NBT components
interface NBTComponent<C extends NBTComponent<C, B>, B extends NBTComponentBuilder<C, B>> 
    extends BuildableComponent<C, B> {
    String nbtPath();
    boolean interpret();
    @Nullable Component separator();
    
    C nbtPath(String nbtPath);
    C interpret(boolean interpret);
    C separator(@Nullable ComponentLike separator);
}

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

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

interface StorageNBTComponent extends NBTComponent<StorageNBTComponent, StorageNBTComponent.Builder> {
    Key storage();
}

NBT and Data Components

Common Patterns and Best Practices

Component Creation

  • Use factory methods like Component.text(), Component.translatable() for basic components
  • Use builders for complex components with multiple properties
  • Prefer immutable operations - methods return new instances rather than modifying existing ones

Style Application

  • Chain style methods for fluent API usage: component.color(RED).decorate(BOLD)
  • Use Style.style() factory methods for reusable styles
  • Apply styles to components using .style() method

Audience Management

  • Use Audiences.audience() to create composite audiences for broadcasting
  • Check audience properties using pointer system for conditional logic
  • Handle audience-specific capabilities gracefully

Performance Considerations

  • Components are immutable - cache frequently used components
  • Use Component.empty() instead of creating empty text components
  • Prefer Component.join() for combining multiple components efficiently