服务端接口 - 插件

API 包路径: mcdreforged.api.types

class mcdreforged.plugin.si.plugin_server_interface.PluginServerInterface(mcdr_server: MCDReforgedServer, plugin: AbstractPlugin)[源代码]: 从 ServerInterface 中派生，PluginServerInterface 在 ServerInterface 的基础上为插件添加了控制插件自己的能力

插件注册

PluginServerInterface.register_event_listener(event: PluginEvent | str, callback: Callable, priority: int | None = None) → None[源代码]

为当前插件注册一个事件监听器

参数:

event -- 事件的 ID，或 PluginEvent 实例。它表示插件要监听的目标事件
callback -- 事件的回调的监听器方法
priority -- 监听器的优先级。如果没有指定，将被设置为默认值 1000

PluginServerInterface.register_command(root_node: Literal, *, allow_duplicates: bool = False) → None[源代码]

为当前插件注册一个命令

参数:: root_node -- 命令树的根节点。它应为一个 Literal 节点
关键字参数:: allow_duplicates -- 若设置为 False（默认值），则将在发现重复的命令根节点时输出警告信息。若设置为 True，将不会输出警告，和以前版本的表现一致

在 v2.13.0 版本加入: allow_duplicates 参数

PluginServerInterface.register_help_message(prefix: str, message: str | RTextBase | Mapping[str, str | RTextBase], permission: int = 0) → None[源代码]

为当前插件注册一个帮助信息，以在 !!help 命令中显示

参数:

prefix -- 你的插件的帮助命令。当玩家点击显示的信息时，会向玩家提示这个前缀参数。建议将其设置为你的插件的入口命令
message -- 一个整洁的命令描述。它可以为一个 str 或者 RText。除此之外它还可为一个将语言映射至描述信息的 dict
permission -- 用户看到此帮助信息的最低权限。在默认参数的情况下，任何人都可以看到此信息

PluginServerInterface.register_translation(language: str, mapping: Mapping[str, str | TranslationKeyDictNested]) → None[源代码]

为当前插件注册给定语言的一个翻译映射表

参数:

language -- 该翻译的语言
mapping -- 一个将翻译键映射为翻译文本的 dict。翻译键可以被表示为根节点下的子节点名称，或嵌套的多层节点的路径。dict 可嵌套多层，路径为从根节点开始每一层节点的名称相连、通过 "." 分隔的 str

PluginServerInterface.register_server_handler(server_handler: ServerHandler)[源代码]

注册一个由插件提供的服务端解析处理器

该服务端解析处理器会在插件的生命周期内生效，将替代由 MCDR 配置文件指定的解析处理器

若多个插件都提供了服务端解析处理器，那么只有首个解析处理器会生效，并且 MCDR 将会输出警告信息

参数:: server_handler -- 将要注册的服务端解析处理器

在 v2.13.0 版本加入.

PluginServerInterface.register_info_filter(info_filter: InfoFilter)[源代码]

注册一个由插件提供的信息过滤器。见 InfoFilter 以了解更多信息

该信息过滤器会在插件的生命周期内生效

警告

信息过滤器的回调函数将在 MCDR 的主线程，而非任务执行者线程上被调用

请确保你的回调函数不会消耗太多时间，否则它可能会影响 MCDR 的性能。除此之外，注意多线程下的竞态问题

参数:: info_filter -- 将要注册的信息过滤器

在 v2.13.0 版本加入.

插件工具

PluginServerInterface.get_self_metadata() → Metadata[源代码]: 返回当前插件的元数据

PluginServerInterface.get_data_folder() → str[源代码]

为当前插件返回一个统一格式的数据文件夹

文件夹的路径将会为 "config/plugin_id"，其中 plugin_id 是当前插件的 id

例子:

with open(os.path.join(server.get_data_folder(), 'my_data.txt'), 'w') as file_handler:
        write_some_data(file_handler)

返回:: 返回数据文件夹的路径

PluginServerInterface.open_bundled_file(relative_file_path: str) → IO[bytes][源代码]

使用二进制只读模式，打开插件中的一个文件

例子:

with server.open_bundled_file('message.txt') as file_handler:
        message = file_handler.read().decode('utf8')
server.logger.info('A message from the file: {}'.format(message))

参数:: relative_file_path -- 你想要打开的文件位于你的插件中的相对位置
返回:: 一个未解码的，bytes 形式的文件型的对象
抛出:: FileNotFoundError -- 如果插件并非是一个多文件插件（换句话来讲，是一个单文件插件）

一个简单的，从一个 json 文件中载入一个 dict 或 Serializable 或 pydantic.BaseModel 类型的配置文件的方法

支持默认配置文件。加载的配置中缺失的键-值对将会使用默认配置文件填充

例 1:

config = {
        'setting_a': 1,
        'setting_b': 'xyz'
}
default_config = config.copy()

def on_load(server: PluginServerInterface, prev_module):
        global config
        config = server.load_config_simple('my_config.json', default_config)

例 2:

class Config(Serializable):
        setting_a: int = 1
        setting_b: str = 'xyz'

def on_load(server: PluginServerInterface, prev_module):
        config = server.load_config_simple(target_class=Config)

例 3:

from pydantic import BaseModel

class Config(BaseModel):
        setting_a: int = 1
        setting_b: str = 'xyz'

def on_load(server: PluginServerInterface, prev_module):
        config = server.load_config_simple(target_class=Config)

假设插件 id 为 my_plugin，此时配置文件将被储存于 "config/my_plugin/my_config.json" 中

参数:

file_name -- 配置文件的文件名。它也可为配置文件的路径
default_config -- 一个储存着默认配置的 dict。当配置文件缺失时，这个参数是必须的，否则将抛出异常。如果 target_class 被给出并且 default_config 缺失，则当配置文件缺失时 target_class 的默认值将会被使用

关键字参数:

in_data_folder -- 如果被设置为 True，则操作配置文件时的路径将为该插件的 数据文件夹 中
echo_in_console -- 是否在控制台中打印配置文件加载相关日志
source_to_reply -- 用于回复加载配置相关日志的命令源
target_class -- 一个派生自 Serializable 或 pydantic.BaseModel 的类。当被指定时，加载的配置文件数据将会被反序列化为一个 target_class 的实例并令其作为方法的返回值
encoding -- 读取配置文件的编码方式。默认值 "utf8"
file_format -- 配置文件的语法格式。默认值：None，意味着 MCDR 将尝试基于配置文件的名字来推断格式
failure_policy -- 用于处理配置文件加载失败错误的策略。"regen" （默认值）：尝试重新生成配置文件；"raise": 直接抛出相关异常
data_processor -- 一个回调函数，用于自定义处理从配置文件中读取的数据。它应仅接受一个参数，并返回一个 bool。参数是解析后的配置文件对象，返回值表示在是否应该在配置文件加载结束时写入新的配置文件数据。用例：插件升级后迁移配置文件的数据
pydantic_model_validate_kwargs -- 仅在 target_class 是一个 pydantic.BaseModel 的子类时会用到。传递给 pydantic.BaseModel.model_validate() 方法的额外 kwargs。若未提供，则使用 {'strict': True}

返回:

一个储存着加载并处理后的配置文件的 dict

在 v2.2.0 版本加入: encoding 参数

在 v2.12.0 版本加入: failure_policy 和 file_format 参数

在 v2.13.0 版本加入: data_processor 参数

在 v2.14.0 版本加入: pydantic.BaseModel 支持以及 pydantic_model_validate_kwargs 参数

一个简单的，将一个 dict 或 Serializable 配置文件保存至 json 文件的方法

参数:

config -- 将要被保存的配置文件实例
file_name -- 配置文件的文件名。它也可为配置文件的路径

关键字参数:

in_data_folder -- 如果被设置为 True，则操作配置文件时的路径将为该插件的 数据文件夹 中
encoding -- 写入配置文件的编码方式。默认值 "utf8"
file_format -- 配置文件的语法格式。默认值：None，意味着 MCDR 将尝试基于配置文件的名字来推断格式
pydantic_model_dump_kwargs -- 仅在 config 是一个 pydantic.BaseModel 时会用到。传递给 pydantic.BaseModel.model_dump() 方法的额外 kwargs。请注意，其 mode 总会被设置为 "json"

在 v2.2.0 版本加入: encoding 参数

在 v2.12.0 版本加入: file_format 参数

在 v2.14.0 版本加入: pydantic.BaseModel 支持以及 pydantic_model_dump_kwargs 参数