Effect Lore Display

Learn how to customize the way effects are displayed in item lore, including visibility controls, formatting, and display limits.

Overview

zItems provides fine-grained control over how effects appear in item lore. You can:

Control visibility of base effects vs additional effects
Limit the number of effects shown
Customize formatting using messages
Show "And More..." when effects are truncated
Separate base lore from effect lore

Display Settings

Per-Item Settings

Configure in your item YAML files (items/*.yml):

id: "my_pickaxe"
# ... other settings ...

# Effect Display Control
nb-effects-view: -1  # How many effects to show
base-effects-visible: true  # Show base effects
additional-effects-visible: true  # Show added effects

nb-effects-view

Controls how many effects are displayed in lore:

Value

Behavior

-1

Show all effects (no limit)

0

Show no effects (hide all)

> 0

Show up to N effects, then "And More..."

Examples:

# Show all effects
nb-effects-view: -1

# Hide all effects
nb-effects-view: 0

# Show first 3 effects only
nb-effects-view: 3

base-effects-visible

Controls whether effects defined in the item config are shown:

# Show base effects
base-effects-visible: true

# Hide base effects (only show added effects)
base-effects-visible: false

Base effects are those defined in the effects: list in the item YAML.

additional-effects-visible

Controls whether effects added via commands are shown:

# Show additional effects
additional-effects-visible: true

# Hide additional effects (only show base)
additional-effects-visible: false

Additional effects are those applied using /zitems effect apply.

Global Default Settings

Configure in config.yml:

# Default value for nb-effects-view if not specified per-item
default-nb-effects-view: -1

This applies to all items that don't specify nb-effects-view in their YAML.

Lore Formatting

Effect lore is formatted using the messages system. Customize in messages.yml:

# Empty line before effects section
effects-lore-header: ""

# Title of effects section
effects-lore-title: "<gray>Effects"

# Each effect line (placeholder: <effect>)
effects-lore-line: "<dark_gray>- <effect>"

# When effects are truncated (nb-effects-view > 0)
effects-lore-more: "<dark_gray>- <white>And More..."

Message Placeholders

effects-lore-line

The <effect> placeholder is replaced with the effect's display-name from the effect YAML:

Effect YAML:

id: "hammer"
type: "HAMMER"
display-name: "<gradient:#FFD700:#FFA500><bold>⚒ HAMMER</bold></gradient>"

Result in lore:

Effects
- ⚒ HAMMER

How Lore Generation Works

During Item Build

When an item is first created (/zitems item give):

Base lore is added from lore: in item YAML
Effect lore is generated based on base-effects-visible and nb-effects-view
Both are combined and applied to the item
Effects are stored in PDC (PersistentDataContainer)

Implementation: ZItem.java:build()

When Effects are Applied

When effects are added via /zitems effect apply:

Effect is added to PDC
Lore is recalculated:
- Base effects = original effects from config
- Additional effects = effects in PDC not in base
Effect lore is regenerated based on visibility settings
Item lore is updated: base lore + new effect lore

Implementation: ZEffectsManager.java:updateItemLoreWithEffects()

Lore Update Flow

┌─────────────────────────────────────────┐
│ Effect Applied via Command              │
│ /zitems effect apply <effect>           │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│ ZEffectsManager.applyEffect()           │
│ - Add effect to PDC                     │
│ - Call applyNoEventEffect()             │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│ updateItemLoreWithEffects()             │
│ - Load all effects from PDC             │
│ - Separate base vs additional           │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│ generateEffectLore()                    │
│ - Filter based on visibility settings   │
│ - Apply nb-effects-view limit           │
│ - Format using Messages enum            │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│ Combine base lore + effect lore         │
│ - Base lore from item config            │
│ - Effect lore from generation           │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│ ItemUtil.setLore()                      │
│ - Apply to ItemMeta                     │
│ - Player sees updated lore              │
└─────────────────────────────────────────┘

Examples

Show All Effects

id: "demo_pickaxe"
material: DIAMOND_PICKAXE
display-name: "<gold>Demo Pickaxe</gold>"
lore:
  - "<gray>A demonstration item"

effects:
  - hammer
  - vein_miner
  - auto_sell

# Show everything
nb-effects-view: -1
base-effects-visible: true
additional-effects-visible: true

Result:

Demo Pickaxe
A demonstration item

Effects
- ⚒ HAMMER
- ⛏ VEIN MINER
- 💰 AUTO SELL

Hide All Effects

id: "secret_pickaxe"
material: DIAMOND_PICKAXE
display-name: "<gold>Secret Pickaxe</gold>"
lore:
  - "<gray>Effects are hidden"

effects:
  - hammer

# Hide effects completely
nb-effects-view: 0

Result:

Secret Pickaxe
Effects are hidden

No effect lore is shown at all.

Limit to 2 Effects

id: "limited_pickaxe"
material: DIAMOND_PICKAXE
display-name: "<gold>Limited Pickaxe</gold>"

effects:
  - hammer
  - vein_miner
  - auto_sell
  - xp_boost

# Only show first 2 effects
nb-effects-view: 2
base-effects-visible: true
additional-effects-visible: true

Result:

Limited Pickaxe

Effects
- ⚒ HAMMER
- ⛏ VEIN MINER
- And More...

The "And More..." line indicates there are additional effects not shown.

Show Base Only

id: "base_only_pickaxe"
material: DIAMOND_PICKAXE
display-name: "<gold>Base Only Pickaxe</gold>"

effects:
  - hammer

# Only show base effects (hide added effects)
nb-effects-view: -1
base-effects-visible: true
additional-effects-visible: false

Result after adding Vein Miner:

/zitems effect apply vein_miner

Base Only Pickaxe

Effects
- ⚒ HAMMER

Vein Miner is NOT shown because additional-effects-visible: false.

Show Additional Only

id: "additional_only_pickaxe"
material: DIAMOND_PICKAXE
display-name: "<gold>Additional Only Pickaxe</gold>"

effects:
  - hammer

# Only show added effects (hide base)
nb-effects-view: -1
base-effects-visible: false
additional-effects-visible: true

Result initially:

Additional Only Pickaxe

No effects shown because only base effect exists.

After adding Vein Miner:

/zitems effect apply vein_miner

Additional Only Pickaxe

Effects
- ⛏ VEIN MINER

Only the added effect is shown.

Custom Formatting

Rainbow Effect List

# messages.yml
effects-lore-title: "<gradient:#FF0000:#FF7F00:#FFFF00:#00FF00:#0000FF:#4B0082:#9400D3>✨ Effects ✨</gradient>"
effects-lore-line: "<gradient:#FFD700:#FFA500>• <effect></gradient>"
effects-lore-more: "<gray>• <italic>Plus more...</italic>"

Result:

✨ Effects ✨
• ⚒ HAMMER
• ⛏ VEIN MINER
• Plus more...

Minimalist Style

# messages.yml
effects-lore-header: ""
effects-lore-title: "<white>─── Effects ───"
effects-lore-line: "<gray><effect>"
effects-lore-more: "<dark_gray>..."

Result:

─── Effects ───
⚒ HAMMER
⛏ VEIN MINER
...

Detailed Style

# messages.yml
effects-lore-title: "<aqua><bold>╔════ Effects ════╗"
effects-lore-line: "<aqua>║ <white><effect>"
effects-lore-more: "<aqua>║ <yellow>[+More Effects]"

Result:

╔════ Effects ════╗
║ ⚒ HAMMER
║ ⛏ VEIN MINER
║ [+More Effects]

Vanilla Items

Effects can be applied to vanilla items using /zitems effect apply (while holding the item).

Vanilla Item Lore Handling

For vanilla items:

Existing lore is preserved
Effect section is added below existing lore
If effects are updated, old effect section is replaced

Example:

/give @s diamond_pickaxe{display:{Lore:['{"text":"My pickaxe"}']}}
/zitems effect apply hammer

Result:

My pickaxe

Effects
- ⚒ HAMMER

Technical Details

Lore Separation

Custom Items:

Base lore is stored in ItemSettings.lore()
Effect lore is generated on-demand
Combined during build() and updateItemLoreWithEffects()

Vanilla Items:

Existing lore is scanned for effect section
Effect section identified by Messages.EFFECTS_LORE_TITLE
Old effect section removed before adding new one

Effect Order

Effects are displayed in the order they appear:

Base effects (if base-effects-visible: true)
Additional effects (if additional-effects-visible: true)

Within each group, effects are in the order they were added.

PDC Storage

All effects (base + additional) are stored in PersistentDataContainer:

Key: Keys.EFFECTS
Type: List<Effect>
Serialized using ZEffectDataType

The distinction between base and additional is recalculated each time by comparing PDC effects with the item config.

Troubleshooting

Effect lore not showing

Check:

Is nb-effects-view set to 0? (Hides all effects)
Is base-effects-visible or additional-effects-visible false?
Does the effect have a display-name in its YAML?

Debug:

# config.yml
debug: true

Look for: [zItems] [DEBUG] Updated item lore for <item> with <N> total effects

Lore duplicated

Cause: Calling updateItemLoreWithEffects() multiple times without clearing previous lore.

Solution: This is handled automatically by zItems. If you're using the API:

// Don't call this repeatedly for the same effect application
effectsManager.updateItemLoreWithEffects(item, effects);

"And More..." not showing

Check:

Is nb-effects-view set correctly? (Must be > 0 and < total effects)
Do you have more effects than the limit?

Example:

nb-effects-view: 5
effects:
  - hammer  # Only 1 effect

Won't show "And More..." because there's only 1 effect (less than limit).

Custom formatting not applying

Check:

Did you edit messages.yml?
Did you /zitems reload after editing?
Are you using valid MiniMessage syntax?

Test:

/zitems reload
/zitems item give @s <item>

If it still doesn't work, check for YAML syntax errors:

[zItems] [ERROR] Failed to load messages.yml: ...

API Usage

Updating Lore Programmatically

EffectsManager effectsManager = plugin.getManager(EffectsManager.class);
ItemStack item = player.getInventory().getItemInMainHand();

// Get all effects from PDC
List<Effect> effects = Keys.EFFECTS.get(
    item.getItemMeta().getPersistentDataContainer(),
    new ArrayList<>()
);

// Update lore
effectsManager.updateItemLoreWithEffects(item, effects);

Generating Effect Lore

The generation logic is in ZEffectsManager.java:

private List<Component> generateEffectLore(
    List<Effect> baseEffects,
    List<Effect> additionalEffects,
    ItemSettings itemSettings
) {
    // Implementation handles:
    // - nb-effects-view limit
    // - base/additional visibility
    // - Message formatting
    // - "And More..." line
}

Best Practices

Use -1 for normal items - Show all effects unless you have a reason to hide them
Use 0 for mystery items - Hide effects for surprise mechanics
Use limits for items with many effects - Prevents lore from becoming too long
Keep effect names concise - Long display names can wrap awkwardly
Test with many effects - Ensure lore doesn't overflow (Minecraft has lore limits)
Use consistent formatting - Edit messages.yml for server-wide style

Effects System - How effects work
Creating Items - Item configuration
Configuration - Global settings
Effect Handlers Reference - All available effects

Need help? Join our Discord or check GitHub Issues!

PreviousEffect Handlers Reference NextCustom Block Tracking

Last updated 5 days ago