Fabric

Adventure supports Fabric on Minecraft: Java Edition 1.16 and up, for both server-side and client-side use. Each major version of Minecraft will usually require a new release of the platform.

The platform supports all features, including localization and custom renderers.

When using at least version 5.3.0, this platform provides a near-native experience by directly implementing Adventure interfaces on Minecraft classes where possible.

The Fabric platform is packaged as a mod, designed to be included in mods via jar-in-jar packaging. As with the rest of the Adventure projects, releases are distributed on Maven Central, and snapshots on Sonatype OSS:

// TODO: Make this a component + insert version placeholder

repositories {
  // for development builds
  maven {
      name = "sonatype-oss-snapshots1"
      url = "https://s01.oss.sonatype.org/content/repositories/snapshots/"
      mavenContent { snapshotsOnly() }
  }
  // for releases
  mavenCentral()
}

dependencies {
    modImplementation include("net.kyori:adventure-platform-fabric:|mod_version|") // for Minecraft 1.21.2-1.21.4
}

repositories {
  // for development builds
  maven(url = "https://s01.oss.sonatype.org/content/repositories/snapshots/") {
      name = "sonatype-oss-snapshots1"
      mavenContent { snapshotsOnly() }
  }
  // for releases
  mavenCentral()
}

dependencies {
    modImplementation(include("net.kyori:adventure-platform-fabric:|modversion|")!!) // for Minecraft 1.21.2-1.21.4
}

The Fabric platform requires fabric-api-base in order to provide the locale change event, fabric-command-api-v2 for the callback click event, and can optionally use Colonel (or fabric-networking-api-v1) to allow the Component and Key argument types to be used on clients without the mod installed. There are no other dependencies.

The easiest way to get started with this platform is to work with the Minecraft game objects that directly implement Adventure interfaces (requires Loom 0.11 or newer).

This covers almost all cases where the default renderer is used.

The following Adventure interfaces are directly implemented:

Audience

• net.minecraft.commands.CommandSourceStack, net.minecraft.server.MinecraftServer, net.minecraft.server.rcon.RconConsoleSource,
• net.minecraft.server.level.ServerPlayer, net.minecraft.client.player.LocalPlayer

Sound.Emitter

• net.minecraft.world.entity.Entity

Sound.Type

• net.minecraft.sounds.SoundEvent

Identified

• net.minecraft.world.entity.player.Player

ComponentLike

• net.minecraft.network.chat.Component

Key

• net.minecraft.resources.ResourceLocation

Keyed

• net.minecraft.resources.ResourceKey

HoverEventSource

• net.minecraft.world.entity.Entity,
• net.minecraft.world.item.ItemStack

SignedMessage

• net.minecraft.network.chat.PlayerChatMessage

SignedMessage.Signature

• net.minecraft.network.chat.MessageSignature

Additionally, all Keys created will be ResourceLocation instances (on Loader 0.14.0+)

Using these injections, getting started is as simple as:

void greet(final ServerPlayer player) {
    Component message = Component.text()
        .content("Hello ")
        .append(player.get(Identity.DISPLAY_NAME)
            .get()
            .color(NamedTextColor.RED)
        );
    player.sendMessage(message);
}

For more complex use cases, FabricServerAudiences or FabricClientAudiences provide additional API.

The logical-server side of the Fabric platform can be accessed any time a server is available, through a FabricServerAudiences instance. By default, translatable components will be rendered with the global translator, but a custom renderer can be passed when initializing the platform.

All AudienceProvider interface methods are supported, except for the permission method. This will become supported as soon as Fabric gets a suitable permissions API.

To get started with Adventure, set up an audience provider like this:

public class MyMod implements ModInitializer {

    private volatile FabricServerAudiences adventure;

    public FabricServerAudiences adventure() {
        if (this.adventure == null) {
            throw new IllegalStateException("Tried to access Adventure without a running server!");
        }
        return this.adventure;
    }

    @Override
    public void onInitialize() {
        // Register with the server lifecycle callbacks
        // This will ensure any platform data is cleared between game instances
        // This is important on the integrated server, where multiple server instances
        // can exist for one mod initialization.
        ServerLifecycleEvents.SERVER_STARTING.register(server ->
            this.adventure = FabricServerAudiences.of(server)
        );
        ServerLifecycleEvents.SERVER_STOPPED.register(server ->
            this.adventure = null
        );
    }
}

From here, audiences can be acquired for players and any other CommandSource. Specialized serializer instances are also available, to allow using game information in component serialization.

As part of the platform’s translation support, the PlayerLocales.CHANGED_EVENT callback will be called any time a player on the server receives an updated language from their client, and allows accessing the current locale for a player.

The Fabric platform provides custom argument types to specify Key and Component parameters in Brigadier commands, and has helpers to easily get an Audience from a CommandSourceStack (yarn: ServerCommandSource) instance.

As an example, here’s a simple command that will echo whatever is provided as input:

// A potential method to be in the mod initializer class above
private static final String ARG_MESSAGE = "message";

void registerCommands(final CommandDispatcher dispatcher, final boolean isDedicated) {
    dispatcher.register(literal("echo").then(argument(ARG_MESSAGE, component()).executes(ctx -> {
        final Component message = component(ctx, ARG_MESSAGE);
        ctx.getSource().sendMessage(Component.text("You said: ").append(message));
    }));
}

Special for the Fabric platform, purely client-side operations are supported. The setup is less involved than it is for the server, since the client is a singleton, and there is only one subject that can be acted on: the client’s player.

This means that for most users the FabricClientAudiences object can be treated as a singleton. The only exception is users using a custom renderer. This makes using Adventure audiences fairly simple, as this code example shows:

void doThing() {
    // Get the audience
    final Audience client = FabricClientAudiences.of().audience();

    // Do something. This will only work when the player is in game.
    client.sendMessage(Component.text("meow", NamedTextColor.DARK_PURPLE));
}

The full functionality of the Audience interface is available, including localization!

Sadly, Adventure can’t provide API for every place chat components are used in the game. However, for areas not covered by the API in Audience, it’s possible to convert components between native and Adventure types. See certain native types which implement Adventure interfaces, and the methods on FabricAudiences for other available conversions.