Dialogue

📍 File Locations

All NPCs and dialogues are defined using JSON files, located in the following folders (these are created automatically when the server is started with the mod installed):

Required folder structure

config/
└── CobbleBetterNPC/
    ├── NPC/                 ← NPC JSON Files
    └── Dialogues/           ← JSON dialog files

These folders are automatically generated when the server starts. No restart is necessary: ​​use /cbn reload to apply the changes.

🧱 Basic structure of a dialogue-type NPC

Dialog-type NPCs are those that, when interacted with, display a dialog interface with options (as in the main Pokémon games).

This type is the most common and versatile.

Minimum required structure

config/
└── CobbleBetterNPC/NPC/nurse_joy_dialogue.json      

{
  "id": "cobblebetternpc:nurse_joy_001",
  "type": "dialogue",
  "resourceIdentifier": "cobblemon:standard",
  "names": ["Enfermera Joy"],
   "interaction": [
    {
      "name": "dialogue one",
      "with": "1",
      "permission": "",
      "dialogue": "cobblebetternpc:nurse_joy_dialogue"
    }
  ]
}

Field	Description	Example
id	Unique identifier for the NPC. Must be a valid identifier (namespace:path). Must never be repeated between NPCs. Used as a key to prevent merges.	"id": "cobblebetternpc:joy_001",
type	"dialogue" for this flow. Define which interaction will be used (DialogueInteraction).	"type": "dialogue",
resourceIdentifier	Define the base type; it can be a Pokemon or an NPC.	"cobblemon:standard" "cobblemon:pikachu"
names	Names that rotate around the NPC (in the name tag).	"names": ["Nurse Joy"],
interaction	Each object defines a visible option when interacting.	name, with, permission and dialogue

Below is an explanation of how each section of the interactions works.

name

• The name is simply a guide; it doesn't matter what you write in it.

  "interaction": [
    {
      "name": "dialogue one",
      "with": "1",
      "permission": "",
      "dialogue": "cobblebetternpc:nurse_joy_dialogue"
    }
  ]

with

• "with" the priority in which the dialogues will be shown.

You can use it however you want, but...

How is it recommended to use it?

We can do it hierarchically:

• Dialogue one will be the first dialogue the player sees, so there always has to be at least one dialogue without permissions. This will be granted to us by the same NPC or another method.

• Dialogue two will be the second menu the player sees, requiring user.1 permission. This same dialogue, or another method, will grant user.2 permission.

• Dialogue three will be the last one the player sees, requiring user.2 permission. Since it has the "with 1" attribute, it will be the first one checked. However, because we didn't have user.2 permission before, it wasn't displayed until we obtained it.

  "interaction": [
    {
      "name": "dialogue three",
      "with": "1",
      "permission": "user.2",
      "dialogue": "cobblebetternpc:nurse_joy_dialogue_3"
    }, 
	{
      "name": "dialogue two",
      "with": "2",
      "permission": "user.1",
      "dialogue": "cobblebetternpc:nurse_joy_dialogue_2"
    },
    {
      "name": "dialogue one",
      "with": "3",
      "permission": "",
      "dialogue": "cobblebetternpc:nurse_joy_dialogue"
    }
  ]

permission

• Permission node (requires LuckPerms). Only visible if the player has it.

  "interaction": [
    {
      "name": "dialogue one",
      "with": "1",
      "permission": "obblebetternpc.staff",
      "dialogue": "cobblebetternpc:nurse_joy_dialogue"
    }
  ]

dialogue

• Dialogue ID (without .json), relative to Dialogues/.

config/
└── CobbleBetterNPC/              
    └── Dialogues/nurse_joy_dialogue.json

  "interaction": [
    {
      "name": "dialogue one",
      "with": "1",
      "permission": "",
      "dialogue": "cobblebetternpc:nurse_joy_dialogue"
    }
  ]

💬 Dialog file (builder format)

config/
└── CobbleBetterNPC/Dialogues/nurse_joy_dialogue

{
  "name": "Nurse Joy",
  "dialogue": [],
  "actions": {}
}

Field	Description	Example
name	Name that appears in the NPC box (above the text).	"name": "Nurse Joy",

{
  "name": "",
  "dialogue": [
    "[page1] npc: Welcome to the Pokémon Center!",
    "[page2] npc: Hello {username}! I'm Nurse Joy. Would you like me to heal your Pokémon?",
    "player -> Yes, please heal my Pokémon!: npc-heal",
    "player -> No, thank you.: npc-declined",
    "[npc-heal] npc: Of course! Let me take your Pokémon for a moment...",
    "auto: close",
    "[npc-declined] npc: Alright! Come back anytime if your Pokémon need rest.",
    "auto: close",
    "quitter: Take care!"
  ],
  "actions": {
    "npc-heal": [
      "set_page('npc-heal')",
      "run_command('pokeheal ' + {username})"
    ],
    "npc-declined": [
      "set_page('npc-declined')"
    ],
    "close": [
      "q.dialogue.close()"
    ]
  }
}

STEP BY STEP

How are pages defined?

• Definition of a page: [id] speaker: text

"[id] speaker: línea 1",
"línea 2",
"línea 3"

[id]: The id is just an identifier; you can use whichever one you want. speaker: npc/player

   ───────────────────────────────────────────────────────
           🔹 PAGE 1: Introductory text
   ───────────────────────────────────────────────────────
     • `[page1]` define a new page ID: "page1"
     • `npc:` indicates that the speaker is the NPC (will use the name "Nurse Joy")
     • The text is displayed on a single line.
     • All subsequent lines belong to this same page,
       until an ID change or button appears.

  "dialogue": [
    "[page1] npc: Welcome to the Pokémon Center!"
  ]

   ───────────────────────────────────────────────────────
                  🔹 PAGE 2: Continued
   ───────────────────────────────────────────────────────
     • `[page2]` Start a new page with ID "page2"
     • `npc:` he remains the speaker
     • `{username}` is automatically replaced by the players name

"dialogue": [
    "[page1] npc: Welcome to the Pokémon Center!",
    "[page2] npc: Hello {username}! I'm Nurse Joy. Would you like me",
    "to heal your Pokémon?"
  ]

Interactive options (buttons)

• Definition of a button: speaker -> button_text: action

Key rule

Buttons will always be displayed on the page that has them defined above.

     ───────────────────────────────────────────────────────
            🔹 BUTTON 1: Interactive button ("Yes")
     ───────────────────────────────────────────────────────
     • `player -> ...` simulates a replica of the player.
     • The button text will be: **"Yes, please heal my Pokémon!"**
     • Clicking executes the action defined in the action. `npc-heal`
       → Since `actions.npc-heal` exists, its commands are executed 
       and the page opens.

  "dialogue": [
    "[page1] npc: Welcome to the Pokémon Center!",
    "[page2] npc: Hello {username}! I'm Nurse Joy. Would you like me",
    "to heal your Pokémon?",
    "player -> Yes, please heal my Pokémon!: npc-heal"
    "[npc-heal] npc: Of course! Let me take your Pokémon for a moment...",
    "auto: close",
  ],
  "actions": {
    "npc-heal": [
      "set_page('npc-heal')",
      "run_command('pokeheal ' + {username})"
    ]
  }

     ───────────────────────────────────────────────────────
        🔹 Page npc-heal: Result after choosing "Yes"
     ───────────────────────────────────────────────────────
     • `[npc-heal]` define a new page with ID "npc-heal"
     • No options → the system will look for "auto:" next.
      At the end of each button or page there must be an "auto" 
      to automatically close.

     ───────────────────────────────────────────────────────
           🔹 BUTTON 2: Interactive button ("No")
     ───────────────────────────────────────────────────────
     • Similar to the previous one, but executes `npc-declined`.

  "dialogue": [
    "[page1] npc: Welcome to the Pokémon Center!",
    "[page2] npc: Hello {username}! I'm Nurse Joy. Would you like me to heal your Pokémon?",
    "player -> Yes, please heal my Pokémon!: npc-heal",
    "player -> No, thank you.: npc-declined",
    "[npc-heal] npc: Of course! Let me take your Pokémon for a moment...",
    "auto: close",
    "[npc-declined] npc: Alright! Come back anytime if your Pokémon need rest.",
    "auto: close",
    "quitter: Take care!"
  ],
  "actions": {
    "close": [
      "q.dialogue.close()"
    ],
    "npc-heal": [
      "set_page('npc-heal')",
      "run_command('pokeheal ' + {username})"
    ],
    "npc-declined": [
      "set_page('npc-declined')"
    ]
  }

    // ───────────────────────────────────────────────────────
    // 🔹 `quitter:` → Special page when pressing ESC
    // ───────────────────────────────────────────────────────
    // • Define the hidden page with `id: "quitter"`
    // • It is only shown if the player escapes.
    // • Message: "Take care!"

   ─────────────────────────────────────────────────────────
          🔹 `actions`: Executable logic
   ─────────────────────────────────────────────────────────
  "actions": {
    // • Generic action to close (implicitly used by `auto: close`).
    "close": [
      "q.dialogue.close()"
    ],

    // • Action performed when pressing "Yes":
    //   1. `set_page('npc-heal')` → Jump to the page with ID "npc-heal".
    //   2. `run_command('pokeheal ' + {username})` → executes `/pokeheal <jugador>`.
    //      (translates to: `q.run_command('pokeheal ' + q.player.username);`)
    "npc-heal": [
      "set_page('npc-heal')",
      "run_command('pokeheal {username}')"
    ],

    // • Action performed when pressing "No":
    //   Just jump to the "npc-declined" page (the message is displayed there).
    "npc-declined": [
      "set_page('npc-declined')"
    ]
  }

config/
└── CobbleBetterNPC/
    ├── NPC/nurse_joy_dialogue.json
    └── Dialogues/nurse_joy_dialogue.json

✔️ Full Example Dialogue

{
  "name": "Nurse Joy",
  "dialogue": [
    "[page1] npc: Welcome to the Pokémon Center!",
    "[page2] npc: Hello {username}! I'm Nurse Joy. Would you like me to heal your Pokémon?",
    "player -> Yes, please heal my Pokémon!: npc-heal",
    "player -> No, thank you.: npc-declined",
    "[npc-heal] npc: Of course! Let me take your Pokémon for a moment...",
    "auto: close",
    "[npc-declined] npc: Alright! Come back anytime if your Pokémon need rest.",
    "auto: close",
    "quitter: Take care!"
  ],
  "actions": {
    "close": [
      "q.dialogue.close()"
    ],
    "npc-heal": [
      "set_page('npc-heal')",
      "run_command('pokeheal ' + {username})"
    ],
    "npc-declined": [
      "set_page('npc-declined')"
    ]
  }
}

✔️ Full Example NPC

{
  "id": "cobblebetternpc:nurse_joy_001",
  "type": "dialogue",
  "resourceIdentifier": "cobblemon:standard",
  "names": ["Nurse Joy"],
  "interaction": [
    {
      "name": "dialogue one",
      "with": "1",
      "permission": "",
      "dialogue": "cobblebetternpc:nurse_joy_dialogue"
    }
  ]
}