Actions System Overview

The actions system allows you to add interactive behaviors to NPCs that execute when players interact with them. Actions can send messages, run commands, play sounds, and more.

How actions work

Actions are organized by triggers - specific events that cause actions to execute:

LEFT_CLICK - Player left-clicks the NPC
RIGHT_CLICK - Player right-clicks the NPC
ANY_CLICK - Player clicks the NPC (left or right)
CUSTOM - Programmatically triggered

When a player triggers an action, all actions registered for that trigger execute in order.

Action execution context

Each action receives an ActionExecutionContext with information about the interaction:

public class ActionExecutionContext {
    private final Npc npc;           // The NPC being interacted with
    private final Player player;      // The player who triggered the action
    private final Location location;  // The NPC's location
    private final ActionTrigger trigger; // What triggered the action
}

Built-in actions

FancyNPCs includes several built-in actions:

Action	Description	Example Value
`MessageAction`	Send a message to the player	`Hello, {player}!`
`PlayerCommandAction`	Execute command as the player	`spawn`
`PlayerCommandAsOpAction`	Execute command as OP	`gamemode creative`
`ConsoleCommandAction`	Execute command from console	`give {player} diamond 1`
`PlaySoundAction`	Play a sound to the player	`ENTITY_EXPERIENCE_ORB_PICKUP`
`SendToServerAction`	Send player to another server (BungeeCord)	`lobby`
`WaitAction`	Delay execution	`2000` (milliseconds)
`BlockUntilDoneAction`	Wait for action completion	-
`ExecuteRandomActionAction`	Execute random action	-
`NeedPermissionAction`	Require permission	`myplugin.vip`

Adding actions to NPCs

Using the API

import de.oliver.fancynpcs.api.actions.ActionTrigger;
import de.oliver.fancynpcs.api.actions.NpcAction;
import de.oliver.fancynpcs.api.actions.ActionManager;

// Get the action manager
ActionManager actionManager = FancyNpcsPlugin.get().getActionManager();

// Get a built-in action
NpcAction messageAction = actionManager.getActionByName("message");

// Create action data
List<NpcAction.NpcActionData> actions = new ArrayList<>();
actions.add(new NpcAction.NpcActionData(0, messageAction, "<green>Hello!</green>"));

// Add to NPC
NpcData data = npc.getData();
data.setActions(ActionTrigger.RIGHT_CLICK, actions);

// Update the NPC
npc.updateForAll();

Using commands

/npc action <npc> <trigger> add <actionType> [value]

Example:

/npc action shop_keeper right_click add message <gold>Welcome to the shop!

Action ordering

Actions execute in the order specified by their order field:

// First action (order 0)
actions.add(new NpcAction.NpcActionData(0, messageAction, "First message"));

// Second action (order 1)
actions.add(new NpcAction.NpcActionData(1, soundAction, "ENTITY_EXPERIENCE_ORB_PICKUP"));

// Third action (order 2)
actions.add(new NpcAction.NpcActionData(2, messageAction, "Second message"));

Placeholders

Many actions support placeholders that are replaced at execution time:

{player} - Player's name
{player_uuid} - Player's UUID
{player_displayname} - Player's display name
{npc} - NPC's name
{npc_id} - NPC's ID
PlaceholderAPI placeholders (if installed)

Example:

// Will show: "Hello, Steve!"
messageAction.execute(context, "Hello, {player}!");

Example: Creating an interactive shop NPC

import de.oliver.fancynpcs.api.*;
import de.oliver.fancynpcs.api.actions.*;
import java.util.ArrayList;
import java.util.List;

public void createShopNpc(Location location, UUID creator) {
    // Create NPC
    NpcData data = new NpcData("shop_npc", creator, location);
    data.setDisplayName("<gold>Shop Keeper</gold>");
    data.setSkin("MHF_Villager");

    // Get action manager
    ActionManager actionManager = FancyNpcsPlugin.get().getActionManager();

    // Create actions for right-click
    List<NpcAction.NpcActionData> rightClickActions = new ArrayList<>();

    // 1. Play sound
    NpcAction soundAction = actionManager.getActionByName("play_sound");
    rightClickActions.add(new NpcAction.NpcActionData(
        0, soundAction, "ENTITY_VILLAGER_YES"
    ));

    // 2. Send welcome message
    NpcAction messageAction = actionManager.getActionByName("message");
    rightClickActions.add(new NpcAction.NpcActionData(
        1, messageAction, "<gold>Welcome, {player}!</gold>"
    ));

    // 3. Wait 1 second
    NpcAction waitAction = actionManager.getActionByName("wait");
    rightClickActions.add(new NpcAction.NpcActionData(
        2, waitAction, "1000"
    ));

    // 4. Open shop (as player command)
    NpcAction cmdAction = actionManager.getActionByName("player_command");
    rightClickActions.add(new NpcAction.NpcActionData(
        3, cmdAction, "shop open"
    ));

    // Add actions to NPC
    data.setActions(ActionTrigger.RIGHT_CLICK, rightClickActions);

    // Create and register NPC
    Npc npc = FancyNpcsPlugin.get().getNpcAdapter().apply(data);
    FancyNpcsPlugin.get().getNpcManager().registerNpc(npc);

    npc.create();
    npc.spawnForAll();
}

Conditional actions

Use NeedPermissionAction to create conditional behavior:

List<NpcAction.NpcActionData> actions = new ArrayList<>();

// Check if player has VIP permission
NpcAction permAction = actionManager.getActionByName("need_permission");
actions.add(new NpcAction.NpcActionData(0, permAction, "myplugin.vip"));

// This only runs if they have permission
NpcAction vipMessage = actionManager.getActionByName("message");
actions.add(new NpcAction.NpcActionData(1, vipMessage, "<gold>VIP access granted!"));

Random actions

Use ExecuteRandomActionAction for variety:

// This will execute one random message
NpcAction randomAction = actionManager.getActionByName("execute_random_action");
actions.add(new NpcAction.NpcActionData(0, randomAction, null));

actions.add(new NpcAction.NpcActionData(1, messageAction, "Hello!"));
actions.add(new NpcAction.NpcActionData(2, messageAction, "Hi there!"));
actions.add(new NpcAction.NpcActionData(3, messageAction, "Greetings!"));

Creating custom actions

You can create custom actions by extending the NpcAction class. See Custom Actions for details.

Actions System Overview

On this page