时装工坊 LyArmourers
LyArmourers 是面向 Minecraft 1.7.10 的时装系统，由 Bukkit 服务端插件和 Forge 客户端 MOD 组成。
服务端负责读取时装库、处理指令与权限、生成时装物品、保存玩家和实体时装、同步模型动作与特效配置；客户端负责管理界面、模型预览、玩家与实体渲染、手持物品渲染、更多动作骨骼兼容以及刀光、脚印、幻影等视觉效果。
项目不是完整的时装制作工具。时装文件需要提前制作并放入服务端时装库，玩家通过客户端界面选择、预览、穿戴或写入物品。
项目信息
| 项目 | 内容 |
|---|---|
| 项目类型 | Bukkit 服务端插件与 Forge 客户端 MOD 混合项目 |
| 项目版本 | 1.0.0 |
| Minecraft 版本 | 1.7.10 |
| Forge 版本 | 1.7.10-10.13.4.1614-1.7.10 |
| Java 版本 | Java 8 |
| 客户端 MOD ID | lyarmourers |
| 服务端插件名 | LyArmourers |
| 服务端主命令 | /lyarmourers |
| 命令别名 | /lysz |
| 业务消息通道 | armourers |
| 粒子消息通道 | lycustom:main |
| 粒子兼容通道 | lycustom |
项目组成
| 模块 | 安装位置 | 用途 |
|---|---|---|
PLUGIN-LyArmourers-1.0.0.jar | Bukkit 服务端的 plugins 目录 | 提供配置加载、时装库、指令、权限、实体时装、物品生成、插件消息、监听器和 API |
MOD-LyArmourers-1.0.0.jar | 每位玩家客户端的 mods 目录 | 提供 Forge 客户端界面、模型读取、模型渲染、动作兼容、物品预览和视觉特效 |
服务端插件与客户端 MOD 需要使用配套版本。
客户端 MOD 是显示和操作时装功能的必要组成部分。未安装客户端 MOD 的玩家无法使用管理界面，也无法看到 .armour、.lyarmourers、.bbmodel 模型以及刀光、脚印、幻影和 LyCustom 粒子效果。
依赖与兼容
| 项目 | 类型 | 说明 |
|---|---|---|
| Minecraft Forge | 客户端必需 | 客户端 MOD 使用 Forge 1.7.10-10.13.4.1614-1.7.10 |
| PlaceholderAPI | 可选软依赖 | 安装后注册 %lysz_部位% 时装显示状态变量 |
| CustomNPCs | 可选兼容 | 客户端可为 noppes.npcs.entity.EntityCustomNpc 渲染 .armour 和 .bbmodel 时装 |
服务端插件和客户端 MOD 只通过插件消息通信。服务端代码不会直接调用客户端 MOD 类。
玩法与数据流
- 服务端管理员把支持的时装文件放入
plugins/LyArmourers/skins。 - 玩家通过
/lyarmourers manager打开客户端时装管理界面。 - 客户端向服务端请求目录、时装类型和预览文件。
- 玩家可以把时装写入背包物品、获取新的时装物品，或合并多个
.armour文件。 - 实体管理界面可以为附近玩家、生物和 CustomNPCs NPC 设置临时时装或永久时装。
- 服务端通过插件消息同步时装路径、实体状态、模型动作和视觉特效，客户端负责实际读取与渲染。
时装库支持多层目录。客户端只能读取服务端时装库索引中存在的文件，路径会经过清理和目录穿越保护，不能通过 .. 访问时装库之外的文件。
支持的时装格式
| 格式 | 说明 |
|---|---|
.armour | Armourer's Workshop 时装文件，使用内置兼容读取、烘焙和渲染流程 |
.lyarmourers | 本项目兼容后缀，按照 .armour 流程读取和渲染 |
.bbmodel | 支持 Blockbench 工程、Bedrock geometry 和 LyCustom ModelData 包装 |
.armour 合成功能只接受真实 .armour 源文件，不能把 .bbmodel 合成为 .armour。合成结果保存在 plugins/LyArmourers/skins/时装合成。
.bbmodel 支持的 geometry 版本为 1.12.0、1.10.0 和 1.8.0。模型可以包含贴图、发光贴图、类型设置、部位隐藏设置、动画关键帧、表达式和粒子事件。
主要功能
时装库与管理界面
- 浏览服务端时装库及多层目录。
- 按名称和时装类型筛选文件。
- 请求并缓存
.armour、.lyarmourers和.bbmodel预览。 - 把时装拖拽到背包物品并写入时装 NBT。
- 以配置的物品模板生成新时装物品。
- 合并多个
.armour时装并保存为新的.armour文件。 - 服务端自动对大型预览文件进行分片传输。
玩家与物品时装
- 渲染玩家头部、身体、腿部、脚部、翅膀和套装时装。
- 渲染剑、弓、镐、斧、铲、锄、盾牌、方块和普通物品时装。
- 支持玩家原版头盔、胸甲、护腿和鞋子槽位中的时装物品。
- 支持背包和快捷栏中的时装模型图标。
- 支持鼠标悬停时在物品提示旁显示模型预览。
- 支持第一人称右臂替换和第一人称手持时装。
- 支持第三人称手持物品与更多动作右手、前臂骨骼挂点。
时装物品使用以下 NBT：
text
LyArmourers
└─ skin: Stringskin 保存去除空白字符后的末级时装文件名 ID。客户端收到全库索引后，再把该 ID 解析为服务端时装库中的真实相对路径。
物品自身的时装 NBT 只改变该物品的外观，不代表把同一时装穿到玩家身体上。
实体时装
- 列出玩家附近
16格内已经加载的玩家、生物和 CustomNPCs NPC。 - 按距离从近到远显示实体，距离相同时按实体 ID 排序。
- 为实体设置临时时装或永久时装。
- 永久数据写入实体 ForgeData NBT，并同步维护
entity-skins.yml索引。 - 临时时装在当前服务端会话内有效，服务端重启后失效。
- 实体加载、区块加载、实体生成和玩家进入服务器时自动同步时装。
- 客户端发现可见实体没有缓存时，会主动请求该实体的时装列表。
- 运行时实体 ID 优先用于定位非玩家实体，减少客户端与服务端 UUID 不一致造成的保存错误。
在目标 Forge/Cauldron 1.7.10 环境中，永久实体时装采用实体 NBT 与 YAML 索引双写。在无法访问 Forge getEntityData() 的纯 Bukkit 环境中，NBT 操作会安全失败，并继续使用 YAML 索引保存和同步。
模型与动作
- 将
.armour时装接入更多动作的上臂、前臂、大腿和小腿骨骼。 - 将玩家
.bbmodel标准骨骼绑定到更多动作玩家模型。 - 自动选择
idle、walk、run、sprint、sneak、attack和swing等动作。 - 支持连续攻击重播与攻击连击动作。
- 支持由服务端强制播放或停止实体模型动作。
- 支持循环动作和动作切换过渡时间的 API 控制。
- CustomNPCs NPC 保留自身动作系统，时装只读取当前
ModelMPM部位矩阵，不会覆盖 NPC 的动作计算。
视觉特效
- 为指定玩家开启第三人称奔跑骨骼幻影。
- 配置幻影寿命、绘制间隔、姿态快照间隔、最大数量和透明度。
- 为指定玩家绑定自定义刀光配置。
- 为指定玩家绑定自定义脚印配置。
- 支持刀光和脚印静态图片或 GIF。
- 支持脚印缩放、宽度、长度、透明度、旋转、移动和颜色动画。
- 支持 LyCustom 粒子消息，当前固定对外粒子名为
暴雪粒子。
刀光和脚印的 YAML 由服务端同步，实际图片或 GIF 不会由服务端传输，需要放在玩家客户端：
| 特效 | 客户端资源目录 |
|---|---|
| 刀光 | resourcepacks/LyArmourers/SwordTrails/ |
| 脚印 | resourcepacks/LyArmourers/FootPrints/ |
服务端配置概览
默认配置位于 plugins/LyArmourers/config.yml。
| 配置项 | 说明 |
|---|---|
debug | 是否记录非查询 API 的详细调用来源与参数 |
render-player-equipment-skins | 是否渲染玩家原版四个装备槽中带时装 NBT 的物品 |
render-item-skin-preview | 是否显示物品槽位时装模型图标和鼠标悬停预览 |
afterimage.lifetime-ticks | 单份幻影的存在时间，单位 tick |
afterimage.draw-interval-ticks | 把最近姿态加入可见幻影队列的最小间隔 |
afterimage.snapshot-interval-ticks | 从真实玩家模型读取骨骼姿态的最小间隔 |
afterimage.maximum-count | 单个玩家同时保留的最大幻影数量 |
afterimage.alpha | 最新幻影的不透明度，范围 0 到 255 |
item.material | 新时装物品使用的基础材质 |
item.name | 新时装物品的显示名称模板 |
item.lore | 新时装物品的 Lore 模板 |
物品名称和 Lore 支持 & 颜色代码，并支持 {skin} 和 {player} 变量。
指令
主命令为 /lyarmourers，别名为 /lysz。
| 指令 | 说明 | 权限 |
|---|---|---|
/lyarmourers manager [玩家] | 为自己或指定在线玩家打开时装管理界面 | lyarmourers.manager |
/lyarmourers entity [玩家] | 为自己或指定在线玩家打开实体时装界面 | lyarmourers.manager |
/lyarmourers setskin <时装ID> | 把指定时装 ID 写入当前手持物品，不改变材质、数量、名称和 Lore | lyarmourers.manager |
/lyarmourers animation <在线玩家> play <动作名> | 强制目标玩家播放一次模型动作 | lyarmourers.manager |
/lyarmourers animation <在线玩家> stop | 停止目标玩家的强制动作并恢复自动动作 | lyarmourers.manager |
/lyarmourers afterimage <在线玩家> <on|off> | 开启或关闭目标玩家奔跑时的第三人称骨骼幻影 | lyarmourers.manager |
/lyarmourers swordtrail <在线玩家> <配置ID|none> | 设置目标玩家的刀光；none 使用 MOD 内置默认刀光 | lyarmourers.manager |
/lyarmourers footprint <在线玩家> <配置ID|none> | 设置目标玩家的脚印；none 关闭脚印 | lyarmourers.manager |
/lyarmourers hidepart <在线玩家> <部位> | 隐藏目标玩家指定部位的时装 | lyarmourers.manager |
/lyarmourers showpart <在线玩家> <部位> | 恢复显示目标玩家指定部位的时装 | lyarmourers.manager |
/lyarmourers reload | 重载配置、服务缓存、刀光和脚印资源，并同步在线玩家 | lyarmourers.admin |
hidepart 和 showpart 支持以下英文部位：
text
head、body、legs、feet、wings、outfit、sword、bow、pickaxe、axe、shovel、hoe、shield、item、block、weapon、all对应的中文部位名称同样可以使用。部位显示状态只保存在当前服务端运行内存中，服务端重启后会清空。
权限
| 权限 | 默认值 | 说明 |
|---|---|---|
lyarmourers.manager | OP | 允许打开并操作时装管理界面、实体界面以及玩家时装和特效管理指令 |
lyarmourers.admin | OP | 允许重载 LyArmourers 配置、刀光和脚印资源 |
PlaceholderAPI 变量
启用 PlaceholderAPI 后，服务端插件注册变量标志 lysz。变量格式为 %lysz_部位%，显示时返回 show，隐藏时返回 hide。
| 变量 | 说明 |
|---|---|
%lysz_head% | 读取头部时装显示状态 |
%lysz_body% | 读取身体时装显示状态 |
%lysz_wings% | 读取翅膀时装显示状态 |
%lysz_sword% | 读取剑类时装显示状态 |
%lysz_all% | 读取全部时装显示状态 |
玩家不存在或部位参数无效时返回空字符串。变量读取的是当前服务端会话状态，不进行持久化。
API 与事件
外部 Bukkit 插件通过 Ly.armourers.client.plugin.api.LyArmourersAPI 使用稳定 API。API 可以设置、清除和查询实体时装，控制玩家部位显示状态、控制全局时装可见状态、读取物品时装、查询时装库，以及播放或停止模型动作。
外部插件可以通过 Start.getInstance().getApi() 获取实现。服务端业务尚未初始化时，该方法返回 null，调用前必须检查 API 是否可用。
Plugin 模块提供以下 Bukkit 事件契约：
| 事件 | 说明 |
|---|---|
EntitySkinUpdateEvent | 实体时装写入前触发，可调整最终时装列表，并可读取是否为持久更新 |
PlayerSkinUpdateEvent | 玩家时装写入前触发，可调整最终时装列表 |
事件类位于 Plugin 模块，外部插件只需要依赖 Plugin Jar。