服务端接口 - 插件
API 包 路径: mcdreforged.api.types
- class mcdreforged.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) None[源代码]
为当前插件注册一个指令
- 参数:
root_node – 指令树的根节点。 它应为一个
Literal节点
- PluginServerInterface.register_help_message(prefix: str, message: str | RTextBase | Dict[str, str | RTextBase], permission: int = 0) None[源代码]
为当前插件注册一个帮助信息，以在
!!help指令中显示- 参数:
prefix – 你的插件的帮助指令。当玩家点击显示的信息时，会向玩家提示这个前缀参数。建议将其设置为你的插件的入口指令
message – 一个整洁的指令描述。它可以为一个 str 或者
RText。除此之外它还可为一个将语言映射至描述信息的 dictpermission – 用户看到此帮助信息的最低权限。在默认参数的情况下，任何人都可以看到此信息
插件工具
- 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 – 如果插件并非是一个多文件插件（换句话来讲，是一个单文件插件）
- PluginServerInterface.load_config_simple(file_name: str = 'config.json', default_config: Optional = None, *, in_data_folder: bool = True, echo_in_console: bool = True, source_to_reply: CommandSource | None = None, target_class: Type[SerializableType] | None = None, encoding: str = 'utf8', file_format: Literal['json', 'yaml'] | None = None, failure_policy: Literal['regen', 'raise'] = 'regen') dict | SerializableType[源代码]
一个简单的，从一个 json 文件中载入一个 dict 或
Serializable类型的配置文件的方法支持默认配置文件。加载的配置中缺失的键-值对将会使用默认配置文件填充
例 1:
config = { 'settingA': 1 'settingB': '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): settingA: int = 1 settingB: str = 'xyz' config: Config def on_load(server: PluginServerInterface, prev_module): global config 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的类。当被指定时，加载的配置文件数据将会被反序列化为一个 target_class 的实例并令其作为方法的返回值encoding – 读取配置文件的编码方式。默认值
"utf8"file_format – 配置文件的语法格式。默认值：
None，意味着 MCDR 将尝试基于配置文件的名字来推断格式failure_policy – 用于处理配置文件加载失败错误的策略。
"regen"（默认值）：尝试重新生成配置文件；"raise": 直接抛出相关异常
- 返回:
一个储存着加载并处理后的配置文件的 dict
在 v2.2.0 版本加入: encoding 参数
在 v2.12.0 版本加入: failure_policy 和 file_format 参数
- PluginServerInterface.save_config_simple(config: dict | Serializable, file_name: str = 'config.json', *, in_data_folder: bool = True, encoding: str = 'utf8', file_format: Literal['json', 'yaml'] | None = None) None[源代码]
一个简单的，将一个 dict 或
Serializable配置文件保存至 json 文件的方法- 参数:
config – 将要被保存的配置文件实例
file_name – 配置文件的文件名。它也可为配置文件的路径
- 关键字参数:
in_data_folder – 如果被设置为 True，则操作配置文件时的路径将为该插件的
数据文件夹中encoding – 写入配置文件的编码方式。默认值
"utf8"file_format – 配置文件的语法格式。默认值：
None，意味着 MCDR 将尝试基于配置文件的名字来推断格式
在 v2.2.0 版本加入: encoding 参数
在 v2.12.0 版本加入: file_format 参数