pluginiPlugin

显示模板

创建和使用可重用的物品外观模板

概述

显示模板是 Zaphkiel 中用于定义物品外观的可重用配置。通过显示模板，你可以为多个物品创建统一的名称和描述格式，避免重复配置。

基础概念

什么是显示模板

显示模板定义了物品的名称和描述的格式结构，使用变量占位符来动态插入物品特定的内容。每个物品可以引用一个显示模板，并提供相应的变量值。

模板与物品的关系

# 显示模板定义格式
weapon_display:
  name: '&7<item_name>'
  lore:
    - '&9<item_type>'
    - '&f<item_description...>'
 
# 物品使用模板
my_sword:
  display: weapon_display  # 引用模板
  name:
    item_name: '魔法剑'     # 提供变量值
  lore:
    item_type: '武器'
    item_description:
      - '一把强大的剑'

创建显示模板

模板文件位置

显示模板配置文件位于 plugins/Zaphkiel/display/ 目录下，支持多个 .yml 文件。

基础模板结构

default_display_1:
  name: '&7<item_name>'
  lore:
    - '&9<item_type>'
    - '&f<item_description...>'
 
default_display_2:
  name: '&7<item_name>'
  lore:
    - '&9<item_type>'
    - '&f<item_description...>'
    - ''
    - '&a+<damage> Damage'
    - '&7+<attack-speed> AttackSpeed &8(<attack-speed-level>)'

模板配置项

配置项说明示例
name物品名称格式'&7<item_name>'
lore物品描述格式列表['&9<item_type>', '&f<item_description...>']

变量系统

变量语法

显示模板使用 <变量名> 语法来定义占位符：

weapon_display:
  name: '&6<item_name> &7[<item_level>]'
  lore:
    - '&9类型: <item_type>'
    - '&f<item_description...>'
    - ''
    - '&c伤害: <damage>'
    - '&b等级: <level>'

特殊变量语法

展开变量 (...)

使用 <变量名...> 语法可以将列表变量展开为多行：

# 模板定义
display_template:
  lore:
    - '&f<item_description...>'  # 展开为多行
 
# 物品配置
my_item:
  lore:
    item_description:
      - '第一行描述'
      - '第二行描述'
      - '第三行描述'
 
# 最终效果
# &f第一行描述
# &f第二行描述
# &f第三行描述

数据映射变量

显示模板可以使用来自 data-mapper 的动态变量：

# 物品配置
my_sword:
  display: weapon_display
  data:
    damage: 100
    level: 5
  data-mapper:
    damage: it
    level_text: |-
      case &level [
        when < 10 -> "新手"
        else -> "专家"
      ]
 
# 显示模板
weapon_display:
  name: '&6<item_name>'
  lore:
    - '&c伤害: <damage>'      # 来自 data-mapper
    - '&b等级: <level_text>'   # 来自 data-mapper 计算

模板应用流程

1. 模板选择

当物品构建时，系统会根据物品的 display 配置选择对应的显示模板。

2. 变量替换

系统使用物品提供的变量值替换模板中的占位符，生成最终的显示内容。

3. 结构处理

模板使用结构化处理来处理复杂的变量替换，包括展开变量和条件显示。

实用模板示例

武器模板

weapon_template:
  name: '&6<item_name> &7[&e<item_level>&7]'
  lore:
    - '&9<item_type>'
    - '&f<item_description...>'
    - ''
    - '&c⚔ 攻击力: &f<damage>'
    - '&b⭐ 等级: &f<level>'
    - '&a✦ 品质: &f<quality>'
    - ''
    - '&7右键使用技能'

消耗品模板

consumable_template:
  name: '&a<item_name> &7x<stack_size>'
  lore:
    - '&2<item_type>'
    - '&f<item_description...>'
    - ''
    - '&e效果:'
    - '&f<effect_description...>'
    - ''
    - '&7右键使用'

装备模板

equipment_template:
  name: '&d<item_name> &7[<tier>]'
  lore:
    - '&5<item_type>'
    - '&f<item_description...>'
    - ''
    - '&c❤ 生命值: &f+<health>'
    - '&9🛡 防御力: &f+<defense>'
    - '&a⚡ 速度: &f+<speed>%'
    - ''
    - '&6套装: <set_name>'
    - '&7装备要求: 等级 <required_level>'

高级功能

条件显示

结合数据映射，可以实现条件显示：

# 物品配置
conditional_item:
  display: conditional_template
  data:
    durability: 80
    max_durability: 100
  data-mapper:
    durability_bar: |-
      if check &durability > 75 then "████████"
      else if check &durability > 50 then "██████  "
      else if check &durability > 25 then "████    "
      else "██      "
    durability_color: |-
      if check &durability > 75 then "&a"
      else if check &durability > 50 then "&e"
      else if check &durability > 25 then "&6"
      else "&c"
 
# 显示模板
conditional_template:
  name: '&f<item_name>'
  lore:
    - '&f耐久度: <durability_color><durability_bar>'

元数据集成

显示模板可以包含元数据配置，为使用该模板的所有物品应用共同的功能。

使用技巧

1. 模板命名规范

建议使用描述性的模板名称：

  • weapon_common - 普通武器模板
  • armor_legendary - 传说装备模板
  • consumable_potion - 药水消耗品模板

2. 变量命名一致性

在所有模板中保持变量命名的一致性：

  • item_name - 物品名称
  • item_type - 物品类型
  • item_description - 物品描述

3. 颜色主题统一

为不同类型的物品使用统一的颜色主题：

  • 武器：红色系 (&c, &4)
  • 防具：蓝色系 (&9, &b)
  • 消耗品：绿色系 (&a, &2)

注意事项

  1. 模板重载：修改显示模板后使用 /zaphkiel reload 重载
  2. 变量匹配：确保物品提供的变量与模板中的占位符匹配
  3. 性能考虑：避免在模板中使用过于复杂的变量处理
  4. 兼容性：模板修改可能影响使用该模板的所有物品

目录