iPlugin | 数据映射

概述

数据映射系统让你可以将物品的自定义数据动态显示在物品的名称和描述中。比如显示武器的伤害值、等级、耐久度等信息，让玩家能够直观地看到物品的属性。

基础概念

什么是数据映射

数据映射就是将物品的 data 数据和 meta.native NBT 数据转换成可以在 display 模板中使用的变量。

工作流程

数据映射系统的工作流程包括三个步骤：

物品配置 - 定义数据和映射规则
Display 模板 - 定义显示格式
系统处理 - 自动应用映射并生成最终显示

item/weapons/swords.yml

my_sword:
  display: weapon_display    # 必须指定 display 模板
  data:
    damage: 100
    level: 5
  meta:
    native:
      CustomStats:
        power: 150
  data-mapper:
    damage: it                    # 映射 data 数据
    level: it                     # 映射 data 数据
    power: "&CustomStats.power"   # 映射 native NBT 数据
  # 物品的 name 和 lore 提供基础变量值
  name:
    item_name: '&6神剑'
  lore:
    item_type: '&9武器'

display/weapon.yml

weapon_display:
  name: '&6<item_name> +<level>'
  lore:
    - '&9<item_type>'
    - '&c攻击力: <damage>'
    - '&e能量: <power>'

数据源类型

data 节点数据映射

映射 data 节点中的数据：

item/weapons/basic_sword.yml

basic_sword:
  display: basic_display
  data:
    damage: 150
    level: 10
    speed: 1.5
  data-mapper:
    damage: it      # 显示 150
    level: it       # 显示 10
    speed: it       # 显示 1.5
  name:
    item_name: '&7基础剑'
  lore:
    item_type: '&9剑'

meta.native NBT 数据映射

映射 meta.native 中的 NBT 数据，支持嵌套路径访问：

item/weapons/advanced_sword.yml

advanced_sword:
  display: advanced_display
  data-mapper:
    greeting: "&hello"                      # 引用 native NBT 中的简单值
    attack_power: "&WeaponData.attack"      # 引用 native NBT 中的嵌套值
    total_stats: "&Stats.strength + &Stats.agility"  # 计算多个 NBT 值
  meta:
    native:
      hello: "world"                        # 简单 NBT 值
      WeaponData:
        attack: 120                         # 嵌套 NBT 值
        defense: 80
      Stats:
        strength: 50
        agility: 30
  name:
    item_name: '&6高级剑'

混合数据映射

同时使用 data 和 meta.native 数据：

item/weapons/hybrid_sword.yml

hybrid_sword:
  display: hybrid_display
  data:
    base_damage: 100
    level: 15
  data-mapper:
    base_damage: it                         # data 数据
    level: it                              # data 数据
    bonus_damage: "&Enchantments.sharpness" # native NBT 数据
    total_damage: |-                       # 混合计算
      math + [ &base_damage &Enchantments.sharpness ]
  meta:
    native:
      Enchantments:
        sharpness: 25
        unbreaking: 3
  name:
    item_name: '&c混合剑'

映射语法

直接映射

使用 it 直接映射 data 节点中的同名值：

item/tools/pickaxe.yml

magic_pickaxe:
  display: tool_display
  data:
    efficiency: 150
    durability: 800
  data-mapper:
    efficiency: it    # 直接映射 data.efficiency
    durability: it    # 直接映射 data.durability

NBT 路径映射

使用 & 前缀访问 NBT 数据：

item/weapons/nbt_sword.yml

nbt_sword:
  display: nbt_display
  data-mapper:
    weapon_name: "&WeaponInfo.name"
    attack_damage: "&WeaponInfo.stats.attack"
    defense_value: "&WeaponInfo.stats.defense"
  meta:
    native:
      WeaponInfo:
        name: "传说之剑"
        stats:
          attack: 150
          defense: 75

高级映射功能

条件映射

根据数值显示不同的文字：

item/weapons/conditional_sword.yml

conditional_sword:
  display: conditional_display
  data:
    level: 15
    durability: 80
  data-mapper:
    level_text: |-
      case &level [
        when < 10 -> "新手"
        when < 20 -> "熟练"
        when < 50 -> "专家"
        else -> "大师"
      ]
    
    durability_status: |-
      if check &durability > 75 then "完好"
      else if check &durability > 50 then "良好"
      else if check &durability > 25 then "破损"
      else "即将损坏"
  name:
    item_name: '&6条件剑'

Display 模板配置

基础模板

display/weapon.yml

weapon_display:
  name: '&6<item_name> +<level>'
  lore:
    - '&9<item_type>'
    - '&c攻击力: <damage>'
    - '&a攻击速度: <speed>'
    - '&b等级: <level>'

高级模板

display/advanced_weapon.yml

advanced_weapon_display:
  name: '&6<weapon_name> &7[<level_text>]'
  lore:
    - '&9<item_type>'
    - '&c⚔ 总攻击力: &f<total_attack> &7(<base_attack> + <enhancement_bonus>)'
    - '&e⚡ 强化率: &f<enhancement_percent>%'
    - '&f耐久度: <durability_color><durability_bar> &7<durability>/<max_durability>'
    - ''
    - '&7状态: <durability_status>'

数据映射

目录