Architecture

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

Project Structure

Top-Level Directories

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:

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):

src-client/
├── ll/
│   ├── api/
│   │   ├── input/
│   │   │   ├── 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):

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

┌─────────────────────────────────────────┐
│           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:

-- xmake.lua
option("target_type")
    set_default("server")
    set_values("server", "client")

Compilation Differences

API Availability

Runtime Behavior

Server: - Loaded by PreLoader into bedrock_server_mod.exe (generated from bedrock_server.exe by PeEditor during installation; the original is kept as bedrock_server.exe.bak) - Hooks server initialization - Provides server-side events and services

Client: - Loaded by PreLoader into Minecraft.Windows.exe (patched in place by PeEditor during installation; the original is kept as Minecraft.Windows.exe.bak) - Hooks client initialization - Provides client-side input, rendering, and UI

Design Patterns

Singleton Pattern

Used for global registries: - EventBus::getInstance() - CommandRegistrar::getInstance(bool isClientSide) - 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

Related

• Build Guide — Building from source
• API Reference — Complete API documentation