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.save task 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 — IOManagerStrategy interface + 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.

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

1. Requires Minecraft 1.21.1 + NeoForge 21.1.241+.
2. Drop the jar into .minecraft/mods/ (install on both client and server for both sides to take effect).
3. A config file .minecraft/config/hddmode-config.toml is generated on first launch.

🛠️ Building

gradlew build

Output: build/libs/hddmode-<version>.jar

Dev note: this project adds -Djavax.net.ssl.trustStoreType=WINDOWS-ROOT to gradle.properties for the MITM-proxy dev environment; you may remove it on a normal network.

⚙️ Configuration

.minecraft/config/hddmode-config.toml

🤝 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 后，客户端内置服务器平均 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

提示：性能数据因硬件、视角、模组组合而异，以上为同一机器两次实测的对照，仅供参考。

📦 安装

1. 需要 Minecraft 1.21.1 + NeoForge 21.1.241+。
2. 将 hddmode-<version>.jar 放入 .minecraft/mods/（客户端与服务器均安装则两端生效）。
3. 首次启动后生成配置文件 .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

🤝 兼容性

• 兼容：Bobby、Distant Horizons（遥远的地平线）、JourneyMap、Xaero 小地图、Sodium、Lithium、FerriteCore、Create 等（不覆盖其钩子，仅增强文件流缓冲）。
• 安卓：PojavLauncher / FCL 下自动完全静默（NO-OP），保证稳定。
• 不支持：Fabric / Quilt（本模组为 NeoForge 专属）。

📄 开源协议

LGPL-3.0-only —— 允许其他模组调用本模组的 I/O 接口，但不污染闭源项目。