HDD Mode
- By
Like most PS4-era console games, this mod provides HDD (mechanical hard drive) storage I/O strategy optimization for Minecraft 1.21.1.
HDD Mode
Like most PS4-era console games, this mod provides HDD (mechanical hard drive) storage I/O strategy optimization for Minecraft 1.21.1 / NeoForge.
HDD Mode targets frame drops and server tick stutter caused by disk I/O during chunk loading/saving and mod cache reads/writes. Through hardware auto-detection, separate local/server strategies, write coalescing and cache warm-up, it significantly reduces disk-I/O-induced lag — without touching vanilla chunk generation.
✨ Features
- Hardware adaptive — auto-detects storage type at startup (HDD / SATA SSD / NVMe), with manual override in the config file.
- Local strategy (single-player / LAN host):
- Async world saving + write coalescing (buffer pool, 500ms default / 1000ms aggressive merge window)
- Freeze-free auto-save (intercepts the vanilla
ServerLevel.savetask and defers it) - Save rollback protection (aggressive mode only: pre-write backup, auto-restore after a crash)
- Remote strategy (dedicated server):
- Automatically unloads local write hooks (the client doesn't save the world)
- Boosts read buffers of Bobby / Distant Horizons chunk cache files (OS page-cache warm-up)
- Aggressive mode requires a memory pre-check (default ≥ 6GB, falls back to Conservative)
- Android safety fuse — enters a fully silent NO-OP mode on Android (PojavLauncher / FCL): no mixins, no thread pools, no config reads.
- Zero-damage — does not modify vanilla chunk generation; does not override hooks of Bobby / DH / Sodium / Lithium etc.
- Strategy pattern —
IOManagerStrategyinterface +LocalIOManager/RemoteIOManager, injected via a factory: zero if-else on hot paths.
📊 Measured Performance
Data measured with the BenchMark mod (120s each). Test rig: HDD (auto-detected); ran with Distant Horizons 1024-view-distance LoD and Tectonic's large terrain generation to increase read/write load.
| Metric | Without HDD Mode | With HDD Mode | Change |
|---|---|---|---|
| Avg FPS | 74.7 | 78.1 | +4.6% 🟢 |
| Avg MSPT (ms) | 56.65 | 50.27 | -11.3% 🟢 |
| Avg TPS | 17.65 | 19.89 | +2.24 🟢 |
| Max MSPT (ms) | 512.83 | 100.69 | -80.4% 🟢 |
| 1% Low FPS | 12.7 | 13.7 | +7.9% 🟢 |
Conclusion: With HDD Mode enabled, average server tick time drops ~11% (avg TPS rises from 17.65 to near-max 19.89), peak stutter drops from 512ms to 101ms (-80%), and both average FPS and 1% Low improve — under a heavy LoD-loading + large-terrain-generation workload.
Test environment: Intel Core i7-4790K · AMD Radeon RX 6500 XT · 16GB RAM · Windows 10 · HDD
Note: Results vary by hardware, viewpoint and mod list; the table is a like-for-like comparison on the same machine.
📦 Installation
- Requires Minecraft 1.21.1 + NeoForge 21.1.241+.
- Drop the jar into
.minecraft/mods/(install on both client and server for both sides to take effect). - A config file
.minecraft/config/hddmode-config.tomlis generated on first launch.
🛠️ Building
gradlew build
Output: build/libs/hddmode-<version>.jar
Dev note: this project adds
-Djavax.net.ssl.trustStoreType=WINDOWS-ROOTtogradle.propertiesfor the MITM-proxy dev environment; you may remove it on a normal network.
⚙️ Configuration
.minecraft/config/hddmode-config.toml
| Key | Default | Description |
|---|---|---|
storage_type |
AUTO |
AUTO / HDD / SSD / NVME, override hardware detection |
force_mode |
AUTO |
AUTO / CONSERVATIVE / AGGRESSIVE, force local strategy mode |
local.enable_async_save |
true |
Async world save |
local.enable_write_merge |
true |
Write coalescing (buffer pool) |
local.enable_auto_save_async |
true |
Freeze-free auto-save |
local.enable_rollback_protection |
true |
Rollback protection (aggressive mode) |
local.conservative_buffer_size |
8192 |
Conservative buffer (bytes) |
local.conservative_merge_window_ms |
500 |
Conservative merge window (ms) |
local.aggressive_buffer_size |
65536 |
Aggressive buffer (bytes) |
local.aggressive_merge_window_ms |
1000 |
Aggressive merge window (ms) |
remote.enable_cache_boost |
true |
Remote cache read-buffer boost |
remote.cache_buffer_size |
262144 |
Cache buffer (bytes) |
remote.enable_minimap_async |
true |
Async minimap metadata |
remote.enable_resource_streaming |
true |
Async resource/sound streaming |
remote.aggressive_min_memory_gb |
6 |
Min memory for aggressive (GB) |
🤝 Compatibility
- Compatible: Bobby, Distant Horizons, JourneyMap, Xaero's Minimap, Sodium, Lithium, FerriteCore, Create, etc. (does not override their hooks — only boosts file-stream buffers).
- Android: fully silent (NO-OP) on PojavLauncher / FCL for stability.
- Not supported: Fabric / Quilt (NeoForge-only mod).
📄 License
Licensed under the GNU Lesser General Public License v3.0 (LICENSE) — allows other mods to use its I/O interfaces without contaminating closed-source projects.
HDD Mode 中文说明
像大多数 PS4 时代主机游戏那样，为 Minecraft 1.21.1 / NeoForge 提供 HDD（机械硬盘）存储 I/O 读取策略优化。
HDD Mode 针对机械硬盘在区块加载/保存、模组缓存读写等场景下的卡顿问题，通过硬件自适应 + 本地/服务器双策略 + 写入合并 + 缓存预热，在不修改原版区块生成机制的前提下，显著降低磁盘 I/O 造成的掉帧与服务器 tick 卡顿。
✨ 特性
- 硬件自适应：启动时自动检测存储介质（HDD / SATA SSD / NVMe），支持配置文件手动覆盖。
- 本地策略（单机 / 局域网主机）：
- 异步世界保存 + 写入合并（缓冲池，合并窗口默认 500ms / 激进 1000ms）
- 自动保存防卡顿（拦截
ServerLevel.save定时任务转为异步/延迟执行） - 存档回滚保护（仅激进模式：写前备份，崩溃自动恢复）
- 服务器策略（连接远程专用服务器）：
- 自动卸载本地写盘钩子（客户端不保存主世界）
- 强化 Bobby / Distant Horizons 区块缓存文件读取缓冲（OS 页缓存预热）
- 激进模式需内存前置校验（默认 ≥ 6GB，不足自动回退保守模式）
- 安卓熔断：检测到 PojavLauncher / FCL 等安卓环境时立即进入完全静默 NO-OP 模式（不注入 Mixin、不初始化线程池、不读配置）。
- 零破坏性：不修改原版区块生成机制；不覆盖 Bobby / DH / Sodium / Lithium 等模组的钩子。
- 策略模式：
IOManagerStrategy接口 +LocalIOManager/RemoteIOManager，通过工厂注入，热代码路径零 if-else。
📊 优化效果实测
数据模组作者开发的另一个模组 BenchMark 模组 实测生成（各 120 秒）。测试环境：机械硬盘（模组自动检测为 HDD）；运行 Distant Horizons（遥远的地平线）1024 视距 LoD，并开启 Tectonic 模组的大型地形生成以增加读写负载。
| 指标 | 未启用优化 | 启用 HDD Mode | 提升 |
|---|---|---|---|
| 平均帧率 / Avg FPS | 74.7 | 78.1 | +4.6% 🟢 |
| 平均 MSPT（服务器） | 56.65 | 50.27 | -11.3% 🟢 |
| 平均 TPS | 17.65 | 19.89 | +2.24 🟢 |
| 最高 MSPT（峰值卡顿） | 512.83 | 100.69 | -80.4% 🟢 |
| 1% Low FPS | 12.7 | 13.7 | +7.9% 🟢 |
结论：启用 HDD Mode 后，客户端内置服务器平均 tick 时间下降约 11%（平均 TPS 从 17.65 提升到接近满速的 19.89），峰值卡顿从 512ms 大幅降到 101ms（-80%），平均帧率与 1% Low 均有提升——在高负载的 LoD 加载 + 大型地形生成场景下，磁盘 I/O 造成的卡顿被显著缓解。
测试环境：Intel Core i7-4790K · AMD Radeon RX 6500 XT · 16GB RAM · Windows 10 · HDD
提示：性能数据因硬件、视角、模组组合而异，以上为同一机器两次实测的对照，仅供参考。
📦 安装
- 需要 Minecraft 1.21.1 + NeoForge 21.1.241+。
- 将
hddmode-<version>.jar放入.minecraft/mods/（客户端与服务器均安装则两端生效）。 - 首次启动后生成配置文件
.minecraft/config/hddmode-config.toml。
🛠️ 构建
gradlew build
产物位于：build/libs/hddmode-<version>.jar
开发环境提示：本项目在透明 MITM 代理环境下于
gradle.properties加入了-Djavax.net.ssl.trustStoreType=WINDOWS-ROOT（本机适配），正常网络可删除。
⚙️ 配置
.minecraft/config/hddmode-config.toml
| 配置项 | 默认值 | 说明 |
|---|---|---|
storage_type |
AUTO |
AUTO / HDD / SSD / NVME，手动覆盖硬件检测 |
force_mode |
AUTO |
AUTO / CONSERVATIVE / AGGRESSIVE，强制本地策略模式 |
local.enable_async_save |
true |
异步世界保存 |
local.enable_write_merge |
true |
写入合并（缓冲池） |
local.enable_auto_save_async |
true |
自动保存防卡顿 |
local.enable_rollback_protection |
true |
激进模式存档回滚保护 |
local.conservative_buffer_size |
8192 |
保守模式缓冲区（字节） |
local.conservative_merge_window_ms |
500 |
保守模式合并窗口（毫秒） |
local.aggressive_buffer_size |
65536 |
激进模式缓冲区（字节） |
local.aggressive_merge_window_ms |
1000 |
激进模式合并窗口（毫秒） |
remote.enable_cache_boost |
true |
远程缓存文件读取缓冲增强 |
remote.cache_buffer_size |
262144 |
缓存缓冲区（字节） |
remote.enable_minimap_async |
true |
小地图元数据异步批量写入 |
remote.enable_resource_streaming |
true |
资源包 / 音效流异步解压 |
remote.aggressive_min_memory_gb |
6 |
服务器激进模式最小内存（GB） |
🤝 兼容性
- 兼容：Bobby、Distant Horizons（遥远的地平线）、JourneyMap、Xaero 小地图、Sodium、Lithium、FerriteCore、Create 等（不覆盖其钩子，仅增强文件流缓冲）。
- 安卓：PojavLauncher / FCL 下自动完全静默（NO-OP），保证稳定。
- 不支持：Fabric / Quilt（本模组为 NeoForge 专属）。
📄 开源协议
LGPL-3.0-only —— 允许其他模组调用本模组的 I/O 接口，但不污染闭源项目。
The HDD Mode Team
