DialogDSL

插件

· 作者 Axiumyuyu

Paper 中用于对话框的 Kotlin DSL 和路由系统

0 本站下载 0 关注 更新于 4 个月前

最新 2.2.0 · 26.2 · Paper / Purpur

一键开服(送7天)

让对话再次伟大

使用此 DSL 的示例

使用此 DSL 的示例

简体中文

Paper Dialog DSL

我实在是受够 .build() 了,因此产生了这个项目

Paper Dialog DSL 是一个专为 Paper 1.21.10+ 对话框 API (Dialog API) 打造的 Kotlin 声明式 UI 框架。它彻底消灭了繁琐的 Java Builder 嵌套、生命周期样板代码和危险的组件覆盖问题,带给你极其丝滑、类型安全的 UI 编写体验。

查看项目源码及 test 包中的示范用法获取更多帮助,直接拉到本地研究也可以,我不太喜欢写README,嗯

对比

在原生 Paper API 中写一个带有输入框的对话框,你得这么写:

原生写法:

val oldDialog = Dialog.create { dialogBuilder ->
    dialogBuilder.empty()
        .base(
            DialogBase.builder(mm.deserialize("Title"))
                .canCloseWithEscape(true)
                .inputs(
                    listOf(
                        DialogInput.numberRange(
                            "test2",
                            mm.deserialize("<aqua>输入数字"),
                            0f,
                            100f
                        )
                            .initial(0f)
                            .build(),
                        DialogInput.bool(
                            "test",
                            mm.deserialize("勾选<sprite:blocks:block/stone>")
                        ).build(),

                        DialogInput.text(
                            "test3",
                            mm.deserialize("<sprite:\"minecraft:items\":item/porkchop>请输入文本")
                        ).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的写法:

val newDialog = DialogSetup {
    DialogContent(mm.deserialize("Title")) {
        canCloseWithEscape(true)
        NumRangeInput("test2", mm.deserialize("<aqua>输入数字"), 0f to 100f, 0f, 1.0f, 300)
        BoolInput("test", mm.deserialize("勾选<sprite:blocks:block/stone>"))
        TextInput("test3", mm.deserialize("<sprite:\"minecraft:items\":item/porkchop>请输入文本"))
    }
    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:

repositories {
    mavenCentral()
    maven { url = uri("https://jitpack.io") }
}

dependencies {
    implementation("com.github.Axiumyuyu:PaperDialogDSL:Tag")
}


快速开始

有一个还没写完的用法在USAGE.md

1. 创建主UI

使用 DialogSetup { ... } 块来声明一个静态的注册表对话框。框架将 UI 划分为两个区域:DialogContent (展示与输入区) 和 DialogType (底部按钮路由区)。


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 层泛型参数压缩为一行代码:


class MyPluginBootstrap : PluginBootstrap {
    override fun bootstrap(context: BootstrapContext) {
        val manager = context.lifecycleManager
        manager.registerDialog(NamespacedKey("playertd","test"), newDialog)
    }
}

3. 动态对话框

由于Paper 的bug(Issue #13555),目前无法在 Bootstrap 阶段使用 ItemDisplay ,如果必须使用,则不能在Bootstrap阶段注册,只能使用动态对话框。

// 在命令执行器或事件监听器中:
val dynamicUI = MainMenuUI.build()

player.showDialog(dynamicUI)


支持的对话框类型

DSL 支持所有 Paper 原生的对话框布局:

  • UIType.NOTICE: 纯展示,允许 0 或 1 个按钮。
  • UIType.CONFIRMATION: 二选一,严格要求必须定义 2 个按钮。
  • UIType.MULTI_ACTION: 支持无限按钮,支持 columns 参数实现网格排版。
  • UIType.DIALOG_LIST: 传入 RegistrySet<Dialog> 展示多个子对话框列表。
  • UIType.SERVER_LINKS: 展示服务器配置的外部链接。

路由系统 (Route)

为多页面对话框场景提供导航栈管理与生命周期安全的声明式路由方案。

核心接口

接口 何时使用 要点
Route 绝大多数页面,如列表页、详情页、表单页等 支持后退导航。无状态用 object,带参用 data class
RootRoute 模块入口/主菜单,作为路由树的根节点 配合 AutoRootSetup 零样板生成菜单。从指令或事件入口调用 DialogRouter.openRoot() 启动
AtomicRoute 高危操作,如经济扣费、数据库写入、不可中断的多步事务 强制实现 onRollback 处理断线/死亡回滚;禁止 ESC 关闭;自动检测并触发事务回滚

快速使用

// 命令/事件中打开根菜单
DialogRouter.openRoot(player, MainMenu)
// 页面内导航
context.navigate(SomeRoute)           // 压栈跳转
context.replace(state.copy(x = v))    // 替换当前页(更新状态重绘)
context.goBack()                      // 返回上一页
context.abortTransaction()            // 中断事务(自动调用 onRollback)

使用 AutoRootSetup 快速创建主菜单:

object MainMenu : RootRoute {
    override fun render(context: DialogRouteContext) =
        AutoRootSetup(context, mm.deserialize("主菜单")) {
            "实体列表" to ListRoute
            "编辑" to EditRoute("uuid-1234", "Pig")
            "设置" to SettingsRoute()
        }
}

生命周期保护

RouteCleanUp 自动监听玩家掉线/死亡事件。若当前页面为 AtomicRoute,自动触发 onRollback 回滚并清理路由栈,防止事务泄露。

完整示例参考 src/test/.../route/RouteTest.kt 和 RouteTest2.kt。


License

本项目采用 MIT 许可证授权。

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:

val oldDialog = Dialog.create { dialogBuilder ->
    dialogBuilder.empty()
        .base(
            DialogBase.builder(mm.deserialize("Title"))
                .canCloseWithEscape(true)
                .inputs(
                    listOf(
                        DialogInput.numberRange(
                            "test2",
                            mm.deserialize("<aqua>输入数字"),
                            0f,
                            100f
                        )
                            .initial(0f)
                            .build(),
                        DialogInput.bool(
                            "test",
                            mm.deserialize("勾选<sprite:blocks:block/stone>")
                        ).build(),

                        DialogInput.text(
                            "test3",
                            mm.deserialize("<sprite:\"minecraft:items\":item/porkchop>请输入文本")
                        ).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:

val newDialog = DialogSetup {
    DialogContent(mm.deserialize("Title")) {
        canCloseWithEscape(true)
        NumRangeInput("test2", mm.deserialize("<aqua>输入数字"), 0f to 100f, 0f, 1.0f, 300)
        BoolInput("test", mm.deserialize("勾选<sprite:blocks:block/stone>"))
        TextInput("test3", mm.deserialize("<sprite:\"minecraft:items\":item/porkchop>请输入文本"))
    }
    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:

repositories {
	mavenCentral()
	maven { url = uri("https://jitpack.io") }
}

dependencies {
	implementation("com.github.Axiumyuyu:PaperDialogDSL:Tag")
}


Quick Start

There's a WIP Help page at USAGE.md

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).


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)

由于 Paper 的一个 Bug(Issue #13555),ItemDisplay 无法在引导阶段(Bootstrap stage)使用。如果你必须使用它,就不能在引导阶段注册,而必须使用运行时对话框。

// 在命令执行器或事件监听器中:
val dynamicUI = MainMenuUI.build()

player.showDialog(dynamicUI)

支持的对话框类型

DSL 支持所有原生的 Paper 对话框布局:

  • UIType.NOTICE:纯展示,允许 0 或 1 个按钮。
  • UIType.CONFIRMATION:二选一,严格需要恰好 2 个按钮。
  • UIType.MULTI_ACTION:支持无限数量的按钮,并提供 columns 参数用于网格布局。
  • UIType.DIALOG_LIST:传递一个 RegistrySet<Dialog> 以显示子对话框列表。
  • UIType.SERVER_LINKS:显示服务器上配置的外部链接。

路由系统 (Route System)

一种用于多页面对话框场景的声明式路由解决方案,提供导航栈管理和生命周期安全性。

核心接口

接口 适用场景 关键点
Route 大多数页面 —— 列表、详情、表单等 支持返回导航。无状态页面使用 object,带参数的页面使用 data class
RootRoute 模块入口 / 主菜单,作为路由树的根节点 配合 AutoRootSetup 实现零样板代码的菜单。通过命令或事件中的 DialogRouter.openRoot() 启动
AtomicRoute 高风险操作 —— 经济扣费、数据库写入、不可中断的多步事务 必须实现 onRollback 以处理断开连接或死亡恢复;禁用 ESC 关闭功能;自动检测并在生命周期事件触发时回滚

快速开始

// 从命令或事件中打开根菜单
DialogRouter.openRoot(player, MainMenu)

// 页面内导航
context.navigate(SomeRoute)           // 压入导航(保留历史记录)
context.replace(state.copy(x = v))    // 替换当前页面(更新状态并重新渲染)
context.goBack()                      // 返回上一页
context.abortTransaction()            // 中止事务(自动触发 onRollback)

使用 AutoRootSetup 快速创建主菜单:

object MainMenu : RootRoute {
    override fun render(context: DialogRouteContext) =
        AutoRootSetup(context, mm.deserialize("Main Menu")) {
            "Entity List" to ListRoute
            "Edit" to EditRoute("uuid-1234", "Pig")
            "Settings" to SettingsRoute()
        }
}

生命周期保护

RouteCleanUp 会自动监听玩家断开连接或死亡的事件。如果当前页面是 AtomicRoute,它将触发 onRollback 并清理路由栈,以防止事务泄漏。

完整示例请参阅 src/test/.../route/RouteTest.kt 和 RouteTest2.kt。


许可证

本项目采用 MIT 许可证授权。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源