跳到正文
返回搜尋

Pier

作者 Redstone-Circuit-Communication

Loads LeviLamina mods written in other languages through one C ABI (manifest type: pier).

  • 112 次下載
  • 7 個星標
  • 更新於
  • 1 個專案依賴
26.51.3

README26.51.3

Pier

让 C++ 之外的语言也能写 LeviLamina 模组的装载器。

Build Release Apache-2.0 BDS 1.26.51 LeviLamina 26.51.7

English · 简体中文

Pier 用一份 C ABI 把基岩服务端暴露出来。模组就是一个会说这份 ABI 的动态库, 所以用什么语言写,是作者的选择,不是平台替他做的决定。

Rust、C++、Go 和 Zig 都有官方绑定。任何有 C FFI 的语言都可以有自己的绑定, 而且加一个绑定不需要动 Pier。

Pier 为什么存在

它的前身是 levilamina-rust-loader, 当初只为回答一个问题:LeviLamina 的模组能不能用 Rust 写?

能。而这个答案带出了一个更难的问题。那个装载器的接口是一次加一个函数长出来的, 底下的形状错了,而且错在补丁补不掉的地方:

  • 布局按构建目标分岔。 函数表里的条件编译,让它的尾部在客户端构建和服务端构建上 落在不同的偏移。为此在版本号高位打了个标记补救,可这个标记护不住任何一个没重新编译的 模组——分岔点之后的每一个槽位都打到了错的函数指针上,而两边都编得过。
  • 中心直接呼叫每个能力包。 派发表里写着各个包的函数名,每一个名字都是一条从中心 伸向能力包的链接边,于是能力包根本删不掉。「可选」是文档里的一个词,不是代码的性质。
  • 读不到的值,变成了看起来合理的值。 一个读不出来的字段返回 0,而 0 对多数东西 来说都是个合法答案。土地保护模组读不到事件里的维度,写了 unwrap_or(0),于是 每个事件都被当成发生在主世界——主世界拒绝、别处全部放行,一行日志都没有。
  • 事件名做子串匹配。 上游哪天新增一个含相同词干的事件,订阅方就会被静默劫持到 载荷形状完全不同的合成事件上,而且没有任何办法再订到真事件。

这四条单独看都能修,也确实补过几个。但合起来它们说明的是一件补丁修不了的事: 这个接口从来不是设计出来的,是长出来的,而那些补丁是在守一个本就不该存在的形状。

那个装载器是测试版。测试版的作用就是告诉你该怎么正经地建,它做到了,然后就不再维护。

Pier 是重新设计:先有接口,后有实现。

Pier 是怎么设计的

Pier 的全部就是一份头文件 packages/pier-abi/include/sdk/abi.h。 仓库里的 C++ 宿主照着它实现,各语言的绑定也照着它写。下面几节讲的,是这个头文件里定下来的几件事各自是怎么运作的。

所有目标共用同一张函数表

PierApi 里没有条件编译。客户端专用的槽位、自定义维度的槽位,在每一种构建里都占着同样的位置; 对应的能力包没编进来时,这些槽位的值是 NULL。

模组想知道宿主有没有某个能力,就在运行时看那个槽位是不是 NULL。同一份模组源码因此在服务端和客户端都编得过。 早先为了区分构建在版本号高位加的标记,以及维护那个标记的一串补丁,都已经删掉了。

能力包自己向宿主注册

Pier 由八个 C++ 包组成。pier-host 管着函数表和模组的生命周期,但不知道表里填的是什么。 每个能力包通过一套服务提供方接口(SPI)向宿主登记四样东西:

登记什么宿主什么时候用
槽位包装载时填进 PierApi
拆除步骤(带 stage 编号)卸载时按 stage 从小到大执行
卸载否决允许卸载之前逐个询问
事件提供方解析一次订阅时

把某个包从构建里删掉,它就不会登记,对应的槽位停在 NULL,pier-host 的代码一行不用改。 根构建文件里每个包是一行 includes(...):删掉那一行,配置、编译、运行都照常。 有一条检查在每次推送时把每个包轮流删掉,再构建一遍。

自注册有一个前提:所有包都编译成 object 库,不能是静态库。链接静态库时,链接器会丢掉没有被外部符号引用的编译单元, 而登记用的正是没有外部引用的文件级静态对象。它们被丢掉以后,对应的功能就不见了,启动日志里一个字也没有。 这一条写进契约以后,还是在四个包上被违反过一次,之后才加了检查。

跨边界传的是名字和 id

指向服务端内部对象的指针不会跨过 ABI。玩家用选择器表示,实体用 id,方块用维度加坐标;每次调用,宿主都重新查一遍。

所以句柄可以跨 tick 保存。实体没了以后再调用,宿主查不到它,返回一个错误,调用不会落到一块已经释放的内存上。 每次调用也因此要多查一次表。

按名字找玩家时有一处要当心:账号名对不上时,选择器会退到显示名去找,而显示名可以被别的模组改。 一个玩家把自己的显示名改成某个离线玩家的账号名,按名字寻址的调用就会落到他身上。 所以权限、经济、归属判定都用 xuid;Rust 绑定把两种选择器做成了不同的类型,在调用的地方就能看出用的是哪一种。

谁分配的缓冲区,谁释放

跨边界的缓冲区由产出它的一方分配和释放,接收方想留下内容就自己复制。

形状谁分配接收方怎么用
PierStr(指针 + 长度)调用方在调用返回前读完,要留就复制
Sink 回调宿主在 sink 里复制走,返回后指针失效
车道的 data / vtable提供方存活标志为真时才调用

ABI 上没有哪个调用会返回一个要对方去释放的指针:那样需要两边用同一个分配器,而模组和宿主各用各的。 所有输出都通过 sink 交出来。

结构化数据用 SNBT 文本传递,不按值传结构体,这样表达不了引擎内存布局的语言也能用。

答不上来的时候

一个槽位答不上来时,会做下面三件事中的一件:返回一个能表示「没有答案」的值;打一条日志并回退,在日志里写明回退成了什么;或者拒绝执行。

举个例子:一个判断「这个玩家能不能进领地」的函数,可能因为读不到玩家而答不上来。 如果它只返回 bool,读不到时返回 false,调用方分不清「不能进」和「不知道」;返回 true,读不到的玩家就进去了。 所以这类函数的返回类型里留着第三种情况。

日志写的是下一步该做什么。同样是订阅失败,日志写的是「这个事件在当前 BDS 版本上不存在,注册表里相近的有 A、B、C」, 读日志的人看完就知道该去改哪个名字。

订阅时事件名怎么匹配

宿主里只有一个匹配器 idMatches:要么完全相等,要么是带命名空间分隔符的后缀,不做子串匹配。 假如有两个匹配器,一个按子串、一个按后缀,同一个名字在两处可能匹配到两个不同的事件。

解析按这个顺序进行,哪一步认领了,就由哪一步负责到底:

  1. 事件提供方认领。认领了但订阅失败,就报错,不往下交给别的路径。
  2. 注册表里的精确名,然后是唯一的后缀。
  3. 都没找到就报错,并列出相近的 id。

提供方排在注册表前面,是因为命令事件的发射器就在注册表里,可 LeviLamina 只把它派发给带类型的监听器: 动态路径查得到它,却收不到事件。这类提供方声明自己接管注册表里的那条路径。纯合成的事件声明自己不接管; 以后上游出现同样后缀的 id 时,宿主会打一条告警,这种遮蔽在日志里就看得到。

新功能怎么加进函数表

新增一个能力,就在表尾追加一个槽位,版本号不动。重排、删除或者修改签名时, PIER_ABI_VERSION 和 PIER_ABI_MIN_SUPPORTED 一起推进到同一个数;在那之前编译的模组,装载时会被拒绝,日志里写着原因。

装载时判断的是一个区间:MIN_SUPPORTED <= 模组的版本 <= 宿主的版本。

tools/abi-v1.slots 记着已发布的槽位顺序。每次推送都有检查拿当前的表和它比,改动了已有槽位的提交会在这一步失败。

仓库里的检查脚本

object 库那一条,最早只写在契约里,交付说明也说它成立;后来它在完全依赖自注册的四个包上被违反了。 从那以后,契约里的规则都配了一个检查脚本,放在 tools/checks/。

python3 tools/run-checks.py 一次跑完所有检查。它们查的是编译器和 clippy 查不到的东西:头文件能不能按 C11 和 C++20 各编一遍, 槽位顺序是不是只增不减,Rust 镜像和头文件是不是逐个参数对得上,能力包之间有没有横向依赖,有没有注释在描述代码没做的事。

有三条检查盯的错误,在编译期完全看不到,装载时才出现,出现时的日志也看不出和构建有什么关系。 比如 manifest 的 type 写错,模组根本不会被扫到,也不报错;少写了内存操作符,构建全部通过,启动服务器时才被拒绝。

每条检查都写明了它覆盖什么、看不到什么。交付说明引用检查结果时照抄这句话,读的人就知道哪些部分还得靠人去看。

规则本身在 CONTRACT.md 里,每一条都附了理由。

写一个模组

Rust 是第一个官方绑定,也是功能最全的;C++ 直接使用头文件, Go 把模组构建成 c-shared DLL,Zig 通过 translate-c 读取头文件。

use levilamina::prelude::*;

struct MyMod;

impl LeviMod for MyMod {
    fn on_load(ctx: &ModContext) -> Result<Self> {
        ctx.logger().info("hello from Rust");
        Ok(MyMod)
    }
}

levilamina::register_mod!(MyMod);
  • 写你的第一个模组 从构建到装上服务器走一遍。
  • pier-mod-template 是一个直接就能跑的 Rust 模组: 它会打日志、订阅聊天、注册命令、排一个延迟任务。在 GitHub 上点 Use this template,或者用 cargo generate,都能从它开始。

绑定另一门语言

一份文件就够了。sdk/abi.h 能被 C11 解析,FFI 工具直接吃;它同时就是参考文档: 每个槽位都写明参数含义、失败时返回什么、对线程有什么要求。

  1. 镜像 PierApi,无条件声明每一个字段,不带任何目标分支。
  2. 导出 pier_main,往 vtable 里填 struct_size、abi_version、mod_flags 和三个生命周期回调。
  3. 调用任何非核心槽之前,先查 struct_size 覆盖得到它,再查槽位非空。

bindings/rust/pier-sys-rs 是参考实现。 加一门语言 有详细步骤, CONTRACT.md 第十节是权威版本。

安装

用 lip:

lip install github.com/Maskviva/Pier

或者把发布压缩包解压到 plugins/pier/。

Pier 需要 BDS 1.26.51 上的 LeviLamina 26.51.7。 LegacyMoney 是可选的:它走延迟加载, 没装的服务器照常启动,只有经济相关的调用返回失败值。

从源码构建

xmake f --toolchain=clang-cl --target_type=server && xmake   # 宿主本体 pier.dll
cargo build --release                                        # Rust 绑定与示例

宿主用 clang-cl 构建(CI 安装的是 LLVM 21.1.8),xmake.lua 给每个目标都选了它。MSVC 的 cl 会在 LeviLamina 的 EventCoordinatorPimpl.h 上报 C2491,hook 这个函数的两个文件在其他编译器下会直接 #error。

两条构建线之间没有构建依赖,只有那份头文件,所以它们可以分别修。

python3 tools/run-checks.py   # 契约第九节的机器检查

参与开发

先读 CONTRACT.md;和它冲突的代码是要改的那一方。 欢迎新的语言绑定,而且它不需要这个仓库改任何东西。

致谢

Pier 站在别人的工作上,这几个项目值得的不只是依赖列表里的一行。

  • LeviLamina 是整个平台。Pier 本身是一个 LeviLamina 模组, 用的是它的钩子、事件总线、命令、服务和 SDK。没有它,就没有可以装模组的地方。
  • LegacyScriptEngine(LSE)让我们知道一个服务端事件该是什么意思。 Pier 的许多事件钩的是和 LSE 同名事件相同的引擎函数,后来补上的大部分事件,从漏斗、发射器到计分板, 是照着 LSE 的挂点补上的。
  • iListenAttentively(ILA,作者 MiracleForest)是 LSE 自己所依赖的事件库, 也是 Pier 判断该钩哪里的第二份参照。Pier 的事件逐个和它对照过,其中攻击方块、凋零破坏、起床和生物破坏方块的钩点沿用了它的选择。
  • MoreDimensions 是自定义维度的来源。Pier 向引擎注册维度的方式沿用它, 也从它不得不钩的那些地方学到了东西。
  • LegacyMoney(LLMoney)是 Pier 经济函数背后的后端,这些函数文档里写明的语义以它的源码为准。

感谢每一位维护者。它们各自保留自己的许可证,条款见各自的仓库;哪个事件参照了哪一个项目, 见致谢页。

许可

Apache-2.0,见 LICENSE。


与 Mojang、Microsoft、LeviMC 无关。Minecraft 是 Mojang Synergies AB 的商标。

安裝 Pier

執行端
  • 伺服器端
平台
  • win-x64

在伺服器目錄中用 lip 執行:

lip install github.com/Maskviva/Pier@26.51.3
從 GitHub 下載