实体侦探
Entity Detective 是一款专为服务器端 Fabric 设计的模组,其唯一使命就是快速定位由实体引发的延迟问题。一条指令即可告诉你哪些类型的实体正在消耗最多的 MSPT(每刻毫秒数)、哪些惰性生物正在无声地堆积,以及哪些持久性生物永远不会消失——同时扫描所有已加载维度,无需客户端模组支持。在单人游戏中也可使用,且无需开启作弊模式。
功能介绍
-
热点扫描 — 在所有维度运行一次 20 tick 的采样,无需任何参数即可返回按 MSPT(每刻毫秒数)排名前五的最昂贵实体类型——当你不知道从何入手时,这是一种快速的初步排查手段。
-
惰性生物检测 — 精准定位那些被困在区块中、且周围 128 格内无玩家存在的生物——这正是 Minecraft 用于判断生物消失检查的确切阈值——服务器永远不会自然清理这些生物。
-
持久性生物检测 — 查找那些即使经过 tick 也绝不会消失的生物,包括被命名牌命名的生物、手持物品的生物、拴绳拴住的动物以及载具上的骑手。
-
MSPT 分析 — 测量每种实体类型每刻消耗的毫秒数,或一次性对所有类型进行分析并按消耗排序,或者仅检查指定区块范围内的所有实体。
-
区块加载器检测 — 服务器负载通常由区块加载器引起。快速找到它们。列出所有维度中处于活动状态的传送门区块加载器(主世界 ↔ 下界配对)和末影珍珠停滞室。
-
方块实体 ticking 审计 — 使用 --ticking-only 找出大型农场中哪些方块实体在观察窗口期间实际进行了 ticking;使用 --debug 查看每个位置的具体 tick 次数,而非汇总的 MSPT。
-
玩家画像(nark) — 测量任意在线玩家周围 21×21 区块范围内所有实体类型的 MSPT 开销,以找出其位置附近哪些实体性能消耗较高。
生活质量功能
-
各维度摘要 — 按数量排序查看所有实体类型,每个维度一个区块,同时涵盖主世界、下界和末地
-
可点击的传送链接 — 聊天界面中的每个区块标题和单个实体行均可点击,并直接粘贴 /tp <玩家名称> x y z 到区块中心或精确的实体位置
-
实时生物上限 — 检查当前与各类实体的最大数量,并通过颜色编码的饱和度显示,让您一目了然地察觉生物上限压力
-
命令别名 — 支持使用 /entitydetective 和 /ed 两个命令
命令结构
/entitydetective
├── mob <category>
│ │ category: monster | creature | ambient | axolotls | water_creature | water_ambient
│ │ (bare) — 各维度按类型计数的汇总
│ │ --lazy-only — 类型计数表,仅统计惰性区块中的非持久化生物
│ │ --persistent [subtype] — 类型计数表,仅统计持久化生物
│ │ subtype: all | name-tagged | holding-item | structure-spawn | in-vehicle | leashed | custom
│ │ --world <dim> — 范围限定为:主世界 | 下界 | 末地
│ │ --range <chunks> — 范围限定为以你为中心的 (2N+1)×(2N+1) 区块正方形(0 = 单个区块)
│ │ --detail — 展开为按区块分组的实体列表,并附带可点击的 /tp 链接
│ └── cap — 实时生物上限(当前值 vs 最大值,带颜色编码)
│
├── entity
│ │ (bare) — 按类型和数量汇总的所有实体信息,按维度分组
│ │ --lazy-only — 类型计数表,仅统计惰性区块中的非持久化实体
│ │ --persistent — 类型计数表,仅统计持久化实体
│ │ --world <dim> — 范围限定为特定维度
│ │ --detail — 展开为按区块分组的实体列表,并附带可点击的 /tp 链接
│ ├── --range <chunks> — 范围内每种实体类型的即时普查(0 = 单个区块;无刻数窗口)
│ ├── locate <type> — 定位任意类型的实体(从实时世界进行标签补全,支持子字符串匹配)
│ │ --lazy-only, --world <dim>, --range <chunks>, --detail
│ │ --ticking-only (仅限方块实体) — 筛选实际进行过刻更新的坐标位置
│ ├── profile <type> [ticks]
│ │ 在指定刻数窗口内测量 MSPT(每刻毫秒数)开销(默认 100 刻 / 5 秒;最大 6 000 刻 / 5 分钟)
│ │ --world <dim>, --range <chunks>
│ │ --debug (仅限方块实体) — 显示每个位置的刻数统计,而非聚合后的 MSPT
│ └── profile all [ticks]
│ 同时分析所有类型的实体,并按 MSPT 开销降序排列
│ (bare): 所有维度 | --world <dim>: 单个维度 | --range <chunks>: 本地范围
│
└── item
│ (bare) — 按维度分组的掉落物品汇总,根据严重程度进行颜色编码
│ --lazy-only — 类型计数表,仅统计惰性区块
│ --world <dim> — 范围限定为特定维度
│ --range <chunks> — 范围限定为你当前位置周围的区块正方形
│ --detail — 展开为按区块分组的物品列表,并附带可点击的 /tp 链接
└── locate <item_id>
查找包含特定物品类型的区块(支持标签补全、子字符串匹配)
--lazy-only, --world <dim>, --range <chunks>, --detail
chunks — 检测所有维度中的活跃区块加载器
├── loaders — 仅限传送门加载器(配对主世界 ↔ 下界连线)
└── stasis — 仅限末影珍珠停滞舱
当你在匹配的维度中时,坐标可点击进行 /tp 传送
hotspot — 前 5 名实体热点扫描(20 刻采样,所有维度)
nark <player> — 分析在线玩家周围 21×21 区块范围内的所有实体类型
`--detail` 必须始终作为最后一个参数。`--range` 和 `--world` 互斥。使用 `/ed` 作为 `/entitydetective` 的简写别名。
---
### 为何惰性生物与持久化生物至关重要
> **惰性实体(Lazy mobs)** 是指那些位于玩家 128 格范围内之外的区块中的非持久性实体——这正是 Minecraft 实体的消失逻辑所使用的确切阈值。由于这些区块从不更新实体,正常的消失检查也就永远不会运行。实体会在此无限期地堆积。使用 `--lazy-only` 可以获取正在堆积的实体类型统计表格,然后添加 `--detail` 以按区块分组并生成可点击的 `/tp` 链接,直接传送至问题所在处。
> **持久性实体(Persistent mobs)** 会被游戏引擎标记为永不消失,即使在完全更新的区块中也是如此。这包括使用了命名牌的实体、任何拾取了地上掉落物的实体、拴绳拴住的动物以及骑在载具上的实体。由于它们永远不会消失,因此会随着时间推移不断积累,从而增加服务器的 Tick 消耗。使用 `--persistent` 查看它们正在何处堆积,并使用 `--persistent <subtype>` 缩小范围以定位特定原因。
---
### 示例输出
**`/entitydetective mob monster --lazy-only`**(类型统计表)
-- 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`**(按区块分组,可点击)
-- 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`**(按严重程度着色)
-- 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
---
### 无需客户端模组 · 跨维度可用 · 兼容单人模式 · 尊重 LuckPerms 权限
*单人世界的所有者拥有完全访问权限,无需开启作弊模式。在服务器上,需要 OP 等级 2 或具备 `entitydetective.command` 的 LuckPerms 节点。*
[Releases](https://github.com/netcrafts/Entity-Detective/releases) · [Source](https://github.com/netcrafts/Entity-Detective) · [License: MIT](https://github.com/netcrafts/Entity-Detective/blob/main/LICENSE)
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 <player> — 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
评论 0
登录后参与评分
还没有评论,来抢沙发吧