BanDialog

BanDialog

BanDialog is a Velocity addon for LiteBans that replaces the normal ban disconnect with a native Minecraft dialog during the configuration phase.

Banned players remain connected to the proxy long enough to read a fully configurable ban notice. They are never forwarded to a backend server, and the Disconnect action immediately closes the connection with your configured message.

Features

• Intercepts LiteBans ban rejections before the default disconnect screen is shown.
• Displays a native vanilla dialog to 1.21.6+ clients during the configuration phase.
• Keeps the held connection alive with configuration-phase keep-alives.
• Prevents banned players from connecting to backend servers.
• Supports a datapack-style YAML dialog definition.
• Supports Adventure MiniMessage in dialog text fields, including colors, gradients, decorations, and <newline>.
• Replaces {player}, {uuid}, {banned_by}, {reason}, {date}, {expiry}, and {ban_id} placeholders.
• Handles the default Disconnect button without showing the client "Waiting for Server" screen.
• Provides atomic configuration reloads through /bandialog reload.

Requirements

• Java 21
• Velocity with Minecraft 1.21.6+ dialog packet support
• LiteBans
• A Minecraft 1.21.6+ client for players who should receive the dialog

Installation

1. Install LiteBans on the Velocity proxy.
2. Copy bandialog-1.0.0.jar to the proxy's plugins directory.
3. Start the proxy once to generate plugins/bandialog/config.yml.
4. Edit the configuration, then run /bandialog reload from the proxy console.

Commands

Configuration

The dialog node mirrors the vanilla dialog data format. You can use the vanilla fields for the selected dialog type, such as type, body, inputs, action, yes, no, actions, exit_action, columns, can_close_with_escape, pause, and after_action.

Text component fields (title, external_title, contents, label, tooltip, and description) use MiniMessage. For example:

dialog:
  type: "minecraft:notice"
  title: "<red><bold>BAN NOTICE</bold></red>"
  can_close_with_escape: true
  after_action: "close"

  body:
    - type: "minecraft:plain_message"
      contents: "<gray>You are banned from this network.</gray><newline><newline><gold>Reason:</gold> <white>{reason}</white><newline><gold>Banned by:</gold> <white>{banned_by}</white>"

  action:
    label: "<red>Disconnect</red>"
    action:
      type: "custom"
      id: "bandialog:disconnect"

date-format: "yyyy-MM-dd HH:mm:ss"
permanent-text: "<red>Permanent</red>"
disconnect-message: "<gray>You have been disconnected from the ban notice screen.</gray>"

Text formatting

MiniMessage formatting works in text component fields:

title: "<gradient:red:gold><bold>Network Ban</bold></gradient>"
contents: "<gray>Read the following carefully.</gray><newline><color:#55ff55>Appeals are available on our website.</color>"

Supported examples include <red>, <green>, <rainbow>, <gradient>, <bold>, <italic>, <underlined>, <color:#ffffff>, and the shorthand <color:#fff>. Use <newline> for a compact line break inside one body message. Literal \n sequences are also normalized to line breaks.

Placeholders

Behaviour notes

• The default bandialog:disconnect custom action is handled by BanDialog and disconnects the player immediately.
• If a minecraft:notice dialog uses after_action: "wait_for_response" with that default disconnect action, BanDialog changes it to close at runtime to avoid the vanilla "Waiting for Server" screen.
• Invalid YAML, invalid date formats, or a missing dialog.type do not replace the currently active configuration during reload.

Support

Please include the Velocity version, client version, LiteBans version, BanDialog version, and the full proxy error when reporting an issue.

AI notice

This project utilizes artificial intelligence tools to assist in its development.