- 版权类型
- 原创
- 语言支持
- 多语言
- 前置组件
- Levilamina-Rust-Loader（https://www.minebbs.com/resources/levilamina-rust-loader-levilamina-rust.17046/）
- 适配版本（基岩）
- 26.x
[MD]
# levilamina-mod-template-rs
一个用 **Rust** 编写 [LeviLamina](https://github.com/LiteLDev/LeviLamina)
Minecraft 基岩版专用服务器 mod 的模板，不需要 C++ 工具链。
这个模板对接的是
[**levilamina-rust-loader**](https://github.com/Maskviva/levilamina-rust-loader)——
教会 LeviLamina 把 Rust cdylib 当成一等公民 mod 加载的那个 loader mod。服务器上
不装它，这个模板做出来的 mod 就是个空壳。
[English](README.md)
## 这里面有什么
`src/lib.rs` 是一个完整能跑的 mod（不是空骨架），演示了 v0.1 的完整 API 面：
日志、带取消功能的事件订阅、自定义命令、定时任务、控制台命令执行。读一遍，
把用不上的部分删掉就行。
## 使用方法
1. 点上面的 **Use this template** 生成一个新仓库，然后 clone 下来。
2. 改名字：
- `Cargo.toml` → `[package] name = "..."`
- `manifest.json` → `"name"`（必须跟你安装时用的文件夹名一致）和 `"entry"`
（cargo 产物的文件名——crate 名里的连字符会变成下划线，比如 `my-mod` →
`my_mod.dll`）
- `src/lib.rs` → 把 `HelloWorld` 这个结构体和里面日志/命令用到的字符串
改成你自己的
3. 写你的 mod。四个演示的部分（事件订阅、自定义命令、定时任务、命令执行）
哪个用不上就删哪个。
4. 编译和部署：
```shell
cargo build --release
```
把 `target/release/<你的crate名>.dll` 和 `manifest.json` 一起放进
`<服务器>/plugins/<你的mod名>/`（也可以直接用这个模板自带的 CI，每次 push
/release 会自动编译打包）。
## API 速览
```rust
use levilamina::prelude::*;
struct MyMod;
impl LeviMod for MyMod {
fn on_load(ctx: &ModContext) -> Result<Self> {
ctx.logger().info("hello from Rust!");
Ok(MyMod)
}
fn on_enable(&mut self, ctx: &ModContext) -> Result<()> {
let server = ctx.server();
server.register_command("hello", "Say hello", CommandPermission::Any, |inv| {
inv.success(&format!("Hello, {}!", inv.origin));
})?;
server
.subscribe_event("PlayerChatEvent", EventPriority::Normal, |ev| {
if ev.snbt().contains("creeper") {
ev.cancel();
}
})?
.forget();
Ok(())
}
}
levilamina::register_mod!(MyMod);
```
所有生命周期钩子和回调（事件、命令、定时任务）都跑在**服务器线程**上。
`Server::get()` 配合 `Server::schedule`/`schedule_after` 是唯二线程安全的入口，
供后台线程（Tokio 任务等）把工作重新交回游戏主线程。完整契约见
[`levilamina-rust-loader` 的 DESIGN.md](https://github.com/Maskviva/levilamina-rust-loader/blob/main/docs/DESIGN.md)。
## 前置条件
- Rust（`x86_64-pc-windows-msvc` 目标——Windows 上的默认目标）
- 目标服务器已安装 [LeviLamina](https://lamina.levimc.org/) 和
`levilamina-rust-loader`
## 贡献
有问题就开 issue。欢迎 PR。
如果是 loader 本身的 bug，或者想要新的 API 原语（世界访问、玩家句柄……），
那些在
[levilamina-rust-loader](https://github.com/Maskviva/levilamina-rust-loader)
里，不在这个仓库——这里只是起始骨架。
## 协议
CC0-1.0——公共领域。这份起始代码你想怎么用都行，不需要署名。
---
*与 Mojang、Microsoft、LeviMC 均无关联。Minecraft 是 Mojang Synergies AB 的
商标。*
[/MD]
