Placeholders

Summary

The placeholder API find and interpolates placeholders within a given text using processors.

Thus defining a placeholder is %processor:query%. The query part is optional depending of the processor.

If you wish to use % as a normal character, escape it with another such as %% will format to %.

Here is a simple example showing how to greet and tell the day of the week to a player:

import com.xpdustry.distributor.api.Distributor;
import com.xpdustry.distributor.api.key.Key;
import com.xpdustry.distributor.api.key.MutableKeyContainer;
import com.xpdustry.flex.FlexAPI;
import com.xpdustry.flex.placeholder.PlaceholderContext;
import mindustry.gen.Player;

// A key for the day argument
final var DAY = Key.of("my_plugin", "day", String.class);
final Player player = /* get player, lets name him Anuke */;
// The subject of the placeholder is an audience, wrap the player in a player audience
final var subject = Distributor.get().getAudienceProvider().getPlayer(player);
final var text = "Hello %player:name%, today is %argument:my_plugin:day%.";
// Create the argument container
final var arguments = MutableKeyContainer.create();
arguments.set(DAY, "Monday");
// Now create the context and pump it into the pipeline
final var result = FlexAPI.get().getPlaceholders().pump(new PlaceholderContext(subject, text, arguments));
// Enjoy the result
player.sendMessage(result); // "Hello Anuke, today is Monday"

In the case a processor is not found or if it returns null due to an error, it will not interpolate the placeholder, leaving it as it is in the result text.

Built-ins

• argument: %argument:<namespace>:<name>%. Will retrieve an entry from the placeholder arguments and call toString on it. Fails if not found.

• player: %player:<property>%. Extracts one of the following properties if the subject is a player audience:

  • name: The name of the player without colors
  • name_colored: The name of the player with colors
  • tile_x: The x tile coordinates of a player
  • tile_y: The y tile coordinates of a player
  • world_x: The x world coordinates of a player
  • world_y: The y world coordinates of a player
  • color: The color of a player as hex
  • team_color: The color of a player team as hex

• audience: %player:<property>%. Extracts one of the default audience properties if the subject supports them:

  • name: The name of the audience without colors
  • name_colored: The name of the audience with colors
  • color: The color of a audience as hex
  • team_color: The color of a audience team as hex

  Use it instead of player whenever you can for compatibility with non-mindustry audiences.

• permission: %permission:<permission>%. Check whether the audience has a given permission, if yes, the permission is returned, otherwise it fails. This processor is intended for template filters.

• template: %template:<name>%. Use a predefined template, fails if it does not exists. Templates can either be defined in the plugin configuration or in code with the TemplateManager obtainable via FlexAPI.get().getTemplates().

Register

It's quite simple, here's an example showcasing a processor that reverses the name of the subject:

import com.xpdustry.distributor.api.key.StandardKeys;
import com.xpdustry.flex.FlexAPI;

FlexAPI.get().getPlaceholders().register("reverse_name", context -> {
    final var name = context.getSubject().getMetadata().getOptional(StandardKeys.NAME).orElse("Unknown");
    return new StringBuilder(name).reverse().toString();
});

You can also override existing processors, but if you do, try to not break their API.