原创 闭源 DoJewelry-1.0.0 一款可自定义的饰品背包插件 兼容1.12.2-1.21.11 1.12.2-1.21.11

# DoJewelry Wiki
作者：明东
技术交流群1038832814
DoJewelry 是一个兼容 AttributePlus 的饰品插件。玩家可以通过饰品界面装备饰品，插件会把饰品物品交给 AttributePlus 读取属性，并支持饰品背包、槽位解锁、金币/点券/物品消耗、YAML/MySQL 数据存储。
## 兼容版本
- Minecraft: `1.12.2 - 1.21.11`
- Java: `Java 8+`
- 服务端: Bukkit / Spigot / Paper
> 注意：DoJewelry 本体已做跨版本处理，但 AttributePlus、Vault、PlayerPoints 也必须使用对应服务端版本可用的插件。
## 依赖插件
必装：
- AttributePlus
可选：
- Vault：用于金币解锁
- PlayerPoints：用于点券解锁
- PlaceholderAPI：当 PlayerPoints API 不可用时，可作为点券余额备用读取方式
## 安装方法
1. 把 `DoJewelry-1.0.0.jar` 放入服务器 `plugins` 文件夹。
2. 确认已安装 AttributePlus。
3. 如果需要金币解锁，安装 Vault 和经济插件。
4. 如果需要点券解锁，安装 PlayerPoints。
5. 启动服务器生成配置。
6. 修改 `plugins/DoJewelry/config.yml`、`storage.yml`、`messages.yml`。
7. 使用 `/dojewelry reload` 重载插件。
发布用混淆版文件：
```text
DoJewelry-1.0.0-obfuscated.jar
```
不要把普通版和混淆版同时放进 `plugins`，它们插件名相同，会冲突。
## 命令
| 命令 | 权限 | 说明 |
| --- | --- | --- |
| `/dojewelry` | `dojewelry.open` | 打开自己的饰品界面 |
| `/dj` | `dojewelry.open` | `/dojewelry` 的别名 |
| `/dojewelry open <玩家>` | `dojewelry.admin` | 为指定玩家打开饰品界面 |
| `/dojewelry reload` | `dojewelry.admin` | 重载配置、存储和消息 |
## 权限
```yml
dojewelry.open:
default: true
dojewelry.admin:
default: op
```
## 配置文件
插件会生成三个主要配置：
```text
plugins/DoJewelry/config.yml
plugins/DoJewelry/storage.yml
plugins/DoJewelry/messages.yml
```
### config.yml
主配置，控制界面、饰品槽、背包、点券备用方案。
### storage.yml
数据存储配置，支持：
- `yaml`
- `mysql`
### messages.yml
消息文本配置，支持 `&` 颜色代码。
## 界面布局
DoJewelry 使用字符布局控制界面槽位。
每一行必须是 9 个字符，行数必须和 `gui.size` 对应。
示例：
```yml
gui:
title: "&8饰品"
size: 54
layout:
- "*********"
- "*********"
- "**A*C*D**"
- "*BBBBBBB*"
- "*BBBBBBB*"
- "*********"
```
字符含义：
| 字符 | 含义 |
| --- | --- |
| `*` | 普通填充格，无功能 |
| `A/C/D` | 饰品槽，对应 `slots.A`、`slots.C`、`slots.D` |
| `B` | 饰品背包格，对应 `backpack.layout-key: "B"` |
一行九格中间放一个饰品槽：
```yml
- "****A****"
```
对应配置：
```yml
slots:
A:
attribute-enabled: true
default-unlocked: true
```
## 饰品槽配置
示例：
```yml
slots:
A:
attribute-enabled: true
default-unlocked: true
accept:
name-regex: ".*戒指.*"
lore-mode: any
lore-regex:
- ".*饰品.*"
- ".*戒指.*"
empty-icon:
material: AMETHYST_SHARD
name: "&d戒指槽"
lore:
- "&7放入名称或 Lore 含戒指/饰品的物品"
- "&7属性状态: &a生效"
locked-icon:
material: BARRIER
name: "&c戒指槽未解锁"
lore:
- "&7点击解锁"
unlock:
money: 0
points: 0
items: []
```
### attribute-enabled
是否让该槽位里的饰品属性生效。
```yml
attribute-enabled: true
```
- `true`：饰品会加入 AttributePlus 属性源
- `false`：饰品可以放入和保存，但不加属性
### default-unlocked
玩家是否默认解锁该槽位。
```yml
default-unlocked: false
```
- `true`：玩家初始可用
- `false`：需要点击锁定图标并支付解锁消耗
### accept
限制哪些物品可以放入该槽。
```yml
accept:
name-regex: ".*戒指.*"
lore-mode: any
lore-regex:
- ".*饰品.*"
- ".*戒指.*"
```
规则：
- `name-regex`：匹配物品显示名，留空表示不检查名称
- `lore-regex`：匹配物品 Lore，留空列表 `[]` 表示不检查 Lore
- `lore-mode: any`：任意一条 Lore 正则命中即可
- `lore-mode: all`：每一条 Lore 正则都必须命中
如果名称和 Lore 都配置了，两个条件都必须满足。
## 槽位解锁
解锁支持三种消耗：
- 金币
- 点券
- 物品
示例：
```yml
unlock:
money: 10000
points: 50
items:
- material: EMERALD
amount: 3
name-regex: ""
lore-mode: all
lore-regex: []
```
### 金币
依赖 Vault 和经济插件。
```yml
money: 10000
```
### 点券
优先调用 PlayerPoints API。
```yml
points: 50
```
如果 PlayerPoints API 不可用，会使用 `points.balance-placeholder` 和 `points.take-command` 备用方案。
### 物品
```yml
items:
- material: EMERALD
amount: 1
name-regex: ""
lore-mode: all
lore-regex: []
```
物品条件说明：
| 字段 | 说明 |
| --- | --- |
| `material` | Bukkit 材质名 |
| `amount` | 需要数量 |
| `name-regex` | 显示名正则，留空不检查 |
| `lore-mode` | `any` 或 `all` |
| `lore-regex` | Lore 正则列表 |
## 饰品背包
饰品背包用于保存备用饰品，不会添加 AttributePlus 属性。
示例：
```yml
backpack:
enabled: true
layout-key: "B"
accept:
name-regex: ""
lore-mode: any
lore-regex:
- ".*饰品.*"
- ".*戒指.*"
- ".*项链.*"
- ".*护符.*"
empty-icon:
material: GRAY_STAINED_GLASS_PANE
name: "&7饰品背包"
lore:
- "&7可存放备用饰品"
```
`layout-key: "B"` 表示界面布局里所有 `B` 都是背包格。
```yml
layout:
- "*BBBBBBB*"
- "*BBBBBBB*"
```
上面会生成 14 个饰品背包格。
## 点券配置
```yml
points:
balance-placeholder: "%playerpoints_points%"
take-command: "points take %player% %amount%"
```
变量：
| 变量 | 说明 |
| --- | --- |
| `%player%` | 玩家名 |
| `%uuid%` | 玩家 UUID |
| `%amount%` | 扣除数量 |
正常安装 PlayerPoints 时，插件会优先调用 PlayerPoints API，不依赖命令扣点。
## 数据存储
### YAML
适合单服：
```yml
type: yaml
```
数据保存到：
```text
plugins/DoJewelry/data.yml
```
### MySQL
适合多服共享或集中备份：
```yml
type: mysql
mysql:
host: "127.0.0.1"
port: 3306
database: "minecraft"
username: "root"
password: "password"
table-prefix: "dojewelry_"
use-ssl: false
connection-timeout-ms: 5000
```
插件会自动创建三张表：
| 表 | 说明 |
| --- | --- |
| `<prefix>unlocked` | 玩家槽位解锁数据 |
| `<prefix>items` | 玩家已装备饰品数据 |
| `<prefix>backpack` | 玩家饰品背包数据 |
## AttributePlus 属性生效方式
DoJewelry 不直接解析属性数值。
流程：
1. 玩家把饰品放入槽位。
2. 插件检查槽位是否解锁、物品是否允许放入。
3. 如果 `attribute-enabled: true`，插件把该物品加入 AttributePlus 属性源。
4. AttributePlus 根据物品 Lore 读取属性。
5. 玩家关闭界面或更换饰品后，属性会刷新。
因此，饰品物品的属性格式需要符合 AttributePlus 的 Lore 规则。
## 常见问题
### 放入饰品后没有属性
检查：
- 该槽位是否 `attribute-enabled: true`
- 物品 Lore 是否符合 AttributePlus 属性格式
- AttributePlus 是否正常加载
- 玩家是否已经解锁该槽位
### 物品不能放入槽位
检查：
- `accept.name-regex` 是否匹配物品显示名
- `accept.lore-regex` 是否匹配物品 Lore
- `lore-mode` 是 `any` 还是 `all`
### 背包格没有出现
检查：
- `backpack.enabled` 是否为 `true`
- `backpack.layout-key` 的字符是否写在 `gui.layout` 里
- 每一行布局是否正好 9 个字符
### 低版本材质不存在怎么办
插件会自动对部分高版本材质做 fallback。
例如：
- `AMETHYST_SHARD` 在 1.12.2 不存在时会退回到旧版可用材质
- `GRAY_STAINED_GLASS_PANE` 在旧版会退回到旧版玻璃板或玻璃
### 修改 slots 节点名会怎样
`slots` 节点名也是数据 ID。
例如：
```yml
slots:
A:
```
玩家数据会保存到 `A`。
如果你把 `A` 改成 `ring`，旧的 `A` 数据不会自动迁移。


- 兼容版本：`1.12.2 - 1.21.11`
- 必装依赖：`AttributePlus`
- 可选依赖：`Vault`、`PlayerPoints`、`PlaceholderAPI`
- 数据支持：`YAML / MySQL`
- 属性来源：`AttributePlus Lore 属性`