Entity Detective

Entity Detective

Entity Detective is a server-side Fabric mod built for one job: find entity-related lag fast. One command tells you which entity types are costing the most MSPT, where lazy mobs are silently accumulating, and where persistent creatures will never despawn — across every loaded dimension at once, no client mod needed. Works in singleplayer without enabling cheats.

---

What it does

• Hotspot scan — Run a 20-tick sample across all dimensions and get back the top-5 most expensive entity types ranked by MSPT, with no arguments needed — a fast first pass when you don't know where to look.
• Lazy mob detection — Pinpoint mobs stranded in chunks with no player within 128 blocks — the exact threshold Minecraft uses for despawn checks — where the server will never clean them up naturally
• Persistent mob detection — Find name-tagged mobs, item-holders, leashed animals, and vehicle riders that will never despawn even when they do tick.
• MSPT profiling — Measure how many milliseconds per tick any entity type is consuming, or profile every type at once sorted by cost, or just examine every entity inside a variable chunk range
• Chunk loader detection — Server load is often caused by chunk loaders. Find them fast. List all active portal chunk loaders (paired OW ↔ Nether) and ender pearl stasis chambers across every dimension.
• Block entity ticking audit — Use --ticking-only to find which block entities in a large farm actually ticked during an observation window, and --debug to see per-position tick counts instead of aggregate MSPT.
• Player profiling (nark) — Measure the MSPT cost of all entity types in the 21×21 chunk range surrounding any online player, to find what's expensive near their location.

---

Quality of life features

• Per-dimension summaries — See every entity type sorted by count, one block per dimension, across overworld, nether, and end simultaneously
• Clickable teleport links — Every chunk header and individual entity line is clickable in chat and pastes /tp <playername> x y z directly to the chunk centre or exact entity location
• Live mob cap — Check current vs. maximum entities per category with colour-coded saturation so you can spot mob cap pressure at a glance
• Command alias — Available as both /entitydetective and /ed

---

Command structure

/entitydetective
├── mob <category>
│   │   category: monster | creature | ambient | axolotls | water_creature | water_ambient
│   │   (bare)              — Type-count summary per dimension
│   │   --lazy-only         — Type-count table, non-persistent mobs in lazy chunks
│   │   --persistent [subtype]  — Type-count table, persistent mobs only
│   │       subtype: all | name-tagged | holding-item | structure-spawn | in-vehicle | leashed | custom
│   │   --world <dim>       — Scope to overworld | nether | end
│   │   --range <chunks>    — Scope to (2N+1)×(2N+1) chunk square (0 = single chunk)
│   │   --detail            — Expand to chunk-grouped entity list with clickable /tp links
│   └── cap                 — Live mob cap (current vs max, colour-coded)
│
├── entity
│   │   (bare)              — Summary of all entity types by count, per dimension
│   │   --lazy-only         — Type-count table, non-persistent entities in lazy chunks
│   │   --persistent        — Type-count table, persistent entities only
│   │   --world <dim>       — Scope to a specific dimension
│   │   --detail            — Expand to chunk-grouped entity list with clickable /tp links
│   ├── --range <chunks>    — Instant census of every entity type within range (0 = single chunk; no tick window)
│   ├── locate <type>       — Locate any entity type (tab-complete from live world, substring match)
│   │       --lazy-only, --world <dim>, --range <chunks>, --detail
│   │       --ticking-only  (block entities only) — filter to positions that actually ticked
│   ├── profile <type> [ticks]
│   │       Measure MSPT cost over a tick window (default 100 ticks / 5 s; max 6 000 ticks / 5 min)
│   │       --world <dim>, --range <chunks>
│   │       --debug         (block entities only) — per-position tick counts instead of aggregate MSPT
│   └── profile all [ticks]
│           Profile every entity type simultaneously, sorted by MSPT cost descending
│           (bare): all dimensions | --world <dim>: one dimension | --range <chunks>: local
│
└── item
    │   (bare)              — Dropped item summary per dimension, colour-coded by severity
    │   --lazy-only         — Type-count table, lazy chunks only
    │   --world <dim>       — Scope to a specific dimension
    │   --range <chunks>    — Scope to chunk square around your position
    │   --detail            — Expand to chunk-grouped item list with clickable /tp links
    └── locate <item_id>
            Find chunks with a specific item type (tab-complete, substring match)
            --lazy-only, --world <dim>, --range <chunks>, --detail

chunks — Detect active chunk loaders across all dimensions ├── loaders — Portal loaders only (paired OW ↔ Nether lines) └── stasis — Ender pearl stasis chambers only Coordinates are clickable /tp when you're in the matching dimension

hotspot — Top-5 entity hotspot scan (20-tick sample, all dimensions)

nark — Profile all entity types in the 21×21 chunk range around an online player

`--detail` must always be the last flag. `--range` and `--world` are mutually exclusive. Use `/ed` as a shorthand alias for `/entitydetective`.

---

### Why lazy and persistent mobs matter

> **Lazy mobs** are non-persistent mobs in chunks with no player within 128 blocks — the exact threshold Minecraft's despawn logic uses. Because those chunks never tick entities, the normal despawn check never runs. Mobs accumulate there indefinitely. Use `--lazy-only` to get a type-count table of what's building up, then add `--detail` for chunk-grouped clickable `/tp` links to teleport directly to the problem.

> **Persistent mobs** are flagged by the game engine to never despawn, even in fully-ticking chunks. This includes name-tagged mobs, any mob that has picked up a dropped item off the ground, leashed animals, and mobs riding vehicles. Because they never despawn, they accumulate over time and increase the server's tick cost. Use `--persistent` to see where they are building up, and `--persistent <subtype>` to narrow to a specific cause.

---

### Sample output

**`/entitydetective mob monster --lazy-only`** (type-count table)

-- lazy monster [overworld]: 45 entities -- minecraft:zombie 28 minecraft:skeleton 12 minecraft:creeper 5 Total: 45 entities across 3 types

**`/entitydetective mob monster --lazy-only --detail`** (chunk-grouped, clickable)

-- monster [overworld] (lazy, --detail): 45 entities in 2 chunks -- Chunk (12, -4) × 31 → /tp @s 192 ~ -64 [196, 63, -61] — minecraft:zombie [191, 64, -68] — minecraft:skeleton "Bob" (name tagged) ...

**`/entitydetective entity profile all --range 10`**

-- Base Profile: 10-chunk range (100 ticks) -- 3.636mspt TOTAL ×102 1.779mspt avg: 0.040ms piglin ×44 1.188mspt avg: 0.043ms hoglin ×28 0.402mspt avg: 0.040ms strider ×10 3.636mspt TOTAL ×102

**`/entitydetective item`** (severity-coloured)

-- Item Types [overworld]: 2 847 items -- 2 130 items (142 entities) minecraft:cobblestone ← red 480 items ( 48 entities) minecraft:gravel ← yellow 12 items ( 4 entities) minecraft:diamond ← green

---

### No client mod required · Works cross-dimension · Singleplayer compatible · Respects LuckPerms

*Singleplayer world owner has full access without enabling cheats. On servers, requires op level 2 or the `entitydetective.command` LuckPerms node.*  
Releases · Source · License: MIT