PLUGIN Click Actions

Click Actions

NpcPlugin lets you build action chains that run when players click an NPC.

Editor tips

• Remove an action: middle-click an existing action
• Add actions quickly: shift-click an action type to append it
• Reorder / insert: pick up an action type onto your cursor and click a slot

Action types

---

Variables & expressions

Some action types (and parts of the editor) accept expressions.

NpcPlugin supports numeric variables using $...:

• $<name>
  • Searches variables in this order:
    • local
    • instance
    • global
• $local.<name>
• $instance.<name>
• $global.<name>

If a variable is missing or cannot be read, it is treated as 0.

Always-available variables

These variables exist for every click-action execution (they do not require SetVariable):

• $self.rightClick / $self.right_click
  • 1 if the current action execution was triggered by a right click, else 0
• $self.leftClick / $self.left_click
  • 1 if the current action execution was triggered by a left click, else 0
• $self.sneaking
  • 1 if the player is sneaking, else 0
• $self.flying
  • 1 if the player is sneaking, else 0
• $self.op
  • 1 if the player is sneaking, else 0
• $loop.index
  • Current loop index (only meaningful inside Loop actions)

---

Command

Runs a command as the clicking player.

• Input can be with or without leading / (stored as /...)

• Supports variables/expressions via the action system (see SetVariable + expressions)

• Replaces placeholders:

• {player} / %player% / <player>

• {player_name} / %player_name% / <player_name>

If command-checking is enabled, the editor validates syntax before saving.

Examples:

msg {player} Hello!
msg {player} You have $coins coins

---

Server

Sends the clicking player to a BungeeCord server.

• Uses the BungeeCord plugin message channel
• The stored server name can also contain variables

---

Wait

Pauses the chain before continuing.

You can switch between two modes in the editor:

Time mode

• Left/Right click to adjust the time
• Shift+Left/Shift+Right for bigger steps
• Range is clamped (min 0.05s, max 600s)

Command mode

Instead of waiting for time, the chain waits until a command is triggered:

• Wait stores a name (string)
• The chain continues only after an admin runs:

/npc wait <player> <name> [values...]

If [values...] are provided, they are exposed to the next actions as local variables:

• <name>[0], <name>[1], ... (numeric values; invalid numbers become 0.0)

DialogMenu / clickable-text trigger (custom action)

In addition to /npc wait ..., the wait can also be resumed via custom clickable actions.

NpcPlugin registers a handler for custom click actions with the namespace npc:

• Action id: npc:<name>
• Payload: JSON object

All JSON entries that are numeric are mapped to variables for the next actions:

• <name>[<jsonKey>] = <jsonValue>

Example (conceptual):

• Wait action name: minigame
• Click action id: npc:minigame
• Payload:

{
  "players": 3,
  "max_players": 12
}

This will resume the chain and make the following variables available:

• $minigame[players] = 3
• $minigame[max_players] = 12

Example Command:

/tellraw @p {"click_event":{"action":"custom","id":"npc:minigame","payload":{"players":3,"max_players":12}},"text":"Test"}

---

Animation

Plays an animation on the NPC for the clicking player.

• Left click: next animation
• Right click: previous animation

---

Path

Makes the NPC walk along a saved path.

Configuration:

• Path name (must exist; must be in the same world)
• Speed (0.01 to 1.0)
• For all: if enabled, all viewers see the NPC walking
• Change real location: if enabled, the NPC’s real location is updated while walking

When the path finishes, the chain continues automatically.

---

SetVariable

Sets a numeric variable.

Configuration:

• Type:
  • Local: stored per-player (PersistentDataContainer)
  • Instance: stored on the NPC (custom data)
  • Global: stored server-wide (saved to global-variables.yml)
• Name: must match ^[a-zA-Z_][a-zA-Z0-9_]*$
• Value: an expression

If the value is missing, the action does nothing (admins get a warning).

Examples:

Example: give a player 10 coins (global)

• Type: Global
• Name: coins
• Value:

$global.coins + 10

Example: store a per-player "times clicked" counter (local)

• Type: Local
• Name: clicks
• Value:

$local.clicks + 1

Then you can use it in commands:

msg {player} Clicks: $local.clicks

---

Condition

Runs a sub-chain only if its expression is true.

• You edit the sub-chain like a normal action list
• The condition expression is edited via the "value" item

Examples:

Example: only run if the player is sneaking

Condition value:

$self.sneaking == 1

Sub-chain example:

Command: msg {player} You are sneaking!

Example: require at least 100 global coins

Condition value:

$global.coins >= 100

Sub-chain example:

Command: msg {player} You have enough coins.

---

Loop

Repeats a sub-chain.

There are two loop types:

While-loop

• Repeats while the expression is true

For-loop

• Repeats with an integer loop index
• Configurable values:
  • Start (optional; default 0)
  • End (required)
  • Step (optional; default 1)

You can change the loop type by Shift-clicking the action.

Examples:

Example: run a sub-chain 5 times (for-loop)

• End value:

4

Sub-chain example (index is available as $loop.index):

Command: msg {player} Loop index: $loop.index

---

Npc

Opens a special editor that lets you apply NPC options as an action.

This is mainly used to change how the NPC looks/behaves for:

• Only the clicking player (per-player override)
• Everyone (global)

Two flags exist:

• Change globally: applies the configured options to the NPC’s global options
• Reset to default: removes per-player overrides and resets to the NPC’s defaults

---

Stop

Stops the current chain immediately (and stops nested chains too).

---

Run-on-show

In the action editor you can enable Run on show.

If enabled, the chain triggers when the NPC is shown to a player (not only when clicked).