迁移自 MCDR 0.x¶
文件结构¶
MCDR 已将其文件结构重构为适合作为 python 软件包安装的结构,因此于 MCDR 0.x 中使用的某些文件/文件夹可直接删除:
utils/
resources/
requirements.txt
LICENSE
readme.md
readme_cn.md
MCDReforged.py (如果你仍要使用它可以从 github 获取——现在它只作为 MCDR 的启动脚本)
日志文件夹已从 log/
重命名为 logs/
。
配置文件¶
配置文件有相当多的变化,虽然 MCDR 在使用旧版配置文件的情况下仍然可以使用,但我们仍强烈建议你生成一个新的默认配置文件,并将旧配置项填入新的配置文件中。
你可以将旧的 config.yml
重命名为 old_config.yml
并启动 MCDR。 MCDR 将重新生成一份配置文件并自动退出。然后打开这两个配置文件并迁移你的配置选项。
权限文件¶
权限系统没有任何改变,因此你可以继续用着旧的权限文件。
插件¶
大部分旧的 MCDR 插件只需做出一些小改动以适配新的 MCDR。有些旧插件甚至无需更改即可运行在新的 MCDR 中。
元数据¶
元数据是插件内部的一个全局变量。它用来存储插件的基本信息和依赖关系。一个插件有必要声明它的元数据,这样 MCDR 才能正确地处理所有的插件。
如果一个旧式插件没有声明元数据,它仍然可以被 MCDR 加载,但在控制台中将会显示一个警告。
点击 此处 以查看更多关于元数据的信息。
监听器¶
兼容性¶
新版的 MCDR 实现了更好的事件和监听器系统,插件可以将任意函数注册为事件监听器。
大多数 MCDR 0.x 风格的事件监听器都保留了下来,现在作为相关事件的自动注册的默认监听器工作。
on_info
on_user_info
on_server_startup
on_server_stop
on_mcdr_stop
on_player_joined
on_player_left
如果你定义了一个在以上列表中的函数,那么 MCDR 会在你的插件加被加载时自动把它注册为一个事件监听器。这个监听器的默认优先级是 1000
。
以下两个事件已从 MCDR 中移除:
on_death_message
on_player_made_advancement
如果你的插件依赖于这两个事件,这里有一个替代方案:即将到来。
监听器参数¶
在 MCDR 0.x 中,玩家加入的事件监听器接受 2 或 3 个参数。以下的两个定义方式都有效:
def on_player_joined(server: ServerInterface, player: str):
pass
def on_player_joined(server: ServerInterface, player: str, info: Info):
pass
然而,在当前版本的 MCDR 中,前者将不被接受,只有定义 3 个参数的后者被接受。
除了玩家加入的事件监听器外,其他事件监听器的回调参数保持不变。
多线程¶
MCDR 0.x 为每个插件分配单独的线程以执行其事件监听器回调。这种做法带来了不可预知的插件执行顺序,并极大影响了整体性能。这样的多线程也使得在所有插件完成回调后很难执行任何工作。
在新版 MCDR 中,所有事件监听器回调在名为 TaskExecutor
的单线程中调用,以解决上述的问题。
如果你的插件依赖于来自 MCDR 的多线程以执行一些并行操作,或你的插件需要执行一些 I/O 或网络操作,并需要耗费一些时间,那最好创建一个新线程来手动执行它们,以保证 MCDR 不会被这些操作阻塞。
MCDR 还提供了一个简单的函数装饰器 new_thread
,用于在调用函数时使函数为多线程。下面是一个示例:
from mcdreforged.api.decorator import *
# undecorated function
def my_slow_method1():
time.sleep(10)
@new_thread # decorated function, will run at a new thread
def my_slow_method2():
time.sleep(10)
@new_thread('MyThread') # specify the thread name
def my_slow_method3():
time.sleep(10)
使用 @new_thread
修饰器,则每次调用 my_slow_method2
时,都会创建一个新的守护线程来执行它。关于 @new_thread
的详细信息,请查看 此处。
模块位置¶
如果你的插件需要导入一些 MCDR 内置模块,如 RText 或 Rcon,请查看模块的位置。
MCDR 集合了所有有用的类/函数至 mcdreforged.api
包中。建议从 api
包中导入所需的模块。
如需导入所有 RText 类,可使用 from mcdreforged.api.rtext import *
。
如需导入所有 Rcon 类,可使用 from mcdreforged.api.rcon import *
。注意,Rcon
类已被重命名为 RconConnection
。
对于懒人,你可以使用 from mcdreforged.api.all import *
来向插件中导入所有内置模块。
服务器实例 API¶
如果给定的 info 参数不是来自用户,则 reply
方法将产生一个 TypeError
。
add_help_message
方法已重命名为 register_help_message
。