80 lines
2.6 KiB
Markdown
80 lines
2.6 KiB
Markdown
# 配置可见文本 MiniMessage 支持设计
|
||
|
||
## 背景
|
||
|
||
AuQuestEngine 当前通过 `ColorUtil.color` 将配置中的 `&` 颜色码和 `#RRGGBB` 十六进制颜色转换成 Bukkit legacy 文本。任务配置、语言配置和奖励提示都依赖这个工具，最终通过现有 `sendMessage(String)` 路径发送给玩家。
|
||
|
||
本次目标是让配置里的玩家可见文本支持 MiniMessage，同时保留旧配置兼容性。
|
||
|
||
## 范围
|
||
|
||
纳入 MiniMessage 支持的配置文本：
|
||
|
||
- `lang.yml` 中的语言文本。
|
||
- 任务配置中的 `display_name`。
|
||
- 任务配置中的 `description`。
|
||
- 任务配置中的 `messages.receive`。
|
||
- 任务配置中的 `messages.complete`。
|
||
- 任务配置中的 `rewards.messages`。
|
||
|
||
不纳入本次范围：
|
||
|
||
- `rewards.commands`，它是控制台命令，不是玩家可见文本。
|
||
- 硬编码的命令提示。
|
||
- 控制台日志。
|
||
- 调试输出。
|
||
- API 返回类型调整。
|
||
|
||
## 方案
|
||
|
||
采用兼容式解析：
|
||
|
||
1. `ColorUtil` 继续作为统一文本格式入口。
|
||
2. 旧格式 `&a文本` 和 `#RRGGBB文本` 继续支持。
|
||
3. 新格式 `<green>文本</green>`、`<gradient:red:blue>文本</gradient>` 等 MiniMessage 标签可用于配置文本。
|
||
4. 解析结果仍返回 legacy `String`，保持现有 `Quest`、`QuestReward`、`MessageUtil` 和 API 方法签名不变。
|
||
|
||
## 数据流
|
||
|
||
配置加载后：
|
||
|
||
1. 读取 YAML 原始字符串。
|
||
2. 通过 `ColorUtil.color` 统一解析。
|
||
3. 对 MiniMessage 文本解析成 Adventure `Component`。
|
||
4. 将 `Component` 序列化为 legacy `String`。
|
||
5. 现有发送逻辑继续调用 `sendMessage(String)`。
|
||
|
||
列表文本通过 `ColorUtil.color(List<String>)` 逐行处理。
|
||
|
||
## 兼容性
|
||
|
||
旧配置无需迁移：
|
||
|
||
```yml
|
||
display_name: "&a[初级] &f新手成长之路"
|
||
```
|
||
|
||
新配置可以使用 MiniMessage：
|
||
|
||
```yml
|
||
display_name: "<green>[初级]</green> <white>新手成长之路</white>"
|
||
```
|
||
|
||
如果配置文本混用两种格式，优先保证旧 `&` 颜色码仍能按原行为生效，同时 MiniMessage 标签能被识别。
|
||
|
||
## 错误处理
|
||
|
||
MiniMessage 解析应使用非严格模式，避免配置中未知标签或普通尖括号文本导致任务加载失败。无法识别的文本应尽量保留为可见内容，而不是抛出异常中断插件启用或重载。
|
||
|
||
## 测试
|
||
|
||
新增针对 `ColorUtil` 的测试，覆盖：
|
||
|
||
- legacy `&` 颜色码仍可转换。
|
||
- `#RRGGBB` 仍可转换。
|
||
- MiniMessage 基础颜色标签可转换为 legacy 输出。
|
||
- MiniMessage 装饰标签可转换为 legacy 输出。
|
||
- 列表文本逐行解析。
|
||
|
||
实现前先写失败测试，再实现最小改动使测试通过。
|