跳到主要内容

时装文件与通用字段

文件结构​

cosmetics/ 目录下的每个 .yml 文件就是一个时装分类（等级），文件名即分类 ID：

cosmetics/
├── wings.yml       → 分类 wings
├── legendary.yml   → 分类 legendary
└── eternal.yml     → 分类 eternal

文件内每个最外层键是一件时装。分类要出现在衣橱里，还需在 menus/categories.yml 中登记同名分类。开启多件穿戴后，分类也是计算「每类穿几件」的单位。

时装 ID 全局唯一

时装卡、数据库、指令都使用时装 ID。即使在不同文件中，ID 也不能重复，也不要在上线后修改已发放的 ID。

完整字段一览​

star_wings:                       # 时装 ID
  type: meg                       # 渲染模式：meg / display / equipment / body
  name: '<gradient:#FFE153:#66CCFF>星辰之翼</gradient>'
  model: star_wings               # 仅 meg：ModelEngine 模型 ID
  permission: cloudcosmetics.cosmetic.star_wings   # 可选，用于说明显示
  lore:                           # 可选，衣橱 / 商城说明
    - '&7由星光凝成的双翼。'
    - '{default_lore}'
  icon:                           # 衣橱 / 商城中的图标
    material: FEATHER
    custom-model-data: 0
    item-model: ''
  order: 10                       # 排序，越小越前（旧版写法 slot 仍可用）
  menu-slot: 8                    # 可选：固定格位（从 0 起算）
  menu-page: 1                    # 可选：配合 menu-slot 指定页码（从 1 起算）
  scale: 1.0                      # 模型倍率
  follow-rotation: true           # 是否跟随玩家朝向
  offset: { x: 0.0, y: 0.0, z: 0.25 }
  animation: idle                 # 单一动画；或使用 animations 按状态切换
  attributes:                     # 拥有即生效的属性 BUFF
    max-health: 10
  totem: false                    # 不死图腾（可选）
  equip-group: full-body          # 可选：互斥群组，同组只保留新穿戴的一件
  shop: { enabled: true, price: 1000 }
  card: { ... }                   # 可选，覆盖默认时装卡外观
字段说明适用模式
type渲染模式，见四种渲染模式。不填时：有 model 视为 meg，否则视为 display全部
name显示名称，支持 & 色码与 MiniMessage全部
modelModelEngine 模型 IDmeg
permission默认 cloudcosmetics.cosmetic.<ID>，供 {permission} 显示全部
lore衣橱与商城说明，见 Lore 与时装卡全部
icon菜单图标，与身上显示的模型无关全部
order在衣橱 / 商城中的排序，数值越小越前面；相同时按 ID 排序。旧写法 slot 仍可用全部
menu-slot固定放在指定格位（从 0 起算），见菜单与商城全部
menu-page配合 menu-slot 指定页码（从 1 起算），默认 1全部
scale模型倍率，最小 0.01meg display body
follow-rotation跟随玩家转向，见转向与跟随meg display body
offset位置偏移，按玩家朝向计算meg display body
animation / animations动画，见动画meg
attributes属性 BUFF，见属性 BUFF全部
totem 等不死图腾，见不死图腾全部
equip-group互斥群组（2.10.8 起），同组时装跨分类也只能穿一件，见多件穿戴全部
shop商城上架与价格，见菜单与商城全部
card时装卡外观，见 Lore 与时装卡全部

图标 icon​

icon:
  material: PAPER
  custom-model-data: 10017   # 旧式模型编号，0 = 不使用
  item-model: ''             # 1.21.4+ item model，如 'namespace:item'

使用 CraftEngine 物品作图标：

icon:
  source: craftengine
  item: 'your_namespace:your_item'
  material: PAPER            # CraftEngine 不可用时的备用图标

文字格式​

写法示例
传统色码'&6黄金之翼'
MiniMessage 渐变'<gradient:#FFFFCE:#FFE153>圣光之杖</gradient>'

两种格式都能用，但同一段文字中请确保 MiniMessage 标签正确闭合。

安全修改流程​

  1. 修改前复制一份目标 YML。
  2. 只用空格缩进，不要使用 Tab。
  3. 先在测试服执行 /cosmetic reload，查看控制台有无 Skipped cosmetic 或 YAML 错误。
  4. 检查第一 / 第三人称、他人视角、传送与重生后再上线。
最后于 更新