LagLens Quick Usage Guide

Getting Started

Installation

1. Drop laglens-1.0.0.jar into your plugins/ folder
2. Restart your server
3. LagLens will auto-generate plugins/LagLens/config.yml

First Steps

/laglens

This shows your server's current performance status including TPS, memory usage, and any detected lag sources.

Essential Commands

Performance Overview

/laglens

Shows:

• Current TPS (color-coded: green = good, yellow = warning, red = critical)
• Memory usage percentage
• Number of loaded chunks
• Online player count
• Server health status
• Count of active lag sources

Scan for Lag Sources

/laglens scan

Features:

• Lists all chunks exceeding thresholds
• Color-coded severity (yellow = warning, red = critical)
• For players: clickable [TELEPORT] buttons to jump directly to problems
• Shows detailed breakdown of entity types, redstone activity, and more

Teleport to Problematic Chunks

/laglens tp 100 50              # Current world
/laglens tp 100 50 world_nether # Specific world

• Teleports you to the center of the specified chunk
• Auto-adjusts height for safety
• Shows chunk information on arrival
• Great for investigating lag sources found in scans

Clear Boats and Bubble Elevators

/laglens clear boats         # Default radius (64 blocks)
/laglens clear boats 128     # Medium clear radius  
/laglens clear boats 256     # Large clear radius
/laglens clear boats 512     # MASSIVE clear radius

Features:

• Removes all boats in the specified radius around you
• Optionally clears soul sand and magma blocks (configurable in config.yml)
• Perfect for clearing stuck bubble elevators
• Shows detailed removal count results
• Maximum radius of 512 blocks for massive boat accumulations
• Default radius increased to 64 blocks for better coverage

Clear Minecarts and Rail Systems

/laglens clear minecarts         # Default radius (32 blocks)
/laglens clear minecarts 64      # Medium clear radius
/laglens clear minecarts 128     # Large clear radius  
/laglens clear minecarts 256     # MASSIVE clear radius

Features:

• Removes all types of minecarts in the specified radius around you
• Optionally clears rail blocks (configurable in config.yml)
• Perfect for clearing minecart cramming issues
• Supports all minecart types: chest, hopper, furnace, TNT, spawner, command minecarts
• Shows detailed removal count results
• Maximum radius of 256 blocks for large transport systems
• Default radius of 32 blocks for targeted clearing

Configuration Management

/laglens reload

Reloads config.yml without restarting the server - perfect for tweaking thresholds on the fly.

Key Configuration Options

Essential Thresholds (config.yml)

thresholds:
  entities:
    warning: 50    # Total entities per chunk
    critical: 100
  mobs:
    warning: 30    # Living entities (excluding players)
    critical: 60
  minecarts:
    warning: 10    # Minecart lag sources
    critical: 25
  boats:
    warning: 15    # Boat entities
    critical: 30
  dropped_items:
    warning: 50    # Items on ground
    critical: 150
  entity_cramming:
    warning: 8     # Entities in same block space
    critical: 15
  minecart_cramming:
    warning: 5     # Minecarts clustered in 3x3x3 area
    critical: 10
  bubble_boats:
    warning: 3     # Boats on bubble columns (scanned in radius!)
    critical: 8
  redstone:
    warning: 40    # Redstone components (MUCH less strict!)
    critical: 100
  hoppers:
    warning: 8     # Hopper count
    critical: 20

Monitoring Frequency

monitoring:
  scan_interval: 20      # Check every 20 ticks (1 second)
  chunks_per_tick: 10    # Scan 10 chunks per tick (prevent scan lag)
  bubble_boat_scan_radius: 1  # Check 1 chunk around each chunk (reduced spam)
  
  # WARNING SPAM PREVENTION
  warning_cooldown: 60        # Wait 1 minute between warnings for same chunk+lagtype
  warn_once_per_chunk: true   # Only warn once per chunk+lagtype until issue is resolved

Clear Boats Settings

clear_boats:
  default_radius: 64        # Default radius for clear command (increased!)
  max_radius: 512          # Maximum allowed radius for massive clearing
  clear_soul_sand: true    # Also remove soul sand when clearing boats
  clear_magma_blocks: true # Also remove magma blocks when clearing boats

# Clear Minecarts Settings
clear_minecarts:
  default_radius: 32        # Default radius for clear command
  max_radius: 256          # Maximum allowed radius for large systems
  clear_rails: false       # Also remove regular rails when clearing minecarts
  clear_powered_rails: false # Also remove powered rails when clearing minecarts
  clear_detector_rails: false # Also remove detector rails when clearing minecarts

Discord Integration

discord:
  enabled: false                    # Enable Discord webhook alerts
  webhook_url: "YOUR_WEBHOOK_URL"   # Discord webhook URL
  send_alerts: true                 # Send lag alerts to Discord
  
  alerts:
    include_server_info: true       # Include TPS/memory in alerts
    ping_role_id: ""               # Role ID to ping for critical alerts
    critical_only: false           # Only send critical alerts
    warning_color: "0xFFA500"      # Warning alert color (orange)
    critical_color: "0xFF0000"     # Critical alert color (red)

Common Use Cases

Daily Health Check

/laglens

Quick status check - green TPS means you're good!

Investigating Player Reports

/laglens scan

When players report lag, scan to see what chunks are problematic, then click [TELEPORT] to investigate instantly!

Proactive Maintenance

Set conservative thresholds to catch problems before they impact TPS:

entities:
  warning: 30    # Lower threshold = earlier detection

Clearing Minecart Cramming

When you get minecart cramming warnings:

/laglens scan                    # Identify the problem chunk
[Click TELEPORT] or /laglens tp  # Go to the problematic chunk
/laglens clear minecarts 64      # Clear crammed minecarts

Advanced Options:

• Use larger radius for massive systems: /laglens clear minecarts 128
• Enable rail clearing in config.yml to completely dismantle broken transport systems
• Check different minecart types with /kill @e[type=chest_minecart,distance=..32]

Tuning for Your Server

• Large servers: Increase thresholds to reduce noise
• Small servers: Decrease thresholds for early detection
• Creative servers: Lower redstone and entity thresholds
• Survival servers: Focus on mob and item thresholds

Understanding Warning Types

Warning Spam Prevention

LagLens now includes intelligent warning spam prevention:

• Reduced cooldown: 1 minute between warnings (was 2 minutes)
• Lag-type specific warnings: Only warns once per chunk per lag type until resolved
• Automatic reset: When a chunk's lag is fixed, warnings can trigger again
• Less chat clutter: Focus on actual problems instead of repeated alerts
• Smart detection: Different lag types in the same chunk can each warn once

Clear Boats Command

Usage: /laglens clear boats [radius]

• Purpose: Remove stuck boats and bubble elevator components
• Default radius: 16 blocks around you
• Configurable: Choose whether to also clear soul sand and magma blocks
• Safe limits: Maximum 64 block radius to prevent server lag
• Detailed results: Shows exactly what was removed

Perfect for:

• Cleaning up stuck bubble elevators
• Removing boat farms that got out of control
• Clearing transportation systems causing lag

Discord Integration

LagLens supports Discord webhook alerts for real-time lag notifications.

Features:

• Rich embeds with detailed lag source information
• Color-coded alerts (orange for warnings, red for critical)
• Server status included (TPS, memory, player count)
• Suggested actions for boat/bubble elevator issues
• Role pinging for critical alerts
• Spam prevention works with Discord too

Setup:

1. Create a Discord webhook in your server channel
2. Copy the webhook URL
3. Set discord.enabled: true in config.yml
4. Paste your webhook URL in discord.webhook_url
5. Configure alert settings as needed

Example Discord Alert:

CRITICAL Lag Source Detected
Location: World: world, Chunk: 30, -13
Issue Type: Entity Cramming (Minecart Cramming)
Severity: 12 (limit: 5)
Details: Minecart Cramming: 12 minecarts clustered in 3x3x3 area
URGENT: Clear Minecart Cramming!
/laglens tp 30 -13 world
Then use clear command:
/laglens clear minecarts 64
Or for larger radius:
/laglens clear minecarts 128
Or kill manually:
/kill @e[type=minecart,distance=..16]
/kill @e[type=chest_minecart,distance=..16]
/kill @e[type=hopper_minecart,distance=..16]

12 minecarts crammed - Fix ASAP!
Server Status: TPS: 16.8, Players: 8, Memory: 72%

Entity Cramming Warnings

• Cause: Multiple entities occupying the same block space
• Common sources: Mob farms, transport systems, player traps
• Fix: Spread entities out, optimize farm designs

Minecart Warnings

• Cause: Too many minecarts in storage systems or transport networks
• Fix: Use item elevators, optimize storage, clear unused minecarts

Minecart Cramming Warnings

• Advanced Detection: Detects when 5+ minecarts are clustered within a 3x3x3 block area
• More Realistic: Uses spatial proximity instead of exact block matching
• Cause: Minecarts stuck together in storage systems, transport jams, or broken contraptions
• Thresholds: Warning at 5 minecarts clustered, Critical at 10+ clustered
• Fix Options:

  /kill @e[type=minecart,distance=..16]           # Clear all minecarts nearby
  /kill @e[type=chest_minecart,distance=..16]     # Only chest minecarts
  /kill @e[type=hopper_minecart,distance=..16]    # Only hopper minecarts
  

• Why Important: Clustered minecarts cause collision detection lag and can freeze transport systems

Boat Warnings

• Cause: Excessive boats from transportation or breeding farms
• Fix: Clear unused boats, optimize boat elevators

Bubble Boat Warnings

• Cause: Boats stuck on soul sand bubble columns (common in elevators)
• Detection: Scans in a 1-chunk radius with smart overlap prevention
• Advanced detection: Finds boats on bubble columns, soul sand, magma blocks, and nearby water
• Spam prevention: Only the closest chunk reports each boat (no duplicate warnings)
• Fix: Clear stuck boats, improve bubble elevator design, use clear boats command

Dropped Item Warnings

• Cause: Too many items on the ground from farms or player activity
• Fix: Add hoppers to collect items, clear old drops

Mob Warnings

• Cause: Excessive mobs from farms, breeding, or spawning areas
• Fix: Kill excess mobs, optimize farm limits, improve mob management

Redstone Warnings (Less Strict Now)

• Cause: Complex redstone contraptions
• Thresholds: Now 100/200 instead of 40/100 - much more reasonable!
• Fix: Optimize circuits, reduce clock frequency, spread across chunks

Clickable Warnings

When lag warnings appear in chat, admins can now click [TELEPORT] to instantly jump to the problematic chunk! No more copying coordinates manually.

Example warning:

[LagLens] Chunk 100, 50 has 120 entities (limit: 100) [TELEPORT]
                                                        ↑ Click this!

Pro Tips

1. Click the [TELEPORT] links - Instant investigation!
2. Use /laglens scan regularly - Don't wait for lag to investigate
3. Use /laglens clear boats 512 for massive issues - Nuclear option for huge boat problems
4. Set up Discord alerts - Get notified instantly when lag sources appear
5. Warnings won't spam anymore - Each chunk only warns once until fixed
6. Entity cramming detection - Catches mob farm issues early
7. Bubble boat detection - Finds stuck boat elevators automatically
8. Monitor during peak hours - Most lag happens when server is busiest
9. Redstone is less strict now - Fewer false positives from normal builds

Permissions for Staff

# Basic moderator - can check and scan
laglens.use: true
laglens.scan: true

# Advanced moderator - can also clear entities
laglens.clear: true  # Clear boats and minecarts

# Admin - full access including teleport and config
laglens.admin: true  # Gets clickable teleport warnings