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.

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

The current action types are:

• Command
• Close Dialog
• Interact Block
• Open Trading
• Open Default Dialog
• Open Dialog
• Open Dialog (Conditional)
• Scoreboard

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 in config/easy_npc/security.cfg (executeAsUserCommandAllowList.<LEVEL>); list command names only, wildcards are not supported, and a restart is required after editing
• The effective command authority is still capped by the NPC's stored command level
• If a command only needs the player as a target, prefer running it as the NPC with @initiator (for example /tp @initiator …) instead of enabling Execute as player

See Permissions for the full allowlist rules and troubleshooting.

Closes the currently open dialog screen.

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

Opens the NPC trading screen.

Opens the default dialog for the NPC.

Opens a named dialog entry by label, regardless of the conditions defined on the target dialog.

Opens a named dialog entry by label only if all conditions of the target dialog are met for the player; otherwise nothing happens. Use this for dialogs gated by an execution limit (e.g. "max 3 per day"), required items, scores, or other conditions. The unconditional Open Dialog action ignores those conditions, so both options remain available.

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

Actions can be attached to different 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.

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

• 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-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

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/week/month/lifetime)
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 hand, off hand, or either
Advancement	The player has completed an advancement
Experience level	The player's XP level compared against a value
Player health	The player's health in percent compared against a value
NPC health	The NPC's own health in percent compared against a value
Entity health	The health in percent of another entity, addressed by its UUID
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
Time of day	The world time (0-23999) compared against a value
Weather	The current weather is clear, rain, or thunder
Fallback	Runs only if no other action in the set executed

Value-based conditions use an operator: ==, !=, >, >=, <, <=. That also covers the negated case, so you can require that a player does not meet a condition.

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.

Has item in hand can additionally be limited to the main hand, the off hand, or accept either one.

Execution limit counts per player and per action. The duration decides when the counter resets: per minute, hour, day, week, month, or lifetime (never resets).

This is what makes "one reward per day" or "this quest can be started only once" work without any scoreboard setup.

All three health conditions compare a percentage, not absolute hearts, so they keep working when the max health changes:

• Player health - the interacting player, e.g. "only heal below 50%"
• NPC health - the NPC itself, e.g. a different dialog when the guard is wounded
• Entity health - another entity by UUID, e.g. "the boss is below 25%, open the retreat dialog". Copy the UUID from the target NPC's configuration screen.

• Time of day compares the raw world time inside a day. Useful values: 0 sunrise, 6000 noon, 12000 sunset, 18000 midnight. A shop that closes at night is Time of day < 12000.
• Weather matches CLEAR, RAIN, or THUNDER.

Both are evaluated in the dimension the player is in.

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 per day (execution limit)
• unlock a dialog button after a scoreboard milestone
• a merchant that only trades during the day
• a shelter NPC that only invites players in during a thunderstorm

These placeholders are available in actions:

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

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

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.