服务端接口 - 通用

API 包 路径: mcdreforged.api.types

class mcdreforged.plugin.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。目前，插件上下文仅在如下场景中可用：

1. 入口点模块 的加载

2. 事件监听器 回调函数的调用

3. 指令 回调函数的调用

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, language: str | None = None, **kwargs) → str | RTextBase

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

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

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

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

参数:

• translation_key – 翻译键

• args – 用于格式化的参数（args）

• _mcdr_tr_language – 指定在该次翻译中使用的语言。若未指定，则使用 MCDR 所使用的语言

• language – 已弃用，将于 v2.15 移除。请使用关键字参数 _mcdr_tr_language 替代

• 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_file_path(plugin_id: str) → str | None

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

参数:

plugin_id – 要查询文件路径的插件的 ID

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

重新加载所有 更改过 的插件，加载所有新插件，并卸载所有删除的插件

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 – 在默认值的情况下，该事件会被派发至任务执行者 (task executor) 线程中分发。如果它被设置为 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

返回一个简单的插件指令源，用于例如执行指令时使用

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

ServerInterface.execute_command(command: str, source: CommandSource = 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

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

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

ServerInterface.rcon_query(command: str) → str | None

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

参数:

command – 你要发送给 rcon 服务端的指令

返回:

服务端返回的 rcon 指令执行结果。如果 rcon 没有运行或 rcon 执行失败，则返回 None

ServerInterface.schedule_task(callable_: Callable[[], Any], *, block: bool = False, timeout: float | None = None) → None

在任务执行者 (task executor) 线程中添加一个任务

参数:

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

关键字参数:

• block – 是否需要阻塞至可调用对象执行结束

• timeout – 若 block=True，最大的阻塞时间