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.