服务端接口 - 通用

API 包路径: mcdreforged.api.types

class mcdreforged.plugin.si.server_interface.ServerInterface(mcdr_server: MCDReforgedServer)[源代码]

ServerInterface 是插件与服务端交互的接口，包含许多 API。它的子类 PluginServerInterface 包含了额外的让插件控制插件自己的 API

建议使用 server 作为 ServerInterface 变量的名字，这在本文档中被广泛使用

实例获取

classmethod ServerInterface.get_instance() → ServerInterface | None[源代码]: 一个类方法，用于为插件在任何地方获取一个 ServerInterface 实例，只要 MCDR 正在运行

ServerInterface.as_basic_server_interface() → ServerInterface[源代码]

返回一个 ServerInterface 实例。返回值的类型是 ServerInterface

它可用于在你想要传递一个 ServerInterface 时，移除 ServerInterface 中包含着的插件信息

ServerInterface.as_plugin_server_interface() → PluginServerInterface | None[源代码]

返回一个 PluginServerInterface 实例

如果该对象就是一个 PluginServerInterface 实例，则直接返回它自己

如果当前存在可用的插件上下文，返回相关插件对应的 PluginServerInterface。目前，插件上下文仅在如下场景中可用：

入口点模块的加载
事件监听器回调函数的调用
命令回调函数的调用

classmethod ServerInterface.si() → ServerInterface[源代码]

get_instance() 的别名 / 缩写，永不返回 None

抛出:: RuntimeError -- 如果 MCDR 未在运行

classmethod ServerInterface.si_opt() → ServerInterface | None[源代码]

get_instance() 的别名 / 缩写，返回一个可能存在的 ServerInterface 实例

返回:: ServerInterface 实例。如果失败则为 None

classmethod ServerInterface.psi() → PluginServerInterface[源代码]

组合 get_instance() + as_plugin_server_interface() 的缩写，永不返回 None

抛出:: RuntimeError -- 获取 PluginServerInterface 失败。原因可能是 MCDR 未在运行（见 si()），或者插件上下文不可用（见 as_plugin_server_interface()）

classmethod ServerInterface.psi_opt() → PluginServerInterface | None[源代码]

组合 get_instance() + as_plugin_server_interface() 的缩写，返回一个可能存在的 PluginServerInterface 实例

返回:: 当前插件的 PluginServerInterface 实例。如果失败则为 None

实用工具

ServerInterface.MCDR = True: MCDR 的标识符属性

property ServerInterface.logger: Logger: 一个好用的将信息记录到控制台的 logger

ServerInterface.tr(translation_key: str, *args, _mcdr_tr_language: str | None = None, **kwargs) → str | RTextBase[源代码]

返回一个代表着翻译键的翻译文本，并使用提供的 args 及 kwargs 进行格式化

如果 args 或者 kwargs 包含 RText 元素，则结果将为一个 RText，否则结果将是一个 str

如果翻译键未被识别，返回值将为翻译键本身

见此处以了解为你的插件注册翻译的方法

参数:

translation_key -- 翻译键
args -- 用于格式化的参数（args）
_mcdr_tr_language -- 指定在该次翻译中使用的语言。若未指定，则使用 MCDR 所使用的语言
kwargs -- 用于格式化的关键字参数（kwargs）

ServerInterface.rtr(translation_key: str, *args, **kwargs) → RTextMCDRTranslation[源代码]

返回一个 RTextMCDRTranslation 组件。它仅在被显示或被序列化前进行翻译

使用这一个方法而不是 tr() 可以让你自动地使用用户的偏好语言展示你的文本

当然如果你愿意的话，除了使用该方法，你也可以自己手动构建 RTextMCDRTranslation

参数:

translation_key -- 翻译键
args -- 用于格式化的参数（args）
kwargs -- 用于格式化的关键字参数（kwargs）

在 v2.1.0 版本加入.

ServerInterface.has_translation(translation_key: str, *, language: str | None = None, no_auto_fallback: bool = False)[源代码]

检查给定的翻译是否存在

请注意，如果当前语言翻译失败，MCDR 将尝试使用"en_us"进行重试。如果你不希望有这种自动重试行为，请将参数 no_auto_fallback 设置为 True

值得注意，你不需要把传递与这个翻译相关的 *args 和 **kwargs 传给这个方法，因为存在性检查不需要它俩

参数:

translation_key -- 翻译键

关键字参数:

language -- 可选参数，用于检查翻译是否存在时使用的语言
no_auto_fallback -- 当设置为 True 时，如果翻译失败，MCDR 不会使用"en_us"进行第二次尝试

在 v2.12.0 版本加入.

服务端控制

ServerInterface.start() → bool[源代码]

启动服务端，并返回启动情况

如果服务端正在运行或正在由其他插件启动，它将返回 False

返回:: 操作是否成功。若服务端已启动，或者服务端因命令错误或 MCDR 状态无法启动，操作将会失败

ServerInterface.stop() → bool[源代码]

通过向服务端发送其对应的关闭命令来软停止服务端

此操作不会关闭 MCDR。MCDR 会继续运行，除非 exit() 被调用

返回:: 操作是否成功。若服务端已停止，操作将会失败

ServerInterface.kill() → bool[源代码]

杀死整个服务端进程组，即硬停止服务端

MCDR 会继续运行，除非 exit() 被调用

返回:: 操作是否成功。若服务端已停止，操作将会失败

ServerInterface.wait_until_stop() → None[源代码]: 等待，直到服务端停止

备注

当前线程将被阻塞

ServerInterface.wait_for_start() → None[源代码]

等待，直到到服务端能够被启动

事实上，这是 wait_until_stop() 的一个别名

ServerInterface.restart() → bool[源代码]

重新启动服务端

它首先会 软停止 服务端，然后 等 到服务端完全停止后，再 启动 服务端

返回:: 操作是否成功。若服务端已停止，操作将会失败

ServerInterface.stop_exit() → bool[源代码]

软停止 服务端并退出 MCDR

返回:: 操作是否成功。若服务端已停止，操作将会失败

ServerInterface.exit() → bool[源代码]

当服务端停止时，退出 MCDR

它跟直接使用参数 True 调用 set_exit_after_stop_flag() 是一样的，不过这个方法还会帮你做一次服务端未在运行的检测

示例用法：

server.stop()  # Stop the server
# do something A
server.wait_for_start()  # Make sure the server is fully stopped. It's necessary to run it in your custom thread
# do something B
server.exit()  # Exit MCDR

返回:: 操作是否成功。若服务端仍在运行，操作将会失败

ServerInterface.set_exit_after_stop_flag(flag_value: bool) → None[源代码]

设置用于指示 MCDR 在服务端停止时是否应退出的标志

如果设置为 True，MCDR 将在服务端停止后退出，否则（设置为 False 时）MCDR 将继续运行

当服务端启动时，该标志将被设置为 True

该标志值的值也会在命令 !!MCDR status 的第 5 行中显示

ServerInterface.is_server_running() → bool[源代码]: 服务端是否正在运行

ServerInterface.is_server_startup() → bool[源代码]: 服务端是否已经启动

ServerInterface.is_rcon_running() → bool[源代码]: MCDR 的 RCON 服务是否正在运行

ServerInterface.get_server_pid() → int | None[源代码]

返回服务端进程的 pid，如果服务端已经停止，则返回 None

注意，这个 pid 对应的是一个 bash 进程，它是真实服务端进程的父进程

返回:: 返回服务端进程的 pid，如果服务端已经停止，则返回 None

ServerInterface.get_server_pid_all() → List[int][源代码]

返回一个储存了服务端进程组内所有进程的 pid 的列表

返回:: 一个 pid 列表。如果服务端已经停止，或者 pid 查询失败，则这个列表将为空

在 v2.6.0 版本加入.

ServerInterface.get_server_information() → ServerInformation[源代码]

返回一个基于服务端输出推断得到的，储存着当前服务端的信息的 ServerInformation 对象

如果服务端未启动，或者相关的信息未被解析，则其若干个属性可能为 None

在 v2.1.0 版本加入.

文本交互

ServerInterface.execute(text: str, *, encoding: str | None = None) → None[源代码]

通过将命令内容发送到服务端的标准输入流来执行服务端命令

参见

方法 execute_command()，如果你想要在 MCDR 的命令系统中执行命令

参数:: text -- 你要发送的命令内容
关键字参数:: encoding -- 文本的编码方法。留空以使用 MCDR 配置文件中的编码方法

ServerInterface.tell(player: str, text: str | RTextBase, *, encoding: str | None = None) → None[源代码]

使用 /tellraw 等命令向特定玩家发送消息

参数:

player -- 目标玩家的名字
text -- 你想发送的信息

关键字参数:

encoding -- 文本的编码方法。留空以使用 MCDR 配置文件中的编码方法

ServerInterface.say(text: str | RTextBase, *, encoding: str | None = None) → None[源代码]

使用 /tellraw @a 等命令在游戏中广播消息

参数:: text -- 你要发送的消息
关键字参数:: encoding -- 文本的编码方法。留空以使用 MCDR 配置文件中的编码方法

ServerInterface.broadcast(text: str | RTextBase, *, encoding: str | None = None) → None[源代码]

在游戏和控制台中广播消息

若服务端未在运行，则仅向控制台发送消息

参数:: text -- 你要发送的消息
关键字参数:: encoding -- 文本的编码方法。留空以使用 MCDR 配置文件中的编码方法

ServerInterface.reply(info: Info, text: str | RTextBase, *, encoding: str | None = None, console_text: str | RTextBase | None = None)[源代码]

对信息源的答复

如果 Info 来自玩家，那么使用 tell 方法来回复玩家；如果 Info 来自控制台，则使用 server.logger.info 来输出到控制台；在其他情况下，Info 不是来自用户，抛出 IllegalCallError

参数:

info -- 你要回复的 Info 目标
text -- 你要发送的消息

关键字参数:

encoding -- 文本的编码方法
console_text -- 如果指定了该参数，那么在回复控制台时，将使用 console_text 来代替

抛出:

IllegalCallError -- 如果这个 Info 并非来自一位用户

插件查询

ServerInterface.get_plugin_metadata(plugin_id: str) → Metadata | None[源代码]

返回指定插件的元数据。若插件不存在，则返回 None

参数:: plugin_id -- 要查询元数据的插件的 ID

ServerInterface.get_plugin_type(plugin_id: str) → PluginType | None[源代码]

返回指定插件的种类。若插件不存在，则返回 None

参数:: plugin_id -- 要查询种类的插件的 ID

在 v2.13.0 版本加入.

ServerInterface.get_plugin_file_path(plugin_id: str) → str | None[源代码]

返回指定插件的文件路径。若插件不存在，则返回 None

参数:: plugin_id -- 要查询文件路径的插件的 ID

ServerInterface.is_plugin_file_changed(plugin_id: str) → bool | None[源代码]

返回指定插件的文件是否有变化。若插件不存在，则返回 None

注意：文件夹插件的插件文件总被认为是有变化的

参数:: plugin_id -- 要查询文件是否有变化的插件的 ID

在 v2.13.0 版本加入.

ServerInterface.get_plugin_instance(plugin_id: str) → Any | None[源代码]

返回指定插件的入口点。若插件不存在，则返回 None

如果目标插件是一个单文件插件且需要对 MCDR 的事件做出反应，那么请使用这个功能而不是手动导入（import）你想要的插件。这是因为这个 API 是唯一能让你的插件获得与 MCDR 所使用的插件实例相同的方法

示例用法：

我的一个插件 id 为 my_api 的 API 插件的入口点模块
def some_api(item):
        pass
另一个需要我的 API 插件的插件
server.get_plugin_instance('my_api').some_api(an_item)

参数:: plugin_id -- 要获取入口点模块实例的插件 ID
返回:: 返回指定插件的入口点。若插件不存在，则返回 None

ServerInterface.get_plugin_list() → List[str][源代码]: 返回一个包含所有 已加载 插件的 ID 列表，例如：["my_plugin_id", "another_plugin_id"]

ServerInterface.get_unloaded_plugin_list() → List[str][源代码]: 返回一个包含所有 未加载 插件的文件路径列表，例如：["plugins/MyPlugin.mcdr"]

在 v2.3.0 版本加入.

ServerInterface.get_disabled_plugin_list() → List[str][源代码]: 返回一个包含所有 被禁用 插件的文件路径列表，例如：["plugins/MyPlugin.mcdr.disabled"]

在 v2.3.0 版本加入.

ServerInterface.get_all_metadata() → Dict[str, Metadata][源代码]: 返回一个包含所有加载的插件元数据的字典，键值对为 (插件 id, 元数据)

插件操作

警告

所有的插件操作都会触发依赖性检查——这可能会导致不必要的插件操作

不推荐在插件事件插件被加载或插件被卸载期间进行插件操作在这些事件发生时，MCDR 正处于一次进行中的插件操作流程之中，此时并不适合触发另一次插件操作

如果你确实在插件事件插件被加载或插件被卸载期间进行了插件操作，MCDR 将会延迟这些插件操作的执行至首个插件操作结束。对于这种延后执行的情况，下述 API 的返回值将总会是 false 或 None

ServerInterface.load_plugin(plugin_file_path: str) → bool[源代码]

从给定的文件路径加载一个插件

参数:: plugin_file_path -- 要加载插件的文件路径。例如："plugins/my_plugin.py"
返回:: 从给定的文件路径加载一个插件

ServerInterface.enable_plugin(plugin_file_path: str) → bool[源代码]

从给定的文件路径启用一个被禁用的插件

参数:: plugin_file_path -- 要启用插件的文件路径。例如："plugin/my_plugin.py.disabled"
返回:: 插件是否被成功启用

ServerInterface.reload_plugin(plugin_id: str) → bool | None[源代码]

重载一个由插件 ID 给定的插件

参数:: plugin_id -- 要重新加载的插件的 ID。例如："my_plugin"
返回:: 返回一个 bool 表示插件是否被成功重载，若插件不存在则返回 None

ServerInterface.unload_plugin(plugin_id: str) → bool | None[源代码]

卸载一个由插件 ID 给定的插件

参数:: plugin_id -- 要卸载的插件的 ID。例如："my_plugin"
返回:: 返回一个 bool 表示插件是否被成功卸载，若插件不存在则返回 None

ServerInterface.disable_plugin(plugin_id: str) → bool | None[源代码]

禁用一个由插件 ID 给定的插件

参数:: plugin_id -- 要禁用的插件的 ID。例如："my_plugin"
返回:: 并返回一个 bool 表示插件是否被成功禁用，若插件不存在则返回 None

ServerInterface.refresh_all_plugins() → None[源代码]: 重新加载所有插件，加载所有新插件，并卸载所有被删除的插件

ServerInterface.refresh_changed_plugins() → None[源代码]: 重新加载所有 更改过 的插件，加载所有新插件，并卸载所有删除的插件

一个高可自定义的插件操作 API，提供了对要操作内容的细粒度控制方式：在单一操作中，加载 / 卸载 / 重载 / 启用 / 禁用给定的插件

小技巧

下面是一些不同的插件“重载”场景，以及对应的建议操作方式

MyPlugin.mcdr 文件保持不变：重载 my_plugin
MyPlugin.mcdr 文件内容发生了变化：重载 my_plugin
MyPlugin.mcdr 被一个新的 MyPlugin_v2.mcdr 所取代了：在单次调用中，卸载 my_plugin 并加载 MyPlugin_v2.mcdr

参数:

load -- 一个可选的插件 文件路径 列表，包含将要被加载的插件
unload -- 一个可选的插件 ID 列表，包含将要被加载的插件
reload -- 一个可选的插件 ID 列表，包含将要被重载的插件
enable -- 一个可选的插件 文件路径 列表，包含将要被启用的插件
disable -- 一个可选的插件 ID 列表，包含将要被禁用的插件

返回:

如果所有操作成功则返回 True；如果存在失败则返回 False；如果当前调用栈中出现了链式插件操作，则返回 None

在 v2.13.0 版本加入.

ServerInterface.dispatch_event(event: PluginEvent, args: Tuple[Any, ...], *, on_executor_thread: bool = True) → None[源代码]

向所有加载的插件分发事件

如果该事件在任务执行者线程上，则会被立即触发。如果在其他线程上，则会被入队等候 (enqueued)

备注

你不能分发与任何一个 MCDR 内置事件拥有相同事件 ID 的事件

示例

对于分发事件的插件:

server.dispatch_event(LiteralEvent('my_plugin.my_event'), (1, 'a'))

对于监听事件的插件:

def do_something(server: PluginServerInterface, int_data: int, str_data: str):
        pass

server.register_event_listener('my_plugin.my_event', do_something)

参数:

event -- 要分发的事件。它必须是一个 PluginEvent 实例。为了更简单地使用，你可以为这个参数创建一个 LiteralEvent 实例
args -- 用于调用事件监听器的参数。一个 PluginServerInterface 实例将被自动添加到参数列表的开头

关键字参数:

on_executor_thread -- 在默认值的情况下，该事件会被派发至任务执行者 (TaskExecutor) 线程中分发。如果它被设置为 False，则事件将会被立即分发

配置

ServerInterface.get_mcdr_language() → str[源代码]: 返回 MCDR 当前使用的语言

ServerInterface.get_mcdr_config() → dict[源代码]: 返回一个 dict 表示 MCDR 当前使用的配置信息

ServerInterface.modify_mcdr_config(changes: Dict[Tuple[str, ...] | str, Any])[源代码]

修改 MCDR 的配置

修改操作会立即被写入磁盘并在 MCDR 中生效

目前 MCDR 不会验证值的类型是否正确

示例用法:

server.modify_mcdr_config({'encoding': 'utf8'})
server.modify_mcdr_config({'rcon.address': '127.0.0.1', 'rcon.port': 23000})
server.modify_mcdr_config({('debug', 'command'): True})

参数:: changes -- 一个储存了对配置文件的修改的 dict。对于 dict 中的键值：键可以是一个储存了指向配置值的路径的 tuple，或者一个用 "." 将路径拼接而成的 str；值为被修改配置的值

在 v2.7.0 版本加入.

ServerInterface.reload_config_file(*, log: bool = False)[源代码]

从配置文件重载 MCDR 的配置

其效果与命令 !!MCDR reload config 相同

关键字参数:: log -- 是否输出配置文件变更的相关日志

在 v2.7.0 版本加入.

权限

ServerInterface.get_permission_level(obj: str | Info | CommandSource) → int[源代码]

返回一个 int，表示给定对象拥有的权限级别

obj 对象可以是一个表示玩家名的 str，一个 Info 实例或者一个 命令源

参数:: obj -- 你要查询的对象
抛出:: TypeError -- 当给定对象的类型不支持权限查询时

ServerInterface.set_permission_level(player: str, value: str | int) → None[源代码]

设置给定玩家的权限等级

参数:

player -- 你想设置权限级别的玩家名字
value -- 你想将玩家设置为的目标权限级别，它可以是一个代表权限级别的 int 或 str。例如：1， "1"，或 "user"

抛出:

TypeError -- 如果数值参数不是一个正确的权限级别

ServerInterface.reload_permission_file()[源代码]

从权限文件重载 MCDR 的权限数据

其效果与命令 !!MCDR reload permission 相同

在 v2.7.0 版本加入.

命令

ServerInterface.get_plugin_command_source() → PluginCommandSource[源代码]

返回一个插件命令源，可用于执行 MCDR 命令

该命令源不是玩家或控制台，它拥有最高的权限等级，它使用 logger 来处理回复

ServerInterface.get_player_command_source(player: str) → PlayerCommandSource[源代码]

返回一个玩家命令源，可用于模拟玩家执行 MCDR 命令

注意：绑定到返回的命令源的 Info 对象是一个不包含任何内容空对象

参数:: player -- 目标玩家的名字

在 v2.15.0 版本加入.

ServerInterface.get_console_command_source() → ConsoleCommandSource[源代码]

返回一个控制台命令源，可用于模拟控制台执行 MCDR 命令

注意：绑定到返回的命令源的 Info 对象是一个不包含任何内容空对象

在 v2.15.0 版本加入.

ServerInterface.execute_command(command: str, source: CommandSource | None = None) → None[源代码]

在 MCDR 的命令系统中执行一条命令

参见

方法 execute()，如果你想要往服务端的标准输入流中发送文本

参数:

command -- 你想要执行的命令
source -- 用于执行该条命令的命令源。如果它未被指定，MCDR 将会使用 get_plugin_command_source() 来获得默认的命令源

偏好

ServerInterface.get_preference(obj: str | PlayerCommandSource | ConsoleCommandSource) → PreferenceItem[源代码]

获取给定对象的 MCDR 偏好

该对象可以是一个表示玩家名称的 str，或者是一个命令源。命令源仅支持 PlayerCommandSource 以及 ConsoleCommandSource

参数:: obj -- 你要查询的偏好的对象
抛出:: TypeError -- 若给定对象的类型不支持偏好查询

在 v2.1.0 版本加入.

ServerInterface.get_default_preference() → PreferenceItem[源代码]: 返回默认的 MCDR 偏好

在 v2.8.0 版本加入.

ServerInterface.set_preference(obj: str | PlayerCommandSource | ConsoleCommandSource, preference: PreferenceItem)[源代码]

设置给定对象的 MCDR 偏好

该对象可以是一个表示玩家名称的 str，或者是一个命令源。命令源仅支持 PlayerCommandSource 以及 ConsoleCommandSource

参数:

obj -- 你要设置的偏好的对象
preference -- 设置给定对象的 MCDR 偏好

抛出:

TypeError -- 若给定对象的类型不支持偏好查询

在 v2.8.0 版本加入.

杂项

ServerInterface.is_on_executor_thread() → bool[源代码]

当前线程是否为任务执行者 (TaskExecutor) 线程

任务执行者线程是解析消息和触发监听器的主线程，是一些调用 ServerInterface API 所需的线程

ServerInterface.is_on_async_executor_thread() → bool[源代码]

当前线程是否为异步任务执行者 (AsyncTaskExecutor) 线程

异步任务执行者线程，是触发所有异步的监听器回调的线程

在 v2.14.0 版本加入.

警告

(Beta API)

ServerInterface.get_event_loop() → AbstractEventLoop[源代码]: 返回异步任务执行者线程中运行的事件循环。该事件循环会被所有异步事件监听器回调使用

在 v2.14.0 版本加入.

警告

(Beta API)

ServerInterface.rcon_query(command: str) → str | None[源代码]

通过 rcon 连接向服务端发送命令

参数:: command -- 你要发送给 rcon 服务端的命令
返回:: 服务端返回的 rcon 命令执行结果。如果 rcon 没有运行或 rcon 执行失败，则返回 None

ServerInterface.schedule_task(callable_: Callable[[], _T] | Coroutine[Any, Any, _T], *, block: bool = False, timeout: float | None = None) → Future[_T][源代码]

在任务执行者 (TaskExecutor) 或异步任务执行者 (AsyncTaskExecutor) 线程中添加一个任务

参数:

callable -- 将要被执行的可调用对象或协程对象。它应当接受 0 个参数

关键字参数:

block -- 是否需要阻塞至可调用对象执行结束
timeout -- 若 block=True，最大的阻塞时间

在 v2.14.0 版本加入: callback 参数支持 协程对象 或 协程函数

返回值现为一个 Future

警告

(Beta API)