高级插件 HMCWraps ⚙️自定义皮肤和颜色用于工具和装备 2026-08-30

HMCWraps 中文使用手册（自编译汉化版）

> 版本：1.8.2（Paper 26.1.2）· 适用服务端：Paper / 其他 Paper 系（支持 Folia）
> 本手册对应"中文化自编译版"：插件消息、命令帮助、配置注释、GUI 默认文本均已汉化。

## 一、这是什么

HMCWraps 是一个"物品皮肤"插件：给武器、工具、盔甲等物品套上一层**纯外观皮肤**（自定义模型 ID、颜色、名称、描述等），不改变物品的属性和附魔，服务端兼容 EULA。

两种皮肤形式：
- **虚拟皮肤**：玩家在 `/wraps` 界面里直接给手持物品套用，免费/权限控制。
- **实体皮肤纸**：一个可以发放、交易的物品（默认是纸），玩家拿它对目标物品使用即可套上皮肤；卸下时按配置决定是否归还皮肤纸。

## 二、安装

1. 把编译好的 `HMCWraps-1.8.2.jar` 放进服务器的 `plugins/` 文件夹。
2. 重启服务器（或 `reload`）。首次启动会自动生成 `plugins/HMCWraps/` 文件夹，里面有：
- `config.yml` —— 主配置（注释已中文化）
- `messages.properties` —— 玩家消息（已中文化，也可自行修改）
- `wraps/` —— 皮肤文件目录（示例：`emerald_wraps.yml`、`silver_wraps.yml`）
- `collections/` —— 合集文件目录（示例：`some_collections.yml`）
3. 开服后执行 `/wraps` 打开皮肤界面，或者 `wraps list` 查看已加载的皮肤。

> 提示：`plugins/HMCWraps/` 里的 `config.yml` 和 `messages.properties` 是**运行时文件**，插件更新后不会覆盖你改过的内容（只补充新增的配置项/消息 key）。所以以后升级插件时，这个文件夹里的中文配置可以一直保留。

## 三、快速上手（给物品做第一个皮肤）

前提：你的服务器有一套物品资源包（物品的 Custom Model Data / Item Model 指向对应模型）。

1. 在 `plugins/HMCWraps/wraps/` 新建一个文件，例如 `my_wraps.yml`：

```yaml
enabled: true
items:
DIAMOND_SWORD:
wraps:
fire_sword:
uuid: 'fire_sword' # 皮肤唯一 ID，全插件不能重复
id: '1' # 自定义模型 ID（或插件钩子）
name: '<red>火焰 <gray>皮肤' # 皮肤界面里显示的名字（MiniMessage 格式）
lore:
- '<gray>让你的剑燃烧起来！'
glow: true # 界面里是否发光
flags:
- 'HIDE_ATTRIBUTES'
physical: # 可选：对应的实体皮肤纸
id: 'PAPER'
model-id: 2
name: '<red>火焰 <gray>皮肤纸'
keep-after-unwrap: true
```

2. 执行 `/wraps reload` 加载。
3. 玩家手持钻石剑，执行 `/wraps` 打开界面，左键点击皮肤即可套用。

## 四、常用命令

所有命令都以 `/wraps` 开头。`[玩家]` 默认是执行者自己（`@s`）。

| 命令 | 作用 | 所需权限 |
|---|---|---|
| `/wraps` | 打开皮肤界面 | `hmcwraps.wraps`（仅当配置开启界面权限检查） |
| `/wraps open <玩家>` | 为其他玩家打开皮肤界面 | `hmcwraps.commands.open` |
| `/wraps reload` | 重载配置与消息 | `hmcwraps.commands.reload` |
| `/wraps wrap <皮肤UUID> [玩家] [-actions]` | 给手持物品套皮肤 | `hmcwraps.commands.wrap` / `.wrap.self` |
| `/wraps unwrap [玩家] [-actions]` | 卸下手持物品的皮肤 | `hmcwraps.commands.unwrap` / `.unwrap.self` |
| `/wraps preview <皮肤UUID> [玩家]` | 预览皮肤效果 | `hmcwraps.commands.preview` |
| `/wraps give wrapper <皮肤UUID> [玩家] [数量]` | 发放实体皮肤纸 | `hmcwraps.commands.give.wrapper` |
| `/wraps give unwrapper [玩家] [数量]` | 发放皮肤卸除纸 | `hmcwraps.commands.give.unwrapper` |
| `/wraps drop <皮肤UUID> <x> <y> <z> [数量]` | 在世界指定坐标丢出皮肤纸 | `hmcwraps.commands.drop` |
| `/wraps list` | 列出所有皮肤与合集 | `hmcwraps.commands.list` |
| `/wraps help` | 查看帮助 | 任意 |
| `/wraps convert [confirm]` | 把 ItemSkins 配置文件转成 HMCWraps 格式 | `hmcwraps.commands.convert` |
| `/wraps create <文件名> <UUID> [合集]` | 用手持物品生成皮肤文件 | `hmcwraps.commands.create` |
| `/wraps debug ...` | 调试信息/配置/皮肤/玩家/物品/日志上传 | `hmcwraps.debug` |

常用权限：
- `hmcwraps.admin` —— 拥有全部命令权限（默认 OP）
- `hmcwraps.management` —— 除 reload / convert 外的所有管理命令
- `hmcwraps.commands.physical` / `.virtual` —— 实体皮肤纸 / 虚拟皮肤相关命令
- `hmcwraps.shortcut.disable` —— 拥有后禁用"潜行+右键"快捷打开

## 五、皮肤文件格式

皮肤文件放在 `plugins/HMCWraps/wraps/`，可以嵌套最多 10 层文件夹。格式：

```yaml
enabled: true
items:
物品A或合集名:
wraps:
皮肤ID:
uuid: '唯一ID'
id: '模型ID或钩子'
name: '<red>皮肤名字'
lore: ['<gray>描述']
glow: true
flags: ['HIDE_ATTRIBUTES']
color: '#FF0000' # 皮革盔甲颜色
enchantments:
SHARPNESS: 3 # 皮肤纸自带的附魔（可选）
permission: '权限节点' # 虚拟套用所需权限
locked-name: '<red>未解锁' # 没权限时界面显示的名字
locked-lore: ['<gray>需要购买']
locked-item:
id: 'BARRIER' # 没权限时界面显示的物品
physical: # 实体皮肤纸
id: 'PAPER'
model-id: 2
name: '<green>皮肤纸'
lore: ['<gray>对物品使用']
keep-after-unwrap: true # 卸下皮肤后是否归还
preview: true # 是否允许预览
sort: 1 # 排序用 ID（越小越靠前）
actions: # 套用皮肤时执行的动作
any:
SOUND:
- 'BLOCK_NOTE_BLOCK_PLING 1 1'
```

高级字段（了解即可）：`wrap-name` / `wrap-lore`（套上皮肤后物品显示的名字/描述）、`wrap-flags`、`wrap-nbt`、`wrap-durability`（模拟耐久）、`armor-imitation`（护甲伪装）、`remove-trim`、`glint-override`、`wrap-tooltip-style`、`wrap-lore-type`、`range`（耐久区间）、`item-model` / `equippable` / `trim` 等新版本组件。

## 六、合集（Collections）

把多个物品归为一个合集，皮肤按合集名配置即可一次套用到全部物品：

```yaml
collections:
SWORDS:
- 'NETHERITE_SWORD'
- 'DIAMOND_SWORD'
- 'IRON_SWORD'
```

合集文件放在 `plugins/HMCWraps/collections/`。

## 七、GUI 界面

`config.yml` 的 `inventory:` 节可以自定义界面：
- `title`：界面标题（默认"皮肤"）
- `type`：`PAGINATED`（分页）或 `SCROLLING`（滚动）；`rows`：行数
- `sort-order`：排序优先级（收藏 / 权限 / 排序 ID / 模型 ID）
- `shortcut.enabled`：潜行+右键快捷打开
- `item-change-enabled`：界面内切换物品不关界面
- `target-item-slot`：显示手持物品的格子
- `items`：自定义固定物品（按钮、装饰），支持 `fills` 填充多个格子

### 界面动作（Actions）

在皮肤的 `actions` / `inventory-actions` 或界面的 `inventory.items.*.actions` 中配置，键为点击方式（`left` / `right` / `any`），值为动作列表：

`PARTICLE`、`PARTICLE_MULTI`、`SOUND`、`TITLE`、`SUBTITLE`、`ACTIONBAR`、`MESSAGE`、`COMMAND`、`CONSOLE_COMMAND`、`SCROLL_FORTH`、`SCROLL_BACK`、`NEXT_PAGE`、`PREVIOUS_PAGE`、`UNWRAP`、`CLOSE_INVENTORY`、`TOGGLE_FILTER`、`CLEAR_FAVORITES`、`SET_FAVORITE`、`WRAP`、`PREVIEW`。

## 八、常见问题

**Q：套上皮肤后物品外观没变化？**
检查资源包是否加载了对应模型；确认 `id`（模型 ID）与资源包一致；确认材质不是 AIR。

**Q：中文会不会乱码？**
本汉化版已修复消息文件的 UTF-8 读取问题，`messages.properties` 可以直接写中文。若以后用原版，需要把中文转成 `\uXXXX` 转义。

**Q：为什么玩家在界面里看到的是"未解锁"？**
皮肤配置了 `permission`，玩家没有对应权限。`config.yml` 的 `permissions:` 节可以调整是否检查权限。

**Q：改完配置怎么生效？**
`/wraps reload`（无需重启服务器）。

**Q：实体皮肤纸怎么给玩家？**
`/wraps give wrapper <皮肤UUID> <玩家>`；卸除纸用 `/wraps give unwrapper <玩家>`。

## 九、与其他插件联动（ItemsAdder / Oraxen / Nexo 等）

HMCWraps 原生支持一批自定义物品插件，都是**软依赖**：装了对应插件就自动启用集成，不装也不影响插件本身运行。

支持的插件：**ItemsAdder、Oraxen、Nexo、MythicMobs（MythicCrucible）、CraftEngine、ExecutableItems、MMOItems**；此外还有 PlaceholderAPI 变量，以及 zAuctionHouse / AuctionGUI+ / AxAuctions / AxTrade 拍卖交易集成（在 `config.yml` 的 `integrations:` 节配置）。

### 以 ItemsAdder 为例

皮肤配置里的 `id` 字段可以直接填 ItemsAdder 物品 ID（格式 `itemsadder:命名空间:物品ID`）。套上皮肤后，物品会变成该 ItemsAdder 物品的外观（模型、发光、颜色都走 ItemsAdder 的配置），卸下皮肤时自动还原原来的物品：

```yaml
items:
DIAMOND_SWORD:
wraps:
fire_sword:
uuid: 'fire_sword'
id: 'itemsadder:my_items:fire_sword'
name: '<red>火焰 <gray>皮肤'
```

`itemsadder:` 前缀同样可以用在这些位置：

- 实体皮肤纸材质：`physical.id`，例如 `id: 'itemsadder:my_items:wrap_paper'`
- GUI 未解锁时显示的物品：`locked-item.id`
- 全局禁用：`config.yml` 的 `global-disable.itemsadder` 列表，禁止指定 ItemsAdder 物品被套皮肤

另外 `/wraps create` 支持直接从手里的 ItemsAdder 自定义物品生成皮肤文件。

注意：使用 `itemsadder:` 前缀的前提是服务器已安装 ItemsAdder。Oraxen（`oraxen:`）、Nexo（`nexo:`）、Mythic（`mythic:`）等其他插件用法相同，只是前缀不同。