GTNH Credits 编辑器

基本信息

属性	值
形态	独立 Swing 桌面应用，不是 Minecraft 内的 GUI，也不打进 mod jar
Gradle 子模块	`creditsEditor`（`settings.gradle.kts` 的 `include("creditsEditor")`）
主类	`net.noiraude.creditseditor.CreditsEditorApp`（`application { mainClass.set(...) }`）
产物名	`credits-editor`（`applicationName`），安装后命令为 `gtnh-credits-editor`
语言	Java 21（`java { toolchain { languageVersion.set(JavaLanguageVersion.of(21)) } }` + `options.release.set(21)`）
Look & Feel	FlatLaf `3.5.4` 的 `FlatLightLaf`，在 `main` 首行 `setup()`（`CreditsEditorApp.java:17`）
依赖	`project(":libCredits")`（与 mod 共用同一套解析 / 序列化代码）、`gson`（`runtimeOnly`，因为 libCredits 里 gson 是 `compileOnly`）、`flatlaf`
仓库占比	仓库 304 个文件中 216 个来自本子模块（158 个 Java + 28 个 PNG 图标 + 10 个 `messages_*.properties` 等），是仓库中体积最大的部分 —— mod 本体 `src/` 只有 24 个文件，`libCredits/` 22 个

功能

编辑 credits.json 数据与配套的 .lang 翻译文件。

读取 / 写入的路径

工具按资源根（目录或资源包 zip）打开，内部只认两条路径（CreditsLayout 枚举）：

assets/gtnhcredits/credits.json
assets/gtnhcredits/lang/*.lang

命令行传入的路径有四种处理分支（creditsEditor/README.md 「Usage」节）：

传入路径	行为
已存在的目录	作为资源树打开
已存在的 `.zip` 文件	作为 Minecraft 资源包打开
不存在、无 `.zip` 后缀	自动创建目录并作为资源树打开
不存在、带 `.zip` 后缀	自动创建 zip并写入 `pack.mcmeta`（`pack_format` 固定为 1，即 MC 1.7.10 的资源包格式，`PackMcmeta.PACK_FORMAT`）

命令行

gtnh-credits-editor [OPTIONS] [<path>]

参数	行为
`<path>`	启动时直接打开的路径，可为目录或 `.zip`；省略则打开空界面，用 File > Open / File > New 载入
`-h`, `--help`	打印用法后以退出码 0 结束
`-v`, `--version`	打印版本后以退出码 0 结束
`--resource=<path>`	与位置参数 `<path>` 等价

参数非法时把错误打到 stderr 并提示 --help，以退出码 1 结束（CreditsEditorApp.java:29-37）。命令名取自系统属性 app.name，缺省 gtnh-credits-editor（CreditsEditorApp.java:56-60）。

菜单

三个顶级菜单（ui/EditorMenuBar.java）：

菜单	条目
File	Open、New、—、Save、Save As、—、Quit
Edit	Undo、Redo、—、Manage Locales
Help	Shortcuts、—、About

界面语言由 10 个 messages_<locale>.properties 决定（cs、de、en、es、fr、it、ja、pt、ru、zh），跟随 JVM 的 user.language / user.country。Manage Locales 列出的可选语言来自 Locale.getAvailableLocales()，按当前 UI 语言的 Collator 排序（service/KnownLocales.java:29-43）—— 即可编辑的 .lang 语言集合由运行编辑器的 JVM 决定，而非仓库里预置的列表。

编辑能力

所有编辑动作走统一的撤销 / 重做命令栈（command/CommandStack、command/CommandStackSnapshot），共 21 个命令实现（command/impl/）：

分类	命令
分类	`AddCategoryCommand`、`RemoveCategoryCommand`、`EditCategoryDisplayNameCommand`、`EditCategoryDetailsCommand`、`MoveCategoriesOrderCommand`
人员	`AddPersonCommand`、`RemovePersonCommand`、`AddMembershipCommand`、`RemoveMembershipCommand`、`AddPersonRoleCommand`、`RemovePersonRoleCommand`、`MoveRolesOrderCommand`
角色	`EditRoleDisplayNameCommand`
语言	`AddLocaleCommand`、`RemoveLocaleCommand`、`AbstractLocaleCommand` 派生的 `AbstractEditLangFieldCommand`
导入	`TsvImporter` / `TsvImportCommandFactory`（TSV 批量导入，配套 `ui/dialog/ImportTsvDialog`）
其他	`DocumentEditCommand`、`EditFieldCommand`、`CompoundCommand`、`AbstractCommand`（基类）

EditAbortedException 用于让用户取消编辑时干净地退出命令而不污染撤销栈。

安装与运行

方式	命令	产物
仓库内直接运行	`./gradlew :creditsEditor:run`	自动以 `src/main/resources` 为参数
仓库内指定路径	`./gradlew :creditsEditor:run --args="<path>"`	—
安装到 `~/.local`	`./gradlew :creditsEditor:install`	`~/.local/bin/gtnh-credits-editor`（+ `.bat`）、`~/.local/lib/gtnh-credits-editor.jar`（含依赖的 fat jar）
自定义前缀	`./gradlew :creditsEditor:install -PPREFIX=/usr/local`，或 `PREFIX=/usr/local ./gradlew :creditsEditor:install`	同上，落在 `$PREFIX` 下
卸载	`./gradlew :creditsEditor:uninstall`	沿用同一 `PREFIX` 解析规则
跨平台发布包	`./gradlew :creditsEditor:releaseZip`	`gtnh-credits-editor-<version>.zip`（启动脚本 + fat jar + Windows 安装器）
Windows 安装器	`./gradlew :creditsEditor:windowsInstaller`	`creditsEditor/build/distributions/gtnh-credits-editor-<version>-setup.exe`（NSIS）

PREFIX 的解析优先级为：Gradle 属性 -PPREFIX > 环境变量 PREFIX > ~/.local（build.gradle.kts 的 installPrefix）。

Linux 上 install 额外写入 freedesktop .desktop 入口与 hicolor 图标（32 / 48 / 64 / 128 px），使编辑器出现在 GNOME / KDE 应用启动器中；macOS 与 Windows 不写。

主机环境要求

windowsInstaller 任务需要 NSIS 的 makensis。Linux x86_64 主机上任务会自行下载 Debian 的 nsis 3.08-3 deb 到 build/tools/nsis/ 并解出 makensis；macOS / Windows 主机若 makensis 不在 PATH 上则直接抛 GradleException 并提示用包管理器安装。
generateActionIcons 任务需要 rsvg-convert 与 optipng 同时在 PATH 上，否则抛 GradleException。该任务把 src/main/icons/tango/ 下的 SVG 栅格化成 16 / 24 / 32 / 48 px 的 PNG；生成结果已提交，因此没有这两个工具也能构建。
测试套件强制 java.awt.headless=true；需要真实图形环境的 Swing 测试用 assumeFalse(isHeadless()) 自行跳过（build.gradle.kts 的 tasks.named<Test>("test")）。