datapack_standard.md

数据包接口规范

RFC，当前版本0.1.3

引言

本规范希望能透过定义部分规定，让数据包作者共同遵守，最终能编写可读性及扩展性更高的数据包。 本规范主要针对希望开放接口供其他数据包使用，以及希望使用其他数据包接口的数据包。

为了方便统一管理模块，本规范会同时提供一个 std 模块，实现部分单一模块较为困难实现的功能。

名词定义

为了方便，本文将会先定义一些名词，以免过于累赘。

• 模块: 数据包内的不同目录(文件夹)，但不包括如tags, functions等定义内部文件种类的目录。
• 重构: 即改变数据包架构，如改变模块名称、把部分命令移到别的函数内的行为。
• 内部函数: 即该命令函数的实际内容。为了只在某条件下运行那命令函数，而把实际内容移至别的命令函数，并把命令函数内容改为 execute (条件检查) run function 内部函数。

命名、结构规范

所有模块、命令函数等的名称，应遵从snake_case的要求，单词之间以_分开。如需序号亦应在序号后加上_分开，以免混淆。

(如 2_json 与 2json 意思有所不同。前者为序号。后者的2能解读为to，即变为，的意思)

命名空间可加上作者标识_前缀，可以为组织名称。以避免发生命名冲突。所有命名空间名称应长于4个字符，并且应避免与现有mod、其他数据包的命名空间出现冲突。(它们都是使用这个系统，出现冲突可能带来未知影响。)

单一数据包只应有一个命名空间，其他命名空间只应该用作处理命令函数标签、接口实现等事情。

• 需要在高频运行的命令函数(主函数，一个模块只可有一个，不包括子模块)应命名为 tick。如无依赖则应加上 std:tick 标签。
• 应最先运行的命令函数(系统状态改变时)应命名为 init。
• 需要在数据包加载时运行的命令函数应放在 _init 模块内，放在命名空间之下。
• 在移除数据包时执行的命令函数应命名为 (命名空间):delete。

数据包加载、移除

加载执行命令

每个数据包加载时应先执行如下命令：

# 宣示成功加载:
scoreboard players set #(命名空间) common 0
# 宣示实现的接口
scoreboard players set #(接口定义的假名) common 0
# 其他命令...

加载方式

没有依赖：使用 std:load 标签。（std:load之前会定义common这个记分板变量供其他数据包作数据包沟通使用）

当数据包出现加载依赖时，如b需要在a之后加载(常见于接口使用)。以下假设它们的命名空间分别为b和a。

• a应定义一个命令函数标签，名为 (a):dependents，在a加载后(执行完a的_init模块内的函数后)执行那标签的命令函数。基本上所有打算开放接口的数据包都应该定义这个标签，其命名空间应避免和其他模块产生冲突。
• 而b的_init模块内的命令函数应加上(a):dependents 标签，不应加上std:load 标签。

如需使用 std 数据包里的库，直接调用 std:(库)/init 即可，std:load保证了 std 数据包必定在此命令函数执行前加载完毕。

卸载数据包

除了地图专用 (map-specific) 的数据包以外，其他数据包应定义 (命名空间):delete 以供移除相关资料，并调用 #(命名空间):delete以移除依赖其的数据包。其子模块亦应提供删除用命令函数，并加上 (依赖数据包命名空间):delete 标签，以在依赖模块被删除时一并删除。

检测成功加载

数据包应包含 (命名空间):check 函数以检测其有否正确加载，以及其需要的接口有没有被实现。此命令函数应加上 std:check 标签。

例子：

# foo:check
# 如果#foo不为0则代表有部分检查出现错误，之后tick的模块应该检查这分数决定应否执行。
execute unless score #foo common matches 0 run say 数据包foo未能正确加载！
# 检查接口，发现问题则设置 #foo common 分数为1。如果#foo common分数不为1则不用检查，因为已经出问题了。
execute if score #foo common matches 0 store result score #foo common unless score #foo_interface1 common matches 0 run 数据包foo的接口 interface1 没有被实现！
# 检查依赖函数(不是加载依赖，故此可独立加载，需要检测)，发现问题则设置 #foo common 分数为1。如果#foo common分数不为1则不用检查，因为已经出问题了。
execite if score #foo common matches 0 store result score #foo common unless score #std_rnd common matches 0 run 数据包std的rnd模组未能加载！数据包foo不能使用！

所有拥有 std:check 标签的命令函数都会在加载后第一游戏刻运行一次，早于第一个 std:tick 执行。

注：使用std:check 不是依赖于std数据包。

接口

接口类型

• 调用外部系统
  • 命令函数：需要外部系统提供一个命令函数以达到指定功能。一般为地图专用数据包用接口。
  • 命令函数标签：提供给外部系统聆听事件以作出处理。聆听此事件（拥有此标签）的命令函数可以多于一个。

    注意: 标签文件禁止使用 "replace":true，因为这样会影响到其他模块。

    使用命令函数标签时应定义一个假名，被调用的函数只应在那假名为指定分数时执行(调用内部函数)。如需阻止之后其他函数执行，则可以更改那假名数值。如1为能够执行，0为不能执行。

• 提供于外部系统
  • 函数：传入分数，执行后回传处理后的分数或根据传入分数进行操作。

    注意：没人能保证传入的分数不会被改变。

    建议使用 common 记分板变量，传入分数假名建议为 #param, #param1...，而回传分数假名建议为 #result, #result1...

• 其他，请参考实际数据包文档决定如何使用。
  • 实体标记（marker）
  • 记分板假名（fake player name）