元数据

声明元数据

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

下面是一个元数据例子：

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

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

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

下面是一个例子：

{
    "schema_version": 1,
    "id": "example_plugin",
    "version": "1.0.0",
    "name": "Example Plugin",
    "description": "Example plugin for MCDR",
    "authors": [
        {"name": "Fallen_Breath"}
    ],
    "links": {
        "source": "https://github.com/MCDReforged/MCDReforged-ExamplePlugin"
    },
    "dependencies": {
        "mcdreforged": ">=2.16.0"
    }
}

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

对于多文件插件，元数据文件必须存在，其 id、version 字段也都是必须的

小技巧

对于 Python 包依赖，建议将它们声明在名为 requirements.txt 的文件中，然后把它打包进你的打包插件中

属性

schema_version

mcdreforged.plugin.json 的格式版本。对于 v2.16.0 中引入的格式，请使用 1。省略此字段表示版本为 0，该版本仍受支持。如果版本比 MCDR 所支持的更新，MCDR 将会发出警告，并尝试读取其中已知的字段

此字段不能替代插件的 version，也不能替代其对 mcdreforged 的依赖要求

注意

仅用于 mcdreforged.plugin.json，不适用于单文件插件的元数据

在 v2.16.0 版本加入.

字段键名：schema_version
字段类型：int
备用值：0

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

自 v2.16.0 版本弃用: 请使用 authors 作为替代。此字段仍然受支持。当同时提供这两个字段时，author 中的名字会被追加到 authors 中，且不会去重

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

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

字段键名：author
字段类型：str 或 list[str]
备用值：None

authors

插件的原作者和主要创作者。每个人可以是一个包含其名字的字符串，也可以是一个 dict——其中 name 为必需字段，email 和 homepage 为可选的字符串字段。你可以只提供一个人，也可以提供一个由人组成的列表，并在其中混合使用字符串和 dict

'authors': [
    'Alice',
    {
        'name': 'Bob',
        'email': 'bob@example.com',
        'homepage': 'https://example.com/bob',
    }
]

在 v2.16.0 版本加入.

字段键名：authors
字段类型：str 或 Dict[str, str] 或 List[Union[str, Dict[str, str]]]
备用值：None

maintainers

当前维护该插件的人。此字段的格式与 authors 相同

在 v2.16.0 版本加入.

字段键名：maintainers
字段类型：str 或 Dict[str, str] 或 List[Union[str, Dict[str, str]]]
备用值：None

link

自 v2.16.0 版本弃用: 请使用 links 作为替代。此字段仍然受支持。当 links.homepage 缺失或为 None 时，本字段的值将作为 links.homepage 使用

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

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

字段键名：link
字段类型：str
备用值：None

links

与插件相关的链接。以下所有键都是可选的：

homepage：插件主页
source：源代码仓库
documentation：文档页面
issues：问题追踪页面

'links': {
    'homepage': 'https://example.com',
    'source': 'https://github.com/example/my_plugin',
    'issues': 'https://github.com/example/my_plugin/issues'
}

在 v2.16.0 版本加入.

字段键名：links
字段类型：Dict[str, Optional[str]]
备用值：None

license

插件的许可证。推荐使用 SPDX 许可证标识符，例如 LGPL-3.0

在 v2.16.0 版本加入.

字段键名：license
字段类型：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，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，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

requirements_file

多文件插件内部的 Python 依赖文件。此字段决定了哪个文件会被用于依赖检查、打包和 Python 依赖安装：

如果省略，则当 requirements.txt 存在时，MCDR 会使用它
如果在 JSON 中设为 null``（在 Python 中为 ``None），则不使用任何依赖文件
如果设为一个字符串，则该文件必须存在，即使其值为 "requirements.txt"

该路径相对于插件根目录，且必须位于插件根目录之内。不允许使用绝对路径，也不允许包含 .. 路径片段。例如，"requirements_file": "deps/runtime.txt" 会选中插件 deps 目录中的一个文件

注意

在单文件插件中不可用

在 v2.16.0 版本加入.

字段键名：requirements_file
字段类型：str 或 None
备用值：如果 requirements.txt 存在，则自动使用它

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