Dialogue

This guide explains how to create a Dialogue NPC, how the dialogue system works internally, and how NPC behaviours affect appearance and behavior in the world.

The goal of this document is not only to show what to write, but to explain why each field exists and what problem it solves.

All examples shown below are real, tested, and working.

---

📁 Required Folder Structure

config/
└── CobbleBetterNPC/
    ├── NPC/
    │   └── dialogues/
    │       └── dialogue_001.json
    └── Dialogues/
        └── dialogues/
            └── dialogue_001.json

📌 Why two different folders?

CobbleBetterNPC separates responsibilities:

Folder	Purpose
NPC/	Defines the NPC entity (appearance, behaviors, interactions)
Dialogues/	Defines the conversation logic (text, pages, buttons, actions)

This separation allows:

• Reusing the same dialogue for multiple NPCs

• Editing dialogue text without touching the NPC entity

• Keeping large projects organized and scalable

📌 Creating and reloading files

• Generate example files with:

  /cbn create example dialogue

• Apply changes without restart using:

  /cbn reload

---

🧍 Dialogue NPC File (Entity Definition)

📄 config/CobbleBetterNPC/NPC/dialogues/dialogue_001.json

This file defines the NPC as an entity in the world:

• What type of NPC it is

• How it behaves physically

• What dialogue opens when a player interacts

{
  "id": "cobblebetternpc:dialogues/dialogue_001",
  "type": "dialogue",
  "resourceIdentifier": "cobblemon:standard",
  "names": ["Dialogues"],
  "presets": [""],
  "isMovable": false,
  "canDespawn": false,
  "isInvulnerable": true,
  "isLeashable": false,
  "allowProjectileHits": false,
  "hideNameTag": false,
  "interaction": [
    {
      "name": "dialogue one",
      "with": "1",
      "permission": "",
      "dialogue": "cobblebetternpc:dialogues/dialogue_001"
    }
  ],
  "behaviours": [
    {
      "type": "cobblemon:apply_behaviours",
      "behaviours": [
        "cobblemon:player_textured",
        "cobblemon:looks_at_players",
        "cobblemon:core"
      ]
    },
    {
      "type": "add_variables",
      "variables": [
        {
          "variableName": "player_texture",
          "category": "cobblemon.entity.variable.category.appearance",
          "type": "TEXT",
          "defaultValue": "Feddupp"
        }
      ]
    }
  ]
}

---

🧾 NPC Fields Explained (Line by Line)

🔹 id

"id": "cobblebetternpc:dialogues/dialogue_001"

• Unique identifier for the NPC

• Must never be duplicated

• Used internally to register and reload NPCs

• Recommended format:

  namespace:category/name

---

🔹 type

"type": "dialogue"

• Defines how the NPC reacts to interaction

• "dialogue" means:

  • Right-click opens a dialogue UI

If this is not "dialogue", no dialogue will open.

---

🔹 resourceIdentifier

"resourceIdentifier": "cobblemon:standard"

• Defines the base entity model

• Controls:

  • Model

  • Animations

  • Default hitbox

Examples:

• cobblemon:standard → humanoid NPC

• cobblemon:pikachu → Pokémon NPC

---

🔹 names

"names": ["Dialogues"]

• Name displayed above the NPC

• Supports:

  • Color formatting

• Used purely for presentation

---

🌍 World & Safety Settings

"isMovable": false,
"canDespawn": false,
"isInvulnerable": true,
"isLeashable": false,
"allowProjectileHits": false,
"hideNameTag": false

These fields control how the NPC behaves in the world.

Field	What it does	Why it matters
isMovable	Prevents movement	Keeps NPC in place
canDespawn	Prevents despawn	NPC is permanent
isInvulnerable	No damage	Protects NPC
isLeashable	Cannot be leashed	Prevents griefing
allowProjectileHits	Blocks arrows	Anti-trolling
hideNameTag	Shows name	Player clarity

---

🔁 Interaction – Dialogue Selection Logic

"interaction": [
  {
    "name": "dialogue one",
    "with": "1",
    "permission": "",
    "dialogue": "cobblebetternpc:dialogues/dialogue_001"
  }
]

This section defines which dialogue opens when the player interacts.

Fields explained

Field	Purpose
name	Informational only
with	Priority (lower = checked first)
permission	Required permission (empty = everyone)
dialogue	Dialogue ID (no .json)

📌 Rule: If multiple interactions exist, the system:

1

Step 1

Sorts interactions by with (lowest first).

2

Step 2

Checks permissions for each interaction in order.

3

Step 3

Opens the first valid dialogue found.

---

🤖 Behaviours

Behaviours define how the NPC behaves physically, not what it says.

{
  "type": "cobblemon:apply_behaviours",
  "behaviours": [
    "cobblemon:player_textured",
    "cobblemon:looks_at_players",
    "cobblemon:core"
  ]
}

---

🧑 player_textured

• Applies a player skin to the NPC

• Requires the variable player_texture

{
  "variableName": "player_texture",
  "type": "TEXT",
  "defaultValue": "Feddupp"
}

Use this when:

• Creating human NPCs

• Representing staff or story characters

---

👀 looks_at_players

• NPC rotates its head to look at nearby players

• Improves immersion

• Strongly recommended for dialogue NPCs

---

🧠 core

Provides essential base AI logic.

What it handles

• Orientation

• Behaviour coordination

• Internal ticking

---

💬 Dialogue File (Conversation Logic)

📄 config/CobbleBetterNPC/Dialogues/dialogues/dialogue_001.json

This file defines what is said, what choices appear, and what actions are executed.

{
  "name": "&#B8C4CCDialogue",
  "gibber": {
    "npc": { "step": 3, "interval": 0.02, "allowSkip": true },
    "player": { "step": 3, "interval": 0.02 }
  },
  "dialogue": [
    "[page1] npc: &#A08C7DHello, welcome to the example of the <player> dialogue type NPC!",
    "[page2] player: &#E6C88CThank you so much, this looks great!",
    "[page3] npc: &#8C4B50Do you want a diamond and a farewell message?",
    "player -> &#76B7C4Yes!: npc-reward",
    "player -> &#C476B7No.: npc-declined",
    "[npc-reward] npc: &#A0C87DHere's your diamond, see you later",
    "auto: close",
    "[npc-declined] npc: &#C88C4BWell, I won't give you anything, goodbye..",
    "auto: close",
    "quitter: &#D2C6B8ESC Exit Message!"
  ],
  "actions": {
    "close": ["q.dialogue.close()"],
    "npc-reward": [
      "set_page('npc-reward')",
      "run_command('give ' + <player> + ' minecraft:diamond 1')"
    ],
    "npc-declined": ["set_page('npc-declined')"]
  }
}

---

📄 Pages

Syntax:

[id] speaker: text

Element	Meaning
id	Page identifier
speaker	npc or player
<player>	Automatically replaced

Pages exist to:

• Separate dialogue states

• Allow jumps using set_page

• Support branching conversations

---

🔘 Buttons

Syntax:

player -> Button Text: action_id

Rules:

• Buttons belong to the last page above them

• Clicking a button executes its action

---

⚙️ Actions

Actions are reusable logic blocks.

Common actions:

Action	Purpose
set_page('id')	Jump to a page
run_command(...)	Execute a server command
close	Close dialogue

---

⏩ auto: close

• Automatically closes the dialogue

• Used when a page has no buttons

• Ideal for final informational messages

---

🚪 quitter

quitter: ESC Exit Message

• Message shown only if the player presses ESC

• Does not execute actions

• Used as an exit flavor message

---