laglens

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 ``` clickable [TELEPORT] buttons - 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 ``` Default radius increased to 64 blocks - Removes all boats in the specified radius around you - Default radius increased to 64 blocks (configurable in config.yml) - Perfect for clearing stuck bubble elevators - Shows detailed removal count results - Default radius increased to 64 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 ``` Default radius of 32 blocks - Removes all types of minecarts in the specified radius around you - Default radius of 32 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 - Default radius of 32 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)

```yaml 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

```yaml 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

```yaml 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

```yaml 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: ```yaml 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

- Survival servers: Increase thresholds to reduce noise - Survival servers: Decrease thresholds for early detection - Survival 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: - Smart detection: 1 minute between warnings (was 2 minutes) - Smart detection: Only warns once per chunk per lag type until resolved - Smart detection: When a chunk's lag is fixed, warnings can trigger again - Smart detection: Focus on actual problems instead of repeated alerts - Smart detection: Different lag types in the same chunk can each warn once

Clear Boats Command

Detailed results: `/laglens clear boats [radius]` - Detailed results: Remove stuck boats and bubble elevator components - Detailed results: 16 blocks around you - Detailed results: Choose whether to also clear soul sand and magma blocks - Detailed results: 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.

Spam prevention - Spam prevention with detailed lag source information - Spam prevention (orange for warnings, red for critical) - Spam prevention included (TPS, memory, player count) - Spam prevention for boat/bubble elevator issues - Spam prevention 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

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

Minecart Warnings

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

Minecart Cramming Warnings

- Why Important: Detects when 5+ minecarts are clustered within a 3x3x3 block area - Why Important: Uses spatial proximity instead of exact block matching - Why Important: Minecarts stuck together in storage systems, transport jams, or broken contraptions - Why Important: Warning at 5 minecarts clustered, Critical at 10+ clustered - Why Important: ``` /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

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

Bubble Boat Warnings

- Fix: Boats stuck on soul sand bubble columns (common in elevators) - Fix: Scans in a 1-chunk radius with smart overlap prevention - Fix: Finds boats on bubble columns, soul sand, magma blocks, and nearby water - Fix: 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

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

Mob Warnings

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

Redstone Warnings (Less Strict Now)

- Fix: Complex redstone contraptions - Fix: 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. Redstone is less strict now - Instant investigation! 2. Redstone is less strict now - Don't wait for lag to investigate 3. Redstone is less strict now - Nuclear option for huge boat problems 4. Redstone is less strict now - Get notified instantly when lag sources appear 5. Redstone is less strict now - Each chunk only warns once until fixed 6. Redstone is less strict now - Catches mob farm issues early 7. Redstone is less strict now - Finds stuck boat elevators automatically 8. Redstone is less strict now - Most lag happens when server is busiest 9. Redstone is less strict now - Fewer false positives from normal builds

Permissions for Staff

```yaml

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 ```