# LagLens Quick Usage Guide<\/p>\n
## Getting Started<\/p>\n
### Installation
\n1. Drop `laglens-1.0.0.jar` into your `plugins\/` folder
\n2. Restart your server
\n3. LagLens will auto-generate `plugins\/LagLens\/config.yml`<\/p>\n
### First Steps
\n“`
\n\/laglens
\n“`
\nThis shows your server’s current performance status including TPS, memory usage, and any detected lag sources.<\/p>\n
## Essential Commands<\/p>\n
### Performance Overview
\n“`
\n\/laglens
\n“`
\n**Shows:**
\n– Current TPS (color-coded: green = good, yellow = warning, red = critical)
\n– Memory usage percentage
\n– Number of loaded chunks
\n– Online player count
\n– Server health status
\n– Count of active lag sources<\/p>\n
### Scan for Lag Sources
\n“`
\n\/laglens scan
\n“`
\n**Features:**
\n– Lists all chunks exceeding thresholds
\n– Color-coded severity (yellow = warning, red = critical)
\n– For players: **clickable [TELEPORT] buttons** to jump directly to problems
\n– Shows detailed breakdown of entity types, redstone activity, and more<\/p>\n
### Teleport to Problematic Chunks
\n“`
\n\/laglens tp 100 50 # Current world
\n\/laglens tp 100 50 world_nether # Specific world
\n“`
\n– Teleports you to the center of the specified chunk
\n– Auto-adjusts height for safety
\n– Shows chunk information on arrival
\n– Great for investigating lag sources found in scans<\/p>\n
### Clear Boats and Bubble Elevators
\n“`
\n\/laglens clear boats # Default radius (64 blocks)
\n\/laglens clear boats 128 # Medium clear radius
\n\/laglens clear boats 256 # Large clear radius
\n\/laglens clear boats 512 # MASSIVE clear radius
\n“`
\n**Features:**
\n– Removes all boats in the specified radius around you
\n– **Optionally clears soul sand and magma blocks** (configurable in config.yml)
\n– Perfect for clearing stuck bubble elevators
\n– Shows detailed removal count results
\n– **Maximum radius of 512 blocks** for massive boat accumulations
\n– **Default radius increased to 64 blocks** for better coverage<\/p>\n
### Clear Minecarts and Rail Systems
\n“`
\n\/laglens clear minecarts # Default radius (32 blocks)
\n\/laglens clear minecarts 64 # Medium clear radius
\n\/laglens clear minecarts 128 # Large clear radius
\n\/laglens clear minecarts 256 # MASSIVE clear radius
\n“`
\n**Features:**
\n– Removes all types of minecarts in the specified radius around you
\n– **Optionally clears rail blocks** (configurable in config.yml)
\n– Perfect for clearing minecart cramming issues
\n– Supports all minecart types: chest, hopper, furnace, TNT, spawner, command minecarts
\n– Shows detailed removal count results
\n– **Maximum radius of 256 blocks** for large transport systems
\n– **Default radius of 32 blocks** for targeted clearing<\/p>\n
### Configuration Management
\n“`
\n\/laglens reload
\n“`
\nReloads config.yml without restarting the server – perfect for tweaking thresholds on the fly.<\/p>\n
## Key Configuration Options<\/p>\n
### Essential Thresholds (config.yml)
\n“`yaml
\nthresholds:
\n entities:
\n warning: 50 # Total entities per chunk
\n critical: 100
\n mobs:
\n warning: 30 # Living entities (excluding players)
\n critical: 60
\n minecarts:
\n warning: 10 # Minecart lag sources
\n critical: 25
\n boats:
\n warning: 15 # Boat entities
\n critical: 30
\n dropped_items:
\n warning: 50 # Items on ground
\n critical: 150
\n entity_cramming:
\n warning: 8 # Entities in same block space
\n critical: 15
\n minecart_cramming:
\n warning: 5 # Minecarts clustered in 3x3x3 area
\n critical: 10
\n bubble_boats:
\n warning: 3 # Boats on bubble columns (scanned in radius!)
\n critical: 8
\n redstone:
\n warning: 40 # Redstone components (MUCH less strict!)
\n critical: 100
\n hoppers:
\n warning: 8 # Hopper count
\n critical: 20
\n“`<\/p>\n
### Monitoring Frequency
\n“`yaml
\nmonitoring:
\n scan_interval: 20 # Check every 20 ticks (1 second)
\n chunks_per_tick: 10 # Scan 10 chunks per tick (prevent scan lag)
\n bubble_boat_scan_radius: 1 # Check 1 chunk around each chunk (reduced spam)<\/p>\n
# WARNING SPAM PREVENTION
\n warning_cooldown: 60 # Wait 1 minute between warnings for same chunk+lagtype
\n warn_once_per_chunk: true # Only warn once per chunk+lagtype until issue is resolved
\n“`<\/p>\n
### Clear Boats Settings
\n“`yaml
\nclear_boats:
\n default_radius: 64 # Default radius for clear command (increased!)
\n max_radius: 512 # Maximum allowed radius for massive clearing
\n clear_soul_sand: true # Also remove soul sand when clearing boats
\n clear_magma_blocks: true # Also remove magma blocks when clearing boats<\/p>\n
# Clear Minecarts Settings
\nclear_minecarts:
\n default_radius: 32 # Default radius for clear command
\n max_radius: 256 # Maximum allowed radius for large systems
\n clear_rails: false # Also remove regular rails when clearing minecarts
\n clear_powered_rails: false # Also remove powered rails when clearing minecarts
\n clear_detector_rails: false # Also remove detector rails when clearing minecarts
\n“`<\/p>\n
### Discord Integration
\n“`yaml
\ndiscord:
\n enabled: false # Enable Discord webhook alerts
\n webhook_url: “YOUR_WEBHOOK_URL” # Discord webhook URL
\n send_alerts: true # Send lag alerts to Discord<\/p>\n
alerts:
\n include_server_info: true # Include TPS\/memory in alerts
\n ping_role_id: “” # Role ID to ping for critical alerts
\n critical_only: false # Only send critical alerts
\n warning_color: “0xFFA500” # Warning alert color (orange)
\n critical_color: “0xFF0000” # Critical alert color (red)
\n“`<\/p>\n
## Common Use Cases<\/p>\n
### Daily Health Check
\n“`
\n\/laglens
\n“`
\nQuick status check – green TPS means you’re good!<\/p>\n
### Investigating Player Reports
\n“`
\n\/laglens scan
\n“`
\nWhen players report lag, scan to see what chunks are problematic, then **click [TELEPORT]** to investigate instantly!<\/p>\n
### Proactive Maintenance
\nSet conservative thresholds to catch problems before they impact TPS:
\n“`yaml
\nentities:
\n warning: 30 # Lower threshold = earlier detection
\n“`<\/p>\n
### Clearing Minecart Cramming
\nWhen you get minecart cramming warnings:
\n“`
\n\/laglens scan # Identify the problem chunk
\n[Click TELEPORT] or \/laglens tp # Go to the problematic chunk
\n\/laglens clear minecarts 64 # Clear crammed minecarts
\n“`
\n**Advanced Options:**
\n– Use larger radius for massive systems: `\/laglens clear minecarts 128`
\n– Enable rail clearing in config.yml to completely dismantle broken transport systems
\n– Check different minecart types with `\/kill @e[type=chest_minecart,distance=..32]`<\/p>\n
### Tuning for Your Server
\n– **Large servers**: Increase thresholds to reduce noise
\n– **Small servers**: Decrease thresholds for early detection
\n– **Creative servers**: Lower redstone and entity thresholds
\n– **Survival servers**: Focus on mob and item thresholds<\/p>\n
## Understanding Warning Types<\/p>\n
### Warning Spam Prevention
\nLagLens now includes intelligent warning spam prevention:
\n– **Reduced cooldown**: 1 minute between warnings (was 2 minutes)
\n– **Lag-type specific warnings**: Only warns once per chunk per lag type until resolved
\n– **Automatic reset**: When a chunk’s lag is fixed, warnings can trigger again
\n– **Less chat clutter**: Focus on actual problems instead of repeated alerts
\n– **Smart detection**: Different lag types in the same chunk can each warn once<\/p>\n
### Clear Boats Command
\n**Usage**: `\/laglens clear boats [radius]`
\n– **Purpose**: Remove stuck boats and bubble elevator components
\n– **Default radius**: 16 blocks around you
\n– **Configurable**: Choose whether to also clear soul sand and magma blocks
\n– **Safe limits**: Maximum 64 block radius to prevent server lag
\n– **Detailed results**: Shows exactly what was removed<\/p>\n
**Perfect for:**
\n– Cleaning up stuck bubble elevators
\n– Removing boat farms that got out of control
\n– Clearing transportation systems causing lag<\/p>\n
### Discord Integration
\nLagLens supports **Discord webhook alerts** for real-time lag notifications.<\/p>\n
**Features:**
\n– **Rich embeds** with detailed lag source information
\n– **Color-coded alerts** (orange for warnings, red for critical)
\n– **Server status** included (TPS, memory, player count)
\n– **Suggested actions** for boat\/bubble elevator issues
\n– **Role pinging** for critical alerts
\n– **Spam prevention** works with Discord too<\/p>\n
**Setup:**
\n1. Create a Discord webhook in your server channel
\n2. Copy the webhook URL
\n3. Set `discord.enabled: true` in config.yml
\n4. Paste your webhook URL in `discord.webhook_url`
\n5. Configure alert settings as needed<\/p>\n
**Example Discord Alert:**
\n“`
\nCRITICAL Lag Source Detected
\nLocation: World: world, Chunk: 30, -13
\nIssue Type: Entity Cramming (Minecart Cramming)
\nSeverity: 12 (limit: 5)
\nDetails: Minecart Cramming: 12 minecarts clustered in 3x3x3 area
\nURGENT: Clear Minecart Cramming!
\n\/laglens tp 30 -13 world
\nThen use clear command:
\n\/laglens clear minecarts 64
\nOr for larger radius:
\n\/laglens clear minecarts 128
\nOr kill manually:
\n\/kill @e[type=minecart,distance=..16]
\n\/kill @e[type=chest_minecart,distance=..16]
\n\/kill @e[type=hopper_minecart,distance=..16]<\/p>\n
12 minecarts crammed – Fix ASAP!
\nServer Status: TPS: 16.8, Players: 8, Memory: 72%
\n“`<\/p>\n
### Entity Cramming Warnings
\n– **Cause**: Multiple entities occupying the same block space
\n– **Common sources**: Mob farms, transport systems, player traps
\n– **Fix**: Spread entities out, optimize farm designs<\/p>\n
### Minecart Warnings
\n– **Cause**: Too many minecarts in storage systems or transport networks
\n– **Fix**: Use item elevators, optimize storage, clear unused minecarts<\/p>\n
### Minecart Cramming Warnings
\n– **Advanced Detection**: Detects when 5+ minecarts are clustered within a 3x3x3 block area
\n– **More Realistic**: Uses spatial proximity instead of exact block matching
\n– **Cause**: Minecarts stuck together in storage systems, transport jams, or broken contraptions
\n– **Thresholds**: Warning at 5 minecarts clustered, Critical at 10+ clustered
\n– **Fix Options**:
\n “`
\n \/kill @e[type=minecart,distance=..16] # Clear all minecarts nearby
\n \/kill @e[type=chest_minecart,distance=..16] # Only chest minecarts
\n \/kill @e[type=hopper_minecart,distance=..16] # Only hopper minecarts
\n “`
\n– **Why Important**: Clustered minecarts cause collision detection lag and can freeze transport systems<\/p>\n
### Boat Warnings
\n– **Cause**: Excessive boats from transportation or breeding farms
\n– **Fix**: Clear unused boats, optimize boat elevators<\/p>\n
### Bubble Boat Warnings
\n– **Cause**: Boats stuck on soul sand bubble columns (common in elevators)
\n– **Detection**: Scans in a 1-chunk radius with smart overlap prevention
\n– **Advanced detection**: Finds boats on bubble columns, soul sand, magma blocks, and nearby water
\n– **Spam prevention**: Only the closest chunk reports each boat (no duplicate warnings)
\n– **Fix**: Clear stuck boats, improve bubble elevator design, use clear boats command<\/p>\n
### Dropped Item Warnings
\n– **Cause**: Too many items on the ground from farms or player activity
\n– **Fix**: Add hoppers to collect items, clear old drops<\/p>\n
### Mob Warnings
\n– **Cause**: Excessive mobs from farms, breeding, or spawning areas
\n– **Fix**: Kill excess mobs, optimize farm limits, improve mob management<\/p>\n
### Redstone Warnings (Less Strict Now)
\n– **Cause**: Complex redstone contraptions
\n– **Thresholds**: Now 100\/200 instead of 40\/100 – much more reasonable!
\n– **Fix**: Optimize circuits, reduce clock frequency, spread across chunks<\/p>\n
## Clickable Warnings<\/p>\n
When lag warnings appear in chat, admins can now **click [TELEPORT]** to instantly jump to the problematic chunk! No more copying coordinates manually.<\/p>\n
**Example warning:**
\n“`
\n[LagLens] Chunk 100, 50 has 120 entities (limit: 100) [TELEPORT]
\n \u2191 Click this!
\n“`<\/p>\n
## Pro Tips<\/p>\n
1. **Click the [TELEPORT] links** – Instant investigation!
\n2. **Use `\/laglens scan` regularly** – Don’t wait for lag to investigate
\n3. **Use `\/laglens clear boats 512` for massive issues** – Nuclear option for huge boat problems
\n4. **Set up Discord alerts** – Get notified instantly when lag sources appear
\n5. **Warnings won’t spam anymore** – Each chunk only warns once until fixed
\n6. **Entity cramming detection** – Catches mob farm issues early
\n7. **Bubble boat detection** – Finds stuck boat elevators automatically
\n8. **Monitor during peak hours** – Most lag happens when server is busiest
\n9. **Redstone is less strict now** – Fewer false positives from normal builds<\/p>\n
## Permissions for Staff<\/p>\n
“`yaml
\n# Basic moderator – can check and scan
\nlaglens.use: true
\nlaglens.scan: true<\/p>\n
# Advanced moderator – can also clear entities
\nlaglens.clear: true # Clear boats and minecarts<\/p>\n
# Admin – full access including teleport and config
\nlaglens.admin: true # Gets clickable teleport warnings
\n“`<\/p>\n","protected":false},"excerpt":{"rendered":"
LagLens: Minecraft server plugin that detects lag sources, monitors TPS, and clears problematic entities automatically.<\/p>\n","protected":false},"featured_media":91553,"template":"","meta":{"_minecraft_slug":"laglens","_minecraft_project_id":"ZVCDutCy","_minecraft_author":"blstmo","_minecraft_license":"MIT","_minecraft_downloads":224,"_minecraft_follows":2,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"laglens.zip","_minecraft_size_bytes":5009717,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-16T12:25:17.550804Z","_minecraft_date_created":"2025-06-09T08:04:05.592350Z","_minecraft_date_modified":"2025-06-02T01:59:35.067435Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/laglens","_minecraft_icon_attachment_id":91553,"_minecraft_imported_at":"2026-06-05T05:32:18+00:00","_minecraft_import_hash":"0b88760f12dd0dd86bc6707fc18396eb","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[124,126,90,127,128,123,92],"mod_loader":[130,132,133],"minecraft_version":[62,37,73,74,38,78],"class_list":["post-91552","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-bukkit","mod_category-management","mod_category-optimization","mod_category-paper","mod_category-purpur","mod_category-technology","mod_category-utility","mod_loader-bukkit","mod_loader-paper","mod_loader-purpur","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5"],"yoast_head":"\n