插件中繼資料

添加插件的元数据(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 的依赖项目均为硬性依赖;缺失这些依赖会导致插件不能加载。

備註

对于 authorsdependencies 两个属性来说,花括号可以在只有一个元素的情况下省略不写,比如上文示例中的 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 才能正确生成。