配置说明

LyArmourers 由 Bukkit 服务端插件和 Minecraft 1.7.10 Forge 客户端 MOD 组成。两部分配置分别生效，不能把服务端 YAML 或客户端贴图放入错误目录。

部分	用途	配置位置
Plugin	Bukkit 启动、基础渲染开关、幻影参数、时装物品模板、时装库、实体时装、指令、消息同步和特效资源	`plugins/LyArmourers/config.yml`
Forge MOD	客户端界面、模型读取、玩家与实体渲染、动作兼容、刀光、脚印和幻影显示	玩家客户端 `mods` 目录及客户端资源目录

客户端 MOD 使用 Forge 1.7.10-10.13.4.1614-1.7.10，对应 Minecraft 1.7.10。需要显示时装模型、管理界面、物品预览、刀光、脚印和幻影的玩家必须安装配套 MOD，并把 MOD Jar 放入客户端 mods 目录。

配置文件总览

文件或目录	所属	用途
`plugins/LyArmourers/config.yml`	Plugin	当前服务端基础配置
`plugins/LyArmourers/skins/`	Plugin	服务端时装库根目录
`plugins/LyArmourers/effect-resources/sword-trails/`	Plugin	刀光 YAML 配置目录
`plugins/LyArmourers/effect-resources/footprints/`	Plugin	脚印 YAML 配置目录
`plugins/LyArmourers/player-data.yml`	Plugin	保存玩家选择的刀光和脚印 ID
`plugins/LyArmourers/entity-skins.yml`	Plugin	实体永久时装 UUID 索引、离线修改和旧数据迁移
客户端 `resourcepacks/LyArmourers/SwordTrails/`	Forge MOD	刀光静态图片或 GIF
客户端 `resourcepacks/LyArmourers/FootPrints/`	Forge MOD	脚印静态图片或 GIF
项目根目录 `config.yml`	旧版配置	保留旧配置结构，不是当前 Plugin 默认配置来源
项目根目录 `skin.yml`	旧版配置	旧版物品 Lore、实体名称与时装映射配置；现有证据未包含完整内容

服务端 `config.yml`

当前默认配置来源是 Plugin/src/main/resources/config.yml，运行时由 Bukkit 写入 plugins/LyArmourers/config.yml。服务端业务通过 PluginSettings 读取 Plugin 提供的原始 Bukkit 配置。

yaml

debug: false

# 是否渲染玩家装备时装
render-player-equipment-skins: true

# 是否允许客户端显示物品槽位中的时装模型图标和鼠标悬停时装预览
render-item-skin-preview: true

# 第三人称奔跑幻影
afterimage:
  lifetime-ticks: 12
  draw-interval-ticks: 2
  snapshot-interval-ticks: 2
  maximum-count: 6
  alpha: 70

# 时装生成物品
item:
  material: "LEATHER_CHESTPLATE"
  name: "&b{skin}"
  lore:
    - "&7时装：&f{skin}"
    - "&7生成玩家：&f{player}"

基础开关

配置项	类型	默认值	说明
`debug`	布尔值	`false`	是否记录非查询 API 的调用来源和详细参数
`render-player-equipment-skins`	布尔值	`true`	是否读取并渲染玩家原版头盔、胸甲、护腿和鞋子槽中带时装 NBT 的物品
`render-item-skin-preview`	布尔值	`true`	是否把物品槽位图标替换为时装模型，并在鼠标悬停时显示时装预览

render-player-equipment-skins 只控制玩家原版四个装备槽的兜底读取。关闭后，装备槽物品中的时装 NBT 不再自动显示，但以下内容不受影响：

API 或实体界面设置的玩家时装。
玩家和实体的手持物品时装。
NPC 与普通实体时装。
管理界面中的时装预览。

render-item-skin-preview 只控制背包、快捷栏等物品槽位中的时装模型图标和鼠标悬停预览。关闭后，槽位恢复显示物品自身图标，但第一人称、第三人称、穿戴时装和管理界面预览不受影响。

两个开关会由服务端同步给在线客户端。执行 /lyarmourers reload 后，新配置会重新发送给全部在线玩家；客户端离开当前服务器后恢复默认开启状态。

调试日志

debug: true 时，服务端插件会记录以下非查询 API 操作：

设置或清除实体时装。
设置玩家指定部位的显示状态。
设置玩家是否接收全局实体时装同步。
播放或停止模型动作。

日志可包含来源插件、调用位置、线程、目标实体及操作参数。读取实体时装、读取显示状态、读取物品时装名和查询时装库等查询操作不会输出这类调试日志。

时装库目录请求、预览请求和正常的预览分片发送不会输出常规调试消息。协议解析失败、文件不存在或回包过大等异常仍会保留警告。

幻影参数

配置项	类型	默认值	有效范围	说明
`afterimage.lifetime-ticks`	整数	`12`	`1`～`1200`	单份可见幻影的存在时间，单位 tick
`afterimage.draw-interval-ticks`	整数	`2`	`1`～`1200`	把最近姿态加入可见幻影队列的最小间隔，单位 tick
`afterimage.snapshot-interval-ticks`	整数	`2`	`1`～`1200`	从真实玩家模型读取最新骨骼姿态的最小间隔，单位 tick
`afterimage.maximum-count`	整数	`6`	`1`～`64`	单个玩家同时保留的最大幻影数量
`afterimage.alpha`	整数	`70`	`0`～`255`	最新幻影的不透明度

snapshot-interval-ticks 负责更新最近的骨骼姿态，draw-interval-ticks 决定何时把最近姿态加入可见队列，二者不要求互为倍数。

每份幻影会按剩余生存时间连续降低透明度，时间归零后才会移除。玩家停止疾跑时只停止生成新幻影，已经生成的幻影会继续自然淡出；关闭该玩家的幻影状态时，客户端会立即清除其现有幻影。

执行 /lyarmourers reload 后，服务端会把全部幻影参数重新同步给在线客户端。新进入服务器的客户端也会收到当前参数。

时装物品模板

配置项	类型	默认值	说明
`item.material`	字符串	`LEATHER_CHESTPLATE`	创建新时装物品时使用的基础材质文本
`item.name`	字符串	`&b{skin}`	新时装物品的显示名称
`item.lore`	字符串列表	见默认配置	新时装物品的 Lore

item.material 由 Plugin 的物品工具解析，项目代码支持材质名称、数字 ID 和数据值。名称和 Lore 支持 & 颜色代码以及以下变量：

变量	内容
`{skin}`	本次写入物品的完整时装库相对路径
`{player}`	接收生成物品的玩家名称

物品模板只用于创建新的时装物品，包括空槽生成和管理界面的快捷获取。把时装拖拽到已有物品时，只会写入 LyArmourers.skin NBT，不会覆盖目标物品原有的材质、数量、名称或 Lore。

管理界面的快捷获取使用内置 APPLE 作为基础物品，不读取 item.material；显示名称、Lore 和时装 NBT 仍由服务端继续写入。

内置固定配置

以下内容由当前代码固定，不从 config.yml 读取：

内容	固定值或位置
服务端时装库	`plugins/LyArmourers/skins/`
业务插件消息主通道	`armourers`
客户端协议判别字节	`64`
粒子主通道	`lycustom:main`
粒子兼容通道	`lycustom`
刀光配置目录	`plugins/LyArmourers/effect-resources/sword-trails/`
脚印配置目录	`plugins/LyArmourers/effect-resources/footprints/`

旧版授权连接参数和时装库路径均不再从当前 config.yml 读取。

时装库路径会经过清理和目录穿越保护。客户端不能通过 .. 读取 plugins/LyArmourers/skins/ 之外的文件。

时装库目录

默认时装库为：

text

plugins/LyArmourers/skins/

目录可以多层嵌套，客户端管理界面会显示服务端返回的完整相对路径。服务端当前识别以下格式：

后缀	用途
`.armour`	Armourer's Workshop 时装文件
`.lyarmourers`	按 `.armour` 兼容流程处理的项目后缀
`.bbmodel`	Blockbench 工程、Bedrock geometry 或 LyCustom ModelData 包装

时装合成功能只接受真实 .armour 文件，合成结果写入：

text

plugins/LyArmourers/skins/时装合成/

输出文件后缀固定为 .armour。.bbmodel 和 .lyarmourers 不能作为真实 .armour 源文件参与合成。

刀光配置

刀光配置目录：

text

plugins/LyArmourers/effect-resources/sword-trails/

每个 .yml 或 .yaml 文件代表一份完整刀光配置。顶层 id 是玩家选择刀光时使用的唯一标识。目录为空时，Plugin 会生成带简体中文注释的示例配置。

yaml

id: "示例刀光"
texture: "2.png"
red: 255
green: 255
blue: 255
alpha: 255
additive: true
lifetime: 8.0
width-scale: 4.0

配置项	类型	说明
`id`	字符串	配置唯一 ID
`texture`	字符串	客户端刀光资源目录中的相对图片或 GIF 路径
`red`	整数	红色分量，范围 `0`～`255`
`green`	整数	绿色分量，范围 `0`～`255`
`blue`	整数	蓝色分量，范围 `0`～`255`
`alpha`	整数	透明度，范围 `0`～`255`
`additive`	布尔值	是否使用发光叠加混合
`lifetime`	数值	刀光保留 tick；示例说明原版攻击采样通常在前 `5` tick 内完成
`width-scale`	数值	刀光宽度倍率，`1.0` 使用武器真实柄端到尖端宽度

additive: true 使用 SRC_ALPHA + ONE 的发光叠加混合。刀光几何仍取自更多动作快照或时装武器的真实端点，YAML 只控制贴图、颜色、透明度、混合方式、寿命和宽度。

刀光图片不会由服务端发送，必须放入每位玩家客户端的以下目录：

text

<游戏目录>/resourcepacks/LyArmourers/SwordTrails/

其中 <游戏目录> 是占位路径。texture 填写相对于 SwordTrails 目录的路径，例如 2.png 或 effects/刀光.gif。

刀光选择设为 none 时，玩家使用 MOD 内置的默认刀光参数，不是完全关闭刀光。

脚印配置

脚印配置目录：

text

plugins/LyArmourers/effect-resources/footprints/

每个 .yml 或 .yaml 文件代表一份完整脚印配置。目录为空时，Plugin 会生成带简体中文注释的示例配置。

yaml

id: "示例脚印"
texture: "1.png"
width: 0.5
length: 0.5
spacing: 0.5
red: 255
green: 255
blue: 255
alpha: 150
additive: false
mirror-left: true
lifetime: 80
animation:
  - "scale 2.0 200 缓出"
  - "scale 1.0 200 缓入缓出"
  - "rotate 360 1000 线性"
  - "alpha 0 500 缓入"

基础参数

配置项	类型	说明
`id`	字符串	配置唯一 ID
`texture`	字符串	客户端脚印资源目录中的相对图片或 GIF 路径
`width`	数值	单个脚印宽度，单位为格
`length`	数值	单个脚印长度，单位为格
`spacing`	数值	同一只脚连续生成脚印所需的最小水平距离，单位为格
`red`	整数	红色分量，范围 `0`～`255`
`green`	整数	绿色分量，范围 `0`～`255`
`blue`	整数	蓝色分量，范围 `0`～`255`
`alpha`	整数	透明度，范围 `0`～`255`
`additive`	布尔值	是否使用发光叠加混合
`mirror-left`	布尔值	是否水平镜像左脚贴图
`lifetime`	整数	没有有效 `animation` 时使用的兼容生命周期 tick
`animation`	字符串列表	按顺序执行的脚印动画动作

spacing 只用于限制同一只脚的连续脚印距离，过滤接地判定抖动，不是固定时间采样间隔。

存在有效 animation 时，动作会严格按照列表顺序执行，后一项继承前一项的最终状态。全部动作执行完成后脚印立即删除，此时 lifetime 不参与删除。没有有效动画动作时，客户端使用内置兼容动画和 lifetime。

脚印图片不会由服务端发送，必须放入每位玩家客户端的以下目录：

text

<游戏目录>/resourcepacks/LyArmourers/FootPrints/

脚印选择设为 none 时不绘制脚印。

动画动作

动作	参数格式	说明
`delay`	`毫秒`	保持当前尺寸、旋转、位置、颜色和透明度
`scale`	`目标倍率毫秒 [缓动]`	同时改变宽度和长度倍率
`scale-width`	`目标倍率毫秒 [缓动]`	只改变宽度倍率
`scale-length`	`目标倍率毫秒 [缓动]`	只改变长度倍率
`alpha`	`目标透明度毫秒 [缓动]`	渐变到 `0`～`255` 的绝对透明度
`rotate`	`相对角度毫秒 [缓动]`	在当前角度基础上继续旋转
`move`	`向右格数向前格数向上格数毫秒 [缓动]`	按脚印生成时的玩家朝向相对移动
`color`	`红绿蓝毫秒 [缓动]`	渐变到目标 RGB 颜色

动作名称同时兼容以下中文写法：

英文	中文
`delay`	`延迟`
`scale`	`缩放`
`scale-width`	`宽度`
`scale-length`	`长度`
`alpha`	`透明度`
`rotate`	`旋转`
`move`	`移动`
`color`	`颜色`

可用缓动：

写法	效果
`线性`	全程匀速
`缓入`	开始较慢，随后加速
`缓出`	开始较快，随后减速
`缓入缓出`	开始慢、中间快、结束慢

省略缓动参数时默认使用 缓入缓出。缓动只接受表中的四种简体中文写法。

单份脚印 YAML 最多读取 128 个动作，单个动作最长 600000 毫秒。未知动作或参数不合法的动作会被忽略，并写入客户端日志。

特效配置同步

Plugin 启动或执行 /lyarmourers reload 时，会逐个读取刀光和脚印目录中的 UTF-8 YAML。每个插件消息发送一份完整 YAML，不会拆分正文。

玩家登录并等待客户端插件消息通道就绪后，服务端会：

发送当前全部刀光和脚印 YAML。
发送在线玩家 UUID 与刀光 ID、脚印 ID 的绑定关系。
把新玩家的绑定关系广播给其他在线客户端。

玩家选择保存在：

text

plugins/LyArmourers/player-data.yml

每位玩家最多选择一份刀光和一份脚印。客户端按被渲染玩家的 UUID 查找配置，不会让所有玩家共用观察者自己的特效选择。

执行 /lyarmourers reload 后，客户端会先原子替换配置定义并清除旧图片与 GIF 帧缓存，再恢复在线玩家的特效绑定。YAML 无效、绑定 ID 不存在或本地贴图缺失时，不绘制对应特效。

静态图片和 GIF 只存在于客户端。GIF 首次使用时会预解码合成帧，保留文件中的逐帧延时并循环播放。

`entity-skins.yml`

plugins/LyArmourers/entity-skins.yml 用于保存实体永久时装的 UUID 索引、离线修改和旧数据迁移。实体永久数据在目标 Forge/Cauldron 1.7.10 环境中同时写入实体 ForgeData NBT。

该文件由插件业务维护，不建议手动改变数据结构。实体尚未加载时，服务端插件可以通过 YAML 索引保留修改；实体加载后会把索引内容写回 NBT。永久清空会保留空列表标记，防止旧 NBT 在区块再次加载时恢复已经删除的时装。

临时时装不会作为永久记录保存。服务端重启后，旧会话的临时 NBT 会被判定为过期，并由永久索引覆盖。

客户端资源目录

客户端 MOD 初始化时会检查以下目录，不存在时创建空文件夹：

text

<游戏目录>/resourcepacks/LyArmourers/SwordTrails/
<游戏目录>/resourcepacks/LyArmourers/FootPrints/

服务端 YAML 中的 texture 必须与客户端相应目录中的相对路径一致。支持静态图片和 GIF。服务端不会把这些图片传给客户端，因此服务器更换配置后，需要确保所有需要显示特效的玩家都拥有对应文件。

只有实际使用内置示例配置时，客户端才会按需生成对应的透明示例图片。

Forge MOD 配置边界

项目包含 ConfigHandler、ConfigHandlerClient、ConfigHandlerOverrides、ConfigSynchronizeHandler 和客户端 MOD 配置界面类，说明 Forge MOD 拥有独立客户端配置与同步逻辑。

现有项目证据没有提供这些 Forge 配置类中的完整配置键、默认值和生成文件内容，因此本页不列出无法确认的客户端配置项。服务端 plugins/LyArmourers/config.yml 中的渲染开关和幻影参数会通过插件消息同步给客户端，不应在客户端目录中复制同名 YAML。

旧版根目录 `config.yml`

项目根目录还保留一份旧版 config.yml，内容包括授权码、压缩包密码、临时时装展示时间、可选时装库路径、旧物品模板、方块时装物品消耗、更新日志和幻影参数。

yaml

code: "xxxxx"
ZipPassword: "unknow"
ShowTime: 30

# skin-library: "D:\\skin"

GiveItem:
  material: "APPLE"
  name: "&c时装物品&f[%skin%]"
  lore:
    - "&6时装:&a %skin%"
    - "&6第一任拥有者:&a %player%"

BlockSkinConsume: true

Log:
  PlayerUpdate: true
  EntityUpdate: true

afterimage:
  lifetime-ticks: 12
  draw-interval-ticks: 2
  snapshot-interval-ticks: 2
  maximum-count: 6
  alpha: 70

当前 Plugin 默认配置已经改为 debug、两个渲染开关、afterimage 和 item 结构。项目说明同时确认授权连接参数和时装库路径不再从当前 Plugin config.yml 读取。因此不要把以下旧键直接复制到新配置并认为仍会生效：

旧配置项	当前状态
`code`	不属于当前 Plugin 默认配置
`ZipPassword`	不属于当前 Plugin 默认配置
`ShowTime`	不属于当前 Plugin 默认配置
`skin-library`	当前时装库目录由代码固定
`GiveItem`	已由 `item` 配置组替代
`BlockSkinConsume`	不属于当前 Plugin 默认配置
`Log.PlayerUpdate`	当前默认配置改用 `debug` 控制 API 调试日志
`Log.EntityUpdate`	当前默认配置改用 `debug` 控制 API 调试日志

旧版物品模板使用 %skin% 和 %player%，当前 item 模板使用 {skin} 和 {player}，两套变量格式不能混用。

旧版 `skin.yml`

项目根目录存在旧版 skin.yml。已确认的文件注释说明，它曾用于根据忽略颜色代码和空格后的物品 Lore、实体名称匹配时装，并提示旧命令 /sz reload config 可以重载。

当前提供的文件内容已经截断，无法确认完整配置结构、全部节点和现有代码是否继续读取该文件。因此不应根据截断示例新增或修改映射项，也不应把旧重载命令视为当前版本已确认入口。

当前项目说明确认实体模型只能通过实体管理界面、公开 API 或实体 NBT 中保存的时装列表显式设置，不再按实体名称自动匹配模型，也不扫描独立自动替换规则文件。新配置应使用当前时装库、实体时装和公开 API 机制，不依赖旧版名称自动映射。

重载范围

执行 /lyarmourers reload 需要权限 lyarmourers.admin。完整重载会处理：

plugins/LyArmourers/config.yml。
服务端业务缓存。
刀光 YAML。
脚印 YAML。
在线客户端的装备槽渲染开关。
在线客户端的物品预览开关。
在线客户端的幻影参数。
在线玩家的刀光和脚印配置及绑定关系。

修改客户端本地图片或 GIF 后，服务端重载可以让客户端清除旧贴图缓存并重新读取资源，但图片文件本身仍需要提前放在每个客户端的对应目录中。

配置说明 ​

配置文件总览 ​

服务端 config.yml ​

基础开关 ​

调试日志 ​

幻影参数 ​

时装物品模板 ​

内置固定配置 ​

时装库目录 ​

刀光配置 ​

脚印配置 ​

基础参数 ​

动画动作 ​

特效配置同步 ​

entity-skins.yml ​

客户端资源目录 ​

Forge MOD 配置边界 ​

旧版根目录 config.yml ​

旧版 skin.yml ​

重载范围 ​

配置说明

配置文件总览

服务端 `config.yml`

基础开关

调试日志

幻影参数

时装物品模板

内置固定配置

时装库目录

刀光配置

脚印配置

基础参数

动画动作

特效配置同步

`entity-skins.yml`

客户端资源目录

Forge MOD 配置边界

旧版根目录 `config.yml`

旧版 `skin.yml`

重载范围