Skip to content

Architecture

This document provides an overview of LeviLamina's project structure, design principles, and architectural decisions.

Project Structure

Top-Level Directories

Text Only
1
2
3
4
5
6
7
8
9
LeviLamina/
├── src/              # Common + Server code
├── src-client/       # Client-specific code
├── src-server/       # Server-specific code
├── src-test/         # Test code
├── docs/             # Documentation
├── scripts/          # Build and utility scripts
├── builder/          # Header generation scripts
└── bin/              # Build output

Source Directory Organization

src/ — Common + Server

Contains code shared between server and client, plus server-only implementations:

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
src/
├── ll/
│   ├── api/          # Public API (255 headers)
│   │   ├── base/     # Foundation types
│   │   ├── command/  # Command system
│   │   ├── event/    # Event system
│   │   ├── form/     # UI forms
│   │   ├── mod/      # Mod management
│   │   ├── service/  # Service registry
│   │   └── ...       # Other modules
│   └── core/         # Internal implementation (34 files)
│       ├── mod/      # Mod loading
│       ├── command/  # Built-in commands
│       ├── form/     # Form handlers
│       └── tweak/    # Game tweaks
└── mc/               # Bedrock headers (反编译)
    ├── server/
    ├── world/
    ├── network/
    └── ...

src-client/ — Client-Only

Client-specific extensions and overrides (28 files):

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
src-client/
├── ll/
│   ├── api/
│   │   ├── KeyRegistry.h      # Input binding
│   │   ├── KeyHandle.h
│   │   └── event/
│   │       ├── input/         # Input events
│   │       ├── render/        # Render events
│   │       └── client/        # Client lifecycle
│   └── core/
│       └── (8 files)          # Client implementations
└── mc/
    └── client/                # Client-specific BDS headers

src-server/ — Server-Only

Server-specific extensions (5 files):

Text Only
1
2
3
4
5
6
7
8
9
src-server/
├── ll/
│   ├── api/
│   │   ├── event/server/      # Server events
│   │   └── service/           # Server services
│   └── core/
│       └── (10 files)         # Server implementations
└── mc/
    └── server/                # Server-specific BDS headers

Layered Architecture

Layer 1: mc/ — Bedrock Engine Headers

  • Source: Reverse-engineered from Minecraft Bedrock Dedicated Server
  • Purpose: Provides C++ interfaces to game internals
  • Maintenance: Generated by header_generator tool from BedrockAnalyzer dumps
  • Scope: Read-only, not modified by LeviLamina

Key Namespaces: - ::Actor, ::Player, ::Mob — Entity system - ::Level, ::Dimension, ::BlockSource — World management - ::ServerInstance, ::Minecraft — Server lifecycle - ::CommandRegistry, ::Command — Command system - ::Packet, ::NetworkIdentifier — Networking

Layer 2: ll/core/ — Internal Implementation

  • Purpose: Implements LeviLamina's core functionality
  • Visibility: Internal, not exposed to mods
  • Dependencies: Uses mc/ headers and ll/api/

Key Components: - ModRegistrar — Mod lifecycle management - NativeModManager — DLL loading - Built-in Commands — /version, /ll, /tpdim, /crash - CrashLogger — Exception handling and Sentry integration - Tweaks — Game modifications (vulnerability fixes, memory allocator, etc.)

Layer 3: ll/api/ — Public API

  • Purpose: Stable API for mod developers
  • Visibility: Exported via LLAPI/LLNDAPI macros
  • Versioning: Semantic versioning with compatibility guarantees

Design Principles: - Type-safe: Heavy use of C++20 concepts and type traits - Error handling: Expected<T> for recoverable errors - Async support: Coroutines and executors - Reflection: Compile-time reflection for serialization - Event-driven: Publish-subscribe event system

Module Dependencies

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
┌─────────────────────────────────────────┐
│           Mod Code (User)               │
└─────────────────┬───────────────────────┘
                  │ uses
┌─────────────────▼───────────────────────┐
│          ll/api (Public API)            │
│  ┌──────────┐  ┌──────────┐  ┌────────┐│
│  │ Command  │  │  Event   │  │  Form  ││
│  └──────────┘  └──────────┘  └────────┘│
│  ┌──────────┐  ┌──────────┐  ┌────────┐│
│  │   Mod    │  │ Service  │  │ Memory ││
│  └──────────┘  └──────────┘  └────────┘│
└─────────────────┬───────────────────────┘
                  │ implements
┌─────────────────▼───────────────────────┐
│        ll/core (Implementation)         │
│  ┌──────────────┐  ┌──────────────────┐ │
│  │ ModRegistrar │  │ NativeModManager │ │
│  └──────────────┘  └──────────────────┘ │
│  ┌──────────────┐  ┌──────────────────┐ │
│  │ CrashLogger  │  │  Built-in Cmds   │ │
│  └──────────────┘  └──────────────────┘ │
└─────────────────┬───────────────────────┘
                  │ uses
┌─────────────────▼───────────────────────┐
│      mc/ (Bedrock Engine Headers)      │
│  ┌──────────┐  ┌──────────┐  ┌────────┐│
│  │  Player  │  │  Level   │  │ Packet ││
│  └──────────┘  └──────────┘  └────────┘│
│  ┌──────────┐  ┌──────────┐  ┌────────┐│
│  │ Command  │  │ Server   │  │ Network││
│  └──────────┘  └──────────┘  └────────┘│
└─────────────────────────────────────────┘

Server vs Client Builds

Build Configuration

Controlled by --target_type in XMake:

Lua
1
2
3
4
-- xmake.lua
option("target_type")
    set_default("server")
    set_values("server", "client")

Compilation Differences

Aspect Server Build Client Build
Source Files src/ + src-server/ src/ + src-client/
BDS Headers bedrockdata:server.8 bedrockdata:client.9
Entry Point DllMain (server) DllMain (client)
API Surface Common + Server Common + Client
Output LeviLamina.dll (server) LeviLamina.dll (client)

API Availability

Module Server Client Notes
Base ✅ ✅ Common
Command ✅ ✅ Common
Event (Player/World) ✅ ✅ Common
Event (Server) ✅ ❌ Server-only
Event (Client/Input/Render) ❌ ✅ Client-only
Form ✅ ✅ Common
Input ❌ ✅ Client-only
Service (Bedrock) ✅ ✅ Common (different implementations)

Runtime Behavior

Server: - Loaded by PreLoader into bedrock_server_mod.exe - Hooks server initialization - Provides server-side events and services

Client: - Loaded by PreLoader into Minecraft.Windows.exe - Hooks client initialization - Provides client-side input, rendering, and UI

Design Patterns

Singleton Pattern

Used for global registries: - EventBus::getInstance() - CommandRegistrar::getInstance() - ServiceManager::getInstance() - ModManagerRegistry::getInstance()

Factory Pattern

Used for dynamic object creation: - PacketRegistrar — Packet factories - EventBus::setEventEmitter() — Event emitter factories

Observer Pattern

Implemented via event system: - EventBus — Subject - Listener — Observer - Event — Notification

Dependency Injection

Implemented via service system: - ServiceManager — Container - Service — Injectable component - subscribeService() — Dependency resolution

Memory Management

Allocation Strategy

  • mimalloc — Default allocator for performance
  • Smart pointers — std::shared_ptr, std::unique_ptr for ownership
  • optional_ref — Non-owning references to Bedrock objects

Hook Management

  • HookRegistrar — Automatic hook registration/cleanup
  • Priority system — Control hook execution order

Thread Safety

Thread Model

  • Server thread — Main game loop (single-threaded)
  • Thread pool — Background tasks
  • Network threads — Packet handling

Synchronization

  • ServerThreadExecutor — Execute on server thread
  • ThreadPoolExecutor — Execute on background threads
  • Atomic operations — Lock-free where possible
  • Mutexes — Protect shared state