📥 安装教程

1. 将 AdventureSkins-1.2.0.jar 放入 plugins/
2. 启动服务器，自动生成默认配置和示例皮肤文件
3. 编辑配置后 /skins reload 热重载
4. 用 LuckPerms 为玩家/组分配皮肤权限

依赖说明

文件结构

plugins/AdventureSkins/
├── config.yml              ← 全局设置 (含 storage 数据库配置)
├── messages.yml            ← 消息文本 (MiniMessage)
├── cosmetics/              ← 皮肤定义
│   └── allay.yml           ← 悦灵系列 (默认)
└── groups/                 ← 物品分组
    └── default_groups.yml  ← 默认分组

🚀 快速上手

第一步：创建皮肤配置

在 plugins/AdventureSkins/cosmetics/ 下创建 YAML 文件：

# my_skins.yml
enabled: true
items:
  DIAMOND_SWORD:
    styles:
      fire_sword:
        name: '<red>烈焰之剑 <gray>皮肤'
        id: '1001'
        permission: 'adventureskins.skin.fire_sword'
        lore:
          - '<gray>点击应用火焰剑皮肤'

第二步：设置权限

# LuckPerms 示例
lp group vip permission set adventureskins.gui true
lp group vip permission set adventureskins.skin.fire_sword true

第三步：使用

1. 玩家手持钻石剑，输入 /skins 或 Shift+右键
2. 在 GUI 中点击皮肤图标即可应用
3. 再次点击或使用移除器可移除皮肤

管理命令速查

/skins reload                    — 重载所有配置
/skins give <玩家> <皮肤ID>       — 给予卷轴皮肤
/skins remover <玩家>             — 给予移除器
/skins wrap <玩家> <皮肤ID>       — 直接为玩家应用皮肤
/skins unwrap <玩家>              — 直接移除玩家皮肤
/skins create                    — 从手持物品生成皮肤配置

⌨️ 命令列表

主命令 /skins

别名: /skin, /askins

🔑 权限节点

基础权限

管理权限

皮肤专属权限

每个皮肤可单独设置 permission 字段，格式自定义：

permission: 'adventureskins.skin.fire_sword'

玩家必须拥有该权限才能使用对应皮肤。未设置 permission 的皮肤任何人可用。

🖥️ GUI 界面

打开方式

• 手持物品输入 /skins
• 手持物品 Shift+右键 (可在 config 中关闭)
• 管理员 /skins open <玩家>

GUI 功能

• 分页浏览 — 皮肤数量多时自动分页
• 目标物品槽 — 底部中间展示当前物品
• 左键应用 — 点击皮肤图标立即应用
• 右键预览 — 右键点击浮空预览效果
• 收藏功能 — 标记常用皮肤，快速找到
• 过滤功能 — 隐藏不想看的皮肤
• 权限锁定 — 无权限的皮肤显示为锁定样式
• 更换物品 — 拖入新物品切换目标

配置项

🎨 皮肤配置

文件位置

皮肤定义文件放在 plugins/AdventureSkins/cosmetics/ 目录下，支持子目录。

每个 .yml 文件可包含多种物品类型的皮肤，顶层需有 enabled: true 和 items: 节点。

完整字段参考

通用皮肤 vs 单一皮肤

通用皮肤（跨材质）

适用于一组物品（如木剑/石剑/铁剑/金剑），无论基础材质是什么都能正确显示模型。

示例 — 通用剑皮肤：

# groups/default_groups.yml
collections:
  BASIC_SWORDS:
    - 'WOODEN_SWORD'
    - 'STONE_SWORD'
    - 'IRON_SWORD'
    - 'GOLDEN_SWORD'

# cosmetics/allay.yml
items:
  BASIC_SWORDS:              # <-- 使用分组名
    styles:
      allay_sword:
        name: '<aqua>悦灵之剑'
        id: 5001
        item-model: 'hmcwraps:allay_sword'       # <-- 跨材质核心
        craftengine-id: 'inkless:allay_sword'     # <-- CE 物品标识
        permission: 'adventureskins.allay.sword'

单一皮肤（指定材质）

仅限特定材质使用，如"暗影悦灵之剑"只给钻石剑和下界合金剑。

示例 — 钻石剑专属皮肤：

items:
  DIAMOND_SWORD:              # <-- 直接用材质名
    styles:
      dark_allay_sword:
        name: '<dark_purple>暗影悦灵之剑'
        id: 5001                                  # <-- CMD 就够了
        item-model: 'hmcwraps:allay_sword'        # <-- 推荐但可选
        permission: 'adventureskins.dark_allay.sword'

对照速查表

基础示例

items:
  DIAMOND_SWORD:
    styles:
      fire_sword:
        name: '<red>烈焰之剑 <gray>皮肤'
        id: '1001'
        permission: 'adventureskins.skin.fire_sword'
        lore:
          - '<gray>让你的剑燃烧起来!'
        glow: true
        sort: 10
        locked-name: '<red><bold>未解锁'
        locked-lore:
          - '<gray>在商城购买后解锁'
        styled-lore:
          - '<red>烈焰系列皮肤'
        styled-lore-mode: 'APPEND'

📦 物品分组

物品分组将多种 Material 归为一组，一个皮肤即可同时适用于组内所有物品。配合 item-model 可实现跨材质通用皮肤。

定义方式

在 groups/*.yml 文件的 collections: 节点中定义（也可在 config.yml 的 groups: 中）：

# groups/default_groups.yml
collections:
  ALL_SWORDS:
    - 'WOODEN_SWORD'
    - 'STONE_SWORD'
    - 'IRON_SWORD'
    - 'GOLDEN_SWORD'
    - 'DIAMOND_SWORD'
    - 'NETHERITE_SWORD'

  BASIC_SWORDS:          # 不含钻石/下界合金
    - 'WOODEN_SWORD'
    - 'STONE_SWORD'
    - 'IRON_SWORD'
    - 'GOLDEN_SWORD'

预定义分组

默认 default_groups.yml 提供以下分组：

使用方式

在皮肤文件中，用分组名替代 Material 名：

items:
  BASIC_SWORDS:        # <-- 通用皮肤：木/石/铁/金剑
    styles:
      allay_sword:
        name: '<aqua>悦灵之剑'
        id: 5001
        item-model: 'hmcwraps:allay_sword'

  DIAMOND_SWORD:       # <-- 专属皮肤：仅钻石剑
    styles:
      dark_allay_sword:
        name: '<dark_purple>暗影悦灵之剑'
        id: 5001
        item-model: 'hmcwraps:allay_sword'

也可用逗号分隔直接指定多个 Material：

items:
  'DIAMOND_AXE, IRON_AXE, NETHERITE_AXE':
    styles:
      lumberjack_axe:
        name: '<dark_green>伐木者'
        id: '4002'

📜 卷轴皮肤

卷轴皮肤是可交易的实体物品，玩家将其拖放到目标物品上即可应用皮肤。

配置

fire_sword:
  name: '<red>烈焰之剑'
  id: '1001'
  scroll:
    id: 'PAPER'                  # 卷轴材质
    model-id: 2001               # CustomModelData
    name: '<red>烈焰 <gray>剑皮肤卷轴'
    lore:
      - '<gray>拖放到剑上应用皮肤'
    keep-after-remove: false     # 移除后是否保留

给予命令

/skins give <玩家> fire_sword

移除器

移除器在 config.yml 的 remover 节点配置，可自定义材质、模型和描述。

/skins remover <玩家>

🛡️ 盔甲系统

AdventureSkins 提供多种盔甲外观修改方式，满足不同需求。

CraftEngine 集成

服务器安装 CraftEngine 时，可通过 craftengine-id 让穿戴的盔甲显示自定义 3D 模型：

DIAMOND_HELMET:
  styles:
    frost_helmet:
      name: '<aqua>冰霜头盔'
      id: '5001'
      craftengine-id: 'mynamespace:frost_helmet'

原理：在物品的 custom_data 组件中写入 craftengine:id 标签，CraftEngine 读取后替换穿戴模型。

Equippable 组件 (1.21.4+)

使用原版 equippable 组件替换装备模型，无需第三方插件：

equippable-model: 'mynamespace:frost_armor'
equippable-slot: 'HEAD'    # 可选, 盔甲自动使用默认槽

盔甲仿冒 (Armor Imitation)

将物品材质临时伪装为另一种盔甲，用于皮革甲染色方案：

armor-imitation: 'LEATHER'    # 伪装为皮革甲
color: '100,200,255'          # 染色 (R,G,B)

纹饰 (Trim)

trim: 'rib'               # 纹饰图案
trim-material: 'diamond'   # 纹饰材质
remove-trim: false          # 是否移除原有纹饰

⚡ 动作系统

手持已包装物品进行交互/攻击时可触发自定义动作。

触发类型

动作类型 (16种)

配置示例

actions:
  interact:
    message:
      - '<gold>⚒ 你挥舞着武器!'
    sound:
      - 'minecraft:block.anvil.use 1.0 1.2'
  hit-player:
    message:
      - '<red>你攻击了一名玩家!'

👁️ 预览系统

预览模式

配置

preview:
  type: 'FLOATING'      # 预览模式
  duration: 5            # 持续时间 (秒)
  rotation: 5            # 旋转速度 (度/tick)
  sneak-cancel:
    enabled: true        # 蹲下取消预览
    action-bar: true     # ActionBar 提示
  bobbing:
    enabled: true        # 上下浮动
    speed: 7             # 浮动速度
    intensity: 0.25      # 浮动幅度

⚙️ config.yml

主配置文件位于 plugins/AdventureSkins/config.yml，包含以下模块：

• permissions — 权限检查控制
• preview — 预览系统设置
• inventory — GUI 界面设置
• remover — 移除器物品配置
• applying — 装扮/重新装扮规则
• preservation — 原始属性保留
• favorites / filter — 收藏与过滤
• global-disable — 全局禁用黑名单
• groups — 物品分组定义
• storage — MySQL / Redis 跨服同步
• items — 皮肤定义 (建议放 cosmetics/ 目录)

详细注释已内置于配置文件中，请直接参阅 config.yml。

🗄️ 跨服数据同步

AdventureSkins v1.2.0 支持通过 MySQL + Redis 在 Velocity 群组服中同步玩家偏好数据。

同步内容

架构

• MySQL — 持久化存储，玩家加入时异步加载，变更时异步写入
• Redis — Pub/Sub 实时通知其他子服刷新缓存，无需等待玩家重新登录

配置

storage:
  mysql:
    enabled: true
    host: 'localhost'
    port: 3306
    database: 'adventureskins'
    username: 'root'
    password: 'your_password'
    table-prefix: 'askins_'     # 表名前缀
  redis:
    enabled: true
    host: 'localhost'
    port: 6379
    password: ''

数据库表 (自动创建)

MySQL 表在插件首次连接时自动创建，无需手动建表。

数据流

玩家修改收藏/过滤 → 更新内存缓存 → 异步写 MySQL → Redis publish
                                                         ↓
其他子服 Redis subscribe → 收到通知 → 异步从 MySQL 重新加载到缓存

💬 messages.yml

消息配置文件位于 plugins/AdventureSkins/messages.yml。

所有消息支持 MiniMessage 格式，变量用 <xxx> 占位。

可用变量

🔗 插件联动

CraftEngine

CraftEngine 是一款资源包管理插件，可为物品定义自定义模型和贴图。AdventureSkins 通过两种方式与其协作：

武器/工具 — item-model（推荐）

CraftEngine 生成资源包时会在 assets/<namespace>/items/ 目录下创建 1.21.4 item model 定义文件。AdventureSkins 通过 item-model 字段设置 item_model 组件，客户端直接按路径渲染模型，无视底层材质。

# 武器/工具：item-model 是跨材质的核心
allay_sword:
  id: 5001
  item-model: 'hmcwraps:allay_sword'       # 设置 item_model 组件
  craftengine-id: 'inkless:allay_sword'     # CE 物品标识（可选）

盔甲 — craftengine-id + item-model

盔甲的穿戴外观需要 CraftEngine 拦截装备渲染数据包。通过 craftengine-id 写入 NBT，CraftEngine 识别后替换穿戴模型（equipment asset）。同时配合 item-model 控制手持/物品栏中的模型显示。

# 盔甲：craftengine-id 控制穿戴渲染，item-model 控制手持渲染
allay_helmet:
  id: 5001
  item-model: 'inkless:allay_helmet'        # 手持/物品栏模型
  craftengine-id: 'inkless:allay_helmet'    # 穿戴渲染（必须）

CraftEngine 配置侧

需要在 CraftEngine 的 resources/<pack>/configuration/ 目录下定义物品：

# CraftEngine 物品定义
items:
  inkless:allay_sword:
    material: IRON_SWORD           # 基础材质（仅用于 /ce give）
    textures:
      - inkless:vanillasets/allay_sword

  inkless:allay_helmet:
    material: DIAMOND_HELMET
    textures:
      - inkless:vanillasets/allay_helmet
    settings:
      equipment:
        asset-id: inkless:allay    # 穿戴模型资产
        slot: head

ItemsAdder / Oraxen / Nexo

通过 id 字段填写对应插件的物品 ID (如 itemsadder:custom_sword)，插件自动 Hook 模型。

PlaceholderAPI

安装 PAPI 后自动注册占位符，可在计分板/聊天/全息图中使用。

🏷️ PAPI 变量

需安装 PlaceholderAPI，插件自动注册以下占位符：

🔧 开发者 API

自定义事件

使用示例

@EventHandler
public void onSkin(ItemSkinEvent event) {
    Player player = event.getPlayer();
    String skinId = event.getSkinId();
    // 自定义逻辑...
    // event.setCancelled(true); // 取消应用
}

❓ 常见问题

Q: 皮肤应用后手持物品外观没变？

A: 确认资源包已正确加载，且 id 或 item-model 对应的模型在资源包中存在。

Q: 盔甲穿戴后没有显示自定义模型？

A: 需要配置 craftengine-id（需 CraftEngine 插件）或 equippable-model（1.21.4+ 原生）。仅 id 只改变手持外观。

Q: 如何让一个皮肤适用于多种物品？

A: 使用物品分组（groups）或逗号分隔的 Material 列表。详见"物品分组"页。

Q: 皮肤在钻石剑上有效，但铁剑/石剑上无效？

A: 这是因为只配置了 id（CustomModelData），CMD 是材质绑定的。要跨材质必须添加 item-model 字段（1.21.4 item_model 组件），它直接告诉客户端用哪个模型渲染，不受底层材质影响。详见"皮肤配置 > 通用皮肤 vs 单一皮肤"。

Q: craftengine-id 和 item-model 有什么区别？

A: item-model 设置 1.21.4 的 item_model 组件，直接控制客户端渲染模型（武器/工具核心）。craftengine-id 写入 NBT 标签让 CraftEngine 识别物品身份，主要用于盔甲穿戴渲染。武器跨材质只需 item-model，盔甲穿戴需要两者配合。

Q: 物理皮肤和虚拟皮肤有什么区别？

A: 虚拟皮肤通过 GUI 直接应用，物理皮肤是可交易的实体物品（PAPER + CustomModelData），拖放到目标物品上应用。

Q: 仿冒盔甲为什么不能放进附魔台？

A: 这是安全保护机制，防止玩家利用材质差异获取不当附魔。移除皮肤恢复原材质后即可正常使用。

Q: 支持热重载吗？

A: 支持。/skins reload 可重载所有配置和皮肤文件，无需重启服务器。

📝 更新日志

v1.2.0 最新

• NEW 通用皮肤机制 — 物品分组 + item-model 实现跨材质皮肤，一个皮肤覆盖所有材质
• NEW 预定义分组 — ALL_SWORDS, BASIC_SWORDS, ALL_PICKAXES 等 14 个开箱即用分组
• NEW CraftEngine 深度集成 — item-model 跨材质武器渲染 + craftengine-id 盔甲穿戴渲染
• NEW MySQL + Redis 跨服同步 — Velocity 群组服玩家收藏/过滤偏好实时同步
• NEW 配置命名重构 — wraps→styles, unwrapper→remover, physical→scroll, collections→groups
• NEW 文件夹重命名 — skins/→cosmetics/, collections/→groups/
• NEW 默认悦灵皮肤 — cosmetics/allay.yml 含通用悦灵 + 暗影悦灵系列
• NEW 向后兼容 — 旧配置键名自动回退读取

v1.1.0

• NEW CraftEngine 集成 — craftengine-id 支持穿戴自定义盔甲模型
• NEW Equippable 改进 — equippable-model 可独立使用，无需指定 slot
• NEW 配置注释 — 所有配置文件添加详细中文注释
• NEW 示例文件 — 新增 example_skins.yml 展示全部可用字段

v1.0.0

• NEW 初始发布 — 完整的物品皮肤系统
• NEW 虚拟/物理皮肤 + 拆包器 + GUI + 预览
• NEW 16 种动作类型 + 自定义事件 API
• NEW 盔甲仿冒 + 假耐久 + Trim + Equippable
• NEW 物品集合 + 收藏/过滤 + 权限保护
• NEW PlaceholderAPI + ItemsAdder/Oraxen/Nexo Hook