HMCL-dev / HMCL-dev/HMCL

[Feature] 支持在 macOS 上直接安装汉化补丁 ZIP

Open
#6,719 8 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Java
Stars
10.1k
Forks
934
Avg merge
1d 5h
Merged PRs (30d)
82

Description

概述 | Summary

希望 HMCL 支持从 ZIP 文件直接安装“汉化补丁/覆盖文件包”到指定的 Minecraft 实例。此类 ZIP 通常使用游戏目录的相对路径(例如 config/kubejs/mods/resourcepacks/vaultpatcher/),并不是一个完整的整合包,不能方便地通过现有的整合包导入流程安装。

On macOS, users should be able to select an instance and a localization overlay ZIP in HMCL and apply it safely without relying on Finder copy/paste or an external script.

原因 | Reason

提出这个功能的直接原因不是单纯找不到实例目录,而是 macOS Finder 对这类补丁的复制、粘贴、目录合并和同名文件覆盖处理不适合实际使用。汉化补丁往往包含大量与现有实例同名的目录和文件,Finder 粘贴后的合并/覆盖结果不够明确,也难以确认是否完整应用,容易导致部分汉化没有生效。

目前用户只能手动尝试 Finder 操作,或运行额外的 .command 脚本。后者虽然可以解决问题,但不是 HMCL 内置能力,普通用户也很难发现和验证脚本来源。

以 All the Mods 10 的一个汉化补丁为例,ZIP 中包含数百个需要覆盖或新增的 config/mods/ 等文件。脚本实际处理了 316 个游戏文件,其中写入 268 个、内容一致跳过 48 个;这说明补丁本质上是“针对已有实例的文件覆盖包”,而不是完整整合包。

详情 | Description

可以在实例菜单或实例文件管理页面增加“导入汉化补丁 / 覆盖文件 ZIP”操作:

  1. 让用户选择目标实例和 ZIP 文件。
  2. 按 ZIP 内的游戏目录相对路径安全地合并文件,而不是依赖 Finder 的粘贴行为。
  3. 预览将要新增、覆盖、跳过的文件,并在覆盖前明确确认。
  4. 仅接受安全的相对路径,拒绝绝对路径和包含 .. 的路径,避免 ZIP 路径穿越。
  5. 安装时保留补丁中未包含的现有文件,并在完成后显示写入、跳过和未处理文件数量。
  6. 如果实现成本允许,可同时支持 Windows、Linux;macOS 是最迫切的使用场景。

该功能不要求 HMCL 识别每个汉化包的具体来源,只需要提供一个安全、可复用的“将 ZIP 内容合并到实例目录”的入口即可。

当前用于验证需求的 macOS .command 脚本(已包含文件校验、原子写入、路径安全检查和处理结果统计)如下:

https://gist.github.com/ct-yx/3bbb2bc4430a2b63fbe813dd1e2f80fa

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the instance menu or instance file-management entry point and the existing integration-pack import flow. Review how the launcher selects an instance and extracts archive contents before defining the ZIP merge and preview flow. Done means safe relative-path validation, explicit new/overwrite/skip confirmation, preserved unrelated files, and result counts after installation.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
desktop, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.