元数据

声明元数据

作为一个仅有单一 .py 文件组成的插件，单文件插件 的元数据声明于其源文件的全局作用域中。它是一个包含着多个键值对的，名为 PLUGIN_METADATA 的 dict 对象

以下是一个元数据字段，其中包含所有可能的键值

PLUGIN_METADATA = {
    'id': 'my_plugin_id',
    'version': '1.0.0',
    'name': 'My Plugin',
    'description': 'A plugin to do something cool',
    'author': 'myself',
    'link': 'https://github.com',
    'dependencies': {
        'mcdreforged': '>=1.0.0',
        'an_important_api': '*'
    }
}

下面的 属性 小节将会使用 python 语法进行元数据声明举例

---

对于多文件插件或者文件夹插件而言，元数据以 json 语法在文件 mcdreforged.plugin.json 中声明

下面是一个例子：

{
    "id": "example_plugin",
    "version": "1.0.0",
    "name": "Example Plugin",
    "description": "Example plugin for MCDR",
    "author": "Fallen_Breath",
    "link": "https://github.com/MCDReforged/MCDReforged-ExamplePlugin",
    "dependencies": {
        "mcdreforged": ">=2.0.0-alpha.1"
    }
}

如果插件未声明元数据字段，则控制台中将出现警告，并使用备用值

属性

id

ID（即插件 ID）是你插件的“身份证号”。它应由小写字母，数字和下划线组成，长度为 1 到 64

以下是一些可用的插件 ID：

• my_plugin

• anotherhelper123

• __a_cool_plugin__

但不允许使用以下ID：

• MyPlugin

• another-helper-123

• a cool plugin

MCDR 使用插件 ID 来区分不同的插件并检查插件间的依赖。 MCDR 中加载的所有插件都应使用不同的插件 ID。如果新加载的插件具有与现有插件完全相同的插件 ID，则新插件将无法加载

请明智地选择你的插件 ID。强烈建议你在发布插件后不要再更改插件 ID

注意

小心可能的包名冲突。非常不推荐为你的插件取一个与标准库 / 第三方库名相同的 id，如 test，否则 MCDR 很可能无法正确地加载你的插件

• 字段键名：id

• 字段类型：str

• 备用值：不含 .py 后缀的插件文件名，如果你的插件是一个单文件插件

version

version 字段代表你的插件版本。它基本上采用了 语义化版本 的格式，不过限制较少，如你可以定义任意长度的版本号

以下一些可用的版本：

• 1.0.0

• 2.0

• 1.2.3-pre4

• 1.8.9-rc.8

• 1.14.1-beta.4+build.54

遵循 语义化版本 格式为你的插件定义版本字符串是一个好主意——易于维护、易于理解

• 字段键名：version

• 字段类型：str

• 备用值：0.0.0

name

你的插件名称——给你的插件起一个好听的名字吧

尽量不要使插件名称太长。你可以把插件的详细信息放在 description 之中

• 字段键名：name

• 字段类型：str

• 备用值：插件 ID

description

你的插件描述。在这里写下你的插件的功能总结吧

此字段是可选的。如果你想偷懒的话可以不填写

处于翻译的目的，除了使用一个 str 作为值外，你还可以使用一个代表着从语言映射到描述文本的 Dict[str, str] 映射作为值，如：

"description": {
    "en_us": "My description in English",
    "zh_cn": "我的中文简介"
}

• 字段键名：description

• 字段类型：Union[str, Dict[str, str]]

• 备用值：None

author

插件作者。如果只有一个作者，可使用 string 而非 list

此字段是可选的。如果你想偷懒的话可以不填写

• 字段键名：author

• 字段类型：str 或 list[str]

• 备用值：None

link

你的插件的网址。你可以将其指向插件的 github 链接。它的值应为一个可访问的网址

此字段是可选的。如果你想偷懒的话可以不填写

• 字段键名：link

• 字段类型：str

• 备用值：None

dependencies

插件的依赖关系。应为一个字典，其中包含多个键值对。键为插件所依赖的插件 ID，值是插件所依赖插件的版本要求

如果你的插件对 MCDR 版本有需求，请使用 mcdreforged 作为插件 ID

版本要求是一个包含若干个版本约束的字符串。约束按空格划分，每个每个由一个运算符和一个基础版本字符串组成。描述基版本时允许使用通配符

运算符列表：

运算符	示例说明	示例说明	允许的值	不允许的值
>=	>=1.2.3	目标版本应大于等于 1.2.3	1.2.3，1.3.0	1.2.0
>	>1.2.3	目标版本应大于 1.2.3	1.2.4，1.3.0	1.2.0，1.2.3
<=	<=1.2.3	目标版本应小于等于 1.2.3	1.2.3，1.1.0	1.2.4，2.0.0
<	<1.2.3	目标版本应小于 1.2.3	1.1.0	1.2.3，1.5
=	=1.2.3	目标版本应等于 1.2.3	1.2.3	1.2，1.2.4
	1.2.3	如果未指定运算符，则默认使用 = 。在这种情况下，目标版本应等于1.2.3	1.2.3	1.2，1.2.4
^	^1.2.3	目标版本应大于等于 1.2.3，且目标版本的第一个版本分段应等于基版本	1.2.3，1.2.4，1.4.4	1.0.0，2.0.0
~	~1.2.3	目标版本应大于等于 1.2.3，并且目标版本的第一和第二版本分段应等于基版本	1.2.3，1.2.4	1.0.0，1.4.4，2.0.0

查看 此处(EN) 或 此处(中文) 以获取版本要求的更多详细信息

如果存在多个声明的条件，则仅当所有条件都接受目标版本时，才接受目标版本

这里是一个依赖关系示例：

'dependencies': {
   'mcdreforged': '>=1.0.0 <2.0',
   'my_library': '>=1.0.0',
   'an_important_api': '*',
   'another_api_1': '1.0.*',
   'another_api_2': '2.7.x',
}

MCDR 将确保仅在满足所有依赖项要求时，你的插件才能成功加载。依赖项缺失，依赖项版本不匹配或出现依赖环路，都会导致依赖关系检查失败

该字段是可选的，如果你的插件没有任何依赖关系，则可以忽略它

• 字段键名：dependencies

• 字段类型：Dict[str, str]

• 备用值：None

entrypoint

你的插件的 入口点 模块

在默认情况下，其值为你的插件的 id。这意味着 my_plugin/__init__.py 将会成为入口点。如果其值为 my_plugin.my_entry，那么 my_plugin/my_entry.py 将成为入口点

MCDR 会对入口点模块进行与单文件插件相同的操作，如默认事件监听器注册

注意

在单文件插件中不可用

• 字段键名：entrypoint

• 字段类型：str

• 备用值：插件 ID

archive_name

在 CLI 中生成的 .mcdr 打包插件的文件名

注意

在单文件插件中不可用

参见

命令行接口 中 pack 指令的 name 选项

• 字段键名：archive_name

• 字段类型：str

• 备用值：None

resources

一个文件或文件夹名称的列表，将用于在 CLI 中打包入 .mcdr 打包插件

注意

在单文件插件中不可用

参见

命令行接口 中的 pack

• 字段键名：resources

• 字段类型：List[str]

• 备用值：None