插件的元数据

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

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

  • 插件 ID、 插件名称、以及版本
  • 说明
  • URL(例如网站)
  • 作者
  • 插件依赖

插件注解

你可以在你的 @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))

文件元数据

对于插件注解中额外添加的元数据,我们也同时建议在 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 以进一步了解相关内容。