SIMPLExClearLagMergeItems v1.0.1

ClearLagMergeItems — Description & Instructions​

What this plugin does​

• Merges ground item entities to reduce lag.
• Shows a floating name above items (e.g., Item xAmount).
• Virtual item stacking: keeps the visible stack size (e.g., 64) while tracking the real total internally.
• Mob stacking: merges duplicate mobs into a single mob with a stack count, and shows a TextDisplay label like Pig × 5.
• Mob stack persistence: periodically saves mob stack counts to mob_stacks.yml and restores them after restarts.
  
  

• How to install / update​

  • Put ClearLagMergeItems.jar in your server plugins/ folder.
  • Start the server once to generate the config.
  • If you already have plugins/ClearLagMergeItems/config.yml, the plugin will not overwrite it automatically.

Commands​

• /clm run: run the merge/cleanup cycle immediately.
• /clm reload: reload the plugin config (and restart the mob label resync/persistence tasks).
• /clm toggle: toggle the plugin’s main functionality (if enabled in your command handler).

Key configuration (config.yml)​

Main loop​

• enabled: master switch.
• interval_seconds: how often the plugin runs automatically.
  • Set 0 to disable automatic runs (manual /clm run only).

Item display (floating text over items)​

• display.enabled: show/hide item name label.
• display.format: supports:
  • {item} = pretty item name
  • {amount} = total amount (virtual total if enabled)

Virtual stacking (recommended)​

• virtual_stack.enabled: enables virtual totals on item entities.
• virtual_stack.physical_amount: visible item stack size (1–127), usually 64.
• virtual_stack.max_total: cap per stack (-1 = unlimited).

Cleanup (optional)​

• cleanup.enabled: removes old ground items before merging.
• cleanup.max_age_seconds: minimum age to remove.
• cleanup.remove_mode:
  • ALL = remove all eligible items
  • VANILLA_ONLY = only remove “plain” vanilla-like drops (no lore/enchants/custom model etc.)
• cleanup.exempt_named_items: skip named items depending on mode/rules.

---

Mob stacking​

Enable + basic rules​

• mob_stack.enabled: enables mob stacking.
• mob_stack.require_no_custom_name: if true, mobs with custom names/nametags are not merged.
• mob_stack.blacklist: entity types never merged (e.g., WITHER, VILLAGER, etc.)

Merge region​

By default, the plugin stacks mobs only if they fit inside a single 3D “box”:

mob_stack:
merge_region:
enabled: true
max_width_x: 32
max_length_z: 32
max_height_y: 10
Meaning: for a same-type group, the plugin only merges them if
max⁡X−min⁡X≤32maxX−minX≤32, max⁡Z−min⁡Z≤32maxZ−minZ≤32, and max⁡Y−min⁡Y≤10maxY−minY≤10.

To revert to the old behavior (merge within each chunk), set:

• mob_stack.merge_region.enabled: false

Mob label (TextDisplay)​

• mob_stack.display.enabled: show/hide stack label.
• mob_stack.display.formatplaceholders:
  • {type} = mob type (sheep includes color)
  • {count} = stack count
• Vertical label placement (anti “too high” tuning):
  • vertical_anchor: HITBOX_TOP
  • hitbox_reference: CENTER_TO_TOP (recommended)
  • offset_y and label_height_scale control fine-tuning.

This system requires minimal setup,
but full customization is available if desired.

I may not be good at explaining things, but I'm here to support you.