Mudcrab

An open-source, high-performance game engine reimplementation compatible with The Elder Scrolls V: Skyrim (Special Edition) assets, built from the ground up in Rust using the Bevy Engine.

Inspired by open-source engine reimplementations like OpenMW, Mudcrab modernizes legacy Bethesda game formats (.esm, .bsa, .nif, .dds, .pex) into GPU-native, stream-friendly formats (glTF 2.0, KTX2 Basis, SQLite 3 / libSQL, Luau) to deliver 60+ FPS high-performance gameplay without loading screens.

• 🚀 Zero Loading Screens: Interior and exterior city transitions load 100% seamlessly in real time using libSQL spatial R-Tree indexing and rkyv zero-copy memory mapping.
• ⚡ High-FPS Vercidium Rendering: Batched instanced indirect draw calls (DrawMeshInstancedIndirect) reduce 5,000+ individual draw calls to under 100 per frame.
• 📜 Luau Scripting Engine (mlua): Replaces single-threaded Papyrus with sandboxed, JIT-compiled Luau scripts. Includes async HTTP networking for live web APIs (e.g. real-world weather sync mods).
• 📱 Cross-Platform (Desktop & Mobile): Native support for Windows, Linux, macOS (Apple Silicon), and Android (ARM64 / POCO F5).
• 🎨 Modern UI (Bevy 0.19 bsn!): Transpiles obsolete Flash (.gfx) menus into hardware-accelerated declarative Bevy UI node trees.
• 🎮 Integrated Mod Manager: Built-in launcher with drag-and-drop archive installation and priority-weighted .esp/.esl plugin load orders.

Mudcrab is organized into a modular Cargo workspace:

mudcrab/
├── Cargo.toml                  # Workspace Root Manifest
├── LEGAL.md                    # Legal & Trademark Disclaimers
├── crates/
│   ├── launcher/      # GUI Setup Wizard & Built-in Mod Manager
│   ├── converter/     # Asset Converter Pipeline (.nif ➔ .glb, .dds ➔ KTX2, .esm ➔ libSQL)
│   ├── shared/        # Versioned coordinate, database, and cell-cache contracts
│   ├── engine/        # Bevy Game Engine Binary (Render, Physics, Luau, Audio)
│   └── dummy-content/ # Synthetic mock asset generation for tests & CI

Mudcrab is being built systematically across 5 core phases. Explore the full roadmap specs in docs/roadmap/.

• Phase 1: Asset Modernization Pipeline (converter) — Transpile legacy .esm, .nif, .dds, and .pex into SQLite 3, glTF 2.0, KTX2, and Luau.
• Phase 2: Core Engine Runtime & Vercidium Renderer (engine) — Runtime, integration, profiling, and acceptance infrastructure implemented; complete real-asset sign-off remains pending.
• Phase 3: Luau Runtime, Declarative UI & Launcher (launcher) — Sandboxed Luau JIT with async web APIs, Flash-to-Bevy bsn! UI conversion, and setup wizard.
• Phase 4: Gameplay Mechanics, Physics & Persistence — Rapier 3D physics, animation blending, combat state machine, and sub-second save state snapshots.
• Phase 5: Hardware Ray-Tracing, Multiplatform & Networking — WebGPU/Vulkan RTGI, DLSS/FSR3 frame gen, native co-op multiplayer, Android ARM64, and OpenXR VR.

• Rust (2024 Edition)
• CMake & Ninja / GCC (for native libSQL / SQLite compilation)

1. Clone the repository:

   git clone https://github.com/Mudcrab-Team/mudcrab.git
   cd mudcrab

2. Check workspace compilation:

   cargo check --workspace

3. Run the Launcher App:

   cargo run -p launcher

Choose Skyrim Data to convert the physical Data folder, or MO2 profile to overlay a Mod Organizer 2 profile. Open MO2 settings, drop the instance folder containing ModOrganizer.ini, and select a detected profile from the dropdown (MO2's active profile is selected by default, falling back to the first detected profile). The Skyrim Data folder is still required as the base. Close settings before dropping the output folder. Source settings apply to Start and Resume and are selected per launcher session. MO2 sources are read in place; native SKSE plugins are not supported. Instances must declare a supported Skyrim gameName. Configured directories may resolve through junctions, but profile, enabled-mod, and asset reparse points are rejected.

cargo run -p converter --bin converter -- repair-failed "<Skyrim Data>" "<output directory>" --mo2-instance "<MO2 instance>" --mo2-profile "<profile>"

This reads the original manifest and stages failed inputs, assets from failed archives, and necessary texture and skeleton dependencies in a unique <output>/.repair-<pid>-<timestamp> directory. Loose MO2 files are read in place. Repair stages the pack for validation, linking unchanged assets where supported, re-finalizes skyrim_world.db to update mesh bounds, and re-runs integration; it does not rebuild the world from plugins. Allow disk space for repaired assets, rewritten metadata, and copies where hard links are unavailable. Omit the MO2 options for physical Data.

The default is a preview: inspect repair-report.json and the staged assets/ folder; the published pack is unchanged except when recovering an earlier interrupted publication. Repeat with --apply to validate existing artifact hashes and publish the repairs. Conversion and repair share exclusive output locking and cannot run while the engine holds its runtime read lock. Publication writes a rollback journal before replacing files and updates the manifest last; the next conversion or repair recovers an interrupted repair. Publication is recoverable, not atomic for readers that do not acquire the lock.

The configuration must match the original conversion, and unresolved failures or failed integration prevent publication. Supply the original encoding settings when needed: --texture-encoder, --texture-fallback-quality, --texture-uastc-level, and --texture-zstd-level (and the corresponding GPU options). GPU repair uses the same GPU encoding worker as conversion, including configured quality and CPU fallback. Changes to MO2 window settings or disabled mod entries do not invalidate the whole conversion cache; winning asset and plugin changes are tracked separately.

Compatibility changes also apply to physical Data-folder conversion: BodySlide/Outfit Studio resources under CalienteTools are excluded as authoring data, the manifest records excluded_inputs, and unsupported NIF versions are rejected explicitly. Particle-size parsing and dynamic-shape recovery restore geometry that was previously omitted.

Dynamic head, hair, and eye meshes now produce geometry. The PR #154 review reports total GLB size increasing from 209 MB to 451 MB; these are reviewer-provided measurements, not a benchmark reproduced here. The script snapshot delta came from instruction dispatch chunking, not the Mudcrab header rename, which was already in main.

The converter copies textures whose DDS blocks a GPU can sample directly (DXT1–DXT5, BC1–BC7) into KTX2 unchanged. Ordinary source textures that need encoding use the CPU by default: uncompressed 8-bit RGB(A) (24-bit, X8R8G8B8, A8R8G8B8, A8B8G8R8, DXGI BGRA/BGRX) is block-compressed to native BC7, and the remaining textures are encoded to UASTC (Basis Universal). With --texture-encoder gpu a wgpu compute shader encodes every texture it takes, uncompressed RGB(A) included, to UASTC instead, writing KTX2 with the same Zstandard supercompression, so the engine needs no changes:

cargo run --release -p converter -- "<Skyrim Data>" "<output directory>" --texture-encoder gpu

Measured by the encoder's author on a full Skyrim SE conversion (Ryzen 5 5600G, RTX 5090, NVMe), from scratch:

The CPU timings were measured before the CPU path wrote native BC for uncompressed textures (as of #119); they describe UASTC encoding on the CPU.

On the author's 20 sample textures, quality was about 0.3–0.5 dB PSNR below the CPU encoder's UASTC level 2, both after BC7 transcoding (desktop) and as ASTC (mobile). The comparison tool is not part of this repository, so treat these figures as indicative.

• --gpu-quality N — endpoint refinement passes, 0–8 (default 2).
• --gpu-batch-mb N — source megabytes packed into one GPU dispatch (default 256).

Textures the GPU path cannot take (volume textures, formats it cannot decode) use the CPU encoder, as does the whole run when no hardware GPU is available. If the GPU fails mid-run (a driver error or a lost device), everything it had not finished is encoded on the CPU instead. Encoded textures are cached separately per encoder, so switching it reconverts only them; copied textures and meshes are reused.

Generated terrain LOD atlases use the GPU by default in new CLI runs and PipelineConfig::new. Their encoder is independent of ordinary source textures, which still default to CPU. To use the GPU for both:

cargo run --release -p converter -- "<Skyrim Data>" "<output directory>" --texture-encoder gpu --cpu-jobs 8 --io-jobs 4

Use --lod-encoder cpu to select CPU terrain encoding. Existing serialized configs without lod_texture_encoder retain the legacy CPU setting.

--gpu-quality and --gpu-batch-mb apply to both GPU encoders. Terrain batches are also bounded by --cpu-jobs, and their GPU slots cap the batch budget at 64 MiB. GPU terrain encoding preserves the three authored atlas mips, tile gutters and sRGB transfer function. Switching encoder recipes or changing GPU quality rebuilds affected LOD atlases; batch-size changes preserve their cache proof. A GPU failure falls back to CPU encoding and is recorded in the report. Fallback chunks have no GPU reuse proof, so a later GPU run retries them. Explicit CPU selection produces the CPU recipe and its reuse proof instead.

Archive extraction uses --cpu-jobs for decoding and --io-jobs for writers. By default it selects runtime inputs and English string banks; --extract-all-archive-files keeps every archive entry. The default --ingestion-sync archive seals flushed cache batches before creating derived files. per-file additionally flushes unique derived payloads; none skips fresh extraction flushes and requires verified reuse. Resuming validates those batches and reconstructs missing or damaged files; archive ordering still determines which override wins. Containing directories are also flushed on Unix; portable directory flushing remains a Windows limitation.

For detailed technical specifications, format breakdowns, and architectural guidelines, explore the docs/specs/ directory:

• architecture.md — Core engine architecture overview & phase milestones.
• nif-to-gltf.md — 3D mesh converter specification (mesh-tools).
• dds-to-ktx2.md — Texture compressor specification (basis-universal + ddsfile).
• esm-to-sqlite.md — Master database specification (libSQL + rkyv).
• pex-to-lua.md — Papyrus bytecode to Luau transpilation spec (mlua).
• mods-and-ui.md — Integrated Mod Manager & Flash-to-Bevy UI strategy.
• launcher.md — First-run setup wizard & launcher workflow.
• vercidium-optimizations.md — High-FPS GPU instancing & HZB culling.
• platforms.md — Target matrix for Desktop, Mobile ARM64, and WebGPU.
• requirements.md — Hardware system specs and optimization analysis.
• features.md — Unlocked capabilities (Zero-loading screens, AI dialogue, native co-op).
• bevy-examples.md — Mapping official Bevy 0.19 patterns to engine subsystems.

We welcome community contributions! Whether you're fixing bugs in asset converters, enhancing Bevy rendering pipelines, or writing documentation, check out our guidelines before submitting a PR:

• 📖 CONTRIBUTING.md — Guide on development workflow, code style (cargo fmt/clippy), and PR guidelines.
• 📜 LEGAL.md — Intellectual property policy and compatibility guidelines.
• 🐛 Issue Tracker — Search existing issues or report a new bug using our template.

Mudcrab is dual-licensed under either of the following licenses at your option:

• MIT License (LICENSE-MIT)
• Apache License, Version 2.0 (LICENSE-APACHE)

Mudcrab is an independent open-source game engine reimplementation. It does not contain or distribute any copyrighted game assets, artwork, 3D models, audio, or game data belonging to Bethesda Softworks LLC or ZeniMax Media Inc. Users must supply their own legally owned copy of The Elder Scrolls V: Skyrim to extract game data.

All trademarks are the property of their respective owners and are used strictly under nominative fair use for compatibility description. Read the full statement in LEGAL.md.