Action Builder

For a full list of wiki pages, see the Home page.

Action Builder

The ActionBuilder is a system that allows you to create, manage, and execute a sequence of predefined actions for a player. This is particularly useful for creating macros, scripted events, or custom command rewards that involve multiple steps.

Core Concepts

• ActionBuilder: The main class that holds a list of Actions.
• Action: An interface representing a single operation to be performed, such as sending a message or running a command.
• ActionExecutor: An internal class that processes the list of actions, handling delays asynchronously.

Creating an ActionBuilder

You create an ActionBuilder by giving it a name, which is used for identification and saving.

// In your DPlugin class
ActionBuilder welcomeAction = new ActionBuilder(this, "WelcomeAction");

Defining Actions

You can chain methods together to build a sequence of actions. Each method call adds a new Action to the list.

welcomeAction
    .sendMessage("&aWelcome to the server, {player}!")
    .playSound("entity.player.levelup", 1.0f, 1.0f, "world", "{player}")
    .delay(20L) // Wait for 1 second (20 ticks)
    .sendMessage("&eHere is your starter kit!")
    .executeCommandAsAdmin("kit starter {player}");

Available Actions

Method	Description
sendMessage(String message)	Sends a colored message to the player. {player} is a placeholder for the player's name.
playSound(...)	Plays a sound for the player. You can specify sound, volume, pitch, world, and target.
delay(long ticks)	Pauses the execution of the action sequence for a specified number of server ticks.
executeCommandAsAdmin(String cmd)	Executes a command from the server console. {player} can be used as a placeholder.
executeCommandAsPlayer(String cmd)	Forces the player to execute a command. {player} can be used as a placeholder.
teleport(String world, ...)	Teleports the player to the specified coordinates.
closeInventory()	Closes the player's currently open inventory.

Executing Actions

To run the sequence of actions for a specific player, call the execute method.

@EventHandler
public void onPlayerJoin(PlayerJoinEvent event) {
    Player player = event.getPlayer();
    // Assuming welcomeAction is accessible here
    welcomeAction.execute(player);
}

This will start the ActionExecutor, which will process the actions one by one. The delay action is handled by BukkitRunnable, so it does not block the main server thread.

Saving and Loading Actions

ActionBuilders can be easily saved to and loaded from YAML files, making them perfect for user-configurable event scripts.

Saving

You can get a YamlConfiguration object from your ActionBuilder and save it using ConfigUtils.

// Get the YamlConfiguration from the builder
YamlConfiguration data = welcomeAction.exportToYaml();

// Save it to a file in the 'actions' folder
ConfigUtils.saveCustomData(this, data, "WelcomeAction", "actions");

This will create plugins/YourPlugin/actions/WelcomeAction.yml with content like this:

ACTION_NAME: WelcomeAction
actions:
- send_message &aWelcome to the server, {player}!
- play_sound entity.player.levelup 1.0 1.0 world {player}
- delay 20
- send_message &eHere is your starter kit!
- execute_as_admin kit starter {player}

Loading

DPP-Core can automatically load all action files from the actions directory at startup.

// In your onEnable method
PluginUtil.loadAllAction();

// You can then retrieve a loaded action from the DPPCore instance
ActionBuilder loadedAction = DPPCore.getInstance().getActions().get("WelcomeAction");

if (loadedAction != null) {
    loadedAction.execute(somePlayer);
}

This allows server administrators to create or modify action scripts in the actions folder without needing to recompile the plugin.