Entity Clearing

The Entity Clearing module automatically removes entities at configurable intervals to prevent server lag caused by excessive entities.

Overview

Purpose: Remove unwanted entities while protecting important ones

Key Features:

  • Automatic clearing at configurable intervals
  • Smart protection system (named, tamed, stacked)
  • Extra protections (boats, breeding, plugins)
  • Customizable whitelist/blacklist
  • Warning notifications before clearing
  • Sound effects and visual alerts

Configuration

Location: plugins/ClearLaggEnhanced/module/entity-clearing/config.yml

Basic Settings

enabled: true
interval: 300                    # Clear interval in seconds (300 = 5 minutes)

Recommended intervals:

  • Small servers (1-20 players): 600 (10 minutes)
  • Medium servers (20-100 players): 300 (5 minutes)
  • Large servers (100+ players): 180 (3 minutes)

Protection Settings

protect-named-entities: true     # Protect entities with custom names
protect-tamed-entities: true     # Protect tamed animals (pets)
protect-armored-entities: false  # Protect entities wearing armor
protect-stacked-entities: false  # Protect stacked entities (requires stacker plugin)
whitelist-all-mobs: false        # If true, only clear items/projectiles

How protection works:

  1. Players are ALWAYS protected (cannot be cleared)
  2. Named entities are protected when protect-named-entities: true
  3. Tamed entities (wolves, cats, horses) protected when protect-tamed-entities: true
  4. Armored entities protected when protect-armored-entities: true
  5. Stacked entities protected when protect-stacked-entities: true
  6. Whitelist - Entities in the whitelist are NEVER cleared regardless of other settings

Important: If protect-stacked-entities: false, an entire stack will be removed even if the entity is named. This requires RoseStacker or WildStacker to be installed.

Extra Protections

extra-protections:
  mobs-in-boats: true            # Protect any mob in a boat
  mobs-from-breeding: true       # Protect mobs spawned from breeding
  modern-showcase: true          # Protect ModernShowcase display cases
  player-heads: true             # Never clear player head items
  pets-module: true              # Protect entities marked as pets

Extra Protection Details:

Mobs in Boats

When mobs-in-boats: true:

  • Any living entity that is a passenger in a boat is protected
  • Prevents accidental clearing of transported mobs
  • Useful for villager trading halls and mob transportation

Example: You're transporting a villager in a boat. Entity clearing happens, but the villager is protected because it's in a boat.

Mobs from Breeding

When mobs-from-breeding: true:

  • Any mob spawned through breeding is permanently tagged and protected
  • Tag persists across server restarts
  • Encourages mob farming instead of wild spawning

Example: You breed two cows. The baby cow is automatically protected from all future entity clears, even after it grows up.

ModernShowcase Protection

When modern-showcase: true:

  • Automatically detects and protects display cases from ModernShowcase plugin
  • Prevents your shop displays from being cleared
  • Requires ModernShowcase to be installed

Player Heads

When player-heads: true:

  • Specifically protects dropped player head items
  • Useful for player markets and decoration
  • Applies to items with type PLAYER_HEAD

Pets Module

When pets-module: true:

  • Generic protection for entities marked as pets by various plugins
  • Checks for common pet metadata/tags
  • Compatible with multiple pet plugins

Whitelist Configuration

whitelist:
  - "VILLAGER"
  - "ZOMBIE_VILLAGER"
  - "IRON_GOLEM"
  - "ARMOR_STAND"
  - "ITEM_FRAME"
  - "GLOW_ITEM_FRAME"
  - "LEASH_HITCH"

How the whitelist works:

  • Entities IN the whitelist are NEVER cleared
  • Entities NOT in the whitelist WILL BE cleared (unless protected by other settings)
  • Players are always protected (don't need to add them)

Common entities to whitelist:

  • VILLAGER - Trading, villages
  • IRON_GOLEM - Village protection
  • ARMOR_STAND - Decorations, shops
  • ITEM_FRAME / GLOW_ITEM_FRAME - Item displays
  • PAINTING - Decorations
  • ITEM_DISPLAY - Modern display entities (1.19.4+)
  • INTERACTION - Interaction entities (1.19.4+)

Common entities to clear (not in whitelist):

  • DROPPED_ITEM - Dropped items on ground
  • EXPERIENCE_ORB - XP orbs
  • ARROW - Arrows, projectiles
  • ZOMBIE, SKELETON, CREEPER - Hostile mobs
  • PRIMED_TNT - Primed TNT entities

Full entity list: Spigot EntityType

Item Whitelist

item-whitelist:
  - "NETHERITE_INGOT"

Purpose: Protect specific dropped item types from being cleared.

Common items to whitelist:

  • NETHERITE_INGOT - Rare, valuable
  • NETHER_STAR - Wither drops
  • DRAGON_EGG - Unique item
  • ELYTRA - Hard to obtain
  • TOTEM_OF_UNDYING - Valuable

Note: Only affects DROPPED_ITEM entities with specific materials.

World Configuration

worlds: []                       # Empty = all worlds

Examples:

Clear entities in all worlds:

worlds: []

Clear entities only in specific worlds:

worlds:
  - "world"
  - "world_nether"

Notifications

notifications:
  broadcast-times: [60, 30, 10, 5]    # Warning times in seconds
  types:
    - "ACTION_BAR"                     # Display type(s)
  console-notifications: false         # Show in console
  sound:
    enabled: true
    name: "BLOCK_NOTE_BLOCK_PLING"
    volume: 1.0
    pitch: 1.2

Notification Types:

  • CHAT - Send message in chat
  • ACTION_BAR - Display above hotbar (recommended)
  • TITLE - Show as large title overlay

Multiple types: You can specify multiple notification types:

types:
  - "ACTION_BAR"
  - "CHAT"

Sound Configuration:

  • enabled - Enable/disable sound
  • name - Sound name (must be valid Minecraft sound)
  • volume - Sound volume (0.0 to 10.0)
  • pitch - Sound pitch (0.5 to 2.0)

Common sounds:

  • BLOCK_NOTE_BLOCK_PLING - Note block pling
  • ENTITY_EXPERIENCE_ORB_PICKUP - XP pickup sound
  • BLOCK_BELL_USE - Bell sound
  • ENTITY_PLAYER_LEVELUP - Level up sound

Usage

Manual Clear

/lagg clear

Immediately clears entities without waiting for the timer.

Check Next Clear

/lagg next

Shows time until next automatic clear.

Testing Protection

Test named protection:

  1. Name an entity with a name tag
  2. Run /lagg clear
  3. Named entity should remain

Test tamed protection:

  1. Tame a wolf or cat
  2. Run /lagg clear
  3. Pet should remain

Test whitelist:

  1. Add entity to whitelist
  2. Spawn that entity type
  3. Run /lagg clear
  4. Entity should remain

Examples

Aggressive Clearing (Large Server)

enabled: true
interval: 180                    # Clear every 3 minutes
protect-named-entities: true
protect-tamed-entities: true
protect-armored-entities: false
whitelist:
  - "VILLAGER"
  - "IRON_GOLEM"
item-whitelist:
  - "NETHERITE_INGOT"
  - "NETHER_STAR"

Result: Clears frequently but protects important entities.

Conservative Clearing (Small Server)

enabled: true
interval: 600                    # Clear every 10 minutes
protect-named-entities: true
protect-tamed-entities: true
protect-armored-entities: true
extra-protections:
  mobs-in-boats: true
  mobs-from-breeding: true
whitelist-all-mobs: true         # Only clear items/projectiles

Result: Only clears items and projectiles, keeps all mobs.

Survival Server Focus

enabled: true
interval: 300
protect-named-entities: true
protect-tamed-entities: true
extra-protections:
  mobs-in-boats: true
  mobs-from-breeding: true
whitelist:
  - "VILLAGER"
  - "ZOMBIE_VILLAGER"
  - "IRON_GOLEM"
  - "ARMOR_STAND"
  - "ITEM_FRAME"
  - "GLOW_ITEM_FRAME"
  - "LEASH_HITCH"
  - "ALLAY"                      # Useful mob
  - "BEE"                        # Farms

Result: Balanced clearing that protects player builds and farms.

Troubleshooting

Entities Not Being Cleared

Check these:

  1. Is enabled: true?
  2. Is the entity in the whitelist? (remove it)
  3. Is the entity named? (set protect-named-entities: false)
  4. Is the entity tamed? (set protect-tamed-entities: false)
  5. Is the entity in a boat? (set mobs-in-boats: false)
  6. Is the entity from breeding? (set mobs-from-breeding: false)
  7. Is whitelist-all-mobs: true? (set to false)

Important Entities Being Cleared

Solutions:

  1. Add entity type to whitelist
  2. Name entities to protect them
  3. Enable extra protections
  4. Check if entity is supported by protection system

Too Many Warnings

Reduce warnings:

notifications:
  broadcast-times: [30, 5]       # Only warn at 30s and 5s

Performance Not Improving

Make clearing more aggressive:

  1. Reduce interval (e.g., 180 seconds)
  2. Remove unnecessary entities from whitelist
  3. Disable extra protections if not needed
  4. Set whitelist-all-mobs: false

Related