插件版处于测试阶段，欢迎前来测试：MsptMap-Plugin
| 🌡️ 区块级热力图 | 按区块所占用的刻耗时着色，由绿经黄至红。弱加载区块着淡灰色；可在设置中让其中有耗时的区块照常染色。热力图亦可同步显示于 Xaero 小地图。 |
| 🧩 七类耗时分别计量 | 随机刻、计划刻、方块更新、方块事件、方块实体、实体与刷怪各自独立计量；悬停详情指出耗时所属的类别。 |
| 🏷️ 加载来源反查 | 反查各区块的加载票来源：玩家加载、强制加载、传送门、末影珍珠、末影龙 等。持有加载票的区块以蓝框标出，悬停详情给出票名及其所在区块的 @x,z 坐标。 |
| 📊 扫描总览 | 单一面板汇总总卡顿、实体数、加载源与卡顿区块 TOP5，且按三个维度合计；地图本身一次仅显示一个维度。 |
| 🖱️ 点击定位 | 点击总览中的条目可将地图定位至对应区块；折叠行可展开完整的加载源列表。总览框与完整列表高于屏幕时右缘出现滚动条，滚轮翻动。 |
| 📡 常态化监控 | 默认关闭。开启后服务端持续监测 MSPT，持续超标即自动扫描，并把卡顿最重的五个区块以可点击的告警发给在线管理员。 |
| 依赖 | 必需性 | 说明 |
|---|---|---|
| Minecraft | 必需 | 可用版本见下表 |
| Fabric Loader | 必需 | ≥ 0.19.3 |
| Fabric API | 必需 | |
| Xaero 的世界地图 | 仅客户端 | 已在 Xaero 1.44.2 / 1.46.0 / 1.46.4 上验证（多数版本使用 1.46.0），其余版本不保证挂载成功 |
| Xaero 的小地图 | 可选 | 勾选「小地图显示热力图」后，热力色同步绘制于小地图。 |
| Mod Menu | 建议安装 | 提供设置界面的快捷入口 |
| Minecraft | 构建目录 | 运行期 Java | Fabric API 下限 |
|---|---|---|---|
| 1.20 – 1.20.2 | versions/1.20.1 |
17 | 0.83.0+1.20 |
| 1.20.3 – 1.20.4 | versions/1.20.4 |
17 | 0.91.1+1.20.3 |
| 1.21 – 1.21.1 | versions/1.21.1 |
21 | 0.100.1+1.21 |
| 1.21.2 – 1.21.4 | versions/1.21.4 |
21 | 0.106.1+1.21.2 |
| 1.21.6 – 1.21.8 | versions/1.21.8 |
21 | 0.127.0+1.21.6 |
| 1.21.10 | versions/1.21.10 |
21 | 0.138.4+1.21.10 |
| 1.21.11 | versions/1.21.11 |
21 | 0.141.2+1.21.11 |
| 26.1 – 26.1.2 | versions/26.1.2 |
25 | 0.144.0+26.1 |
| 26.2 | versions/26.2 |
25 | 0.155.0+26.2 |
| 26.3 | versions/26.3 |
25 | 0.160.5+26.3 |
Note
1.20.5、1.20.6、1.21.5、1.21.9 暂不支持。
从 Modrinth 或 Releases 页 下载最新构建，再将 jar 放入 mods/ 目录。
Important
采样在服务端进行，故两侧均需安装本模组。
Note
Paper 等服务端：可用 MsptMap-Plugin 代替服务端模组，客户端仍安装本模组。插件按服务端版本分为 1.21.6 – 1.21.10、1.21.11 与 26.x 三个包，放入 plugins/ 并在启动命令的 -jar 之前添加 -javaagent；平台兼容性与已知限制见插件仓库。Folia 不支持。
- 打开世界地图，点击左上角的扫描按钮以开始扫描
- 采样完成后，地图按区块的卡顿程度着色：绿 → 黄 → 红；弱加载区块为淡灰色
- 悬停任意区块可查看详情：坐标、加载等级、加载票、实体数、合计 mspt 与各类耗时明细
- 扫描总览显示在扫描按钮旁，给出合计、加载源与卡顿区块 TOP5。点击某一行可将地图定位至该区块；加载源数量多时可展开显示
- 点击 ✕ 按钮清空热力图
加载票指明该区块被保持加载的票据，其后的 @x,z 为票所在区块的坐标；以蓝框标出的区块即持有加载票。
（事实上，玩家周围每个区块均持票，显示简洁，只显示玩家所在区块的加载票）
全部票名
| 票名 | 保持加载的原因 |
|---|---|
玩家加载 |
玩家 |
玩家模拟 |
玩家 |
强制加载 |
被 /forceload 指令强制加载 |
传送门 |
实体经过传送门 |
末影珍珠 |
末影珍珠未落地时 |
世界出生点 |
该区块为世界出生点（1.21.10 及以前名为 start） |
出生点搜索 |
正在执行出生点搜索（1.21.11 起） |
末影龙 |
末影龙战斗占用 |
未知 |
原版的兜底票类型或其他模组的自创加载票 |
[!NOTE] 1.21.4 及以前的游戏没有可查询的票表，故不显示票名与
@x,z，仅显示加载等级。
Tip
单人游戏：地图打开时世界暂停；点击扫描按钮后须关闭地图再等待。
| 指令 | 端 | 作用 |
|---|---|---|
/msptmap scan [秒数] |
服务端 | 发起扫描，结果只写入服务端日志；省略秒数则使用默认的 2 秒，范围 1 ~ 60。 |
/msptmap access <ops|all> |
两端 | 谁能发起扫描：仅 OP（默认）或所有玩家。 |
/msptmap monitor |
两端 | 打印监控状态与各项设置。 |
/msptmap monitor <on|off> |
两端 | 监控总开关，默认关闭；关闭时一并丢弃当前窗口与冷却。 |
/msptmap monitor threshold <mspt> |
两端 | 触发阈值，1.0 ~ 1000.0（默认 40.0）。 |
/msptmap monitor cooldown <分钟> |
两端 | 触发后多长时间内不再扫描，1 ~ 1440（默认 5）。 |
/msptmap monitor audience <op|all> |
两端 | 告警发给谁：仅在线 OP（默认 op），或所有在线玩家。 |
扫描默认限原版权限等级 2（OP）；/msptmap access <ops\|all> 可放开给所有玩家，或恢复默认。access 与 monitor 两条子命令本身始终限 OP。
默认关闭。开启后，服务端检测到 mspt 超过阈值，就把卡顿最重的五个区块作为聊天告警发给在线管理员；点击其中一行可将世界地图打开并定位到该区块。
监控是管理员命令，用 /msptmap monitor <on\|off> 开关，其设置保存在 config/msptmap-server.properties（各项见指令）。
打开 Mod Menu → 设置，或点击地图上的设置按钮。设置保存在 config/msptmap-client.properties，也可直接手改文件。
全部设置项
| 分组 | 设置项 | 作用 |
|---|---|---|
| 扫描 | 秒数 | 采样窗口长度，单位为秒（按游戏刻换算） |
| 颜色 | 采用相对模式 | 颜色按本次扫描中的相对大小判定：最重的区块显示为红色，其余区块与之比较——整体负载较低时，相对卡顿的区块仍可分辨。取消勾选则一律按下方固定的红色阈值判定。 |
| 颜色 | 红色阈值 | 区块耗时达到此值（ms/tick）即显示为最高等级红色；低于此值的区块，颜色由绿经黄连续过渡到红。勾选相对模式时此项不参与判定，且不可调整。 |
| 颜色 | 不透明度 | 热力色填充的不透明度，0.05 ~ 1.00；数值越小，透出的底图越清晰。 |
| 颜色 | 显示弱加载区块 | 以淡灰显示加载等级 32 及以上的区块；这些区块不参与热力着色。 |
| 颜色 | 弱加载区块计时时染色 | 弱加载区块在采样窗口内产生过耗时时，仍按热力色着色。默认关闭；仅勾选「显示弱加载区块」时可用。 |
| 颜色 | 小地图显示热力图 | 在 Xaero 小地图上同步显示热力色。默认关闭。 |
| 悬停详情 | 坐标 / 等级 / 实体数 | 决定哪些行出现在悬停详情中。 |
| 悬停详情 | 加载票 / 计算票 | 在加载等级 / 计算等级行后附带票的来源。 |
| 悬停详情 | 显示为缩写 | 类别名显示为二字母缩写：RT ST BU EV BE EN SP。 |
| 悬停详情 | 显示单位（mspt） | 每类明细行后附 mspt；合计行的单位固定显示，不受此项影响。 |
| 悬停详情 | 合计 | 显示合计 mspt 行。 |
| 悬停详情 | 总览着色 | 扫描总览的数值按热力梯度着色。默认开启。 |
| 悬停详情 | 类别明细 | 七个勾选框（随机刻、计划刻、方块更新、方块事件、方块实体、实体、刷怪）分别控制各类明细行是否显示。 |
恢复默认 可将以上各项恢复为默认值。
flowchart LR
A["客户端<br/>地图按钮"] -->|扫描请求| B["服务端<br/>MsptSampler"]
B --> C["逐区块计时<br/>七类工作"]
C -->|扫描结果| D["客户端<br/>热力图 + 总览"]
服务端采样七类工作的耗时，并将结果发送给发起扫描的客户端，由客户端按区块着色。
| 类别 | 计量位置 |
|---|---|
| 随机刻 | ServerLevel.tickChunk |
| 计划刻 | ServerLevel.tickBlock / tickFluid |
| 方块更新 | NC更新ServerLevel ，PP更新Level.neighborShapeChanged |
| 方块事件 | ServerLevel.doBlockEvent |
| 方块实体 | LevelChunk$BoundTickingBlockEntity.tick |
| 实体 | ServerLevel.tickNonPassenger，以及每 tick 的同步（ChunkMap$TrackedEntity.updatePlayers / ServerEntity.sendChanges） |
| 刷怪 | NaturalSpawner.spawnForChunk |
Important
方块更新会被计量，但不计入合计：其耗时已包含在触发它的类别中。
受技术所限，上表各类计时并不严格准确（可能等于或略小于实际耗时），仅供参考。
需要 JDK 25。
./gradlew build # Windows 使用 gradlew.batMIT © 2026 Drizzle379