MineTuner 统计服务器

MineTuner Statistics Server (MTSS)

一个完全可自定义、多列表的 Fabric 性能覆盖层

---

什么是 MineTuner Statistics Server？

MineTuner Statistics Server 会在你的屏幕上显示一个简洁、可配置的 HUD，展示实时性能与世界数据。与原版调试屏幕不同，MineTuner Statistics Server 旨在永久驻留在你的屏幕上，不显眼、清晰易读，并且完全由你配置。

你可以决定显示哪些数据、它们显示在何处，以及你想要多少个独立的统计面板。所有操作都通过游戏内的拖放 GUI 控制，无需编辑配置文件。

---

统计项目

MineTuner Statistics Server 会追踪服务器、客户端、玩家和系统四大类别的 16 项指标：

统计项	描述	备注
TPS	服务器每秒刻数	按颜色区分绿/黄/红。在单人游戏中，根据实时 MSPT 计算。在多人游戏中，从服务器的 TickingState 数据包中读取。
MSPT	每刻毫秒数	仅限单人游戏 / 局域网 — 在数据不可用的远程服务器上会自动隐藏。
FPS	客户端每秒帧数	按颜色区分：≥60 绿色，≥30 黄色，<30 红色。
Ping	往返延迟（毫秒）	按颜色区分：≤80ms 绿色，≤150ms 黄色，>150ms 红色。
内存	JVM 堆内存使用量（已用 / 最大 MB）	根据堆内存填充百分比按颜色区分。
CPU	JVM 进程 CPU 负载百分比	每 500ms 通过 OperatingSystemMXBean 轮询一次。仅限 HotSpot/OpenJDK — 其他 JVM 供应商显示“N/A”。
实体	当前维度中已加载的实体数量	—
区块	已加载的区块数量	—
已渲染区块部分	渲染通道中的区块部分数量	直接从 LevelRenderer 获取。
坐标	你的方块 XYZ 坐标	向下取整的整数。
朝向	基本方向 + 中间方向	完整的 8 方向：N, NE, E, SE, S, SW, W, NW。
速度	水平移动速度（方块/秒）	根据 deltaMovement × 20 刻/秒计算。
GC 时间	JVM 垃圾回收累计时间（毫秒）	通过 GarbageCollectorMXBean 汇总所有 GC Bean。
生物群系	你当前位置的生物群系	—
光照等级	你所在方块位置的局部光照等级	—
维度	当前维度 ID	例如 overworld、the_nether、the_end。

渲染数字的统计项（TPS、MSPT、CPU、速度）支持可配置的小数位数设置，可通过每个统计项的面板（⚙）按列表调整。

---

功能特性

多个独立的统计列表

你可以创建任意数量的独立 HUD 面板。每个列表都可以独立定位、配置和设置样式。你可以在一个角落放置性能面板，在另一个角落放置坐标/朝向面板——完全由你决定。

拖放定位

打开编辑器（/mtss gui）并将任意列表拖到屏幕上的任何位置。位置会相对于最近的屏幕角保存，因此你的布局在窗口大小调整或分辨率更改后也不会漂移。

中心吸附

拖动时，列表会吸附到屏幕的垂直和水平中心线，并带有可见的参考线和命中标记。吸附轴会被保存——居中的面板无论窗口大小如何都会保持居中。

每个列表的统计控制

在编辑器中右键单击任意列表以打开其上下文菜单：

• ⚙ 编辑统计项 — 启用或禁用单个统计项，上下移动它们，并打开每个统计项的设置：切换标签前缀（例如，隐藏“TPS: ”只显示数值），为数字统计项（TPS、MSPT、CPU、速度）设置小数位数，将可绘制图表的统计项（TPS、MSPT、FPS、CPU、Ping、内存、速度）在文本和滚动历史图表之间切换，并为 TPS、FPS、Ping、内存和 CPU 覆盖良好/警告颜色阈值
• ▤ 外观 — 包含以下选项的子面板：
  • 重命名 — 为列表指定自定义名称
  • 背景 — 切换半透明深色背景
  • 文本阴影 — 切换文本阴影
  • 颜色 / 缩放 — 用自定义颜色覆盖正常的颜色编码，并将列表文本从 0.5 倍缩放到 2.0 倍
  • 模板模式 — 将列表切换为自由格式的模板行（参见下方的 模板模式）
• ⧉ 复制 — 克隆一个列表（包括其所有统计项和设置）作为变体布局的起点
• ✕ 删除 — 完全移除该列表

右键创建

在编辑器屏幕的任何空白区域右键单击，即可在该位置立即创建一个新的统计列表。

打开编辑器的按键绑定

除了 /mtss gui 之外，还有一个按键绑定（默认：H）可以直接打开编辑器——可在 选项 → 控制 → 按键绑定 → MineTuner Statistics Server 中重新绑定。

切换覆盖层的按键绑定

另一个独立的按键绑定（默认未绑定，可在 选项 → 控制 → 按键绑定 → MineTuner Statistics Server 中重新绑定）可以立即显示或隐藏实时覆盖层，而无需打开编辑器——方便直播或截图时使用。它与编辑器相互独立：即使覆盖层被隐藏，打开编辑器仍然可以正常工作，并且仍然显示列表预览。

颜色编码值

TPS、FPS、Ping、内存、CPU 和速度都会根据阈值以情境感知的颜色（绿色/黄色/红色）渲染——你可以在不读取数字的情况下一眼看出是否有问题。对于 TPS、FPS、Ping、内存和 CPU，这些阈值可以通过每个统计项的面板（⚙ → 自定义阈值 »）按列表自定义；速度则使用其自身固定的基于运动的着色方案。

不需要时零开销

当原版调试屏幕（F3）打开时，HUD 渲染器会被完全跳过，并且在编辑器 GUI 激活时覆盖层会被抑制。缓慢的指标（CPU、GC）以 500ms 的节流进行轮询，以避免每帧都频繁调用 OperatingSystemMXBean。

帧一致的线条缓存

所有统计字符串的构建都会在每帧缓存在一个基于代键的 HashMap 中。渲染器和编辑器 GUI 共享相同的缓存，因此同一帧内永远不会重复构建相同的字符串。

模板模式

每个列表默认使用经典模式——每行一个统计项，与 MineTuner Statistics Server 一贯的工作方式完全相同。将列表切换到模板模式后，你可以直接控制其行内容：编写自己的文本并随时插入 {tps} 或 {fps} 等统计项令牌，可在单行中混合多个统计项和字面文本（例如 FPS: {fps} | TPS: {tps:2} | {ping}ms）。完整的令牌表和编辑流程请参阅“用法”下的 模板模式 部分。

---

安装

1. 安装 Fabric Loader（≥ 0.18）
2. 安装 Fabric API
3. 将 MineTuner Statistics Server 的 .jar 文件放入你的 mods 文件夹
4. 启动游戏

要求：

• Minecraft ≥ 26.1
• Java 25 或更新版本
• Fabric API

MineTuner Statistics Server 是一个仅客户端模组。无需在服务器上安装。

---

使用方法

打开编辑器

在聊天框中运行命令 /mtss gui，或按下 MineTuner Statistics Server 按键绑定（默认：H，可在控制设置中重新绑定）。

隐藏覆盖层

按下 切换 MineTuner Statistics Server 覆盖层 按键绑定（默认未绑定，可在 选项 → 控制 → 按键绑定 → MineTuner Statistics Server 中绑定）即可在不打开编辑器的情况下立即显示或隐藏 HUD。动作栏消息会确认覆盖层当前是显示还是隐藏。这只会影响实时覆盖层——即使覆盖层被隐藏，编辑器（/mtss gui 或打开编辑器的按键绑定）仍然可以正常打开并预览你的列表。

编辑器中的控制

操作	结果
左键单击 + 拖动	移动统计列表
右键单击列表	打开上下文菜单（编辑统计项、外观、复制、删除）
右键单击空白区域	在该位置创建一个新列表
Escape	关闭编辑器并保存

编辑统计项面板

在列表的上下文菜单中，点击 ⚙ 编辑统计项 以打开该列表的统计面板：

• 点击统计行以切换其开启或关闭
• 点击 ▲ / ▼ 以在显示顺序中上下移动统计项
• 点击 ⚙ 以打开每个统计项的设置：
  • 显示前缀 — 显示/隐藏标签前缀（例如，隐藏“TPS: ”只显示数值）
  • 小数位数 — 对于数字统计项（TPS、MSPT、CPU、速度），使用 - / + 调整小数位数
  • 渲染为图表 — 对于可绘制图表的统计项（TPS、MSPT、FPS、CPU、Ping、内存、速度），将文本行替换为滚动历史图表
  • 自定义阈值 » — 对于 TPS、FPS、Ping、内存和 CPU，打开一个子面板，仅为此列表覆盖该统计项的绿/黄/红颜色截止点：
  • 使用自定义阈值 开关 — 关闭时，该统计项将回退到其内置的默认阈值
  • 良好 / 警告 步进器 — 使用 - / + 调整（TPS 以 0.5 为步长，其他所有项以整数为步长）。统计项名称下方的副标题会提醒你该统计项是“（越高越好）”（TPS、FPS）还是“（越低越好）”（Ping、内存、CPU），因为两者的工作方向相反
  • 良好/警告值会自动保持在该统计项方向上的正确顺序，因此你不会意外创建反向范围
  • 点击 ◀ 返回 以返回每个统计项的设置面板
• 点击 ✕ 关闭 以返回上下文菜单

外观面板

在列表的上下文菜单中，点击 ▤ 外观 » 以打开：

• 重命名 — 为列表指定自定义名称
• 背景 — 切换半透明深色背景
• 文本阴影 — 切换文本阴影
• 颜色 / 缩放 » — 打开一个子面板：
  • 切换 使用自定义颜色 以覆盖正常的基于阈值的着色
  • 点击 循环颜色 以逐步浏览精选调色板
  • 使用 - / + 调整列表文本在 0.5 倍和 2.0 倍之间的缩放比例
  • 点击 ◀ 返回 以返回外观设置
• 模板模式 — 将列表切换为自由格式的模板行（参见下方的 模板模式）
• 点击 ◀ 返回 以返回上下文菜单

模板模式

经典模式（默认）按照 statOrder 的顺序，每个启用的统计项渲染一行，与上述描述完全一致。模板模式 是列表的可选替代方案：不再是固定的统计行列表，而是编写自己的文本行，并在其中插入统计项令牌——更接近于一种小型超文本标记而非严格的统计列表。这完全是每个列表独立设置的；未处于模板模式的列表行为与所有先前版本完全相同。

开启模板模式

右键单击列表 → ▤ 外观 » → 模板模式 以对该列表开启。开启后，上下文菜单中的 ⚙ 编辑统计项 行将变为 ⚙ 编辑模板行。

编辑模板行

点击 ⚙ 编辑模板行 以打开该列表的行列表：

• 点击现有行以打开文本输入框——输入你的模板，按 Enter 确认，或按 Esc 取消并保留之前的文本
• 点击行旁的 ✕ 将其删除
• 点击 + 添加行 以追加一个新（初始为空）行，然后点击它进行编辑
• 点击 ✕ 关闭 以返回上下文菜单

每个 templateLines 条目都会渲染为一行，按列表顺序排列。

令牌语法

将统计项的令牌名称用花括号括起来以插入其值：{tps} 会插入当前的 TPS 值，并使用其默认小数位数。模板行中的其他所有内容都是字面文本，完全按输入的样子渲染。

令牌	统计项	备注
{tps}	TPS	支持 :N 小数后缀
{mspt}	MSPT	支持 :N 小数后缀；在远程服务器上不渲染内容，与经典模式相同
{fps}	FPS	—
{ping}	Ping	—
{mem}	内存	—
{cpu}	CPU	支持 :N 小数后缀
{entities}	实体	—
{chunks}	区块	—
{rendered}	已渲染区块部分	—
{coords}	坐标	—
{facing}	朝向	—
{speed}	速度	支持 :N 小数后缀
{gc}	GC 时间	—
{biome}	生物群系	—
{light}	光照等级	—
{dimension}	维度	—

在任何支持小数的令牌后添加 :N 以覆盖其小数位数，例如 {tps:2} 表示两位小数，{cpu:0} 表示整数。省略它则使用该统计项的常规默认值（与经典模式使用的默认值相同）。

示例：FPS: {fps} | TPS: {tps:2} | {ping}ms 可能渲染为 FPS: 144 | TPS: 19.86 | 42ms。

字面花括号

要在模板行中显示字面的 { 或 }（而不是开始一个令牌），请将其双写：{{ 渲染为 {，}} 渲染为 }。

无法识别的令牌

拼写错误或未知的令牌——{tsp}、{ping:2}（Ping 没有小数）、{tps:abc}——不会被静默丢弃或视为错误。它会作为字面文本渲染出来（包括花括号，例如 {tsp} 会在屏幕上完全如此显示），因此错误是可见且易于发现和修复的，而不是悄无声息地消失。

着色与当前限制

模板行每行以单一平面颜色渲染——要么是列表的自定义颜色（颜色 / 缩放… → 使用自定义颜色）如果已启用，否则为纯白色。不支持按令牌的内联着色（因此同一行的不同部分不能显示各自的阈值颜色）——这是一个自然的后续功能，但超出了当前版本的范围。经典模式的每个统计项阈值着色和显示前缀设置在模板模式中也不适用；由于你自己编写字面文本，如果不需要标签，直接不输入即可。

模板行始终是纯文本行——模板模式目前不支持将模板行渲染为滚动图表。

配置文件

设置会自动保存到 .minecraft/config/mtss.json。你可以检查或备份此文件，但对于游戏内 GUI 暴露的任何设置，都不需要手动编辑。

一个例外：图表的 GraphStyle（面板背景、网格线、峰值标记、数值显示模式、平滑、缩放模式、颜色模式、宽度/高度）目前仅作为数据模型和渲染使用——对应的 GUI 控件将在后续步骤中添加。在此之前，调整它们意味着直接编辑配置文件中相关统计项的 graphStyle 块。

---

兼容性

• 仅客户端 — 可在任何服务器（原版、Paper、Fabric 等）上运行
• MSPT 仅在单人游戏和局域网世界中显示——在数据无法访问的远程服务器上会被静默隐藏
• 与其他 HUD 模组不冲突——MineTuner Statistics Server 通过 Fabric API 的 HudElementRegistry 注册其覆盖层，并附加在聊天层之前

---

添加统计项（供贡献者参考）

每个统计项的格式化、着色、小数位数以及图表/阈值支持都集中在一个地方：bottled.mtss.stat.StatDefinition。GUI、HUD 渲染器和模板引擎都从 bottled.mtss.stat.StatRegistry 读取——它们都不会针对单个统计项进行切换，因此新统计项无需修改这些文件。

1. 在 MtssConfig.Stat 中添加一个常量。
2. 在 bottled.mtss.stat.stats 中编写一个实现 StatDefinition 的类。对于纯文本统计项，复制最小的现有类（EntitiesStat）；如果需要图表/颜色支持，则复制像 PingStat 这样的阈值统计项。
3. 在 StatRegistry 的静态块中注册其实例。
4. 将其语言键（stat.mtss.<name> 和 mtss.stat.<name>）添加到 en_us.json。
5. 如果是原始游戏/JVM 状态，则从 MtssDataHolder 的采样循环中获取，与现有统计项相同——StatDefinition 实现应保持为薄委托，而不应自行轮询。
6. 在上面的模板模式表中添加其令牌行。

这就是全部的操作范围——无需更新 switch (stat) 块。