Better TPS

A TPS visualization and lag management mod for Minecraft 1.21.1 (Fabric).

💡 If you are frequently troubled by lag and want to know "exactly what is slowing down my game," this mod is for you.

✨ Feature Overview

1️⃣ TPS Visualization HUD (v1.0.0)

Displays real-time TPS (Ticks Per Second) and MSPT (Milliseconds Per Tick), keeping you informed of the game's performance status at all times.

Seven Display Modes

Mode	Description	Best For
HIDDEN	Completely hidden	When data isn't needed
MINI	TPS number only (colored)	Minimalist; won't block the view
COMPACT	Compact TPS + MSPT display	Small footprint; key info only
STANDARD	Standard TPS / MSPT / 1-min average	Recommended for daily use
GRAPH_ONLY	Real-time waveform graph only	Monitoring trends
FULL	Full data + real-time line graph	Detailed monitoring
BIG_DATA	Comprehensive data (entities, chunks, etc.)	In-depth analysis

TPS Color Indicators

Color	TPS Range	Status
🟢 Green	TPS ≥ 18	Smooth performance
🟡 Yellow	TPS ≥ 14	Slight lag
🟠 Orange	TPS ≥ 10	Noticeable lag
🔴 Red	TPS < 10	Severe lag

Screen Position

Supports 5 screen positions: Top-left, Top-right, Bottom-left, Bottom-right, and Top-center. ***

2️⃣ Lag Detection Alerts (v1.1.0)

Automatically monitors game TPS; sends an alert message in the chat when sustained lag (TPS dropping below a custom threshold) is detected.

✅ Customizable lag threshold (default: 10.0 TPS)
✅ Customizable duration for detection (default: 5 seconds)
✅ Built-in cooldown to prevent spamming (default: 30-second cooldown)
✅ Toggleable feature (enabled by default)
✅ Flashing red warning bar at the bottom of the screen

3️⃣ Laggy Chunk Management (v1.1.0)

Scan and identify the "culprit chunks" causing lag with a single click, and choose from three handling methods.

Chunk Scanning

Press F7 to open the management interface; the mod automatically scans nearby chunks and sorts them by "Lag Score":

Lag Score = Entity Count + (Block Entity Count × 2)

📊 Configurable scan range (default radius: 8 chunks)

Three Handling Methods

Action	Description	Best For
Freeze	Stops AI and gravity for all entities in the chunk	Temporarily preserving entities while troubleshooting
Unload	Removes all entities and block entities (irreversible)	Quickly clearing the source of lag
Hard Reset	Kills all entities and clears all block entities	Completely resetting the chunk

⚠️ All actions require a second confirmation to prevent accidental use!

🎮 Usage

Default Keybindings

Key	Function
`F4`	Cycle through HUD display modes
`F5`	Cycle through HUD screen positions
`F6`	Toggle lag alert feature
`F7`	Open laggy chunk management interface

💡 These keys can be modified in the game's "Controls" settings. ### Laggy Chunk Management Interface Controls

Mouse Click: Select chunk
↑ / ↓ Arrow Keys: Navigate up/down
F / U / R: Quickly perform Freeze / Unload / Restore operations
ESC: Close interface
+/-: Adjust lag threshold
T: Toggle lag alerts

⚙️ Configuration

The configuration file is located at .minecraft/config/bettertps.json and supports the following options:

Option	Type	Default	Description
`lagThreshold`	double	`10.0`	TPS threshold for lag alerts
`lagAlertEnabled`	boolean	`true`	Whether lag alerts are enabled
`lagAlertCooldown`	int	`30`	Lag alert cooldown (seconds)
`lagSustainSeconds`	int	`5`	Duration below threshold to trigger alert
`chunkScanRadius`	int	`8`	Chunk scan radius (in chunks)
`hudMode`	String	`COMPACT`	HUD display mode
`hudPosition`	String	`TOP_RIGHT`	HUD screen position

📦 Installation Requirements

Minecraft: 1.21.1
Mod Loader: Fabric Loader ≥ 0.16.9
Dependencies: Fabric API ≥ 0.102.0
Java: 21+

📥 Installation Steps

Install Fabric Loader and Fabric API
Download bettertps-1.1.0.jar
Place the jar file into the .minecraft/mods/ directory
Launch the game and enjoy a smooth experience! ***

🔧 Build (Developers)

# Build using the Python script (Recommended)
& "D:\python3.13.7\python.exe" "D:\项目\beter TPS\build_new.py"

# Or use Gradle (requires proper environment configuration)
./gradlew build

Build output is located at build/libs/bettertps-1.1.0.jar.

📝 Changelog

v1.1.0 (2026-06-28)

✨ Added "Lag Detection Alerts" feature
✨ Added "Laggy Chunk Management" GUI
✨ Support for freezing / unloading / fully restoring laggy chunks
🐛 Fixed entity count display issue in BIG_DATA mode
⚡ Optimized TPS monitoring performance

v1.0.0 (2026-06-26)

🎉 Initial release
✨ Real-time TPS / MSPT visualization HUD
✨ 7 display modes, 5 screen positions
✨ TPS color-coding system

❓ FAQ

Q: Can this mod be used on multiplayer servers? A: Yes! The HUD display and lag alert features work fully on multiplayer servers. However, the "Chunk Management" features (freeze/unload/restore) require server permissions and are limited to single-player or LAN hosts.

Q: Will lag alerts trigger false positives? A: The mod uses a "continuous detection" mechanism; alerts only trigger if the TPS remains below the threshold for a specific duration, preventing false positives caused by momentary fluctuations.

Q: Will the freeze operation corrupt my save file? A: No. Freezing simply halts entity AI and gravity; the entities remain in the world, and you can restore them at any time via "Full Restore" (which effectively respawns the entities).

Q: Can the unload operation be undone? A: No. Unloading removes all entities and block entities within the chunk, and this action is irreversible. Please use with caution! ***

👨‍💻 Author

Author: Computer1101
License: MIT License
Source Code: Not currently public

🙏 Acknowledgments

The Fabric team for the excellent modding framework
The Minecraft community for their support and feedback

If this mod has been helpful to you, please consider leaving a positive review on CurseForge or Modrinth ⭐

Better TPS

Better TPS

一个面向 Minecraft 1.21.1 (Fabric) 的 TPS 可视化与卡顿管理 Mod。

💡 如果你经常被卡顿困扰，想知道"到底是谁在拖慢我的游戏"，这个 Mod 就是为你准备的。

✨ 功能一览

1️⃣ TPS 可视化 HUD（v1.0.0）

实时显示游戏运行的 TPS（每秒 ticks 数）和 MSPT（每 tick 耗时），让你随时掌握游戏性能状态。

七种显示模式

模式	说明	适用场景
HIDDEN	完全隐藏	不需要看数据时
MINI	仅显示 TPS 数字（带颜色）	极简，不遮挡画面
COMPACT	紧凑显示 TPS + MSPT	小空间，关键信息
STANDARD	标准显示 TPS / MSPT / 1分钟均值	日常使用推荐
GRAPH_ONLY	仅显示实时波形图	只看趋势
FULL	完整数据 + 实时折线图	详细监控
BIG_DATA	全量数据（含实体数、区块数等）	深度分析

TPS 颜色指示

颜色	TPS 范围	状态
🟢 绿色	TPS ≥ 18	流畅运行
🟡 黄色	TPS ≥ 14	轻微卡顿
🟠 橙色	TPS ≥ 10	明显卡顿
🔴 红色	TPS < 10	严重卡顿

屏幕位置

支持 5 种屏幕位置：左上、右上、左下、右下、顶部居中。

2️⃣ 卡顿检测提醒（v1.1.0）

自动监控游戏 TPS，当检测到持续卡顿（TPS 低于自定义阈值）时，在聊天栏发送提醒消息。

✅ 可自定义卡顿阈值（默认 10.0 TPS）
✅ 可自定义持续检测时间（默认 5 秒）
✅ 内置冷却机制，避免刷屏（默认 30 秒冷却）
✅ 支持开关（默认开启）
✅ 屏幕底部红色警告条闪烁提示

3️⃣ 卡顿区块管理（v1.1.0）

一键扫描并找出导致卡顿的"元凶区块"，并提供三种处理方式。

区块扫描

按 F7 打开管理界面，Mod 会自动扫描你周围的区块，按"卡顿评分"排序：

卡顿评分 = 实体数量 + 方块实体数量 × 2

📊 扫描范围可配置（默认半径 8 个区块）

三种处理方式

操作	说明	适用场景
冻结	让区块内所有实体停止 AI、停止重力	临时保住实体，排查问题
卸载	移除所有实体和方块实体（不可恢复）	快速清理卡顿源
彻底还原	Kill 所有实体并清空方块实体	完全重置该区块

⚠️ 所有操作都需要二次确认，防止误操作！

🎮 使用方法

默认按键绑定

按键	功能
`F4`	循环切换 HUD 显示模式
`F5`	循环切换 HUD 屏幕位置
`F6`	开关卡顿提醒功能
`F7`	打开卡顿区块管理界面

💡 这些按键可以在游戏的「控制设置」中修改。

卡顿区块管理界面操作

鼠标点击：选择区块
↑ / ↓ 方向键：上下导航
F / U / R：快速执行冻结 / 卸载 / 还原操作
ESC：关闭界面
+/-：调整卡顿阈值
T：开关卡顿提醒

⚙️ 配置说明

配置文件位于 .minecraft/config/bettertps.json，支持以下选项：

配置项	类型	默认值	说明
`lagThreshold`	double	`10.0`	卡顿提醒的 TPS 阈值
`lagAlertEnabled`	boolean	`true`	是否启用卡顿提醒
`lagAlertCooldown`	int	`30`	卡顿提醒冷却时间（秒）
`lagSustainSeconds`	int	`5`	持续低于阈值多少秒后提醒
`chunkScanRadius`	int	`8`	区块扫描半径（区块数）
`hudMode`	String	`COMPACT`	HUD 显示模式
`hudPosition`	String	`TOP_RIGHT`	HUD 屏幕位置

📦 安装要求

Minecraft: 1.21.1
Mod 加载器: Fabric Loader ≥ 0.16.9
依赖: Fabric API ≥ 0.102.0
Java: 21+

📥 安装步骤

安装 Fabric Loader 和 Fabric API
下载 bettertps-1.1.0.jar
将 jar 文件放入 .minecraft/mods/ 目录
启动游戏，享受丝滑体验！

🔧 构建（开发者）

# 使用 Python 构建脚本（推荐）
& "D:\python3.13.7\python.exe" "D:\项目\beter TPS\build_new.py"

# 或使用 Gradle（需要正确配置环境）
./gradlew build

构建产物位于 build/libs/bettertps-1.1.0.jar。

📝 更新日志

v1.1.0 (2026-06-28)

✨ 新增「卡顿检测提醒」功能
✨ 新增「卡顿区块管理」GUI 界面
✨ 支持冻结 / 卸载 / 彻底还原卡顿区块
🐛 修复 BIG_DATA 模式下实体计数显示问题
⚡ 优化 TPS 监控性能

v1.0.0 (2026-06-26)

🎉 首次发布
✨ TPS / MSPT 实时可视化 HUD
✨ 7 种显示模式，5 种屏幕位置
✨ TPS 颜色指示系统

❓ 常见问题

Q: 这个 Mod 能在多人服务器上使用吗？ A: 可以！HUD 显示和卡顿提醒功能在多人服务器上完全可用。但「区块管理」功能（冻结/卸载/还原）需要服务器权限，仅限单人/局域网主机使用。

Q: 卡顿提醒会误报吗？ A: Mod 采用「持续检测」机制，只有 TPS 持续低于阈值一定的时间才会提醒，避免瞬时波动导致误报。

Q: 冻结操作会破坏我的存档吗？ A: 不会。冻结只是让实体停止 AI 和重力，实体仍然存在，你可以随时通过「彻底还原」恢复（实际上是重新生成实体）。

Q: 卸载操作可以撤销吗？ A: 不可以。卸载操作会移除区块内的所有实体和方块实体，且不可恢复。请谨慎使用！

👨‍💻 作者

作者: 计算机1101
许可证: MIT License
源码: 暂不公开

🙏 致谢

Fabric 团队提供的优秀 Mod 开发框架
Minecraft 社区的支持与反馈

如果这个 Mod 帮到了你，不妨去 curseforge/Modrinth 上给我一个好评 ⭐