Skip to content

Dialogue and interaction modes

Set Interaction mode in the NPC editor to choose its normal right-click behavior.

Value Behavior
battle Start the trainer battle, subject to its battle rules.
dialog Open the highest-priority eligible dialogue.
trade Open the shop.
heal Heal the interacting player's Pokémon party.
actions Run interaction actions without opening a default screen.
none Disable configured interaction actions and the normal interaction response.

Configured interact actions run before the normal response in modes other than none. Avoid combining an action that opens a screen with a conflicting normal response. For an NPC controlled entirely by actions, choose actions.

A two-page conversation

The following is a partial trainer preset. Merge these properties into an existing preset; this is not a complete trainer/team definition. The editor exposes the same data in its dialogue list.

{
  "interaction_mode": "dialog",
  "dialogs": [
    {
      "id": "welcome",
      "priority": 0,
      "title": "Village Guide",
      "pages": [
        "<gold>Welcome, %player%!</gold>",
        "Would you like your Pokémon healed?"
      ],
      "allow_esc_close": true,
      "buttons": [
        {
          "id": "welcome-heal",
          "label": "<green>Heal my party</green>",
          "type": "action",
          "actions": [
            {"id": "heal-party", "type": "heal"}
          ]
        },
        {"id": "welcome-leave", "label": "Goodbye", "type": "close"}
      ]
    }
  ]
}

Players advance through pages before reaching the response buttons on the last page. A button with type action closes the current conversation and runs its actions; a dialog action can open the next conversation. Type close only leaves the dialogue.

A dialogue with no response buttons receives a built-in Close response. Keep a reachable exit if you disable Escape. Dialogue rendering uses Cobblemon's native dialogue system.

Selection and restrictions

When opening a dialogue automatically, GreatNPC chooses the eligible entry with the highest priority. Its conditions must all pass. If none qualifies, the built-in conversation is used. A dialog action can target an explicit id; explicit selection does not use the automatic priority/condition selection. Put important restrictions on the button/action itself as well.

A button supports:

Property Meaning
conditions Requirements checked before the button is usable.
hide_when_locked Hide an unavailable button rather than showing it locked.
limit Uses allowed per player on that NPC; 0 means unlimited.
actions Operations to run when clicked.

Use stable, unique IDs for dialogues, buttons and actions. Usage counters refer to IDs; renaming an ID can give players a fresh counter.

Formatting and placeholders

Custom pages, titles and labels use GreatNPC's MiniMessage-style formatting parser. Examples include <gold>, <green> and <bold>. This is the mod's parser, not a guarantee of support for every Adventure MiniMessage tag.

Supported interaction substitutions include %player%, %npc%, %trainer%, %x%, %y%, %z% and %uuid%. %uuid% is the interacting player's UUID; coordinates refer to the NPC.

The preset uses arrays named dialogs, actions and trades. The NPC's internal/editor variable representation stores their serialized lists as dialogs_json, actions_json and trades_json. Do not substitute those variable names for the arrays in a trainer preset.

Continue with actions and events, conditions or trading.