Better TPS
- By
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 buildBuild 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 上给我一个好评 ⭐
The Better TPS Team
