LagMap

模组

· 作者 rofumer

一个服务端 Minecraft 模组,解答了性能分析器通常回避的问题:当前哪个维度、区块和基地正在占用服务器资源?

0 本站下载 0 关注 更新于 1 个月前

最新 0.1.0 · 26.1.2 · NeoForge

一键开服(送7天)

LagMap

一个服务端 Minecraft 模组,用于回答分析器(profilers)通常回避的问题: 当前是哪个维度、哪个区块和哪个基地正在占用服务器资源?

像 spark 这样的工具告诉你哪些代码运行缓慢。LagMap 则告诉你工作在世界中的位置。它按定时器采样所有已加载的区块,根据估算的负载分数对它们进行排名,并生成一份快照,你可以在聊天栏中查看、以 JSON 格式读取,或查看自包含的 HTML 报告。

  • Minecraft: 1.20.1
  • 加载器: Forge 47.x
  • 侧: 仅限服务端(独立服务器或单人游戏中的集成服务器)
  • 需要客户端模组: 否

功能

  1. 刻计时。 测量每个刻的 MSPT(毫秒每刻),并保持滚动计算的 10 秒 / 30 秒 / 60 秒窗口数据 (平均值、最小值、最大值)以及派生的 TPS 数值。
  2. 按维度和按区块采样。 每隔 N 秒(默认 5 秒),它会遍历所有维度中已加载的区块并记录:
    • 实体数量,以及其中有多少实体位于正在被 tick 的区块中
    • 方块实体数量,以及其中有多少方块实体附带了 ticker 且 位于正在被 tick 的区块中
    • 该区块是否被强制加载(这些区块会绕过分数阈值,尽管空白的强制加载区块仍会被挤出前 N 名列表;每维度的 forceLoadedChunkCount 始终报告总数)
    • 区块内最多的实体/方块实体类型
    • 在可配置区块半径内的玩家
  3. 每个区块和每个维度的启发式负载分数(详见下方的警告)。
  4. 导出。 稳定的 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。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源