Display Templates
Create and Use Reusable Item Appearance Templates
Overview
Display templates are reusable configurations in Zaphkiel for defining item appearances. With display templates, you can create a unified format for the name and description of multiple items, avoiding redundant configurations.
Basic Concepts
What is a Display Template
A display template defines the format structure of an item's name and description, using variable placeholders to dynamically insert item-specific content. Each item can reference a display template and provide corresponding variable values.
Relationship Between Templates and Items
# Display template definition format
weapon_display:
name: '&7<item_name>'
lore:
- '&9<item_type>'
- '&f<item_description...>'
# Item using the template
my_sword:
display: weapon_display # Reference the template
name:
item_name: 'Magic Sword' # Provide variable value
lore:
item_type: 'Weapon'
item_description:
- 'A powerful sword'Creating Display Templates
Template File Location
Display template configuration files are located in the plugins/Zaphkiel/display/ directory, and multiple .yml files are supported.
Basic Template Structure
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>)'Template Configuration Items
| Configuration Item | Description | Example |
|---|---|---|
name | Item name format | '&7<item_name>' |
lore | List of item description formats | ['&9<item_type>', '&f<item_description...>'] |
Variable System
Variable Syntax
Display templates use the <variable_name> syntax to define placeholders:
weapon_display:
name: '&6<item_name> &7[<item_level>]'
lore:
- '&9Type: <item_type>'
- '&f<item_description...>'
- ''
- '&cDamage: <damage>'
- '&bLevel: <level>'Special Variable Syntax
Expanded Variables (...)
Using the <variable_name...> syntax allows list variables to be expanded into multiple lines:
# Template definition
display_template:
lore:
- '&f<item_description...>' # Expanded into multiple lines
# Item configuration
my_item:
lore:
item_description:
- 'First line of description'
- 'Second line of description'
- 'Third line of description'
# Final effect
# &fFirst line of description
# &fSecond line of description
# &fThird line of descriptionData-Mapped Variables
Display templates can use dynamic variables from data-mapper:
# Item configuration
my_sword:
display: weapon_display
data:
damage: 100
level: 5
data-mapper:
damage: it
level_text: |-
case &level [
when < 10 -> "Novice"
else -> "Expert"
]
# Display template
weapon_display:
name: '&6<item_name>'
lore:
- '&cDamage: <damage>' # From data-mapper
- '&bLevel: <level_text>' # Calculated from data-mapperTemplate Application Process
1. Template Selection
When an item is constructed, the system selects the corresponding display template based on the item's display configuration.
2. Variable Replacement
The system replaces the placeholders in the template with the variable values provided by the item to generate the final display content.
3. Structure Processing
The template uses structural processing to handle complex variable replacements, including expanding variables and conditional display.
Practical Template Examples
Weapon Template
weapon_template:
name: '&6<item_name> &7[&e<item_level>&7]'
lore:
- '&9<item_type>'
- '&f<item_description...>'
- ''
- '&c⚔ Attack: &f<damage>'
- '&b⭐ Level: &f<level>'
- '&a✦ Quality: &f<quality>'
- ''
- '&7Right-click to use skill'Consumable Template
consumable_template:
name: '&a<item_name> &7x<stack_size>'
lore:
- '&2<item_type>'
- '&f<item_description...>'
- ''
- '&eEffects:'
- '&f<effect_description...>'
- ''
- '&7Right-click to use'Equipment Template
equipment_template:
name: '&d<item_name> &7[<tier>]'
lore:
- '&5<item_type>'
- '&f<item_description...>'
- ''
- '&c❤ Health: &f+<health>'
- '&9🛡 Defense: &f+<defense>'
- '&a⚡ Speed: &f+<speed>%'
- ''
- '&6Set: <set_name>'
- '&7Equipment Requirement: Level <required_level>'Advanced Features
Conditional Display
Combined with data mapping, conditional display can be implemented:
# Item configuration
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"
# Display template
conditional_template:
name: '&f<item_name>'
lore:
- '&fDurability: <durability_color><durability_bar>'Metadata Integration
Display templates can include metadata configurations to apply common functions to all items using the template.
Usage Tips
1. Template Naming Conventions
It is recommended to use descriptive template names:
weapon_common- Common weapon templatearmor_legendary- Legendary armor templateconsumable_potion- Potion consumable template
2. Variable Naming Consistency
Maintain consistent variable naming across all templates:
item_name- Item nameitem_type- Item typeitem_description- Item description
3. Unified Color Theme
Use a unified color theme for different types of items:
- Weapons: Red series (
&c,&4) - Armor: Blue series (
&9,&b) - Consumables: Green series (
&a,&2)
Notes
- Template Reload: After modifying display templates, use
/zaphkiel reloadto reload - Variable Matching: Ensure the variables provided by the item match the placeholders in the template
- Performance Considerations: Avoid using overly complex variable processing in templates
- Compatibility: Template modifications may affect all items using the template