插件的 API 包¶

当你的插件需要从 MCDR 导入，而不是直接导入所需的包时，你可以在 mcdreforged.api 中导入这些包。

mcdreforged.api 是供插件开发者导入的包。通过仅从 API 包导入，插件中目标类的导入可以与目标类的实际位置脱钩。若以后 MCDR 重构了目标类，移动了目标类的位置，只从 API 包导入可以保证你的插件不受影响。

all¶

from mcdreforged.api.all import *

这是导入插件开发所需的所有内容的最简单方法，是懒人的救命稻草。

继续阅读以了解实际导入的内容。

command¶

command 包包含了建立命令树或创建自己的命令的必要条件，包括命令树节点类、命令异常和一些命令实用工具。

例如，若你希望使用 Literal 和 IllegalArgument 来构建你命令树并处理 on_error 异常，则可以这样做：

from mcdreforged.api.command import Literal, IllegalArgument

当然，如果你嫌麻烦，那么也可以：

from mcdreforged.api.command import *

decorator¶

decorator 包包含了一些对插件开发有用的函数装饰器。

new_thread¶

这是一个让你的函数异步执行的单行解决方案。当使用这个装饰器时，函数将在一个新的守护线程中执行。

这个装饰器只将函数的返回值改为创建的 Thread 实例。除了返回值，它还保留了被装饰的函数的所有签名，所以你可以安全地使用被装饰的函数，就像它们没有被装饰一样。

这也是传统 MCDR 0.x 插件的简单的兼容升级方法。

例如：

from mcdreforged.api.decorator import new_thread

def do_something1(text: str):
    print(text)
    time.sleep(5)
    return text

@new_thread
def do_something2(text: str):
    print(text)
    time.sleep(5)
    return text

def on_info(server, info):
    # do_something1('hello')
    do_something2('there')

do_something1 和 do_something2 的唯一区别是 do_something2 由 @new_thread 装饰。所以当执行 do_something2 时，它不会像 do_something1 那样阻塞 MCDR 之后的操作，因为 do_something2 会在另一个线程上执行。

如果你想等待被装饰的函数完成，你可以简单地使用类 threading.Thread 中的 join 方法。记住被装饰函数的返回值已经被修改为 Thread 实例。

do_something2('task').join()

除了简单直接使用原始的 @new_thread 之外，建议为装饰器添加一个线程名参数。

@new_thread('My Plugin Thread')
def do_something3(text: str):
    print(threading.current_thread().getName())  # will be "My Plugin Thread"
    time.sleep(10)

这样，当你通过 server.logger 输出某些内容时，将显示一个有意义的线程名称，而不是简单无意义的 Thread-3。

注意：ServerInterface 类中的某些 api 方法必须在 MCDR 任务执行者线程（TaskExecutor）中调用——在另一线程中调用它们可能会导致异常。

event¶

event 包包含用于创建自定义事件的类和 MCDR 内置事件的类。

你可能已经读过 ServerInterface 类中的 dispatch_event <classes/ServerInterface.html#dispatch-event>`__ 方法。它只接受一个 ``PluginEvent 实例作为第一个参数。所以，如果你想分发你的自定义事件，为了简单起见，请创建一个 LiteralEvent 或一个继承自 PluginEvent 的自定义事件类。

exception¶

MCDR 运行时会使用一些自定义的异常，例如在调用 ServerInterface 的方法时。这是导入它们的方法。

rcon¶

rcon 包仅包含一个类—— RconConnection。这是一个简单的 rcon 客户端，用于连接到任何支持 rcon 协议的 Minecraft 服务端。

RconConnection¶

def __init__(self, address: str, port: int, password: str, *, logger: Optional[Logger] = None)

创建一个 rcon 客户端实例。

参数 address：rcon 服务器的地址

参数 port：rcon服务器的端口

参数 password：rcon服务器的密码

关键字参数 logger：logging.Logger 实例。它用于输出一些警告信息，例如未收到数据包。

connect¶

def connect(self) -> bool

启动与 rcon 服务器的连接并尝试登录。如果登录成功，它将返回 True，否则返回 False。

disconnect¶

def disconnect(self)

断开与服务器的连接。

send_command¶

def send_command(self, command: str, max_retry_time: int = 3) -> Optional[str]

将命令发送到 rcon 服务器，并从返回命令执行结果。

参数 command：要发送到服务器的命令。

参数 max_retry_time：操作的最大重试次数。如果重试次数超过 max_retry_time，则将返回 None。

rtext¶

建议先阅读 Minecraft Wiki 中的原始JSON文本格式页面。

这是一个用于Minecraft的高级文本组件库。

这部分受 Pandaria98 制作的 MCD stext API 的启发，在此表达感谢。

RColor¶

RColor 是一个存储所有 Minecraft 颜色代码的枚举类。

RColor.black
RColor.dark_blue
RColor.dark_green
RColor.dark_aqua
RColor.dark_red
RColor.dark_purple
RColor.gold
RColor.gray
RColor.dark_gray
RColor.blue
RColor.green
RColor.aqua
RColor.red
RColor.light_purple
RColor.yellow
RColor.white
RColor.reset

RStyle¶

RStyle 是一个存储所有 Minecraft 文本样式的枚举类。

RStyle.bold
RStyle.italic
RStyle.underlined
RStyle.strike_through
RStyle.obfuscated

RAction¶

RAction 是一个存储所有点击事件动作的枚举类。

RAction.suggest_command
RAction.run_command
RAction.open_url
RAction.open_file
RAction.copy_to_clipboard

RTextBase¶

RTextBase 是文本组件的一个抽象类，是 RText 和 RTextList 的基类。

to_json_object¶

def to_json_object(self)

抽象方法

返回一个代表其数据的对象，该对象可以被序列化为 json 字符串。

to_json_str¶

def to_json_str(self) -> str

返回一个表示其数据的 json 格式字符串。它可以作为命令 /tellraw <target> <message> 中的第二个参数，以及更多的参数。

to_plain_text¶

def to_plain_text(self) -> str

抽象方法

返回纯文本以供控制台显示。点击事件和悬停事件将被忽略。

copy¶

def copy(self) -> RTextBase

抽象方法

返回其自身。

set_color¶

def set_color(self, color: RColor) -> RTextBase

抽象方法

设置文本的颜色并返回文本组件本身。

set_styles¶

def set_styles(self, styles: Union[RStyle, Iterable[RStyle]]) -> RTextBase

抽象方法

设置文本的样式并返回文本组件本身。

set_click_event¶

def set_click_event(self, action: RAction, value: str) -> RTextBase

用给定的 action 和 value 设置点击事件，并返回文本组件本身。

参数 action：动作的类型

参数 value：操作的字符串值

方法 c 是方法` set_click_event` 的简写。

set_hover_text¶

def set_hover_text(self, *args) -> RTextBase

使用给定的 *args 设置悬停文本并返回文本组件本身。

参数 action：用于创建 RTextList 实例的元素。RTextList 实例作为实际的悬停文本使用。

方法 h 是方法 set_hover_text 的简写。

RText¶

常规文本组件类

def __init__(self, text, color: Optional[RColor] = None, styles: Optional[Union[RStyle, Iterable[RStyle]]] = None)

用特定的文本，颜色和样式创建一个 RText 对象，其中样式可以是 RStyle 或 RStyle 的集合。

RTextTranslation¶

翻译文本组件类。几乎和 RText 相同。

RTextTranslation¶

def __init__(self, translation_key, color: RColor = RColor.reset, styles: Optional[Union[RStyle, Iterable[RStyle]]] = None)

使用特定的 translation_key 创建一个 RTextTranslation 对象。其余参数与 RText 相同。

例如：RTextTranslation('advancements.nether.root.title', color=RColor.red)

RTextList¶

由 RTextBase 对象组成的列表。

RTextList¶

def __init__(self, *args)

使用给定的 *args 创建 RTextList 。

*args 中的对象可以是 str，RTextBase` 或任何实现 __str__ 方法的类。所有的这些对象都将被转换为 RText。

append¶

def append(self, *args) -> RTextList

在当前 RTextList 的末尾添加几个元素，然后返回 RTextList 组件本身。

*args 中的对象可以是 str，RTextBase` 或任何实现 __str__ 方法的类。所有的这些对象都将被转换为 RText。

is_empty¶

def is_empty(self) -> bool

返回一个布尔值，指示 RTextList 是否为空——换句话说——有没有子元素。

types¶

谁不希望在编写插件时，有一个检查器来帮助你减少愚蠢的错误呢？如果你想指定类型以让 IDE 知道你在写什么，这里有一个包可以让你导入一些常用的类。

from mcdreforged.api.types import ServerInterface, Info

def on_info(server: ServerInterface, info: Info):
    # Now auto completion for server and info parameters should be available for IDE
    pass