Pier
作者 Redstone-Circuit-Communication
Loads LeviLamina mods written in other languages through one C ABI (manifest type: pier).
- 112 次下載
- 7 個星標
- 更新於
- 1 個專案依賴
README26.51.3
Pier
让 C++ 之外的语言也能写 LeviLamina 模组的装载器。
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:要么完全相等,要么是带命名空间分隔符的后缀,不做子串匹配。
假如有两个匹配器,一个按子串、一个按后缀,同一个名字在两处可能匹配到两个不同的事件。
解析按这个顺序进行,哪一步认领了,就由哪一步负责到底:
- 事件提供方认领。认领了但订阅失败,就报错,不往下交给别的路径。
- 注册表里的精确名,然后是唯一的后缀。
- 都没找到就报错,并列出相近的 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 工具直接吃;它同时就是参考文档:
每个槽位都写明参数含义、失败时返回什么、对线程有什么要求。
- 镜像
PierApi,无条件声明每一个字段,不带任何目标分支。 - 导出
pier_main,往 vtable 里填struct_size、abi_version、mod_flags和三个生命周期回调。 - 调用任何非核心槽之前,先查
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 的商标。