Actions 🎮

Actions make NPCs interactive. They can run commands, open dialogs, open trading, interact with blocks, or update scoreboards.

Typical examples:

• /say Hello, @initiator
• /give @initiator stone
• /scoreboard players add @initiator coins 1
• /easy_npc dialog open @npc @initiator default

Default permissions limit what an NPC may do. If you use command actions on servers, also read Permissions.

Action Lists 📋

Each action list can contain multiple entries. Actions run from top to bottom in the listed order.

Action Types ⚙️

The current action types are:

• Command
• Close Dialog
• Interact Block
• Open Trading
• Open Default Dialog
• Open Dialog
• Scoreboard

Command

Command actions are the most flexible option. Use them for rewards, messages, scripted events, or integration with other mods.

• Leave Execute as player disabled if the command should run as the NPC
• Enable it only when the command must run in the interacting player's context
• Commands executed as player must be explicitly allowlisted by the server
• The effective command authority is still capped by the NPC's stored command level

Close Dialog

Closes the currently open dialog screen.

Interact Block

Makes the NPC trigger a block interaction at a target position.

Open Trading

Opens the NPC trading screen.

Open Default Dialog

Opens the default dialog for the NPC.

Open Dialog

Opens a named dialog entry by label.

Scoreboard

Scoreboard actions change a value for the interacting player. This is useful for quests, shop progress, currencies, unlock flags, or counters.

Supported operations:

• increase
• decrease
• set

Format:

operation:scoreboard_name:value

Examples:

• increase:coins:5
• decrease:reputation:1
• set:quest_stage:3

Action Events 🧭

Actions can be attached to different events.

Basic Events

• On Interaction
• On Hurt
• On Death
• On Kill
• On Trade

On Trade runs after a successful purchase. Use it when every completed trade should trigger the same logic.

Dialog Events

• On Open Dialog
• On Close Dialog
• On Button Click

Distance Events

• Near
• Close
• Very Close
• In Touch

These actions trigger once when a player enters the matching range, and can trigger again after the player leaves and returns.

Trade Actions vs On Trade 🛒

Trade-related logic can be attached in two different places:

• On Trade for logic that should run after every successful trade
• per-offer trade actions in Trading for logic that should run only for one specific offer

Use On Trade for generic shop behavior, for example:

• add one global purchase counter
• play the same reward command for all offers

Use per-offer trade actions when individual offers should behave differently, for example:

• rare item gives a bonus
• quest item advances a quest stage
• one special offer opens a follow-up dialog

Conditions 🎯

Actions can also have conditions. An action only runs if all of its conditions match (AND logic). For OR behavior, split the logic across several actions, each with its own condition.

Open the condition editor from the action editor via the Conditions button.

Available condition types:

Condition	Checks
Scoreboard	A scoreboard objective compared against a value (e.g. coins >= 10)
Execution limit	How often the action may run per player (per minute/hour/day/...)
Has item in inventory	The player carries an item, optionally a minimum quantity
Has item in hand	The player holds an item in the main/off hand, optionally a minimum quantity
Advancement	The player has completed an advancement
Experience level	The player's XP level compared against a value
Player health	The player's health percentage compared against a value
Player tag	The player has a scoreboard tag
Team	The player is a member of a team
Game mode	The player is in a specific game mode
Fallback	Runs only if no other action in the set executed

Most condition types support a negated comparison (NOT_EQUALS) so you can also require that the player does not meet a condition.

Item quantities

Has item in inventory and Has item in hand default to a quantity of 1. Set a higher number to require more, e.g. 10 diamonds. A quantity of 0 or 1 both mean "at least one". For the inventory check the count is summed across all matching stacks.

Use cases:

• only run an action if coins >= 10
• only trade if the player holds at least 10 diamonds
• let a reward happen only once (execution limit)
• unlock a dialog button after a scoreboard milestone

Placeholders 🧩

These placeholders are available in actions:

Placeholder	Description
@npc	NPC name
@npc-uuid	NPC UUID
@initiator	Player name
@initiator-uuid	Player UUID

Practical Examples 💡

Some useful patterns:

• NPC shopkeeper: On Trade adds a global customer score
• quest merchant: per-offer action updates quest_stage
• teleport guide: dialog button runs a command action
• warning NPC: distance action fires once when the player gets close

Default Interaction Actions ⭐

New NPCs can start with default interaction behavior. If dialog or trading is configured, the NPC may already contain:

• Open Default Dialog
• Open Trading

You can keep, reorder, or remove these actions in the normal action editor.