Adventure chat arguments

Developer's Note:

The two following classes, AdventureChatComponentArgument and AdventureChatArgument depend on a Paper based server which has the Adventure library. If you use this class on a server without the Adventure library, it will throw a PaperAdventureNotFoundException

From Paper 1.16.5 build #473, it now includes Kyori's Adventure API. This library is a replacement of the BungeeCord chat API and has all of 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.

Adventure chat component argument

The AdventureChatComponentArgument 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

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. In order 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 PlayerArgument("target"))
    .withArguments(new TextArgument("title"))
    .withArguments(new StringArgument("author"))
    .withArguments(new AdventureChatComponentArgument("contents"))
    .executes((sender, args) -> {
    	Player target = (Player) args[0];
        String title = (String) args[1];
        String author = (String) args[2];
        Component content = (Component) args[3];
        
        // 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 AdventureChatArgument class is the equivalent Adventure API class for the ChatArgument - it represents infinitely long strings similar to the GreedyStringArgument and allows entity selectors such as @e, @p and so on. The AdventureChatArgument returns a Component, similar to the AdventureChatComponentArgument.

Example - Sending personalized messages to players

We'll take the same example from the ChatArgument class, but using the AdventureChatArgument instead - 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>

In order to broadcast an Adventure Component to all players on the server, we have to use Paper's broadcast(Component, String) method. This method requires a permission node which all players must have in order to receive the broadcasted message. By default, Bukkit-based servers (Spigot and Paper) use the bukkit.broadcast.user permission, which is described here:

new CommandAPICommand("pbroadcast")
	.withArguments(new AdventureChatArgument("message"))
    .executes((sender, args) -> {
        Component message = (Component) args[0];
        
        // Broadcast the message to everyone with broadcast permissions. Read more info about broadcast
        // permissions here: https://bukkit.fandom.com/wiki/CraftBukkit_Commands#Additional_Permissions
        Bukkit.getServer().broadcast(message, "bukkit.broadcast.user");
    })
    .register();