¶ XinxinArmourer 时装插件使用教程
¶ 插件简介
- 高版本的玩家时装插件
- 支持任意实体穿戴时装（测试版）
- 时装数据支持 YAML 文件存储和 MySQL 数据库存储两种方式
- 提供了时装衣柜 GUI，玩家可以通过界面直接放入/取出时装物品来穿戴或脱下时装
- 内置了 MoBends 动作系统支持，可以实现更丰富的时装动作
- 目前兼容龙时 bbmodel 格式时装
¶ 核心兼容
🚀 当前版本： 1.21.1 Fabric
📈 未来计划：
核心兼容 Forge/NeoForge + 1.20.x | 1.21
计划更新兼容更多时装格式
¶ 前置插件
- XinxinPluginCore 1.2.0 版本或以上
¶ 前置模组
- GeckoLib 4.7.7 版本或以上
¶ 添加时装文件
插件加载成功后会在插件文件夹中自动创建 skins 目录，将你制作好的 .bbmodel 时装模型文件放入 skins 文件夹即可
支持在 skins 下创建子文件夹进行分类管理，插件会递归加载所有 .bbmodel 文件
放入文件后执行 /xxa reload 或重启服务器即可加载新的时装
文件夹结构示例：
plugins/XinxinArmourer/skins/
├── 芙莉莲.bbmodel
├── 星野爱.bbmodel
├── 翅膀/
│ └── 天使翅膀.bbmodel
└── 套装/
├── 圣诞套装.bbmodel
└── 万圣节套装.bbmodel
注意： 时装名称就是文件名（不含
.bbmodel后缀），请避免同名文件
¶ 指令权限 & 介绍
[] 为必填项，<> 为可选项
插件主命令为 /cosmetic，同时支持别名 /cos 和 /xxa
以下示例均使用最简短的别名 /xxa
¶ 玩家基础指令
| 命令 | 说明 | 权限 | 默认 |
|---|---|---|---|
/xxa gui |
打开时装衣柜界面 | xinxinarmourer.gui |
所有玩家 |
/xxa info |
查看自己当前穿戴的时装 | 无 | 所有玩家 |
¶ 管理员指令
| 命令 | 说明 | 权限 | 默认 |
|---|---|---|---|
/xxa help |
显示帮助信息 | 无 | 所有玩家 |
/xxa reload |
重载配置文件和时装文件 | xinxinarmourer.admin |
OP |
/xxa list |
列出所有已加载的时装 | 无 | 所有玩家 |
¶ 时装物品指令
| 命令 | 说明 | 权限 | 默认 |
|---|---|---|---|
/xxa give [玩家] [时装名] <数量> |
给予玩家时装物品 | xinxinarmourer.give |
OP |
¶ 穿戴管理指令
| 命令 | 说明 | 权限 | 默认 |
|---|---|---|---|
/xxa wear [玩家] [时装名] |
让指定玩家穿戴时装 | xinxinarmourer.wear |
OP |
/xxa remove [玩家] [时装名] |
让指定玩家脱下指定时装 | xinxinarmourer.wear |
OP |
/xxa removeall [玩家] |
让指定玩家脱下所有时装 | xinxinarmourer.wear |
OP |
/xxa info [玩家] |
查看指定玩家穿戴的时装 | 无 | 所有玩家 |
¶ 实体时装指令
| 命令 | 说明 | 权限 | 默认 |
|---|---|---|---|
/xxa entity [实体ID] [时装名] <hide> |
给实体设置时装，加 hide 隐藏原始模型 |
xinxinarmourer.entity |
OP |
/xxa entityremove [实体ID] |
移除实体的时装 | xinxinarmourer.entity |
OP |
/xxa entitynear [时装名] <范围> <hide> |
给最近的非玩家实体设置时装，默认范围 10 格 | xinxinarmourer.entity |
OP |
/xxa entityclear <范围> |
移除范围内所有实体的时装，默认范围 10 格 | xinxinarmourer.entity |
OP |
/xxa entitydata [实体UUID] |
清除指定实体 UUID 的时装缓存和存储数据 | xinxinarmourer.admin |
OP |
¶ 快速上手
¶ 第一步：安装插件和模组
- 将
XinxinPluginCore和XinxinArmourer插件放入服务端plugins文件夹 - 启动服务器，填写
key.yml中的授权码，重启服务器 - 客户端安装对应版本的 XinxinArmourer 模组
¶ 第二步：添加时装
将 .bbmodel 时装模型文件放入 plugins/XinxinArmourer/skins/ 文件夹，然后执行 /xxa reload 重载时装
执行 /xxa list 可以查看所有已加载的时装列表
¶ 第三步：给玩家时装物品
执行 /xxa give 玩家名 时装名 即可给玩家一个时装物品
比如你有一个叫 芙莉莲 的时装文件：
/xxa give Steve 芙莉莲
这样就会给 Steve 一个芙莉莲的时装物品
¶ 第四步：使用时装衣柜
玩家执行 /xxa gui 即可打开时装衣柜界面
时装衣柜使用流程：
- 执行
/xxa gui打开衣柜 - 衣柜中会显示你当前已穿戴的时装（以物品形式展示）
- 从背包中将时装物品拖入衣柜 → 关闭后自动穿戴
- 从衣柜中将时装物品拖回背包 → 关闭后自动脱下
- 放入非时装物品时会被拒绝并提示
¶ 第五步：使用命令穿戴（管理员）
除了使用时装衣柜，管理员也可以通过命令直接让玩家穿戴时装，同时会在时装衣橱中添加对应的时装物品
/xxa wear Steve 芙莉莲 # 让 Steve 直接穿戴芙莉莲时装（无需物品）
/xxa remove Steve 芙莉莲 # 让 Steve 脱下芙莉莲时装
¶ 实体时装（内测版）
插件支持给服务器中的非玩家实体（如村民、动物等）穿戴时装
¶ 给附近实体穿时装
面朝目标实体，执行：
/xxa entitynear 芙莉莲
这会给你最近的实体穿上芙莉莲时装
如果要隐藏实体原始模型，在命令末尾加上 hide：
/xxa entitynear 芙莉莲 10 hide
这样 10 格范围内最近的实体会穿上时装并隐藏原始模型
¶ 通过实体 ID 穿时装
如果你知道实体的 ID（可以用 F3 查看），也可以直接指定：
/xxa entity 123 芙莉莲 hide
¶ 移除实体时装
/xxa entityremove 123 # 移除指定实体 ID 的时装
/xxa entityclear 20 # 移除你周围 20 格范围内所有实体的时装
提示： 实体时装数据会自动持久化保存，服务器重启后依然有效
¶ 配置文件说明
插件的配置文件位于 plugins/XinxinArmourer/config.yml
¶ 存储配置
默认使用 YAML 文件存储，数据保存在 plugins/XinxinArmourer/data/ 目录下
如果需要使用 MySQL 数据库存储，可以修改以下配置：
storage:
mysql:
enabled: true
host: localhost
port: 3306
database: xinxinarmourer
username: root
password: "你的密码"
启用 MySQL 后如果连接失败会自动回退到 YAML 存储模式
¶ 时装物品配置
可以自定义时装物品的外观：
item:
# 物品材质（Minecraft 物品英文ID，需全大写）
material: PAPER
# 物品名称（%cosmetic% 会替换为时装名称）
name: "&b时装: &f%cosmetic%"
# 物品描述（%cosmetic% = 时装名称，%type% = 时装类型）
lore:
- "&7类型: %type%"
- ""
¶ 时装衣柜配置
可以自定义衣柜界面的标题和提示消息：
gui:
title: "&b&l时装衣柜"
not_cosmetic_item: "&c该物品不是时装物品，无法放入时装衣柜！"
cosmetic_not_found: "&c该时装物品对应的时装不存在！"
¶ 消息配置
可以自定义各种提示消息：
messages:
wear_success: "&a你已穿戴时装: %cosmetic%"
remove_success: "&a你已脱下时装: %cosmetic%"
cosmetic_not_found: "&c时装 %cosmetic% 不存在!"
no_permission: "&c你没有权限执行此操作!"
所有消息支持
&颜色代码
¶ API 接口
插件提供了 CosmeticAPI 供其他插件调用
¶ 获取 API
CosmeticAPI api = XinxinArmourerPlugin.getInstance().getCosmeticAPI();
¶ 穿戴 / 脱下时装
api.wearCosmetic(player, "时装名"); // 穿戴时装
api.removeCosmetic(player, "时装名"); // 脱下指定时装
api.removeAllCosmetics(player); // 脱下所有时装
¶ 查询时装
api.getPlayerCosmetics(player); // 获取玩家穿戴的所有时装
api.hasCosmetic(player, "时装名"); // 检查是否穿戴了指定时装
api.cosmeticExists("时装名"); // 检查时装是否存在
api.getAllCosmeticNames(); // 获取所有已加载的时装名称
¶ 时装物品操作
api.isCosmeticItem(itemStack); // 检查物品是否是时装物品
api.getCosmeticNameFromItem(itemStack); // 获取物品对应的时装名称
api.createCosmeticItem("时装名", 数量); // 创建时装物品
api.addCosmeticDataToItem(itemStack, "时装名"); // 给物品添加时装数据
api.removeCosmeticDataFromItem(itemStack); // 移除物品的时装数据
¶ 同步
api.syncPlayerCosmetics(player); // 同步玩家时装到所有可见玩家
¶ 常见问题
Q：玩家进服看不到时装？
A：确保客户端安装了对应版本的 XinxinArmourer 模组，插件需要模组配合才能渲染时装
Q：添加了时装文件但 /xxa list 看不到？
A：确保文件后缀是 .bbmodel 且放在 skins 文件夹内，然后执行 /xxa reload
Q：玩家重新进服后时装还在吗？
A：是的，时装穿戴数据会自动持久化保存（YAML 或 MySQL），玩家重新进服后会自动加载
Q：实体时装重启后还在吗？
A：是的，实体时装数据也会持久化保存，服务器重启后会自动恢复
Q：如何给所有玩家开放时装衣柜？
A：默认所有玩家都有 xinxinarmourer.gui 权限，可以直接使用 /xxa gui
Q：插件有 Bug 怎么办？
A：请联系作者 QQ: 1072565329，附上完整的报错日志
¶ 插件使用情况
