LagMap
一个服务端 Minecraft 模组,用于回答分析器(profilers)通常回避的问题:
当前是哪个维度、哪个区块和哪个基地正在占用服务器资源?
像 spark 这样的工具告诉你哪些代码运行缓慢。LagMap 则告诉你工作在世界中的位置。它按定时器采样所有已加载的区块,根据估算的负载分数对它们进行排名,并生成一份快照,你可以在聊天栏中查看、以 JSON 格式读取,或查看自包含的 HTML 报告。
- Minecraft: 1.20.1
- 加载器: Forge 47.x
- 侧: 仅限服务端(独立服务器或单人游戏中的集成服务器)
- 需要客户端模组: 否
功能
- 刻计时。 测量每个刻的 MSPT(毫秒每刻),并保持滚动计算的 10 秒 / 30 秒 / 60 秒窗口数据
(平均值、最小值、最大值)以及派生的 TPS 数值。
- 按维度和按区块采样。 每隔 N 秒(默认 5 秒),它会遍历所有维度中已加载的区块并记录:
- 实体数量,以及其中有多少实体位于正在被 tick 的区块中
- 方块实体数量,以及其中有多少方块实体附带了 ticker 且 位于正在被 tick 的区块中
- 该区块是否被强制加载(这些区块会绕过分数阈值,尽管空白的强制加载区块仍会被挤出前 N 名列表;每维度的
forceLoadedChunkCount 始终报告总数)
- 区块内最多的实体/方块实体类型
- 在可配置区块半径内的玩家
- 每个区块和每个维度的启发式负载分数(详见下方的警告)。
- 导出。 稳定的 JSON 快照及静态 HTML 报告,由服务器线程外原子写入。
尚未实现的功能
- 它不测量真实的每区块或每方块实体的刻耗时。请参阅
ROADMAP.md。
- 无客户端 GUI,无实时 Web 仪表板,无游戏内地图覆盖层。
- 无模组特定集成(Compact Machines、FTB Chunks、领地、spark 导入)。
- 无历史时间序列——磁盘上仅保留最新快照。
- 多版本支持不在本次发布范围内;见下文“移植”。
分数仅为估算,而非实测
estimatedScore 是对区块内容物的加权计数。充满正在被 tick 的方块实体的区块得分较高,因为此类区块通常会消耗刻时间——但单个极端的实体可能比一千个漏斗更耗性能,而 LagMap 无法察觉这一点。使用分数来决定下一步去哪里查看,然后使用 spark 进行确认。每次导出都会重复此免责声明,以防将报告粘贴到问题追踪器时丢失该提示。
命令
所有命令默认需要权限等级 2(可配置,参见 permissionLevel)。
| 命令 |
效果 |
/lagmap status |
MSPT 窗口、TPS、采样器状态以及上次采样时的各维度总计。 |
/lagmap top [count] |
上次采样中服务器范围内最热的区块。count 默认为 10,最大为 100。 |
/lagmap dump |
立即采样并写入 latest.json + latest.html,无视配置。 |
/lagmap start |
开始周期性采样。 |
/lagmap stop |
停止周期性采样。刻计时继续运行。 |
/lagmap tp <dimension> <chunkX> <chunkZ> |
传送至该区块中心。仅限玩家使用。 |
典型调查流程:
/lagmap status # MSPT 真的很高吗?哪个维度负载最重?
/lagmap dump # 立即获取一次新鲜样本
/lagmap top 20 # 哪些区块主导了该维度?
/lagmap tp minecraft:overworld 145 -302
/lagmap tp 从地表高度图派生 Y 坐标,这在类主世界维度中有意义,而在下界或自定义维度中则具有误导性——它会向你发出警告。传送会加载目标区块,这是 LagMap 唯一会导致区块加载的地方。
输出文件
相对于服务器目录写入 config/lagmap/:
| 文件 |
内容 |
latest.json |
机器可读的快照。键顺序稳定,schemaVersion: 1。 |
latest.html |
嵌入快照的自包含报告。双击即可打开。 |
两者均先写入临时文件,再移动到位,因此轮询 JSON 的查看器永远不会读到未写完的文档。
本仓库中的 web/viewer.html 是同一个没有内置数据的查看器:打开它并将任何 latest.json 拖拽进去即可。适用于阅读他人发来的快照。
读取 JSON
{
"schemaVersion": 1,
"timestamp": "2026-08-20T12:00:00Z",
"chunkEnumeration": "chunkmap (complete: every fully-loaded chunk)",
"scoreFormula": "estimated (idleEntities*0.10) + ...",
"mspt": {
"last": 48.20,
"tps10s": 20.00,
"last10s": { "samples": 200, "average": 45.10, "min": 38.00, "max": 91.40 },
"last30s": { ... },
"last60s": { ... }
},
"totals": { "dimensions": 3, "loadedChunks": 1841, "entities": 2204, "blockEntities": 9033 },
"dimensions": [ { "dimensionId": "...", "totalEstimatedScore": 0, "hottestChunks": [ ... ] } ],
"topChunks": [ { "dimensionId": "...", "chunkX": 0, "chunkZ": 0, "estimatedScore": 0, ... } ]
}
值得了解的字段:
chunkEnumeration - 已加载区块的发现方式。chunkmap 表示列表完整。fallback 表示由特殊模组票据(ticket)保持打开状态的区块可能缺失;请将报告视为下限值。
entityCount 与 tickingEntityCount - 超出刻更新范围的区块仍保留其内容,但不消耗刻时间。两者之间存在较大差距意味着“大量实体,但当前不耗时”。
scannedChunkCount 与 loadedChunkCount - 这两个数值存在差异属于正常现象,并非错误。loadedChunkCount 是 Minecraft 自身的区块持有者计数,包含那些仅部分生成或位于加载区域边缘的区块。scannedChunkCount 统计的是 LagMap 实际检查过的完全加载的区块——只有这些区块才包含实体和方块实体。仅当 scannedChunkCount 等于 maxChunksPerDimension 时,差距才表示截断。
sampleDurationMicros - LagMap 自身所花费的时间。请留意此项;该工具绝不能成为卡顿的来源。
配置
config/lagmap.toml,首次启动时生成。要点如下:
| 键 |
默认值 |
备注 |
sampling.enabledOnStart |
true |
自动开始采样。 |
sampling.sampleIntervalSeconds |
5 |
数值越低响应越快,但开销越大。 |
sampling.maxChunksPerDimension |
20000 |
每个维度每次采样的安全上限。 |
sampling.collectTypeBreakdown |
true |
在非常大的服务器上关闭以降低采样开销。 |
sampling.nearbyPlayerRadiusChunks |
8 |
用于将玩家归因于热点区块的半径。 |
reporting.topChunksGlobal |
25 |
每个快照在全服务器范围内保留的热点区块数量。 |
reporting.writeJsonEachSample |
true |
设置为 false 以仅在 /lagmap dump 时写入。 |
reporting.permissionLevel |
2 |
使用 /lagmap 命令所需的原版权限等级。 |
scoring.*Weight |
见文件 |
启发式评分的权重。 |
评分权重默认为 idleEntity 0.10、idleBlockEntity 0.05、tickingEntity 1.00、tickingBlockEntity 1.50。空闲内容的权重不为零,因为它们仍然占用内存、区块保存空间和网络带宽——只是不占用刻时间。
开销
LagMap 是一款卡顿检测工具,因此其设计原则是不成为卡顿源:
- 采样是周期性的,而非每刻执行。只有 MSPT 测量会在每刻运行,且仅涉及两次
System.nanoTime() 调用写入预分配的环形缓冲区。
- 采样仅读取已加载的状态。它从不强制加载区块,也从不触碰磁盘。(
/lagmap tp 是唯一的例外,但也仅限于目标区块。)
- “该方块实体是否参与刻更新?”这一问题针对每个方块状态仅回答一次,并在会话期间进行记忆化缓存。
- 所有文件写入均在低优先级守护线程上完成。
- 每个快照中的
sampleDurationMicros 会精确告知你单次采样的开销。
构建
需要 JDK 来运行 Gradle。Minecraft 1.20.1 本身需要 Java 17,如果你本地没有安装,Gradle 会通过 foojay 工具链解析器自动下载。
./gradlew build
模组 jar 包位于 build/libs/lagmap-1.20.1-0.1.0.jar。
Gradle 8.14 支持从 Java 17 到 24 的版本。如果你的默认 java 版本较新,请指定 Gradle 使用受支持的 JDK:
JAVA_HOME=/path/to/jdk-21 ./gradlew build
使用 ./gradlew runServer 运行测试服务器(首次启动时在 run/eula.txt 中接受 EULA)。
移植至新版本 / NeoForge
特定版本的代码被刻意隔离:
| 包 |
依赖 Minecraft? |
备注 |
com.lagmap.model |
否 |
纯记录类。 |
com.lagmap.core |
否 |
刻窗口、采样计划。 |
com.lagmap.score |
否 |
仅计分逻辑。 |
com.lagmap.export |
否 |
JSON + HTML 导出。 |
com.lagmap.platform |
否 |
SnapshotCollector 接口。 |
com.lagmap.platform.forge1201 |
是 |
1.20.1 的实现。 |
com.lagmap.command, LagMapMod, LagMapConfig |
是 |
Brigadier 命令、Forge 事件、Forge 配置。 |
移植工作意味着编写一个新的 SnapshotCollector,重新连接入口点,并适配命令/配置类。其余部分无需更改即可迁移。
模组中唯一使用反射的代码位于
platform/forge1201/LoadedChunkAccess.java:ChunkMap#getChunks() 是受保护的,且没有公开等价方法。它在类初始化时解析一次(同时尝试 Mojang 映射名和 SRG 名),如果失败则回退到公共 API 扫描。采样路径本身不进行任何名称查找。
项目文档
| 文件 |
用途 |
README.md |
LagMap 是什么以及如何使用(即本文件)。 |
ROADMAP.md |
按计划价值与工作量排序的规划工作。长期愿望清单。 |
MEMORY.md |
当前开发状态:已验证的内容、未测试的内容、下一步要做的事。每次会话后更新。 |
DECISIONS.md |
代码如此设计的原因。只增不改。 |
CLAUDE.md |
面向 AI 编码代理的仓库特定指导。 |
许可证
MIT。
LagMap
A server-side Minecraft mod that answers the question profilers usually dodge:
which dimension, chunk and base is loading the server right now?
Tools like spark tell you what code is slow. LagMap tells you
where in the world the work is. It samples every loaded chunk on a timer, ranks them by an
estimated load score, and writes a snapshot you can read in chat, in JSON, or in a
self-contained HTML report.
- Minecraft: 1.20.1
- Loader: Forge 47.x
- Side: server only (dedicated server or the integrated server in single player)
- Client mod required: no
What it does
- Tick timing. Measures MSPT every tick and keeps rolling 10s / 30s / 60s windows
(average, min, max) plus a derived TPS figure.
- Per-dimension and per-chunk sampling. Every N seconds (default 5) it walks the
loaded chunks of every dimension and records:
- entity count, and how many of those entities are in an entity-ticking chunk
- block entity count, and how many of those have a ticker attached and sit in a
ticking chunk
- whether the chunk is force-loaded (these bypass the score threshold, though an empty
one is still out-ranked out of the top-N list; the per-dimension
forceLoadedChunkCount always reports the total)
- the top entity / block-entity types in the chunk
- players within a configurable chunk radius
- A heuristic load score per chunk and per dimension (see the warning below).
- Export. A stable JSON snapshot plus a static HTML report, written atomically off the
server thread.
What it does not do yet
- It does not measure real per-chunk or per-block-entity tick cost. See
ROADMAP.md.
- No client GUI, no live web dashboard, no in-game map overlay.
- No mod-specific integrations (Compact Machines, FTB Chunks, claims, spark import).
- No historical time series - only the newest snapshot is kept on disk.
- Multi-version support is out of scope for this release; see Porting below.
The score is an estimate, not a measurement
estimatedScore is a weighted count of what a chunk contains. A chunk full of ticking
block entities scores high because such chunks usually cost tick time - but a single
pathological entity can out-cost a thousand hoppers and LagMap will not see it. Use the
score to decide where to look next, then confirm with spark. Every export repeats this
disclaimer so it cannot be lost when a report is pasted into a bug tracker.
Commands
All commands require permission level 2 by default (configurable, see permissionLevel).
| Command |
Effect |
/lagmap status |
MSPT windows, TPS, sampler state, and per-dimension totals from the last sample. |
/lagmap top [count] |
The hottest chunks server-wide from the last sample. count defaults to 10, max 100. |
/lagmap dump |
Samples immediately and writes latest.json + latest.html, regardless of config. |
/lagmap start |
Starts periodic sampling. |
/lagmap stop |
Stops periodic sampling. Tick timing keeps running. |
/lagmap tp <dimension> <chunkX> <chunkZ> |
Teleports you to the centre of that chunk. Player-only. |
Typical investigation:
/lagmap status # is MSPT actually high, and which dimension is heaviest?
/lagmap dump # take a fresh sample right now
/lagmap top 20 # which chunks dominate that dimension?
/lagmap tp minecraft:overworld 145 -302
/lagmap tp derives its Y coordinate from the surface heightmap, which is meaningful in
overworld-like dimensions and misleading in the Nether or in custom dimensions - it will
warn you. Teleporting loads the destination chunk, which is the one place LagMap causes
chunk loading.
Output files
Written to config/lagmap/ relative to the server directory:
| File |
Contents |
latest.json |
The machine-readable snapshot. Stable key order, schemaVersion: 1. |
latest.html |
Self-contained report with the snapshot embedded. Double-click to open. |
Both are written to a temporary file and moved into place, so a viewer polling the JSON
never reads a half-written document.
web/viewer.html in this repository is the same viewer with no data baked in: open it and
drop any latest.json onto it. Useful for reading a snapshot someone sent you.
Reading the JSON
{
"schemaVersion": 1,
"timestamp": "2026-08-20T12:00:00Z",
"chunkEnumeration": "chunkmap (complete: every fully-loaded chunk)",
"scoreFormula": "estimated (idleEntities*0.10) + ...",
"mspt": {
"last": 48.20,
"tps10s": 20.00,
"last10s": { "samples": 200, "average": 45.10, "min": 38.00, "max": 91.40 },
"last30s": { ... },
"last60s": { ... }
},
"totals": { "dimensions": 3, "loadedChunks": 1841, "entities": 2204, "blockEntities": 9033 },
"dimensions": [ { "dimensionId": "...", "totalEstimatedScore": 0, "hottestChunks": [ ... ] } ],
"topChunks": [ { "dimensionId": "...", "chunkX": 0, "chunkZ": 0, "estimatedScore": 0, ... } ]
}
Fields worth knowing:
chunkEnumeration - how loaded chunks were discovered. chunkmap means the list is
complete. fallback means chunks held open by an exotic mod ticket may be missing; treat
the report as a lower bound.
entityCount vs tickingEntityCount - a chunk outside the ticking range still holds
its contents but costs no tick time. A big gap between the two means "lots of stuff, not
currently expensive".
scannedChunkCount vs loadedChunkCount - these differ normally, and the gap is not a
bug. loadedChunkCount is Minecraft's own count of chunk holders, which includes chunks
that are only partially generated or sitting on the border of the loaded area.
scannedChunkCount counts the fully loaded chunks LagMap actually inspected - those are
the only ones that hold entities and block entities. A gap only indicates truncation when
scannedChunkCount equals maxChunksPerDimension.
sampleDurationMicros - how long LagMap itself took. Watch this; the tool must not
become the lag.
Configuration
config/lagmap.toml, generated on first start. Highlights:
| Key |
Default |
Notes |
sampling.enabledOnStart |
true |
Start sampling automatically. |
sampling.sampleIntervalSeconds |
5 |
Lower is more responsive and more expensive. |
sampling.maxChunksPerDimension |
20000 |
Safety cap per dimension per sample. |
sampling.collectTypeBreakdown |
true |
Turn off on very large servers to cut sample cost. |
sampling.nearbyPlayerRadiusChunks |
8 |
Radius used to attribute players to a hot chunk. |
reporting.topChunksGlobal |
25 |
Hot chunks kept server-wide per snapshot. |
reporting.writeJsonEachSample |
true |
Set false to only write on /lagmap dump. |
reporting.permissionLevel |
2 |
Vanilla permission level required for /lagmap. |
scoring.*Weight |
see file |
Weights for the heuristic score. |
Scoring weights default to idleEntity 0.10, idleBlockEntity 0.05, tickingEntity 1.00,
tickingBlockEntity 1.50. Idle contents are not weighted at zero because they still cost
memory, chunk saving and network bandwidth - just not tick time.
Overhead
LagMap is a lag tool, so it is built not to be the lag:
- Sampling is periodic, not per-tick. Only MSPT measurement runs every tick, and that is two
System.nanoTime() calls into a preallocated ring buffer.
- Sampling reads only already-loaded state. It never forces a chunk to load and never touches
the disk. (
/lagmap tp is the sole exception, and only for the destination chunk.)
- "Does this block entity tick?" is answered once per block state and memoised for the
session.
- All file writing happens on a low-priority daemon thread.
sampleDurationMicros in every snapshot tells you exactly what a sample cost.
Building
Requires a JDK to run Gradle. Minecraft 1.20.1 itself needs Java 17, which Gradle will
download automatically via the foojay toolchain resolver if you do not have it.
./gradlew build
The mod jar lands in build/libs/lagmap-1.20.1-0.1.0.jar.
Gradle 8.14 supports Java 17 through 24. If your default java is newer, point Gradle at a
supported JDK:
JAVA_HOME=/path/to/jdk-21 ./gradlew build
Run a test server with ./gradlew runServer (accept the EULA in run/eula.txt on first
launch).
Porting to newer versions / NeoForge
Version-specific code is deliberately confined:
| Package |
Depends on Minecraft? |
Notes |
com.lagmap.model |
no |
Plain records. |
com.lagmap.core |
no |
Tick windows, sampling schedule. |
com.lagmap.score |
no |
Scoring only. |
com.lagmap.export |
no |
JSON + HTML. |
com.lagmap.platform |
no |
The SnapshotCollector seam. |
com.lagmap.platform.forge1201 |
yes |
The 1.20.1 implementation. |
com.lagmap.command, LagMapMod, LagMapConfig |
yes |
Brigadier, Forge events, Forge config. |
A port means writing one new SnapshotCollector, re-wiring the entry point, and adapting the
command/config classes. Everything else moves unchanged.
The one piece of reflection in the mod lives in
platform/forge1201/LoadedChunkAccess.java: ChunkMap#getChunks() is protected and has no
public equivalent. It is resolved once at class-init (Mojang-mapped and SRG names are both
tried) and falls back to a public-API scan if that fails. The sampling path itself performs
no name lookups.
Project documents
| File |
Purpose |
README.md |
What LagMap is and how to use it (this file). |
ROADMAP.md |
Planned work, ordered by value-to-effort. Long-term wishlist. |
MEMORY.md |
Current development state: what is proven, what is untested, what to do next. Updated every session. |
DECISIONS.md |
Why the code is the way it is. Append-only. |
CLAUDE.md |
Repo-specific guidance for AI coding agents. |
Licence
MIT.
评论 0
登录后参与评分
还没有评论,来抢沙发吧