Skip to content

cloud-minecraft-extras#

cloud-minecraft-extras contains some optional utilities for the Minecraft integrations.

Note

These utilities depend on adventure. You may need to depend on Adventure and shade it into your project, depending on the platform you’re targeting. Many Minecraft platforms, such as Paper, ship with native implementations of Adventure, in which case you do not need to include it yourself.

Installation#

Cloud Minecraft Extras is available through Maven Central.

<dependencies>
    <dependency>
        <groupId>org.incendo</groupId>
        <artifactId>cloud-minecraft-extras</artifactId>
        <version>2.0.0-beta.10</version>
    </dependency>
</dependencies>

implementation("org.incendo:cloud-minecraft-extras:2.0.0-beta.10")

implementation 'org.incendo:cloud-minecraft-extras:2.0.0-beta.10'

Minecraft Help#

MinecraftHelp is an opinionated implementation of the help system using Adventure components for styling and click handling.

Index View

Index View

Verbose View

Verbose View

All interactions with the Minecraft help system will take place through a MinecraftHelp instance.

You may create an instance with the default styling:

// Assuming YourSenderType extends Audience
MinecraftHelp<YourSenderType> help = MinecraftHelp.createNative(
  "/helpcommand",
  commandManager
);

MinecraftHelp<YourSenderType> help = MinecraftHelp.create(
  "/helpcommand",
  commandManager,
  audienceMapper // YourSenderType -> Audience
);

or you may override the defaults by using a builder:

MinecraftHelp<NativeSenderType> help = MinecraftHelp.<NativeSenderType>builder()
  .commandManager(commandManager)
  .audienceProvider(AudienceProvider.nativeAudience())
  .commandPrefix("/helpcommand")
  .colors(MinecraftHelp.helpColors(NamedTextColor.GREEN, NamedTextColor.RED,
    NamedTextColor.AQUA, NamedTextColor.BLACK, NamedTextColor.WHITE
  ))
  /* other settings... */
  .build();

AudienceProvider<SenderType> audienceProvider = SenderType::audience;
MinecraftHelp<SenderType> help = MinecraftHelp.<SenderType>builder()
  .commandManager(commandManager)
  .audienceProvider(audienceProvider)
  .commandPrefix("/helpcommand")
  .colors(MinecraftHelp.helpColors(NamedTextColor.GREEN, NamedTextColor.RED,
    NamedTextColor.AQUA, NamedTextColor.BLACK, NamedTextColor.WHITE
  ))
  /* other settings... */
  .build();

You then want to invoke MinecraftHelp.queryCommands(query, recipient) in order to query the commands and display the results to the recipient.

Example Help Command
commandManager.command(
  commandManager.commandBuilder("helpcommand")
    .optional("query", greedyStringParser(), DefaultValue.constant(""))
    .handler(context -> {
      help.queryCommands(context.get("query"), context.sender());
    })
);

You may choose to add suggestions to the query argument as well:

Query Suggestions
.optional(
  "query",
  greedyStringParser(),
  DefaultValue.constant(""),
  SuggestionProvider.blocking((ctx, in) -> commandManager.createHelpHandler()
    .queryRootIndex(ctx.sender())
    .entries()
    .stream()
    .map(CommandEntry::syntax)
    .map(Suggestion::suggestion)
    .collect(Collectors.toList())
  )
)

Minecraft Exception Handler#

MinecraftExceptionHandler is an opinionated collection of exception handlers that uses Adventure components for styling.

All interactions with the system are done through an instance of MinecraftExceptionHandler.

// Assuming your sender type extends Audience
MinecraftExceptionHandler.createNative();

MinecraftExceptionHandler.create(audienceProvider // C -> Audience);

You then use the fluent methods to create handlers for the different exception types. If you want to register the default handlers for all types you may use defaultHandlers().

You may supply a decorator which will transform the created components. This is useful if you want to prefix all messages, or apply specific styling.

Example decorator
MinecraftExceptionHandler.createNative()
  .decorator(component -> text()
    .append(text("[Example] ", NamedTextColor.DARK_RED))
    .append(component)
    .build()
  );

When you’re done configuring the builder you need to apply it to the command manager by using registerTo(CommandManager).

Complete example
MinecraftExceptionHandler.<NativeSenderType>createNative()
  .defaultHandlers()
  .decorator(component -> text()
    .append(text("[Example] ", NamedTextColor.DARK_RED))
    .append(component)
    .build()
  ).registerTo(manager);

Localization#

MinecraftExceptionHandler uses the localization system. By default, the exception handler will make use of a ComponentCaptionFormatter that wraps the caption value in a text component.

You may choose to replace the caption formatter with a component formatter that uses MiniMessage by using ComponentCaptionFormatter.miniMessage(). MiniMessage will then be used for both styling and placeholder replacements.

Rich Description#

RichDescription allows for the use of Adventure components in both component and command descriptions. These descriptions are supported by MinecraftHelp. If descriptions are used in other places they are likely to be transformed into plain text.

// Static factory:
Description description = RichDescription.of(text("Hello world!"));

// Statically importable alias:
Description description = RichDescription.richDescription(text("Hello world!"));

// Utility for translatable components:
Description description = RichDescription.translatable("some.key", text("an arg"));

Text Color Parser#

TextColorParser is a parser which parses Adventure TextColors. It parses NamedTextColor, legacy color codes using & as well as hex codes.

ParserDescriptor<?, TextColor> parser = TextColorParser.textColorParser();

Component Parser#

ComponentParser is a parser which parses Adventure Components via a specified “decoder” function.

// This creates a parser that uses MiniMessage for decoding the argument, and uses
// greedy string parsing.
ParserDescriptor<?, Component> parser = ComponentParser.componentParser(
  MiniMessage.miniMessage(),
  StringParser.StringMode.GREEDY_FLAG_YIELDING
);