DialogAPI

# DialogAPI – Custom Dialog API for Minecraft 1. 21. 6

[!(https://img.shields.io/github/v/release/AlepandoCR/DialogAPI)](https://github.com/AlepandoCR/DialogAPI/releases/latest) [!(https://jitpack.io/v/AlepandoCR/DialogAPI.svg)](https://jitpack.io/#AlepandoCR/DialogAPI)

DialogAPI is a developer-focused API for easily testing and extending Minecraft's new native dialogs (1. 21. 6), specifically leveraging the `ServerboundCustomClickActionPacket`. It offers a full Kotlin-based wrapper for creating rich, interactive dialogs with buttons, inputs, and custom actions for Paper plugins.

> ❗ Note: This API is primarily intended as a developer utility. While functional, ongoing maintenance for future Minecraft versions is not strictly guaranteed. Feel free to fork, adapt, and build your own features on top of it.

> ⚠️ Important Consideration: PaperMC is developing its own official Dialog API. While DialogAPI is useful now, developers should keep an eye on Paper's native solution for long-term projects, as it will likely become the standard.

## Table of Contents

• [ Features](#-features)
• [ How to Use](#-how-to-use)
• - [ Adding the API](#-adding-the-api)
• - [ API Initialization](#-api-initialization)
• [ Building a Simple Dialog](#-building-a-simple-dialog)
• - [ DialogData](#-dialog-data)
• - [ Adding Buttons with Actions](#-adding-buttons-with-actions)
• - [ Creating the Dialog](#-creating-the-dialog)
• - [ Opening a Dialog](#-opening-a-dialog)
• [ Creating Custom Actions](#creating-custom-actions)
• - [ Registering an Action](#registering-an-action)
• - [ Action Implementation](#-action-implementation)
• - [ Input Readers](#-input-readers)
• - [ Creating Input Fields](#-creating-input-fields)
• [ Looking for More Examples?](#-looking-for-more-examples)
• [ Extending the API](#-extending-the-api)
• [ Contributing](#-contributing)
• [ Troubleshooting / FAQ](#-troubleshooting--faq)
• [ License](#-license)

## ✨ Features

• Kotlin-first builder pattern for intuitive dialog creation.
• Supports all Vanilla dialog types: `MultiAction`, `List`, `Links`, `Notice`.
• Custom actions via Mojang’s native `ServerboundCustomClickActionPacket` system.
• Robust input reading: text, numbers (including ranges), multiline text, boolean toggles, and single-choice options.
• Flexible dialog bodies: plain text messages and item displays.
• Easy integration with Paper events and plugin lifecycle.

## 🚀 How to Use

### 📦 Adding the API

To add DialogAPI to your project, include the following in your `build.gradle.kts` (or equivalent for your build system like Maven or Gradle Groovy):

```kotlin repositories { maven("https://jitpack.io") }

dependencies { implementation("com.github. AlepandoCR:DialogAPI:v1. 1. 1") } ``` > 💡 Tip: Always check (https://jitpack.io/#AlepandoCR/DialogAPI) or the (https://github.com/AlepandoCR/DialogAPI/releases) for the latest version number.

### 🔧 API Initialization

Call this function in your plugin's `onEnable` method to initialize the API internals and register the required packet listeners. This enables features like `CustomActions` and `InputReaders`, which rely on packet-level data.

> ⚠️ Crucial Step: If you don't call `DialogApi.initialize(this)`, dialogs will still open and render correctly, but essential features like button actions (`CustomAction`) and input field processing (`InputReader`) will not function.

```kotlin // In your main plugin class override fun onEnable() { // Initialize DialogAPI, passing your plugin instance DialogApi.initialize(this) // Your other onEnable logic... logger.info("MyPlugin has been enabled and DialogAPI is initialized!") } ```

## 🛠️ Building a Simple Dialog

This section guides you through creating a basic dialog with a title, body, and a button.

### 📝 Dialog Data

First, define the core data for your dialog using `DialogDataBuilder`:

```kotlin val dialogData = DialogDataBuilder() .title(Component.text("Test Menu")) // The title displayed at the top of the dialog window .externalTitle(Component.text("Menu Test")) // Title shown in server logs when the dialog is opened (useful for debugging) .canCloseWithEscape(true) // Allows the player to close the dialog using the ESC key .afterAction(DialogAction. CLOSE) // Action after dialog closes or button is clicked (default: CLOSE, can be KEEP_OPEN) .addBody( PlainMessageDialogBody( // A simple text body part 100, // Height of this body part Component.text("Hello from DialogAPI! This is a basic dialog example.") ) ) // You can add more body parts, like ItemDialogBody, if needed .build() ```

> 💡 New in DialogDataBuilder: > * `.afterAction(DialogAction. KEEP_OPEN)`: Instructs the dialog to attempt to remain open after a button's `CustomAction` is execu