Dialogue

Crisp, branching Minecraft conversations with a visual browser Studio.

Dialogue is a self-hosted conversation plugin for Paper. Write the conversation, arrange the artwork, preview the complete animation, and publish it into an ItemsAdder, Nexo, or CraftEngine resource pack. In game, each player sees a private cinematic overlay that can run on its own or follow a camera controlled by Typewriter.

Current release: 1.3.3

Updating for Minecraft 26.3

Use Java 25 and PacketEvents 2.14.0 or newer on a 26.3 server. Version 1.3.3 handles
the new empty PUNCH packet while a conversation locks world interaction. It does
not treat that packet as an entity attack or as a dialogue confirmation.

Back up plugins/Dialogue and your provider pack, stop the server, replace the
Dialogue JAR, and restart. Republish in Studio, rebuild the provider pack, and
have the client download it again. Use a resource-pack provider that supports
26.3. Check a complete conversation with your client, shader setup, and camera
integration before opening the server to players; startup checks do not verify
those client-side combinations.

The older Dialogues plugin with YAML conversations and /dialog is a separate
generation. Its YAML files are not automatically imported into this Studio.
Keep its backup and rebuild those conversations in Studio before switching.

What makes Dialogue different

Dialogue is designed as the visual conversation layer of a server. Quest objectives, conditions, and rewards can stay in the quest plugin you already use, while Dialogue handles presentation, player choices, and command hand-offs.

Features

• Multiple conversations with branching dialogue steps
• W/S answer selection and Q to reveal, continue, or confirm
• A guided Write → Design → Choices → Preview → Publish workflow
• Complete browser preview of opening, dark backdrop, typing, choices, and closing animation
• Direct canvas dragging and corner resizing for individual layers
• Shared design across every step by default, with optional step-specific layouts
• Independent speech bubble, name frame, speaker, body text, choice, prompt, pointer, and decoration layers
• More than 500 bundled UI assets: speech bubbles, answer frames, name frames, pointers, and decorations
• 13 bundled atlas fonts plus 12 editable code-native pixel fonts, with multilingual Latin and Cyrillic coverage
• Optional pixel-perfect text effects on dialogue, speaker/rank, choice, and prompt text: one through six hard color bands plus a directional inner shadow
• Twelve text-motion presets and twelve surface-motion presets with per-layer entrance, exit, timing, easing, direction, distance, intensity, cycles, stagger, and deterministic variation controls
• Custom PNG upload for bubbles, name frames, answer frames, pointers, and decorations
• Lossless whole-pixel sizing for bundled and custom pixel artwork
• Optional commands when a conversation starts or ends, a step opens or closes, or an answer is chosen
• Per-dialogue player permissions
• ItemsAdder, Nexo, and CraftEngine publishing, with multi-provider output options
• Command-based use with Typewriter, Citizens, BetonQuest, BeautyQuests, Quests, and similar plugins
• Player-only visibility, interaction locking, hand hiding, and player-state restoration when playback ends

Requirements

ItemsAdder, Nexo, CraftEngine, PacketEvents, Typewriter, and other named plugins are separate products and are not included with Dialogue.

PacketEvents is optional, but strongly recommended for production. It provides reliable empty-hand Q input, strict look and movement locking, hidden hands, a standalone camera anchor, and accurate tracking of client-side cinematic cameras.

The Studio is included in the product release JAR. You do not need to install a separate website, Node.js, Python, or a database.

Installation and first setup

1. Stop the Paper server.
2. Place Dialogue-1.3.3.jar in the server’s plugins directory and remove every older Dialogue JAR.
3. Install ItemsAdder, Nexo, or CraftEngine if the server does not already use one of them.
4. Install PacketEvents 2.14.0+ for the complete playback experience.
5. Start the server. Dialogue creates its configuration, a private Studio token, and a sample project.
6. Run /dialogue web as an operator or administrator with the correct permissions.
7. Open the exact Studio address shown by the command and paste the separately displayed token.
8. Review the sample conversation or create your own, then click Save changes and Publish pack.
9. Rebuild or reload the chosen resource-pack provider.
10. Make sure the player receives the new pack, reconnect, and test /dialogue blacksmith_intro.

The included blacksmith_intro sample is a project template. It is not playable until Publish pack has been run at least once.

Provider refresh after publishing

• ItemsAdder: Dialogue queues /iazip automatically by default, approximately three seconds after publishing.
• Nexo: automatic reload is off by default. Run /nexo reload all when the editing session is finished.
• CraftEngine: automatic reload is off by default. Run /ce reload all after publishing so CraftEngine loads the new source pack and generates its resource pack.
• IA + Nexo: ItemsAdder is queued automatically; Nexo still needs its manual reload unless Nexo auto-reload is enabled in the configuration.
• All three: ItemsAdder is queued automatically; reload Nexo and CraftEngine unless their automatic reload settings are enabled.

After the provider finishes, distribute or reload the rebuilt resource pack and reconnect the test client.

Using Dialogue Studio

1. Write

Enter the speaker and line shown to the player. Choose what Q should do next and add more steps from the left sidebar as the conversation grows. Dialogue IDs are available under Dialogue details and IDs when you need to rename or integrate the conversation.

2. Design

Select a layer above the canvas, then edit that layer’s controls. Drag inside the amber outline to move it. Drag an amber corner handle to resize it.

Each dialogue, speaker/rank, choice, and control-prompt text style can optionally use pixelEffects. Choose one through six colors for hard pixel bands, then set their direction, width, and offset. The separate inner-shadow control colors only the inside of each glyph and exposes color, top/bottom/left/right edge, strip/edge mode, inset, depth, and opacity. Neither effect uses a blurred CSS gradient, and older projects load with both effects disabled.

Design edits apply to all steps by default. Turn off Apply design edits to all steps only when the current step intentionally needs a different layout.

The artwork library and pixel-safe resize settings stay collapsed until they are needed, keeping the main inspector focused on the selected layer.

3. Choices

Add the answers available on the current step. Each answer can:

• continue to another step;
• end the conversation; and
• run one or more server commands.

Preview choice boxes can show example answer boxes while arranging the layout. These examples are preview-only and are never published as real choices.

4. Preview

Use Play complete dialogue animation to review the same opening, backdrop, typing, choice, and closing states that will be published.

Select a motion target to animate the speech bubble, dialogue, name frame, speaker name, choice boxes, choice text, choice pointer, controls prompt, or an individual decoration. Text layers provide 12 text-specific presets and artwork layers provide 12 pixel-safe surface presets. Pick a preset first, then open Fine tune only when you need custom timing, delay, easing, direction, distance, intensity, cycles, stagger, playback behavior, or deterministic seeded variation.

Layer motion is baked into the published PNG states; it does not depend on live Minecraft interpolation. Missing motion settings keep the classic animation used by projects created before 1.3.0.

Use Fit canvas while arranging the design. Switch to 1:1 pixels for the final sharpness check.

5. Publish

Connect Studio to the server, select ItemsAdder, Nexo, CraftEngine, or a multi-provider option, confirm the resource namespace, save, and click Publish pack.

Save changes updates the project stored by Dialogue, but it does not rewrite an already exported provider pack. Click Publish pack again whenever dialogue text, fonts, artwork, layout, choices, pixel effects, or animation settings change. Then rebuild or reload the provider pack and make the client download it.

Useful Studio shortcuts

Project import and export are available from the Project menu. Export a copy before a large redesign or server migration.

Player controls

Dialogue temporarily reserves these controls and blocks normal world interaction while a conversation is active. The player’s held items, off-hand item, visibility, location, velocity, and camera state are restored when the conversation completes, is stopped, is replaced, or the player disconnects.

Configuration

The server configuration is created at:

plugins/Dialogue/config.yml

The defaults are suitable for a local Studio and the standard ItemsAdder/Nexo/CraftEngine directory layouts. After editing this file, run /dialogue reload to apply the changes and restart the Studio listener.

Web Studio settings

To rotate the Studio token, set web.token to an empty value and run /dialogue reload. Dialogue generates and saves a new token.

Playback settings

The default projection is calibrated for a 1920 × 1080 Java client at FOV 70. If the intended audience uses a different profile, test changes to distance and scale in game before publishing the server publicly.

The canvas dimensions control image resolution; they do not force a fullscreen HUD. At display-distance: 0.42 and a 16:9 viewport, start with the following approximate scales, then run /dialogue reload and reopen the conversation:

For other distances, multiply the scale by distance / 0.42. These values fit the whole canvas width, including any transparent margins in the design. Minecraft does not send the player’s FOV or viewport dimensions to the server, so a single server setting cannot guarantee identical coverage for every client. To remove the dark backdrop, set its opacity to zero under Studio’s screen effects, then publish and rebuild the pack.

Resource-pack paths and reloads

The provider and resource namespace are selected in Studio’s Publish step and saved with the project. IA + Nexo preserves the original two-provider output; All three adds CraftEngine. The shipped configuration still retains exports.provider and exports.namespace, but current publishing uses the Studio project settings instead.

Remote Studio access

The safe default, 127.0.0.1:8767, accepts connections only from the Minecraft host. Choose one of these methods for remote administration:

1. SSH tunnel: keep the default configuration and forward port 8767 from your computer.

text
ssh -L 8767:127.0.0.1:8767 account@minecraft-host

Then open http://127.0.0.1:8767 locally.

1. HTTPS reverse proxy: keep web.bind: 127.0.0.1, proxy a dedicated HTTPS hostname to port 8767, and set the external origin.

yaml
web:
bind: 127.0.0.1
port: 8767
public-url: 'https://dialogue.example.com'

web.public-url must be an origin without an added path.

1. Direct port: set web.bind: 0.0.0.0 and web.advertised-host to the server hostname. Only use this on a restricted firewall or trusted network; the built-in listener does not provide TLS on its own.

Run /dialogue web after configuration. Its health-check address should return Dialogue status, not a hosting-provider or nginx welcome page.

Publishing and resource packs

The Publish pack action creates the current dialogue frames and writes them into the selected provider’s pack:

• ItemsAdder: plugins/ItemsAdder/contents/<namespace>/resourcepack/
• Nexo: plugins/Nexo/pack/
• CraftEngine: plugins/CraftEngine/resources/dialogue/resourcepack/

Publishing does not automatically force every connected player to download a changed pack. Complete the provider’s normal pack build and distribution process, then reconnect the test client.

/dialogue publish [provider] is a maintenance command that republishes frames already created by Studio. It does not render unsaved text, artwork, or layout changes. Use Publish pack in Studio for the first publication and after every content change.

Commands

Command aliases: /dialogues and /dlg.

Permissions

dialogue.admin is not a replacement for the more specific permissions. When creating a non-operator staff role, grant dialogue.admin plus each administrative action that role should be allowed to use.

Each dialogue can also have its own player permission. Set it in Studio’s Publish step; leave it blank when everyone may play that conversation.

Integrations

Typewriter

Add a Cinematic Player Command containing:

dialogue <id>

Do not add a player name when Typewriter runs it as the player.

Do not overlap the same frame range with Typewriter’s Spoken Dialogue, Action Bar Dialogue, or Subtitle Dialogue cinematic entries. Those entries create a second dialogue surface and use Minecraft’s XP strip as a progress indicator.

Typewriter remains in control of its camera. Dialogue follows the selected camera without mounting, replacing, or resetting it.

Citizens, quest plugins, and scripted systems

Use the player form when the integration can run a command as the player:

dialogue <id>

Use the console form when the integration supplies a player placeholder:

dialogue play <id> <player>

This works with Citizens command traits and the command actions in common quest plugins, including BetonQuest, BeautyQuests, and Quests.

Commands during a conversation

Studio can run console commands at these points:

• conversation start;
• step enter;
• step exit;
• answer selection; and
• conversation end.

Available placeholders are {player}, {uuid}, {dialogue}, {node}, and {choice}. Save commands without a leading /.

Updating Dialogue

1. Back up plugins/Dialogue and the relevant ItemsAdder/Nexo/CraftEngine pack directory.
2. Stop the server, remove every older Dialogue JAR, and install Dialogue-1.3.3.jar.
3. Start the server and check the console for configuration warnings.
4. Open Studio and click Publish pack once.
5. Rebuild or reload ItemsAdder/Nexo/CraftEngine, distribute the rebuilt pack, and reconnect.
6. Test a short dialogue before reopening the server to players.

Updating to 1.3.2

Version 1.3.1 could reject a single animated dialogue because its texture budget was hard-coded and every unique tile reserved 128 × 128 pixels. Version 1.3.2 uses smaller cells, crops transparent margins, stores solid regions as a single texel, and removes only exact integer pixel repetition. Pixel placement and colors are preserved. The default export budget is now 67,108,864 pixels (256 MiB base RGBA) and can be changed with exports.max-texture-pixels in plugins/Dialogue/config.yml, followed by /dialogue reload. Existing configurations use the new default automatically when the key is absent. Both Studio publishing and /dialogue publish use the same setting. This is an export budget, not a detected GPU limit or a guarantee that the combined pack fits every client.

Install with a full restart and republish, then rebuild the provider pack and download it again. Original saved frames can be reused with /dialogue publish itemsadder.

Updating to 1.3.1

Republish all dialogues after installing this update, then rebuild ItemsAdder with /iazip (or reload the selected provider) and download the new pack. Version 1.3.1 shares identical pixel tiles across animation frames and uses Minecraft’s item-texture directory, reducing decoded texture-atlas usage without reducing image resolution. Old full-frame provider textures are removed during republishing. Existing original frames are retained, so /dialogue publish itemsadder can regenerate an unchanged project without rendering it again in Studio.

The download size shown by ItemsAdder is the compressed ZIP size. Minecraft must also fit the decoded textures into a GPU atlas; increasing a 250 MB download limit does not fix atlas exhaustion. The publisher checks Dialogue’s texture budget before exporting, but other pack content and client hardware still affect the combined atlas. If loading still fails after rebuilding, inspect the client’s .minecraft/logs/latest.log immediately after the failure for atlas stitching or texture errors.

Updating to 1.3.0

Version 1.3.0 adds 12 text-motion presets and 12 surface-motion presets to every editable dialogue layer, with independent entrance and exit behavior plus detailed timing and pixel-safe customization. Existing projects keep their previous animation because missing motion settings use the legacy defaults. Installing the JAR updates the embedded Studio only after the server is stopped and restarted; an already open browser may also need a hard refresh. Save the project, run Publish pack, rebuild or reload the provider pack, and make the client download it before judging in-game motion.

Updating to 1.2.5

Version 1.2.5 adds optional hard-clipped pixel color bands and a customizable directional inner shadow to every editable text role. Existing projects remain visually unchanged because missing pixelEffects settings migrate to disabled defaults. Enable and preview the effects at 1:1 pixels, then save, publish once, rebuild or reload the provider pack, and make the client download the updated pack.

Updating to 1.2.4

Version 1.2.4 adds 12 editable code-native pixel-font families alongside the existing bundled atlas fonts, including Cyrillic coverage for Ukrainian, Russian, Belarusian, Serbian, Macedonian, Kazakh, and Tajik text. The product and commercial-source builds now use visibly different release filenames and embedded edition metadata so the two JARs cannot be mistaken for one another.

Updating to 1.2.3

Version 1.2.3 makes generated dialogue models full-bright so world lighting no longer darkens the PNG artwork. Existing projects must be published once after installing the new JAR, followed by a provider pack rebuild and a fresh client download. Dialogue does not color-correct or re-encode the original PNG files.

When updating from 1.1, the republish is mandatory because current model keys are stored under <resource-namespace>:dialogues/*. An old 1.1 pack cannot find those keys.

Backups

Back up these locations before updates, migrations, or large project changes:

• plugins/Dialogue/config.yml
• plugins/Dialogue/data/
• plugins/Dialogue/web/assets/custom/
• the generated Dialogue files in the selected ItemsAdder, Nexo, or CraftEngine pack

Studio’s Project → Export option is also useful for keeping a portable copy of the conversation project.

Troubleshooting

Compatibility and limits

• The overlay is calibrated for a known client profile; Minecraft does not report each player’s viewport size to the server.
• One publication can contain up to 5,000 rendered frame states, subject to a separate shared-texture budget checked during export.
• Dialogue handles visual conversation presentation and branching. Use a quest or scripting plugin for objectives, conditions, localization workflows, rewards, and other game systems.
• Confirm that you have redistribution and commercial-use rights for all bundled or uploaded artwork and fonts used by your server.

The Studio includes a searchable handbook from its Help button. For server access help, see the remote web access guide (see docs/WEB-ACCESS.md in the download). Release changes are listed in the changelog (see CHANGELOG.md in the download).