Custom Actions

You can register new action types that become available in all menu and dialog YAML files after registration.

Step 1 — Implement `Action`

import com.astralrealms.core.paper.model.action.Action;
import org.bukkit.entity.Player;

// Record constructor arguments are bound from the parsed action string via AstralAdapter.
public record GiveExpAction(int amount) implements Action {

    @Override
    public void execute(Player player, Object context) {
        player.giveExp(amount);
    }
}

Constructor argument resolution

Constructor parameters are resolved from the action's argument string using registered AstralAdapter implementations. The adapters for the most common types are already registered:

Java type	Resolved from
`int`/`Integer`	Parsed integer; decimals truncated toward zero
`long`/`Long`	Parsed long; decimals truncated toward zero
`double`/`Double`	Parsed double
`float`/`Float`	Parsed float
`boolean`/`Boolean`	`"true"`/`"false"`
`String`	Raw argument string
`Component`	MiniMessage-parsed component
`ComponentWrapper`	Wrapped MiniMessage string
`Sound`	Adventure sound key
`Key`	Adventure namespaced key
`UUID`	UUID string
`World`	World name, UUID, or a world placeholder
`Entity`	Entity placeholder or entity UUID
`Block`	Block placeholder or `Location`
`Material`	Bukkit registry lookup
`Location`	`"world,x,y,z"` format
`Duration`	ISO 8601 string (e.g. `PT10S`)
`Enchantment`	An enchantment placeholder (`%…_enchantment_<key>%`) or an `Enchantment`; a plain string key is not accepted
`Collection`	A collection, an array, or a single value wrapped into a one-element list

For custom types, register a new adapter:

AstralPaperAPI.registerAdapter(MyType.class, (node, context) -> new MyType(node.getString()));

Step 2 — Register the Action

Call this during your plugin's onEnable:

AstralPaperAPI.registerAction("give-exp", GiveExpAction.class);

The first argument is the action ID used in YAML.

Step 3 — Use in YAML

actions:
  LEFT:
    - "[give-exp] 500"
    - "[give-exp] 100 <chance=50>"

The argument string (500) is passed to the int amount constructor parameter.

Multi-parameter Actions

If an action takes multiple constructor parameters, separate values in the argument string by a space or use a custom format — the adapter receives the full raw argument string:

public record TeleportAction(double x, double y, double z) implements Action {
    @Override
    public void execute(Player player, Object context) {
        player.teleport(new Location(player.getWorld(), x, y, z));
    }
}

For multi-parameter constructors you may need to register a custom adapter that splits the string manually instead of relying on the generic GenericConstructorAdapter:

AstralPaperAPI.registerAdapter(TeleportAction.class, (node, context) -> {
    String[] parts = node.getString("0 64 0").split(" ");
    return new TeleportAction(
        Double.parseDouble(parts[0]),
        Double.parseDouble(parts[1]),
        Double.parseDouble(parts[2])
    );
});

Placeholder Substitution

The argument string has all %placeholder% tokens substituted before the adapter runs. This means your action receives already-resolved values:

- "[give-exp] %parameters_reward_exp%"

The GiveExpAction constructor receives the integer value of %parameters_reward_exp%, not the placeholder string.

Last modified: 03 September 2026