{"url":"https://levimc.org/mods/github.com/Maskviva/levilamina-rust-loader/","id":"github.com/Maskviva/levilamina-rust-loader","name":"levilamina-rust-loader","description":"Loads LeviLamina mods written in Rust (manifest type: rust).","owner":"Maskviva","logo":"https://levimc.org/mods/icons/b7b68b879232eeb6-288.webp","repository":"https://github.com/Maskviva/levilamina-rust-loader","issues":"https://github.com/Maskviva/levilamina-rust-loader/issues","releases":"https://github.com/Maskviva/levilamina-rust-loader/releases","stars":1,"downloads":49,"updated":"2026-09-01T03:38:56Z","published":"2026-07-04T13:31:05Z","created":"2026-07-04T04:10:12Z","license":"Apache-2.0","side":["server"],"platform":["win-x64"],"gameVersions":["1.26.10"],"tags":["platform:levilamina","type:mod","type:loader"],"latest":{"variant":"","version":"1.0.0","install":"lip install github.com/Maskviva/levilamina-rust-loader@1.0.0"},"readmes":[{"file":"README.md","lang":"en","text":"# levilamina-rust-loader\n\n![levilamina-rust-loader](https://socialify.git.ci/Maskviva/levilamina-rust-loader/image?description=1&font=Raleway&forks=1&issues=1&language=1&logo=https%3A%2F%2Fraw.githubusercontent.com%2FLiteLDev%2FLeviLamina%2Frefs%2Fheads%2Fmain%2Fdocs%2Fmain%2Fcontents%2Flogo.svg&name=1&owner=1&pattern=Circuit+Board&pulls=1&stargazers=1&theme=Auto)\n\n![English](https://img.shields.io/badge/English-inactive?style=for-the-badge)\n[![中文](https://img.shields.io/badge/简体中文-informational?style=for-the-badge)](README.zh.md)\n\n**Teach [LeviLamina](https://github.com/LiteLDev/LeviLamina) to load Minecraft Bedrock Dedicated Server mods written in Rust.**\n\nThis repository is the *engine*: a C++ loader mod plus the two Rust crates\nthat speak its ABI. Install it once on your server, then any Rust mod is just\na `cargo build` away — no C++ toolchain, no xmake, no glue code on the mod\nauthor's side.\n\nLooking to **write** a mod instead of build the loader? Start from\n[**levilamina-mod-template-rs**](https://github.com/Maskviva/levilamina-mod-template-rs)\nand come back here only if you're curious how it works or want to contribute.\n\n## How it works\n\n```\n┌─────────────────────────── bedrock_server_mod.exe ───────────────────────────┐\n│  LeviLamina (C++)                                                            │\n│    └─ levilamina-rust-loader (this repo, C++, install once)                  │\n│         • registers a ModManager for manifest `\"type\": \"rust\"`               │\n│         • loads your cdylib, calls `levi_rs_main(api, handle, out_vtable)`   │\n│         • hands over a versioned C function table (LeviRsApi)                │\n│              ├─ events   : EventBus + DynamicListener ⇆ SNBT strings         │\n│              ├─ commands : RuntimeCommand overloads / console execution      │\n│              ├─ schedule : ServerThreadExecutor (thread-safe entry point)    │\n│              └─ logging  : per-mod LeviLamina logger                         │\n│    └─ your-mod (pure Rust cdylib, `\"type\": \"rust\"`)                          │\n└───────────────────────────────────────────────────────────────────────────────┘\n```\n\nDesign highlights:\n\n- **First-class mods.** Rust mods live in `plugins/<name>/` with a normal\n  `manifest.json`, participate in dependency sorting, and show up in\n  LeviLamina's mod listing like any other mod — because they *are* managed by\n  a real `ModManager`, not injected through a side door.\n- **One universal event channel.** LeviLamina's `DynamicListener` serializes\n  any event to a `CompoundTag`; the bridge round-trips it as SNBT, so Rust can\n  observe *and mutate/cancel* every event — including events published by\n  other mods — without per-event C++ bindings. Run `/levirs events` in-game to\n  dump every event id available on your server.\n- **Honest threading model.** Every callback runs on the server thread.\n  `Server::schedule{,_after}` are the only thread-safe entry points — exactly\n  the bridge you need for Tokio-based agents and services.\n- **Versioned, append-only C ABI** (`src/LeviRsAbi.h` is the single source of\n  truth, mirrored field-for-field by `crates/levilamina-sys`). The loader and\n  a mod refuse to pair on a version mismatch instead of risking UB.\n- **Panic-safe.** Every FFI boundary in the `levilamina` crate is wrapped in\n  `catch_unwind`; a panicking handler logs an error instead of taking down\n  the server.\n- **Unified memory allocator.** `src/MemoryOperators.cpp` routes this DLL's\n  `operator new`/`delete` through LeviLamina's allocator, same as any native\n  mod — required for the loader to be loaded at all.\n\n## Repository layout\n\n```\nsrc/                    C++ loader mod (compiles to levilamina-rust-loader.dll)\ncrates/levilamina-sys/  Raw #[repr(C)] FFI mirror of src/LeviRsAbi.h\ncrates/levilamina/      Safe, ergonomic Rust API built on levilamina-sys\ndocs/DESIGN.md          ABI + architecture decisions, evolution rules\ndocs/PORTING_NOTES.md   LeviLamina API call sites this bridge relies on\nxmake.lua               Builds the C++ mod (repo root doubles as the xmake project root)\nCargo.toml              Workspace for the two Rust crates (repo root doubles as the cargo workspace root)\n```\n\n`crates/levilamina-sys` and `crates/levilamina` are published from this repo\n(not the template repo) because they are versioned in lockstep with the C++\nloader — see [`docs/DESIGN.md`](docs/DESIGN.md) §8 for the ABI evolution\nrules. The C header and the `-sys` crate change in the same commit, always.\n\n## Installation (server admins)\n\n1. Install [LeviLamina](https://lamina.levimc.org/) on your BDS.\n2. Drop a `levilamina-rust-loader` release into `plugins/levilamina-rust-loader/`\n   (or build it yourself, see below).\n3. Install Rust mods into `plugins/<mod-name>/` — each one is a `.dll` +\n   `manifest.json`, same as any other LeviLamina mod.\n\n## Building the loader\n\nRequires [xmake](https://xmake.io) and a Visual Studio 2022 (or clang-cl)\ntoolchain, same as any LeviLamina native mod. **Pin `xmake.lua`'s\n`levilamina`/`bedrockdata`/`prelink` versions to what's actually running on\nyour server before building** — an unpinned `levilamina` can silently\nresolve to a newer SDK than your server's LeviLamina build, which shows up as\nconfusing compile errors (missing members, changed signatures) rather than a\nclear version-mismatch message.\n\n```shell\nxmake f -m release -y\nxmake\n```\n\nThe built mod (DLL + manifest) lands in `bin/`.\n\nTo also build/test the Rust crates in this workspace:\n\n```shell\ncargo build --workspace\ncargo test --workspace\n```\n\n## Writing a mod against this loader\n\nMost people should start from the\n[template repository](https://github.com/Maskviva/levilamina-mod-template-rs)\ninstead of wiring this up by hand. If you're adding `levilamina` to an\nexisting crate:\n\n```toml\n# Cargo.toml\n[lib]\ncrate-type = [\"cdylib\"]\n\n[dependencies]\nlevilamina = { version = \"1.0.0\", git = \"https://github.com/Maskviva/levilamina-rust-loader\" }\n# once published to crates.io: levilamina = \"0.1\"\n```\n\n```jsonc\n// manifest.json — goes next to your .dll in mods/<name>/\n{\n    \"name\": \"my-mod\",                       // must match the folder name\n    \"entry\": \"my_mod.dll\",                  // cargo output (hyphens → underscores)\n    \"type\": \"rust\",\n    \"platform\": \"server\",\n    \"dependencies\": [{ \"name\": \"levilamina-rust-loader\" }]  // guarantees load order\n}\n```\n\n## ABI stability\n\n`LEVI_RS_ABI_VERSION` gates compatibility. Within a major version, `LeviRsApi`\nonly grows (new fields appended at the end, gated by `struct_size`); it never\nreorders or removes fields. See [`docs/DESIGN.md`](docs/DESIGN.md) for the\nfull contract, including the threading model and string/memory ownership\nrules that every FFI call follows.\n\n## Current status & roadmap\n\nv0.1 is intentionally a **narrow, correct core** — the universal primitives\n(events / commands / scheduling / logging) from which everything else can be\nbuilt, since `execute_command` already reaches most of vanilla behaviour.\n\n- [ ] **v0.2** — structured SNBT: typed event views (`serde`-based), proper\n      NBT editing instead of string-level `cancel()`\n- [ ] **v0.2** — direct world access fast path (`get_block` / `set_block` /\n      region snapshots) without the command parser overhead\n- [ ] **v0.3** — player handles (send message/toast/form), form API\n- [ ] **v0.3** — Linux support (LeviLamina's Linux target is in progress\n      upstream)\n- [ ] **v0.x** — async-first API surface (`ServerHandle::run(async fn)` on top\n      of the scheduler), Tokio integration example, AI-agent example\n- [ ] procedural macro sugar: `#[levilamina::event]`, `#[levilamina::command]`\n\nContributions welcome — the ABI evolution rules are documented in\n[`docs/DESIGN.md`](docs/DESIGN.md).\n\n## FAQ\n\n**Why a C++ shim instead of pure Rust against LeviLamina?**\nLeviLamina's mod entry is plain C (`ll_mod_load` etc.), but everything\nuseful — events, commands, coroutine executors — is modern C++ (templates,\n`std::function`, C++20 coroutines) with no C export layer. The loader also\nenforces a unified memory-allocation contract that only code compiled against\nits headers can honestly satisfy. A thin, audited C++ layer that flattens\nthose APIs into a versioned C table is the correct engineering answer; \"pure\nRust\" would mean hand-written FFI against MSVC-mangled symbols — a\nre-implementation of LeviLamina itself.\n\n**Does this work on the client?** Untested; the loader targets\n`\"platform\": \"server\"`. LeviLamina's client support is newer territory.\n\n**Where's the mod template?**\n[`levilamina-mod-template-rs`](https://github.com/Maskviva/levilamina-mod-template-rs) —\nkept separate so \"start a new mod\" stays a one-click GitHub template, instead\nof forking this whole engine repo.\n\n**License:** Apache-2.0 (this repository). LeviLamina itself is LGPL-3.0; the\nloader mod links against it dynamically as a normal mod.\n\n---\n\n*Not affiliated with Mojang, Microsoft, or LeviMC. Minecraft is a trademark of\nMojang Synergies AB.*\n"}],"gallery":[],"versions":[{"version":"1.0.0","prerelease":false,"released":"2026-07-09T10:35:30Z","releaseUrl":"https://github.com/Maskviva/levilamina-rust-loader/releases/tag/v1.0.0","manifestUrl":"https://github.com/Maskviva/levilamina-rust-loader/blob/v1.0.0/tooth.json","info":{"name":"levilamina-rust-loader","description":"Loads LeviLamina mods written in Rust (manifest type: rust).","tags":["platform:levilamina","type:mod","type:loader"]},"variants":{"":[{"side":"server","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina":"26.10.14"}}]}},{"version":"0.1.3","prerelease":false,"released":"2026-07-05T18:27:34Z","releaseUrl":"https://github.com/Maskviva/levilamina-rust-loader/releases/tag/v0.1.3","manifestUrl":"https://github.com/Maskviva/levilamina-rust-loader/blob/v0.1.3/tooth.json","info":{"name":"levilamina-rust-loader","description":"Loads LeviLamina mods written in Rust (manifest type: rust).","tags":["platform:levilamina","type:mod","type:loader"]},"variants":{"":[{"side":"server","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina":"26.10.14"}}]}},{"version":"0.1.2","prerelease":false,"released":"2026-07-04T13:31:05Z","releaseUrl":"https://github.com/Maskviva/levilamina-rust-loader/releases/tag/v0.1.2","manifestUrl":"https://github.com/Maskviva/levilamina-rust-loader/blob/v0.1.2/tooth.json","info":{"name":"levilamina-rust-loader","description":"Loads LeviLamina mods written in Rust (manifest type: rust).","tags":["platform:levilamina","type:mod","type:loader"]},"variants":{"":[{"side":"server","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina":"26.10.14"}}]}}],"dependencies":{"github.com/liteldev/levilamina":{"id":"github.com/LiteLDev/LeviLamina","name":"LeviLamina","owner":"LiteLDev","url":"https://levimc.org/mods/github.com/LiteLDev/LeviLamina/"}},"requiredBy":[]}