UltraDialogue

# UltraDialogue **Give your NPCs conversations, not just commands.** UltraDialogue opens native Minecraft dialogue screens with portraits, branching answers, quest symbols and navigation — with no client mod required. A **Paper 26.1.2** plugin by **Social Studio**, requiring **Java 25**. Open source under the **MIT License**. ## Conversations that react to the player Write one YAML file per character. Answers can lead to another node or character, open a menu, run a command, show a message or title, play a sound, and advance a quest. - **Branching dialogue:** greetings, choices and follow-up scenes. - **Conditions:** permissions, player flags, affinity, inventory items, quest state and optional PlaceholderAPI comparisons. - **Hidden affinity:** characters remember how the player treats them; configurable limits prevent farming positive affinity. - **Persistent player flags:** remember introductions, accepted jobs and story progress. - **Text variants and rotating answers:** vary a conversation while retaining important options. - **Deliveries:** check, take and give items. Taking items is all-or-nothing; conditions are checked again when an answer is clicked. - **Portraits:** NPC/player skins, a fixed skin texture, or an item with a fallback. - **English and Spanish:** built-in messages and dialogue configuration keys. ## Free row layouts A native dialogue grid gives every row the same number of columns. UltraDialogue also provides `layout:` (`filas:` in Spanish): clickable components in the dialogue body allow different row lengths, such as **1–2–2–1** or **3–1**. | Mode | Appearance | |---|---| | Native grid, without `layout:` | Real Minecraft buttons with the usual hover highlight. | | Free rows, without the button pack | Clickable `[ text ]` options. No resource pack needed. | | Free rows, with the button pack | Dark panels with centred text and a coloured double frame. | `nav:` remains a row of **real Minecraft buttons** below the free-row panels. Back, Exit and a custom Rewards button can sit side by side. ## Simple RPG panels The 1.1.2 default is deliberately clean: a **flat dark background**, a **double border**, and aligned **full-width rows**. The same theme applies to every pack-drawn layout panel. Border colours identify the option: white for an ordinary question, green for a main quest, blue for a side quest, purple for a riddle, yellow for rewards, and grey for a locked answer. Colours are configurable without rebuilding the pack. The button pack is **optional**. By default, the plugin offers its bundled pack after a player joins; `buttons: auto` enables panels only after Minecraft confirms the pack loaded. Players who do not load it keep the text presentation. For an externally merged pack, disable the plugin's own delivery and use `buttons: pack` only when that pack includes the UltraDialogue font. In this forced mode the plugin cannot confirm delivery for you. ## Quest symbols Ten named presets use the following text symbols; **the symbols themselves need no resource pack**: | English / Spanish | Symbol | Purpose | |---|---|---| | `quest` / `mision` | `!` | A mission or job, gold-orange | | `main` / `principal` | `•` | Main quest, green | | `side` / `secundaria` | `•` | Side quest, blue | | `riddle` / `acertijo` | `•` | Riddle, purple | | `accept` / `aceptar` | `✓` | Accept, green | | `back` / `volver` | `«` | Go back, light green | | `exit` / `salir` | `×` | Exit, red | | `reward` / `premio` | `±` | Quest rewards, yellow | | `story` / `cuento` | `♪` | An NPC's story, light blue | | `chance` / `probabilidad` | `%` | A chance-based option, orange | Combine presets: `icon: quest side` displays a gold `!` and a blue `•`; the last coloured preset selects the panel border colour. ## Locked options and navigation An answer with `if:` and `locked:` stays visible in grey while its condition is false. Clicking it shows the configured hint and sound, without running its actions. - **Back** walks through this conversation's previous screens, including switches between characters. - **Exit** closes the conversation. - **Per-node titles** organise quest boards, chapters and services. - Without free rows, the native grid remains available; a full-width answer can be placed at the end. ## A complete example Save this as `dialogues/brann.yml`. `npcs: [brann]` links an existing FancyNpcs character named `brann`; it does not create the NPC. ```yaml name: '&6&lBrann' npcs: [brann] start: menu nodes: menu: title: '&6Quest board' text: 'What brings you here?' layout: [1, 2, 1] answers: - {text: '&fMain quest', icon: quest main, goto: main} - text: '&fSide quest' icon: quest side if: 'affinity >= 20' locked: '&7Earn more trust first.' goto: side - {text: '&fA riddle', icon: quest riddle, goto: riddle} - {text: '&fTell me a story', icon: story, goto: story} nav: - back - exit - {text: '&fRewards', icon: reward, goto: rewards} main: text: 'There is a job waiting on the road ahead.' layout: [1] answers: - text: '&fAccept the job' icon: accept actions: ['flag: brann_job_accepted'] goto: accepted nav: [back, exit] accepted: text: 'I will remember that you accepted.' nav: [back, exit] side: text: 'Thank you for earning my trust.' nav: [back, exit] riddle: text: 'What has keys, but opens no locks?' nav: [back, exit] story: text: 'Our village began with a traveller and a promise.' nav: [back, exit] rewards: text: 'This is the reward information screen. Add your own quest conditions and reward actions.' nav: [back, exit] ``` ## Optional integrations - **FancyNpcs:** clicking a linked NPC opens its dialogue. Tagged vanilla entities can also talk. - **PlaceholderAPI:** placeholders in text/actions/conditions, plus affinity and flag placeholders. - **BeautyQuests:** quest conditions and actions, with the `ULTRADIALOGUE` stage type. - **DeluxeMenus or another menu plugin:** the `menu:` action runs a configurable command. - **ViaVersion:** older client protocols can receive clickable chat instead of a native dialog. - **UltraBoss / UltraRevive:** supported item identification for deliveries; these plugins are not required. Plugins can also listen for the Bukkit `DialogueSignalEvent` emitted by `quest: complete`. ## Install and commands 1. Put `UltraDialogue-1.1.2.jar` in `plugins/` and start Paper with Java 25. 2. Configuration and example dialogues appear in `plugins/UltraView/UltraDialogue/`. 3. Edit or add a dialogue, then use `/ud reload`. Close and reopen existing conversations to use their newly loaded definitions. 4. For internal pack delivery, configure a public address and a reachable port — **8083** by default. Otherwise use text buttons or an external pack provider. Administrative commands require **`ultradialogue.admin`** (operators have it by default). Players do not need that permission to talk to linked NPCs. ```text /ud open [player] [node] /ud reload /ud list /ud icons /ud flags [clear [flag]] /ud affinity [id] [set|add|reset] [n] ``` To test the example yourself, run `/ud open brann`. To choose a specific node, include the player: `/ud open brann YourPlayerName menu`. ## Limits and compatibility - The verified server target for this release is **Paper 26.1.2 / Java 25**. Native dialogs were introduced in client version 1.21.6; that does **not** make this JAR compatible with older server versions. - **Folia is not supported.** Bedrock/Geyser behaviour is not verified. - Free-row panels are clickable body text, not native GUI controls: they have no native hover highlight, and the clickable area is the text line rather than the entire 24-pixel drawing. The `nav:` buttons keep native hover behaviour. - The pack also darkens Minecraft's in-world menu background, affecting other in-world menus. It does not control the player's blur setting. - Pack downloads depend on the player's acceptance, network access and server configuration; delivery is not guaranteed simply by opening a port. - YAML actions can execute console commands: only trusted administrators should edit dialogue files. ## Network use The internal pack provider serves the bundled ZIP over HTTP on its configured port. With `host: AUTO`, it queries `api.ipify.org` to discover the public IP. Disabling `resource-pack.enabled` disables that provider and its public-IP lookup. Player-name portraits can also use asynchronous profile resolution through the server API. The screenshots show a configured server: its NPCs, world, quests and fonts are not included with the plugin. **MIT License · Social Studio**