paper-plugins-skill

name	paper-plugins-skill
description	提供 Paper 插件开发技能，包括 Dialog API、Adventure API 等核心 API 的实际使用模式和最佳实践。适用于开发 Paper 插件、GUI 界面、消息系统等场景。

Paper 插件开发技能

此技能适用于 Paper 插件开发。严格遵循此技能的要求，优先使用 Paper 提供的现代 API。

使用时机

• 开发 Paper 插件
• 创建 GUI 界面（使用 Dialog API）
• 发送消息和格式化文本（使用 Adventure API）
• 处理用户输入和交互
• 实现命令系统

核心原则

1. 优先使用 Paper API：使用 Paper 提供的 API 而非 Bukkit API
2. 使用 Adventure API：所有文本消息使用 Component 而非 String
3. 使用 Dialog API：所有 GUI 使用 Dialog API 而非传统 Inventory GUI
4. 参考官方文档：https://docs.papermc.io/paper/dev/
5. Javadoc 参考：https://jd.papermc.io/paper/1.21.11/

快速参考

Dialog API

用于创建 GUI 界面和对话框。详见 dialog-api.md

Adventure API

用于文本消息和组件。详见 adventure-api.md

Command API

用于创建命令。详见 command-api.md

Persistent Data Container (PDC)

用于在方块和实体上存储自定义数据。详见 pdc.md

Particles

用于生成粒子效果。详见 particles.md

Registries

用于注册和检索游戏内容。详见 registries.md

plugin.yml

插件配置文件。详见 plugin-yml.md

Display Entities

用于显示文本、方块和物品实体。详见 display-entities.md

Data Components

用于访问和修改物品数据。详见 data-components.md

Scheduling

用于调度任务执行。详见 scheduling.md

Plugin Configuration

用于创建和管理配置文件。详见 plugin-configuration.md

Recipes

用于创建自定义合成配方。详见 recipes.md

Database

数据库使用最佳实践。详见 database.md

Serialization

序列化最佳实践。详见 serialization.md

项目结构建议

Dialog 处理架构

listeners/
├── DialogListener.java          # 主路由，分发到各个 Handler
└── dialog/
    ├── BaseDialogHandler.java   # 基类
    ├── MessengerDialogHandler.java
    ├── TelegraphDialogHandler.java
    └── ...

GUI 管理架构

gui/
├── GUIManager.java              # GUI 管理器
├── main/
│   └── MainMenuGUI.java        # 主菜单
└── ...

参考文档

本地文档

当遇到 Paper API 实现问题时，可以访问下述文件查询 Javadoc API 和文档

• Paper Javadoc 概要
• Paper 开发文档

在线文档

• Paper 开发文档：https://docs.papermc.io/paper/dev/
• Dialog API 文档：https://docs.papermc.io/paper/dev/dialogs/
• Command API 文档：https://docs.papermc.io/paper/dev/command-api/basics/introduction/
• Adventure API 文档：https://docs.papermc.io/paper/dev/component-api/introduction/
• Persistent Data Container：https://docs.papermc.io/paper/dev/pdc/
• Particles 文档：https://docs.papermc.io/paper/dev/particles/
• Registry API 文档：https://docs.papermc.io/paper/dev/registries/
• Display Entities 文档：https://docs.papermc.io/paper/dev/display-entities/
• Data Components 文档：https://docs.papermc.io/paper/dev/data-component-api/
• Scheduling 文档：https://docs.papermc.io/paper/dev/scheduler/
• Plugin Configuration 文档：https://docs.papermc.io/paper/dev/plugin-configurations/
• Recipes 文档：https://docs.papermc.io/paper/dev/recipes/
• plugin.yml 文档：https://docs.papermc.io/paper/dev/plugin-yml/
• Using databases 文档：https://docs.papermc.io/paper/dev/using-databases/

Context 7 MCP 文档

除此之外，还可以调用 Context 7 MCP 获取文档内容，与 Paper 相关的相关文档的 libraryid 如下：

• /websites/papermc_io_paper_dev
• /websites/jd_papermc_io_paper_1_21_11

编译与构建

运行 ./gradlew build（在 bash）或 ./gradlew.bat build（在 cmd） 以构建插件；在任何功能开发完成后请务必运行一次编译构建以检查是否有报错。 可以使用 ./gradlew check 检查代码质量问题。

常见问题

详见 faq.md