插件中繼資料

添加插件的元数据（Metadata）可以通过给予他们在运行时检查插件的名称、版本、描述、甚至插件的作者的能力帮助用户更容易地识别你的插件。插件的元数据也会用在一些发布插件的地方比如 Ore 。

目前，Sponge 支持以下类型的插件的元数据︰

插件 ID、插件名称、以及版本
說明
網址（例如：網站）
開發者：
插件依赖

插件注解

你可以为你的插件的 @Plugin 注解提供额外（非必须）的元数据。尽管只有 id 是必填项，你仍然可以显式指定所有的信息。一个使用了 @Plugin 中所有的字段的注解看起来像是这样：

import org.spongepowered.api.plugin.Plugin;

@Plugin(id = "myplugin", name = "My Plugin", version = "1.0",
    description = "This is a very cool plugin I made for me",
    url = "http://example.com",
    authors = {"Spongie", "FLARD"},
    dependencies = {@Dependency(id = "otherplugin", optional = true)})

你指定的每一个 @Dependency 都可以带有符合 Dependency#version() 说明的指定适用版本范围 version 属性。此外，optional 属性代表插件在缺失此依赖项目时也能加载。默认，不明确指定为 optional 的依赖项目均为硬性依赖；缺失这些依赖会导致插件不能加载。

備註

对于 authors 和 dependencies 两个属性来说，花括号可以在只有一个元素的情况下省略不写，比如上文示例中的 dependencies = @Dependency(id = "otherplugin", optional = true)。

檔案中繼資料

对于插件注解中额外添加的元数据，我们也同时建议在 JAR 的一个额外的文件中包含元数据，这样的优点有：

易于在构建系统中集成（例如在构建系统中添加版本进插件的元数据）
易于用于发布插件的网站识别（不需要解析插件的字节码文件）

備註

我们强烈建议在对外公开的插件中包含文件元数据 。一些插件托管平台（如 Ore ）需要文件元数据。有关生成它的简单方法，请参见使用注解处理器这一部分。如果插件缺少文件元数据，在某些场合可能会打印警告。

mcmod.info類型

对于 Sponge 插件来说，我们使用一个名为 mcmod.info 的文件，它位于插件 JAR 的根目录中。该格式起源于 Forge 并已被 Minecraft 社区中的多个项目使用，因此我们选择使用它。

mcmod.info 基本上是一个非常简单的 JSON 文件，它将插件元数据定义为若干简单的字段。下面是一个可以供 Sponge 插件使用的示例文件：

[{
    "modid": "myplugin",
    "name": "My Plugin",
    "version": "1.0",
    "description": "This is a very cool plugin I made for me",
    "authorList": [
        "Spongie",
        "FLARD"
    ],
    "dependencies": [
        "otherplugin"
    ]
}]

使用注解处理器

多一个文件等于多一份维护工作；但幸运的是，你大可不必为此头疼。SpongeAPI 能在编译期根据你在 @Plugin 注解中提供的信息自动生成这个文件。

啟用

如果你使用一个构建系统，如 Gradle 或 Maven 等，同时你并没有声明禁用注解处理器，那么你什么都不用做。默认情况下，注解处理器将自动运行并基于 @Plugin 注解的内容生成一个 mcmod.info 文件。

如果你没有在使用构建系统的话，那么你需要手动启用注解处理器。

构建系统兼容

如果你使用 Gradle ，那么 SpongeGradle 将提供针对 Gradle 和插件元数据的额外集成。例如它会自动将 Gradle 构建脚本中定义的项目版本包含在插件元数据中。请参阅設定 Gradle 以进一步了解相关内容。

備註

如果你使用 NetBeans IDE，请确认你取消勾选了 Project Properties > Build > Compile 菜单下的 Compile On Save 的选项，这样 mcmod.info 才能正确生成。