模组菜单 Mod Menu

Mod Menu (模组菜单) 概述

Mod Menu 旨在为你提供一个直观的界面，用于查看和管理已安装的模组列表。

该模组不仅能清晰地展示你当前环境下的模组清单，而且如果已安装的模组本身支持，Mod Menu 还能作为一个便捷的入口，让你快速访问并调整这些模组的配置界面。

此外，Mod Menu 还引入了一系列高级功能来增强用户体验和模组展示效果，包括：

• 本地化支持：允许对模组名称和描述进行翻译。
• 富文本描述：得益于 Patbox 的 Text Placeholder API，模组描述中支持使用 QuickText 格式。
• 智能过滤：能够区分并过滤掉基础的前置库模组，使列表更整洁。
• 更新检测：针对托管在 Modrinth 上的模组或提供自定义更新源的模组，内置了更新检查器。
• 深度配置：针对 Mod Menu 自身提供的所有功能，都给予了用户高度的配置自由。

支持平台

目前，Mod Menu 适用于 Minecraft Java 版 1.14 及更高版本，并支持 Fabric 或 Quilt 加载器。

开发者指南

Mod Menu 为开发者提供了一套丰富的 API 工具集，旨在优化模组在菜单中的呈现方式。这些工具涵盖了语言键（Language Keys）、JSON 元数据（JSON Metadata）以及通过代码实现的 Java API。

翻译 API (Translation API)

你完全无需编写任何 Java 代码，即可对模组的名称、摘要和详细描述进行本地化处理。只需按照指定格式，将翻译键值添加到你所需的语言文件中即可。

翻译 API 使用示例

以下是一个展示 Mod Menu 被翻译成“海盗语”的示例。若要为你自己的模组创建翻译，只需将翻译键末尾的 modmenu 替换为你自己的模组 ID 即可（请注意，不要替换开头的 modmenu），例如：modmenu.descriptionTranslation.traverse。

文件：en_pt.json

"modmenu.nameTranslation.modmenu": "Menu o' mods!",  
"modmenu.descriptionTranslation.modmenu": "Menu o' mods ye installed matey!",  
"modmenu.summaryTranslation.modmenu": "Menu o' mods ye installed matey!"  

提示：在此示例中，摘要（summary）的翻译其实是多余的，因为它与描述（description）的内容完全一致。这里将其列出主要是为了演示一项功能：你可以将摘要（即对模组的一句话简短介绍）与详细描述分开独立翻译，哪怕是在英文原版中也是如此！

Fabric 元数据 API (Fabric Metadata API)

开发者可以通过在 fabric.mod.json 文件中添加特定的元数据来丰富模组的展示信息。

所有相关配置都需要放置在 fabric.mod.json 的自定义块（custom block）中。以下是一个集成了该 API 众多功能的配置示例：

文件：fabric.mod.json

{  
  ...  
  "custom": {  
    "modmenu": {  
      "links": {  
        "modmenu.discord": "https://discord.gg/jEGF5fb"  
      },  
      "badges": [ "library", "deprecated" ],  
      "parent": {  
        "id": "example-api",  
        "name": "Example API",  
        "description": "Modular example library",  
        "icon": "assets/example-api-module-v1/parent_icon.png",  
        "badges": [ "library" ]  
      },  
      "update_checker": true  
    }  
  }  
}  

徽章系统 ("badges": [ ])

虽然对于在 fabric.mod.json 中设置了 "environment": "client" 的模组，系统会自动添加 Client（客户端）徽章，但其他特殊徽章如 Library（前置库）和 Deprecated（已弃用）则需要在此处手动定义。

支持的徽章值包括：

• library：应分配给那些纯粹作为其他模组依赖项存在的模组。默认情况下，这些模组不会向用户展示，除非用户手动切换显示开关。
• deprecated：应分配给那些仅出于历史兼容原因而存在的模组，例如旧版的 API 模块等。

请注意，任何非上述列出的值都将被忽略，且 Mod Menu 目前不支持开发者自定义徽章。如果你认为确实有必要添加新的徽章类型，可以在项目仓库中提交 Issue 进行讨论。

链接系统 ("links": { })

links 对象允许模组作者在描述文本的末尾添加自定义超链接。值得一提的是，如果你在标准的 fabric.mod.json 元数据中指定了 sources 联系方式，它也会自动包含在链接区域中。

links 对象中的任何键都会被添加到链接部分，且该键会被直接用作翻译键。例如：

文件：fabric.mod.json

"custom": {  
    "modmenu": {  
        "links": {  
          "modmenu.discord": "https://discord.gg/jEGF5fb"  
        }  
    }  
}  

上述代码将显示一个文本为“Discord”的链接，因为“Discord”是 Mod Menu 提供的 modmenu.discord 的英文翻译。

Mod Menu 内置了一些默认的链接翻译键，通常遵循 modmenu.<type> 的格式。你可以查阅 Mod Menu 的语言文件以获取完整列表。

如果你希望添加自定义链接，也可以提供自己的翻译。对于任何自定义键，请务必使用你自己的命名空间（而不是 modmenu），以避免冲突。

父级关系 ("parent": "mod_id" or { })

父级关系用于将一个模组显示为另一个模组的子模组。这通常用于将拆分为多个模块的模组进行归类。

以下示例将当前模组定义为模组 'flamingo' 的子模组：

文件：fabric.mod.json

"custom": {  
    "modmenu": {  
        "parent": "flamingo"  
    }  
}  

此外，如果你想将多个模组归类在一个父级下，但这个父级本身并不是一个真实存在的模组，你也可以通过定义虚拟父级来实现。如下例所示，一个模组定义了父级的元数据。请确保所有使用这个虚假/虚拟父级的子模组都包含这份元数据。若存在真实的父级模组，这些元数据将作为备选方案，会被真实模组的元数据覆盖。

文件：fabric.mod.json

"custom": {  
    "modmenu": {  
        "parent": {  
            "id": "this-mod-isnt-real",  
            "name": "Fake Mod",  
            "description": "Do cool stuff with this fake mod",  
            "icon": "assets/real-mod/fake-mod-icon.png",  
            "badges": [ "library" ]  
        }  
    }  
}  

虚拟父级模组仅支持以下元数据字段：

• id (字符串)
• name (字符串)
• description (字符串)
• icon (字符串)
• badges (字符串数组)

禁用更新检查器 ("update_checker": false)

默认情况下，Mod Menu 的更新检查器会利用你模组 JAR 文件的哈希值在 Modrinth 上查找最新版本。如果找到匹配的项目，它会进一步检查是否存在支持当前模组加载器和 Minecraft 版本的更新。如果新文件的哈希值与当前文件不同，它将提示用户进行更新。

如果你希望禁用此功能，可以在 Mod Menu 元数据中将 update_checker 设置为 false：

文件：fabric.mod.json

"custom": {  
    "modmenu": {  
        "update_checker": false  
    }  
}  

Quilt 元数据 API (Quilt Metadata API)

鉴于 Mod Menu 同样支持 Quilt 加载器，上一节 Fabric 元数据 API 中提到的所有功能同样适用于 Quilt 模组，但在自定义元数据的格式上存在细微差别。

在 Quilt 中，你不需要将 "modmenu" 块放置在 "custom" 块内，而是将其直接作为根对象的一个元素。结构如下：

文件：quilt.mod.json

{  
  ...  
  "modmenu": {  
    // 在此处放置你的链接、徽章等配置信息  
  }  
}  

Java API

若要利用 Java API 进行开发，你需要在 Gradle 项目中将 Mod Menu 添加为编译时依赖。这并不会强制你的模组在运行时依赖 Mod Menu，但能确保你在开发环境中可以使用它进行测试。

文件：build.gradle

// 在 repositories 块中添加 Terraformers Maven 仓库  
repositories {  
  maven {  
    name = "Terraformers"  
    url = "https://maven.terraformersmc.com/"  
  }  
}  

// 在 dependencies 块中添加 Mod Menu 作为环境依赖  
dependencies {  
  // 对于 Minecraft 1.20.6 之前的版本，请使用 "modImplementation"  
  implementation("com.terraformersmc:modmenu:${project.modmenu_version}")  
}  

接着，请在 gradle.properties 文件中定义你所使用的 Mod Menu 版本。建议查阅官方版本列表获取最新的版本号；请注意，如果你未使用最新版 Minecraft，可能需要选择对应的旧版 Mod Menu。

文件：gradle.properties

modmenu_version=VERSION_NUMBER_HERE  

提示：如果你不希望在测试环境中加载 Mod Menu，但仍需编译支持 Java API 的代码，可以使用 modCompileOnly 替代 modImplementation（即使 Mod Menu 未更新至你当前运行的 Minecraft 版本，此方法依然有效）。

以此开始 (Getting Started)

要开始使用 API，你需要在一个类上实现 ModMenuApi 接口，并在 fabric.mod.json 中将其添加为类型为 "modmenu" 的入口点（entry point）：

文件：fabric.mod.json

"entrypoints": {  
  "modmenu": [ "com.example.mod.ExampleModMenuApiImpl" ]  
}  

模组配置屏幕 (Mod Config Screens)

模组可以提供一个屏幕工厂（Screen Factory），以便在用户点击配置按钮时打开自定义的配置界面。为此，请在你的 API 实现类中重写 getModConfigScreenFactory 方法。

此功能的预期用途是让模组能够提供其自身的配置界面。配置屏幕的模组 ID 将由可以自动确定该入口点来源的模组容器决定。

提供的外部配置屏幕 (Provided Config Screens)

模组不仅可以为自己，还可以为其他模组提供屏幕工厂，以便通过配置按钮打开。为此，请在你的 API 实现类中重写 getProvidedConfigScreenFactories 方法。

此功能的典型应用场景是像 Cloth Config 这样的模组，它需要为那些使用了其 API 的其他模组提供配置界面。

整合包徽章 (Modpack Badges)

模组可以通过实现 attachModpackBadges 方法，赋予其他模组 Modpack（整合包）徽章。示例如下：

@Override  
public void attachModpackBadges(Consumer<String> consumer) {  
  consumer.accept("modmenu"); // 声明 'modmenu' 是该整合包的一部分  
}  

请注意，“内部”模组（如 Minecraft 本体和模组加载器）无法被赋予整合包徽章，因为它们通常不包含在常规的整合包分发文件中。

静态辅助方法 (Static Helper Methods)

ModMenuApi 还提供了一些便捷的静态辅助方法，方便那些希望与 Mod Menu进行更好集成的模组使用，例如创建自定义的“模组”按钮。

创建模组屏幕实例

调用此方法可直接获取模组列表屏幕的实例：

Screen createModsScreen(Screen previous)  

获取模组按钮文本

调用此方法可获取 Mod Menu 风格的“模组”按钮上应显示的文本内容：

Text createModsButtonText()