💬 Dialogues

Dialogues let EventForge play simple NPC-style text sequences for players.

They are useful for:

quest-style events
tutorials
relic hunts
NPC task chains
story events
custom objective addons

info

EventForge provides the dialogue engine, not the NPC entity itself. You must install the relevant plugin.

You can use dialogues with Citizens, FancyNpcs, vanilla mobs, custom entities, or your own addon logic if something triggers the dialogue.

Basic structure

Dialogues are configured inside an event file:

dialogues:
  guide_intro:
    npc-id: "guide"
    display-name: "Guide Introduction"
    cancel-existing: true
    lines:
      - speaker: "&eGuide"
        text: "&fHello {player}."
        title: "&eGuide"
        subtitle: "&fWelcome."
        sound: ENTITY_VILLAGER_AMBIENT
        delay: 3

The dialogue ID in this example is:

guide_intro

Simple line format

For quick dialogues, you can use a simple list of text lines:

dialogues:
  guide_intro:
    lines:
      - "&eGuide: &fHello there!"
      - "&eGuide: &fBring me 5 relics."

This is the easiest format for small events.

Detailed line format

For more control, use detailed dialogue lines:

dialogues:
  guide_intro:
    npc-id: "guide"
    display-name: "Guide Introduction"
    cancel-existing: true
    lines:
      - speaker: "&eGuide"
        text: "&fWelcome to the ruins, {player}."
        title: "&eGuide"
        subtitle: "&fSearch for ancient relics."
        sound: ENTITY_VILLAGER_AMBIENT
        delay: 3

      - speaker: "&eGuide"
        text: "&fInteract with relic blocks to earn points."
        sound: ENTITY_EXPERIENCE_ORB_PICKUP
        delay: 3

Dialogue settings

Setting	Description
`npc-id`	Optional ID for the NPC or source of the dialogue
`display-name`	Friendly name for the dialogue
`cancel-existing`	Whether to replace the player's current dialogue
`lines`	Dialogue lines to play
`complete-commands`	Console commands to run after the dialogue finishes

Line settings

Setting	Description
`speaker`	Name shown before the line
`text`	Chat text sent to the player
`title`	Optional title
`subtitle`	Optional subtitle
`sound`	Optional Bukkit sound
`delay`	Delay before the next line

Completion commands

You can run commands when a dialogue finishes naturally.

dialogues:
  guide_intro:
    display-name: "Guide Introduction"
    lines:
      - "&eGuide: &fGood luck, {player}!"

    complete-commands:
      - "say {player} completed {dialogue_display}."

Commands run from console.

Do not include / at the start.

Placeholders

Dialogues support these placeholders:

Placeholder	Description
`{player}`	Player name
`{uuid}`	Player UUID
`{dialogue}`	Dialogue ID
`{dialogue_display}`	Dialogue display name
`{npc}`	NPC ID
`{event}`	Event ID
`{event_display}`	Event display name
`{var:key}`	Event variable

Example:

variables:
  guide_name: "&eRelic Guide"
  arena_name: "Spawn Ruins"

dialogues:
  guide_intro:
    npc-id: "relic_guide"
    display-name: "{var:guide_name} Introduction"
    lines:
      - speaker: "{var:guide_name}"
        text: "&fWelcome to {var:arena_name}, {player}."

Full example

id: relic_hunt
enabled: true
display-name: "{var:event_color}Relic Hunt"
duration: 5m

variables:
  event_color: "&6"
  guide_name: "&eRelic Guide"
  arena_name: "Spawn Ruins"

dialogues:
  guide_intro:
    npc-id: "relic_guide"
    display-name: "{var:guide_name} Introduction"
    cancel-existing: true
    lines:
      - speaker: "{var:guide_name}"
        text: "&fWelcome to {var:arena_name}, {player}. Ancient relics are hidden nearby."
        title: "{var:event_color}Relic Hunt"
        subtitle: "&fSearch the ruins for clues."
        sound: ENTITY_VILLAGER_AMBIENT
        delay: 3

      - speaker: "{var:guide_name}"
        text: "&fInteract with ancient blocks and recover fragments to earn points."
        sound: ENTITY_EXPERIENCE_ORB_PICKUP
        delay: 3

    complete-commands:
      - "say {player} has completed the {dialogue_display} dialogue."

How dialogues are started

Dialogues are usually started by an addon, Skript, or custom objective.

For example:

A player clicks an NPC
A player enters a relic area
A player starts a quest
A custom objective reaches a task step

EventForge does not force you to use one NPC plugin.

Using with the Skript addon

If you use EventForgeSkriptAddon, you can start a dialogue from Skript:

start eventforge dialogue "guide_intro" of event "relic_hunt" for player

You can cancel it with:

cancel eventforge dialogue for player

And check whether a player is already in a dialogue:

player player is in eventforge dialogue

Behaviour

dialogue lines play in order
each line can have its own delay
chat text is supported
titles and subtitles are supported
sounds are supported
completion commands run from console
dialogues are cancelled when the player quits
an existing dialogue can be cancelled/replaced

Troubleshooting

Dialogue does not start

Check:

The event is loaded
The dialogue ID is correct
The addon/Skript/objective is actually starting it
The player is online

Sound does not play

Check that the sound name is a valid Bukkit sound.

Example:

sound: ENTITY_VILLAGER_AMBIENT

Completion command does not run

Check:

The dialogue finishes naturally
The command works from console
The command does not start with /

Placeholders do not parse

Check that the placeholder is supported in dialogues.

For event variables, make sure the event has:

variables:
  arena_name: "Spawn Ruins"

Then use:

{var:arena_name}