Dialogs are the main conversation system in Easy NPC. They can be simple text popups, yes/no choices, or larger dialog trees with multiple entries, conditions, and button actions.

These placeholders work in dialog text:

Example:

Hello @initiator, my name is @npc.

Dialog text also supports the @score() macro:

If the scoreboard or value does not exist, the shown value falls back to 0.

Dialog text supports the color and formatting placeholders shown below.

Common examples:

• <red>Warning</red>
• <gold><bold>Quest Complete</bold></gold>
• <gray>Come back later.</gray>

Basic dialog is the fastest setup for short text. It is best for greetings, one-step hints, and simple information screens.

Yes/No dialog adds two buttons with separate actions. It works well for confirmations, quests, shop prompts, or simple branching.

Each button can have its own action list.

Advanced dialog supports multiple entries, multiple text variations, dialog buttons, conditions, and priorities.

If you expand a simpler dialog with extra entries or advanced button logic, it effectively becomes an advanced dialog setup.

The advanced dialog editor lets you manage:

• entry label
• default state
• dialog text
• button list
• conditions
• priority

Only one entry should normally act as the main automatic start point.

Dialog buttons can trigger multiple actions in order. This is where dialogs connect to commands, trading, and follow-up dialogs.

If no actions are defined, the button closes the dialog.

Each dialog button can have its own conditions, set via the Conditions button in the button editor. The same condition types as for actions are available (item, scoreboard, advancement, experience, health, tag, team, game mode, ...), combined with AND logic.

When a button's conditions are not met, the button is disabled and shown with a small lock icon; hovering it explains that the requirements are not yet met. The lock updates live for conditions the client can check itself (held/inventory items, XP level, health), so a "buy" button unlocks the moment the player has enough and re-locks after spending. The server always re-validates the conditions when the button is pressed, so a locked button can never be triggered.

Servers that prefer to hide unavailable buttons instead of locking them can switch this globally in config/easy_npc/dialog_options.cfg:

buttonConditionMode=HIDE

LOCK (default) shows the button greyed out with a lock, HIDE removes it from the dialog entirely. See Configuration Files for the other dialog options.

Execution limits are tracked on the server, so a button that has reached its limit (e.g. "max 3 per day") is also shown as locked: the reached state is synced when the dialog opens, and the button relocks on the next interaction after the final allowed click.

This makes shop-style buttons straightforward, for example:

• Buy 1 for 2 gold — requires 2 minecraft:gold_ingot in the inventory
• Buy 10 for 1 diamond — requires 1 minecraft:diamond in the inventory

Pair the condition with a matching action (e.g. a command that removes the cost and gives the item) so the purchase actually happens when the button is pressed.

Easy NPC automatically prefers entries such as:

• default
• start
• main

You can also mark an entry as default in the editor.

Dialogs can be filtered and ordered with:

• conditions (all types listed under Actions › Conditions, including item conditions with a quantity, scoreboard, advancement, experience level, player health, tag, team and game mode)
• priority values

A dialog is only shown when all of its conditions match. This is useful when the same NPC should react differently depending on player progress.

Note: dialog conditions decide which dialog is shown, while button conditions (see Button Conditions) decide whether an individual button inside a dialog is enabled.

Examples:

• first visit greeting
• quest-ready dialog
• fallback small talk
• hidden dialog only opened by action or command

Current default priority groups in the code are:

• Critical (100)
• High (10)
• Normal (5)
• Low (1)
• Fallback (0)
• Manual Only (-1)

Labels such as default, start, or welcome are treated as high-priority defaults by the current code. Labels such as main, help, or question default to normal priority. Labels such as bye, idle, or thanks default to low priority.

Dialogs with priority Manual Only are never selected automatically and must be opened through an action or command.

Open the current default dialog:

/easy_npc dialog open <NPC> <player>

Open a specific dialog by label:

/easy_npc dialog open <NPC> <player> <dialog_uuid_or_label>

Set a dialog priority:

/easy_npc dialog set priority <NPC> <dialog_uuid_or_label> <priority>

The dialog screen uses normal texture assets and can be changed with a standard resource pack. The current background textures are:

• assets/easy_npc/textures/gui/dialog/scene_small.png
• assets/easy_npc/textures/gui/dialog/scene_medium.png
• assets/easy_npc/textures/gui/dialog/scene_large.png

The dialog navigation and close buttons also use normal textures:

• assets/easy_npc/textures/gui/navigation_button.png
• assets/easy_npc/textures/gui/close_button.png

To change the look, place files with the same paths inside your resource pack and let them override the originals. You do not need to modify the mod jar.

Config UI backgrounds can be overridden in the same way with:

• assets/easy_npc_config_ui/textures/gui/config_screen/background.png
• assets/easy_npc_config_ui/textures/gui/config_screen/background_small.png

Each dialog has its own Dialog Options editor that controls how the dialog screen looks and behaves:

• Allow ESC Close — the player may close this dialog with the ESC key
• Show Close Button — the close button is shown
• Display Avatar — the NPC is rendered next to the dialog text
• Hide unavailable buttons — buttons whose conditions are not met are removed instead of locked
• Avatar Scale, Avatar Top, Avatar Left — size and position of the rendered NPC

The avatar sliders are the fix for a common problem: on large or oddly shaped models the avatar can be cut off or off-center. Adjust scale and offset instead of changing the model.

Turning off ESC close and the close button forces the player to answer with a dialog button. That is useful for a mandatory intro — but make sure at least one button closes the dialog, otherwise the player is stuck.

Options a dialog does not override fall back to the server defaults in config/easy_npc/dialog_options.cfg:

Dialog text is revealed character by character. This is a client setting, so every player can change it for themselves in config/easy_npc/dialog_client.cfg:

Set typewriterEnabled=false to make the full text appear immediately. The full list of config files is on Configuration Files.

Import these from the default presets to see a working setup instead of building one from scratch:

• give_stone_or_dirt_to_a_player (Humanoid Slim) - yes/no dialog with item rewards
• professor_quiz (Humanoid) - branching quiz with several dialog entries
• dialog_colors_and_styles (Humanoid) - all text color and formatting tags
• dialog_execution_limits (Illusioner) - buttons limited to a number of uses per day
• scoreboard_example (Illusioner) - scoreboard conditions and @score() in dialog text

See Default Presets for the complete list.