pluginiPlugin

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 ItemDescriptionExample
nameItem name format'&7<item_name>'
loreList 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 description

Data-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-mapper

Template 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 template
  • armor_legendary - Legendary armor template
  • consumable_potion - Potion consumable template

2. Variable Naming Consistency

Maintain consistent variable naming across all templates:

  • item_name - Item name
  • item_type - Item type
  • item_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

  1. Template Reload: After modifying display templates, use /zaphkiel reload to reload
  2. Variable Matching: Ensure the variables provided by the item match the placeholders in the template
  3. Performance Considerations: Avoid using overly complex variable processing in templates
  4. Compatibility: Template modifications may affect all items using the template

Previous

Config

Next

Item Configuration

On this page