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.

Current condition types:

• scoreboard condition
• execution limit condition

Use cases:

• only run an action if coins >= 10
• let a reward happen only once
• 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.