Data Mapping
Dynamically Display Item Data in Names and Descriptions
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
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'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:
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:
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:
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:
magic_pickaxe:
display: tool_display
data:
efficiency: 150
durability: 800
data-mapper:
efficiency: it # Directly maps data.efficiency
durability: it # Directly maps data.durabilityNBT Path Mapping
Use the & prefix to access NBT data:
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: 75Advanced Mapping Features
Conditional Mapping
Display different text based on numerical values:
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
weapon_display:
name: '&6<item_name> +<level>'
lore:
- '&9<item_type>'
- '&cAttack Damage: <damage>'
- '&aAttack Speed: <speed>'
- '&bLevel: <level>'Advanced Template
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>'