Skip to content

Actions and events

Actions connect NPC interactions to messages, commands, battles, shops and other operations. Edit them in the NPC editor's action list.

Events

Event Trigger
interact A normal interaction with the NPC.
battle_start A trainer battle starts.
battle_win The player wins against the NPC.
battle_lose The player loses to the NPC.
dialog_open A dialogue opens.
dialog_close A dialogue closes.
trade A trade completes.
proximity A player enters the action's radius.

battle_win and battle_lose are from the player's perspective. For dialogue/trade events, filter can restrict the action to a particular dialogue or offer ID. Blank means any ID.

Proximity checks run periodically, not continuously. radius is measured in blocks and has a minimum of one. A player must leave beyond the radius plus a small margin before entering again can trigger the same action.

Action types

type value extra
message Chat message Unused
actionbar Action bar message Unused
title Title Optional subtitle
command Command, normally without / Unused
sound Namespaced sound ID Volume and pitch, such as 1 1
animation Animation ID understood by the NPC Unused
dialog Dialogue ID; blank selects automatically Unused
trade Unused Unused
close Unused Unused
battle Unused Unused
heal Unused Unused
tag_add Player command tag Unused
tag_remove Player command tag Unused
give Item ID Quantity as a string, such as 3

Commands run as the server by default. With as_player: true, they run from the player's command source. level: 0 preserves that player's permission level; 1 through 4 explicitly set the execution level. Only grant command-editing access to trusted administrators.

Custom messages accept the formatting and placeholders used by interactions. Command placeholders are substituted before the command is executed.

A one-time greeting

This partial preset greets each player once per NPC, then tags them.

{
  "interaction_mode": "actions",
  "actions": [
    {
      "id": "first-greeting",
      "event": "interact",
      "type": "message",
      "value": "<gold>Hello, %player%!</gold>",
      "limit": 1
    },
    {
      "id": "mark-visitor",
      "event": "interact",
      "type": "tag_add",
      "value": "village_visitor"
    }
  ]
}

Delays, conditions and limits

Each action can have conditions, limit and delay_ticks. Conditions must all pass. A positive limit is tracked per player, NPC and action ID; 0 is unlimited.

delay_ticks: 20 schedules roughly one second later. The current implementation schedules using elapsed time in 50 ms units, so it is not a strict server-tick timer under lag. Conditions and usage limits are checked when scheduling, not again when the delayed action executes. Delayed actions require the player to be online and the NPC to be loaded when they become due; they are not a persistent job queue.

A command failing does not roll back previously executed actions or a consumed action limit. Keep consequential command sequences small and test them on a disposable NPC first.