~~Make Dialog Great Again~~ ![example using this dsl](https://cdn.modrinth.com/data/cached_images/2cdf73d03b68d098f4d67825017e7d9413d2a42a.png) ![example using this dsl](https://cdn.modrinth.com/data/cached_images/083d9828beeac55b0131f7bea9ff1a0b46343c35.png)

简体中文

# Paper Dialog DSL > 我实在是受够 `.build()` 了，因此产生了这个项目 Paper Dialog DSL 是一个专为 Paper 1.21.10+ 对话框 API (Dialog API) 打造的 Kotlin 声明式 UI 框架。它彻底消灭了繁琐的 Java Builder 嵌套、生命周期样板代码和危险的组件覆盖问题，带给你极其丝滑、类型安全的 UI 编写体验。查看项目源码及 `test` 包中的示范用法获取更多帮助，直接拉到本地研究也可以，我不太喜欢写README，嗯 ## 对比在原生 Paper API 中写一个带有输入框的对话框，你得这么写： **原生写法：** ```kotlin val oldDialog = Dialog.create { dialogBuilder -> dialogBuilder.empty() .base( DialogBase.builder(mm.deserialize("Title")) .canCloseWithEscape(true) .inputs( listOf( DialogInput.numberRange( "test2", mm.deserialize("输入数字"), 0f, 100f ) .initial(0f) .build(), DialogInput.bool( "test", mm.deserialize("勾选") ).build(), DialogInput.text( "test3", mm.deserialize("请输入文本") ).build() ) ) .build() ) .type( DialogType.notice( ActionButton.create( mm.deserialize("1 right"), mm.deserialize("2 right"), 100, DialogAction.customClick( { view, audience -> val test2 = view.getFloat("test2") ?: return@customClick audience.sendMessage(mm.deserialize("test2: $test2")) }, ClickCallback.Options.builder() .uses(-1) .lifetime(Duration.ofMinutes(5)) .build() ) ) ) ) } ``` **使用这个DSL的写法：** ```kotlin val newDialog = DialogSetup { DialogContent(mm.deserialize("Title")) { canCloseWithEscape(true) NumRangeInput("test2", mm.deserialize("输入数字"), 0f to 100f, 0f, 1.0f, 300) BoolInput("test", mm.deserialize("勾选")) TextInput("test3", mm.deserialize("请输入文本")) } DialogType(UIType.NOTICE) { Button( mm.deserialize("1 right"), mm.deserialize("2 right"), 100, -1, Duration.ofMinutes(5) ) { view, audience -> val test2 = view.getFloat("test2") ?: return@Button audience.sendMessage(mm.deserialize("test2: $test2")) } } } ``` --- ## 导入 `build.gradle.kts`： ```kotlin repositories { mavenCentral() maven { url = uri("https://jitpack.io") } } dependencies { implementation("com.github.Axiumyuyu:PaperDialogDSL:Tag") } ``` --- ## 快速开始 ### 1. 创建主UI 使用 `DialogSetup { ... }` 块来声明一个静态的注册表对话框。框架将 UI 划分为两个区域：`DialogContent` (展示与输入区) 和 `DialogType` (底部按钮路由区)。 ```kotlin val MainMenuUI = DialogSetup { // 【上半区：展示与输入】 DialogContent(text("服务器主菜单")) { // 直接调用原生方法 (Escape Hatch) canCloseWithEscape(true) // 渲染文本与物品 Text(text("欢迎来到服务器！请填写或选择以下操作：")) ItemDisplay(ItemType.DIAMOND.createItemStack()) // 渲染交互输入组件 (自动堆叠在展示内容下方) TextInput("player_name", text("你的昵称")) BoolInput("agree_rules", text("同意服务器规则")) NumRangeInput("age", text("你的年龄"), 1f to 100f) } // 【下半区：操作路由】 DialogType(UIType.MULTI_ACTION, columns = 2) { // 独立的退出按钮 ExitButton(text("关闭"), text("点击退出"), 100) // 常规回调按钮 Button(text("提交"), text("保存数据"), 100) { view, audience -> val name = view.getText("player_name") val agree = view.getBoolean("agree_rules") audience.sendMessage(text("收到提交：$name, 同意规则：$agree")) } } } ``` ### 2. 注册在你的 `PluginBootstrap` 中，使用提供的 `registerDialog` 扩展函数，将繁琐的 5 层泛型参数压缩为一行代码： ```kotlin class MyPluginBootstrap : PluginBootstrap { override fun bootstrap(context: BootstrapContext) { val manager = context.lifecycleManager manager.registerDialog(NamespacedKey("playertd","test"), newDialog) } } ``` ### 3. 动态对话框由于Paper 的bug（[Issue #13555](https://github.com/PaperMC/Paper/issues/13555)）,目前无法在 Bootstrap 阶段使用 `ItemDisplay` ，如果必须使用，则不能在Bootstrap阶段注册，只能使用动态对话框。 ```kotlin // 在命令执行器或事件监听器中： val dynamicUI = MainMenuUI.build() player.showDialog(dynamicUI) ``` --- ## 支持的对话框类型 DSL 支持所有 Paper 原生的对话框布局： * `UIType.NOTICE`: 纯展示，允许 0 或 1 个按钮。 * `UIType.CONFIRMATION`: 二选一，严格要求必须定义 2 个按钮。 * `UIType.MULTI_ACTION`: 支持无限按钮，支持 `columns` 参数实现网格排版。 * `UIType.DIALOG_LIST`: 传入 `RegistrySet

English

> I am not a native English Speaker, translated by ai, sorry for the possible mistakes. # Paper Dialog DSL > I'm really fed up with `.build()`, so this project was born Paper Dialog DSL is a Kotlin declarative UI framework built specifically for Paper 1.21.10+'s experimental Dialog API. It completely eliminates verbose Java Builder nesting, lifecycle boilerplate, and dangerous component override issues, giving you an extremely smooth, type-safe UI writing experience. See the source code and examples in `test` package for more help. I don't like write README, anyway. ## Comparison Writing a dialog with an input field using the native Paper API looks like this: **Native approach:** ```kotlin val oldDialog = Dialog.create { dialogBuilder -> dialogBuilder.empty() .base( DialogBase.builder(mm.deserialize("Title")) .canCloseWithEscape(true) .inputs( listOf( DialogInput.numberRange( "test2", mm.deserialize("输入数字"), 0f, 100f ) .initial(0f) .build(), DialogInput.bool( "test", mm.deserialize("勾选") ).build(), DialogInput.text( "test3", mm.deserialize("请输入文本") ).build() ) ) .build() ) .type( DialogType.notice( ActionButton.create( mm.deserialize("1 right"), mm.deserialize("2 right"), 100, DialogAction.customClick( { view, audience -> val test2 = view.getFloat("test2") ?: return@customClick audience.sendMessage(mm.deserialize("test2: $test2")) }, ClickCallback.Options.builder() .uses(-1) .lifetime(Duration.ofMinutes(5)) .build() ) ) ) ) } ``` **Using this DSL:** ```kotlin val newDialog = DialogSetup { DialogContent(mm.deserialize("Title")) { canCloseWithEscape(true) NumRangeInput("test2", mm.deserialize("输入数字"), 0f to 100f, 0f, 1.0f, 300) BoolInput("test", mm.deserialize("勾选")) TextInput("test3", mm.deserialize("请输入文本")) } DialogType(UIType.NOTICE) { Button( mm.deserialize("1 right"), mm.deserialize("2 right"), 100, -1, Duration.ofMinutes(5) ) { view, audience -> val test2 = view.getFloat("test2") ?: return@Button audience.sendMessage(mm.deserialize("test2: $test2")) } } } ``` --- ## Import `build.gradle.kts`: ```kotlin repositories { mavenCentral() maven { url = uri("https://jitpack.io") } } dependencies { implementation("com.github.Axiumyuyu:PaperDialogDSL:Tag") } ``` --- ## Quick Start ### 1. Create the main UI Use the `DialogSetup { ... }` block to declare a static registry dialog. The framework splits the UI into two areas: `DialogContent` (display & input area) and `DialogType` (bottom button routing area). ```kotlin val MainMenuUI = DialogSetup { // 【Upper area: display & input】 DialogContent(text("服务器主菜单")) { // Directly call native methods (Escape Hatch) canCloseWithEscape(true) // Render text and items Text(text("欢迎来到服务器！请填写或选择以下操作：")) ItemDisplay(ItemType.DIAMOND.createItemStack()) // Render interactive input components (automatically stacked below the display content) TextInput("player_name", text("你的昵称")) BoolInput("agree_rules", text("同意服务器规则")) NumRangeInput("age", text("你的年龄"), 1f to 100f) } // 【Lower area: action routing】 DialogType(UIType.MULTI_ACTION, columns = 2) { // Standalone exit button ExitButton(text("关闭"), text("点击退出"), 100) // Regular callback button Button(text("提交"), text("保存数据"), 100) { view, audience -> val name = view.getText("player_name") val agree = view.getBoolean("agree_rules") audience.sendMessage(text("收到提交：$name, 同意规则：$agree")) } } } ``` ### 2. Registration In your `PluginBootstrap`, use the provided `registerDialog` extension function to compress the verbose 5‑layer generic parameters into a single line: ```kotlin class MyPluginBootstrap : PluginBootstrap { override fun bootstrap(context: BootstrapContext) { val manager = context.lifecycleManager manager.registerDialog(NamespacedKey("playertd","test"), newDialog) } } ``` ### 3. Runtime Dialogs Due to a Paper bug ([Issue #13555](https://github.com/PaperMC/Paper/issues/13555)), `ItemDisplay` cannot be used at the Bootstrap stage. If you must use it, you cannot register at Bootstrap and must use runtime dialogs. ```kotlin // In a command executor or event listener: val dynamicUI = MainMenuUI.build() player.showDialog(dynamicUI) ``` --- ## Supported Dialog Types The DSL supports all native Paper dialog layouts: * `UIType.NOTICE`: Pure display, allows 0 or 1 button. * `UIType.CONFIRMATION`: Two‑choice, strictly requires exactly 2 buttons. * `UIType.MULTI_ACTION`: Supports unlimited buttons, with a `columns` parameter for grid layout. * `UIType.DIALOG_LIST`: Pass a `RegistrySet

PaperDialogDSL

2.2.0