Adventure chat arguments

From Paper 1.16.5 build #473 onwards, Paper now includes Kyori's Adventure API. This library is a replacement of the BungeeCord chat API and has all the same functionality as the BungeeCord chat API (and more!). The documentation for this API can be found here.

Since this functions very similar to the Spigot chat arguments, this page won't reiterate everything about how it works, we'll just outline some examples of how to use these arguments instead. Additionally, the names used here may be confusing as they are the same names as on the Spigot chat arguments page but have different return types. This is because the classes on this page are only accessible using commandapi-paper-core or commandapi-paper-shade while the arguments on the Spigot chat arguments page are only available when using commandapi-spigot-core or commandapi-spigot-shade.

Developer's Note:

The three following classes, ChatColorArgument, ChatComponentArgument and ChatArgument depend on a Paper based server which has the Adventure library. If you use any of these classes on a server without the Adventure library, they will throw a PaperAdventureNotFoundException.

Adventure chat color argument

The ChatColorArgument class is used to represent a given chat color (e.g., red or green). This argument returns the NamedTextColor object. If reset is passed to this argument, this will return NamedTextColor.WHITE.

Example – Username color changing plugin

Example – Username color changing plugin

Say we want to create a plugin to change the color of a player's username. We want to create a command of the following form:

/namecolor <chatcolor>

We then use the ChatColorArgument to change the player's name color:

new CommandAPICommand("namecolor")
    .withArguments(new ChatColorArgument("chatcolor"))
    .executesPlayer((player, args) -> {
        NamedTextColor color = (NamedTextColor) args.get("chatcolor");
        player.displayName(Component.text().color(color).append(Component.text(player.getName())).build());
    })
    .register();

Adventure chat component argument

The ChatComponentArgument class accepts raw chat-based JSON as valid input, as declared here. This is converted into Adventure's Component class.

Example – Opening a book with raw JSON content

Example – Opening a book with raw JSON content

In this example, we'll create a simple command which lets you show a book to a user. The syntax for our command is as follows:

/showbook <target> <title> <author> <contents>

We can construct a book using the Adventure API's Book.book(Component, Component, Component...) method. To convert our strings into Component objects, we use the Component.text(String) method. Since Paper supports the Adventure API natively, we can then send this book to a player using the openBook(Book) method:

new CommandAPICommand("showbook")
    .withArguments(new EntitySelectorArgument.OnePlayer("target"))
    .withArguments(new TextArgument("title"))
    .withArguments(new StringArgument("author"))
    .withArguments(new ChatComponentArgument("contents"))
    .executes((sender, args) -> {
        Player target = (Player) args.get("target");
        String title = (String) args.get("title");
        String author = (String) args.get("author");
        Component content = (Component) args.get("contents");

        // Create a book and show it to the user (Requires Paper)
        Book mybook = Book.book(Component.text(title), Component.text(author), content);
        target.openBook(mybook);
    })
    .register();

Adventure chat argument

The ChatArgument represents infinitely long strings similar to the GreedyStringArgument and allows entity selectors such as @e, @p and so on. The ChatArgument returns a SignedMessage.

Example – Sending personalized messages to players

Example – Sending personalized messages to players

We want to create a personalized message broadcasted to all users using a chat component that allows entity selectors. For this command, we want the following syntax:

/pbroadcast <message>

To broadcast an Adventure Component to all players on the server, we have to use Paper's sendMessage(SignedMessage, Bound) method.

new CommandAPICommand("pbroadcast")
    .withArguments(new ChatArgument("message"))
    .executes((sender, args) -> {
        SignedMessage message = (SignedMessage) args.get("message");

        // Sends the message as if it was sent by a player
        Bukkit.getServer().sendMessage(message, ChatType.CHAT.bind(Component.text(sender.getName())));
    })
    .register();