iPlugin | Data Mapping

Overview

The data mapping system allows you to dynamically display an item's custom data in its name and description. For example, you can show a weapon's damage value, level, durability, and other attributes, letting players intuitively see the item's properties.

Basic Concepts

What is Data Mapping

Data mapping is the process of converting an item's data values and meta.native NBT data into variables that can be used in display templates.

Workflow

The data mapping system operates through three steps:

Item Configuration - Define data and mapping rules
Display Template - Define display format
System Processing - Automatically apply mappings and generate the final display

item/weapons/swords.yml

my_sword:
  display: weapon_display    # Must specify a display template
  data:
    damage: 100
    level: 5
  meta:
    native:
      CustomStats:
        power: 150
  data-mapper:
    damage: it                    # Map data from the data node
    level: it                     # Map data from the data node
    power: "&CustomStats.power"   # Map data from native NBT
  # Item's name and lore provide basic variable values
  name:
    item_name: '&6Divine Sword'
  lore:
    item_type: '&9Weapon'

display/weapon.yml

weapon_display:
  name: '&6<item_name> +<level>'
  lore:
    - '&9<item_type>'
    - '&cAttack Damage: <damage>'
    - '&ePower: <power>'

Data Source Types

Data Node Mapping

Map data from the data node:

item/weapons/basic_sword.yml

basic_sword:
  display: basic_display
  data:
    damage: 150
    level: 10
    speed: 1.5
  data-mapper:
    damage: it      # Displays 150
    level: it       # Displays 10
    speed: it       # Displays 1.5
  name:
    item_name: '&7Basic Sword'
  lore:
    item_type: '&9Sword'

Meta.Native NBT Data Mapping

Map NBT data from meta.native, supporting nested path access:

item/weapons/advanced_sword.yml

advanced_sword:
  display: advanced_display
  data-mapper:
    greeting: "&hello"                      # Reference simple value from native NBT
    attack_power: "&WeaponData.attack"      # Reference nested value from native NBT
    total_stats: "&Stats.strength + &Stats.agility"  # Calculate multiple NBT values
  meta:
    native:
      hello: "world"                        # Simple NBT value
      WeaponData:
        attack: 120                         # Nested NBT value
        defense: 80
      Stats:
        strength: 50
        agility: 30
  name:
    item_name: '&6Advanced Sword'

Hybrid Data Mapping

Use both data and meta.native data simultaneously:

item/weapons/hybrid_sword.yml

hybrid_sword:
  display: hybrid_display
  data:
    base_damage: 100
    level: 15
  data-mapper:
    base_damage: it                         # Data from data node
    level: it                              # Data from data node
    bonus_damage: "&Enchantments.sharpness" # Data from native NBT
    total_damage: |-                       # Hybrid calculation
      math + [ &base_damage &Enchantments.sharpness ]
  meta:
    native:
      Enchantments:
        sharpness: 25
        unbreaking: 3
  name:
    item_name: '&cHybrid Sword'

Mapping Syntax

Direct Mapping

Use it to directly map values with the same name from the data node:

item/tools/pickaxe.yml

magic_pickaxe:
  display: tool_display
  data:
    efficiency: 150
    durability: 800
  data-mapper:
    efficiency: it    # Directly maps data.efficiency
    durability: it    # Directly maps data.durability

NBT Path Mapping

Use the & prefix to access NBT data:

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: "Legendary Sword"
        stats:
          attack: 150
          defense: 75

Advanced Mapping Features

Conditional Mapping

Display different text based on numerical values:

item/weapons/conditional_sword.yml

conditional_sword:
  display: conditional_display
  data:
    level: 15
    durability: 80
  data-mapper:
    level_text: |-
      case &level [
        when < 10 -> "Novice"
        when < 20 -> "Skilled"
        when < 50 -> "Expert"
        else -> "Master"
      ]
    
    durability_status: |-
      if check &durability > 75 then "Perfect"
      else if check &durability > 50 then "Good"
      else if check &durability > 25 then "Damaged"
      else "Near Broken"
  name:
    item_name: '&6Conditional Sword'

Display Template Configuration

Basic Template

display/weapon.yml

weapon_display:
  name: '&6<item_name> +<level>'
  lore:
    - '&9<item_type>'
    - '&cAttack Damage: <damage>'
    - '&aAttack Speed: <speed>'
    - '&bLevel: <level>'

Advanced Template

display/advanced_weapon.yml

advanced_weapon_display:
  name: '&6<weapon_name> &7[<level_text>]'
  lore:
    - '&9<item_type>'
    - '&c⚔ Total Attack: &f<total_attack> &7(<base_attack> + <enhancement_bonus>)'
    - '&e⚡ Enhancement Rate: &f<enhancement_percent>%'
    - '&fDurability: <durability_color><durability_bar> &7<durability>/<max_durability>'
    - ''
    - '&7Status: <durability_status>'

Data Mapping

On this page