Actions 🎮

Make your NPC more interactive with powerful actions. Here are some basic examples:

• /say Hello, ... 👋
• /give @initiator stone 🎁
• /scoreboard players add @initiator close 5 📊
• /tp @initiator -28 63 399 🚀

Default permissions limit certain actions, so regular players can't use commands like /give or /tp. Actions can be triggered by specific events such as interacting with a player, NPC getting hurt, NPC dying, player getting close to the NPC, or even opening and closing dialogs.

Action List 📜

You can set up multiple actions for an event or a dialog button. Actions are performed in the order you list them.

You can change the order by using the up and down buttons.

Action Entry 🛠️

Each action has options to customize how it works.

Action Type

The action type decides what the action will do. For example, the command action lets you define the command and who it targets.

Command

Run a command with a specified target.

• Check Execute as player to run commands using the player's permission level.
• Turn on Debug to get insights into errors and more while testing.

Close Dialog

Close the dialog screen after the action is completed.

Interact Block

Trigger an interaction with a block from the NPC.

Open Trading Screen

Open the trading screen for the NPC.

Open Default Dialog

Open the default dialog for the NPC.

Open Named Dialog

Open a specific dialog for the NPC, the dialog name will be validated.

Scoreboard

✨ Since Version 6.2.0

Modify scoreboard values for the interacting player. This action allows you to increase, decrease, or set scoreboard values.

Operations:

• Increase - Add value to scoreboard
• Decrease - Subtract value from scoreboard
• Set - Set scoreboard to specific value

Format: operation:scoreboardName:value

Examples:

• increase:player_score:10 - Adds 10 to player_score
• decrease:health_points:5 - Subtracts 5 from health_points
• set:quest_progress:100 - Sets quest_progress to 100

You can use this with dialogs to track quest progress, player stats, currency systems, and more!

➡️ See Dialog Macros for displaying scoreboard values in dialogs using @score(...).

Action Placeholders 🧩

You can use placeholders in actions for a personal touch:

Placeholder	Description
@npc	Name of the NPC
@npc-uuid	UUID of the NPC
@initiator	Name of the player who started the dialog
@initiator-uuid	UUID of the player who started the dialog

Dialog Macros 🔮

✨ Since Version 6.2.0

Special macros for use in dialogs:

Macro	Description	Example
@score(scoreboard_name)	Display scoreboard value	You have @score(coins) coins

The @score() macro allows you to display scoreboard values directly in dialog text, making it easy to show players their progress, currency, stats, etc.

Example Usage:

Dialog text: "Hello @initiator! You have collected @score(quest_items) items and have @score(player_coins) coins."

This will display the actual scoreboard values for that player in the dialog.

NPC-Specific Commands 🤖

Use NPC-specific commands for more advanced actions. For example, you can open a trading screen during a dialog, open a specific dialog, or interact with a block.

Examples:

• /easy_npc trading open @npc
• /easy_npc dialog open @npc @initiator <dialog-name>
• /easy_npc interact block @npc-uuid ~1 ~1 ~

Action Types 🚀

Explore the different types of actions you can set up for your NPC:

Basic Actions 🔄

Set up basic actions like player interaction, NPC getting hurt, or NPC dying.

Available events:

• On Interaction - When a player interacts with the NPC
• On Hurt - When the NPC takes damage
• On Death - When the NPC dies
• On Kill ✨ (Since Version 6.5.1) - When the NPC kills another entity

The On Kill event triggers when the NPC successfully kills another entity, allowing you to create rewards, achievements, or consequences for NPC combat actions.

Dialog Actions 💬

Define actions for dialog entries, like opening or closing the dialog screen, or clicking on a dialog button.

Available events:

• On Open Dialog - When a dialog is opened
• On Close Dialog - When a dialog is closed
• On Button Click - When a dialog button is clicked

Distance Actions 📏

Trigger actions based on how close the player is:

• Near (within 16 Blocks)
• Close (within 8 Blocks)
• Very Close (within 4 Blocks)
• In Touch (within 1 Block)

Actions trigger once when in range, but can reset and trigger again if the player leaves and re-enters.

Action Conditions 🎯

✨ Since Version 6.3.0

You can now add conditions to actions, making them execute only when specific requirements are met!

Available Condition Types

Scoreboard Condition

Check if a player's scoreboard value meets certain criteria.

Operations:

• EQUALS - Value must equal the specified amount
• GREATER_THAN - Value must be greater than the specified amount
• LESS_THAN - Value must be less than the specified amount
• GREATER_OR_EQUALS - Value must be greater than or equal to
• LESS_OR_EQUALS - Value must be less than or equal to

Example Use Cases:

• Only show a dialog if the player has enough currency: coins >= 100
• Give a reward only if quest progress is complete: quest_stage == 5
• Block access if reputation is too low: reputation > 0

Execution Limit Condition

✨ Since Version 6.3.0

Limit how many times an action can execute.

Example: An action that only triggers 3 times total, perfect for:

• One-time or limited rewards
• Tutorial messages that shouldn't spam
• Special events that can only occur a few times

Using Conditions

In the action editor:

1. Create your action (command, dialog, etc.)
2. Click "Add Condition"
3. Select condition type (Scoreboard or Execution Limit)
4. Configure the condition parameters
5. Save

Actions with conditions will only execute when ALL conditions are met.

Default Interaction Actions 🎯

When players interact with an NPC, it automatically includes the Open Default Dialog and Open Trading actions by default.

These actions will only be triggered if a dialog or trading screen is set up for the NPC. If you prefer not to use these default actions, you can easily remove them under Actions -> Basic Actions -> On Interaction They are only added when the NPC is first spawned and won't be re-added once removed.