# levilamina-rust-loader
[](README.zh.md)
**Teach [LeviLamina](https://github.com/LiteLDev/LeviLamina) to load Minecraft Bedrock Dedicated Server mods written in Rust.**
This repository is the *engine*: a C++ loader mod plus the two Rust crates
that speak its ABI. Install it once on your server, then any Rust mod is just
a `cargo build` away — no C++ toolchain, no xmake, no glue code on the mod
author's side.
Looking to **write** a mod instead of build the loader? Start from
[**levilamina-mod-template-rs**](https://github.com/Maskviva/levilamina-mod-template-rs)
and come back here only if you're curious how it works or want to contribute.
## How it works
```
┌─────────────────────────── bedrock_server_mod.exe ───────────────────────────┐
│ LeviLamina (C++) │
│ └─ levilamina-rust-loader (this repo, C++, install once) │
│ • registers a ModManager for manifest `"type": "rust"` │
│ • loads your cdylib, calls `levi_rs_main(api, handle, out_vtable)` │
│ • hands over a versioned C function table (LeviRsApi) │
│ ├─ events : EventBus + DynamicListener ⇆ SNBT strings │
│ ├─ commands : RuntimeCommand overloads / console execution │
│ ├─ schedule : ServerThreadExecutor (thread-safe entry point) │
│ └─ logging : per-mod LeviLamina logger │
│ └─ your-mod (pure Rust cdylib, `"type": "rust"`) │
└───────────────────────────────────────────────────────────────────────────────┘
```
Design highlights:
- **First-class mods.** Rust mods live in `plugins/<name>/` with a normal
`manifest.json`, participate in dependency sorting, and show up in
LeviLamina's mod listing like any other mod — because they *are* managed by
a real `ModManager`, not injected through a side door.
- **One universal event channel.** LeviLamina's `DynamicListener` serializes
any event to a `CompoundTag`; the bridge round-trips it as SNBT, so Rust can
observe *and mutate/cancel* every event — including events published by
other mods — without per-event C++ bindings. Run `/levirs events` in-game to
dump every event id available on your server.
- **Honest threading model.** Every callback runs on the server thread.
`Server::schedule{,_after}` are the only thread-safe entry points — exactly
the bridge you need for Tokio-based agents and services.
- **Versioned, append-only C ABI** (`src/LeviRsAbi.h` is the single source of
truth, mirrored field-for-field by `crates/levilamina-sys`). The loader and
a mod refuse to pair on a version mismatch instead of risking UB.
- **Panic-safe.** Every FFI boundary in the `levilamina` crate is wrapped in
`catch_unwind`; a panicking handler logs an error instead of taking down
the server.
- **Unified memory allocator.** `src/MemoryOperators.cpp` routes this DLL's
`operator new`/`delete` through LeviLamina's allocator, same as any native
mod — required for the loader to be loaded at all.
## Repository layout
```
src/ C++ loader mod (compiles to levilamina-rust-loader.dll)
crates/levilamina-sys/ Raw #[repr(C)] FFI mirror of src/LeviRsAbi.h
crates/levilamina/ Safe, ergonomic Rust API built on levilamina-sys
docs/DESIGN.md ABI + architecture decisions, evolution rules
docs/PORTING_NOTES.md LeviLamina API call sites this bridge relies on
xmake.lua Builds the C++ mod (repo root doubles as the xmake project root)
Cargo.toml Workspace for the two Rust crates (repo root doubles as the cargo workspace root)
```
`crates/levilamina-sys` and `crates/levilamina` are published from this repo
(not the template repo) because they are versioned in lockstep with the C++
loader — see [`docs/DESIGN.md`](docs/DESIGN.md) §8 for the ABI evolution
rules. The C header and the `-sys` crate change in the same commit, always.
## Installation (server admins)
1. Install [LeviLamina](https://lamina.levimc.org/) on your BDS.
2. Drop a `levilamina-rust-loader` release into `plugins/levilamina-rust-loader/`
(or build it yourself, see below).
3. Install Rust mods into `plugins/<mod-name>/` — each one is a `.dll` +
`manifest.json`, same as any other LeviLamina mod.
## Building the loader
Requires [xmake](https://xmake.io) and a Visual Studio 2022 (or clang-cl)
toolchain, same as any LeviLamina native mod. **Pin `xmake.lua`'s
`levilamina`/`bedrockdata`/`prelink` versions to what's actually running on
your server before building** — an unpinned `levilamina` can silently
resolve to a newer SDK than your server's LeviLamina build, which shows up as
confusing compile errors (missing members, changed signatures) rather than a
clear version-mismatch message.
```shell
xmake f -m release -y
xmake
```
The built mod (DLL + manifest) lands in `bin/`.
To also build/test the Rust crates in this workspace:
```shell
cargo build --workspace
cargo test --workspace
```
## Writing a mod against this loader
Most people should start from the
[template repository](https://github.com/Maskviva/levilamina-mod-template-rs)
instead of wiring this up by hand. If you're adding `levilamina` to an
existing crate:
```toml
# Cargo.toml
[lib]
crate-type = ["cdylib"]
[dependencies]
levilamina = { version = "0.1.0", git = "https://github.com/Maskviva/levilamina-rust-loader" }
# once published to crates.io: levilamina = "0.1"
```
```jsonc
// manifest.json — goes next to your .dll in mods/<name>/
{
"name": "my-mod", // must match the folder name
"entry": "my_mod.dll", // cargo output (hyphens → underscores)
"type": "rust",
"platform": "server",
"dependencies": [{ "name": "levilamina-rust-loader" }] // guarantees load order
}
```
## ABI stability
`LEVI_RS_ABI_VERSION` gates compatibility. Within a major version, `LeviRsApi`
only grows (new fields appended at the end, gated by `struct_size`); it never
reorders or removes fields. See [`docs/DESIGN.md`](docs/DESIGN.md) for the
full contract, including the threading model and string/memory ownership
rules that every FFI call follows.
## Current status & roadmap
v0.1 is intentionally a **narrow, correct core** — the universal primitives
(events / commands / scheduling / logging) from which everything else can be
built, since `execute_command` already reaches most of vanilla behaviour.
- [ ] **v0.2** — structured SNBT: typed event views (`serde`-based), proper
NBT editing instead of string-level `cancel()`
- [ ] **v0.2** — direct world access fast path (`get_block` / `set_block` /
region snapshots) without the command parser overhead
- [ ] **v0.3** — player handles (send message/toast/form), form API
- [ ] **v0.3** — Linux support (LeviLamina's Linux target is in progress
upstream)
- [ ] **v0.x** — async-first API surface (`ServerHandle::run(async fn)` on top
of the scheduler), Tokio integration example, AI-agent example
- [ ] procedural macro sugar: `#[levilamina::event]`, `#[levilamina::command]`
Contributions welcome — the ABI evolution rules are documented in
[`docs/DESIGN.md`](docs/DESIGN.md).
## FAQ
**Why a C++ shim instead of pure Rust against LeviLamina?**
LeviLamina's mod entry is plain C (`ll_mod_load` etc.), but everything
useful — events, commands, coroutine executors — is modern C++ (templates,
`std::function`, C++20 coroutines) with no C export layer. The loader also
enforces a unified memory-allocation contract that only code compiled against
its headers can honestly satisfy. A thin, audited C++ layer that flattens
those APIs into a versioned C table is the correct engineering answer; "pure
Rust" would mean hand-written FFI against MSVC-mangled symbols — a
re-implementation of LeviLamina itself.
**Does this work on the client?** Untested; the loader targets
`"platform": "server"`. LeviLamina's client support is newer territory.
**Where's the mod template?**
[`levilamina-mod-template-rs`](https://github.com/Maskviva/levilamina-mod-template-rs) —
kept separate so "start a new mod" stays a one-click GitHub template, instead
of forking this whole engine repo.
**License:** Apache-2.0 (this repository). LeviLamina itself is LGPL-3.0; the
loader mod links against it dynamically as a normal mod.
---
*Not affiliated with Mojang, Microsoft, or LeviMC. Minecraft is a trademark of
Mojang Synergies AB.*