Repo ↗ · Source README ↗ · Markdown & license bundle

Image reference (original game): The Elder Scrolls V: Skyrim - Special Edition · original-game artwork, provided by IGDB. Image rights remain with their respective owners. This illustrates the referenced original game, not the actual visuals of this rewrite or mod.

Source maintainer: Mudcrab-Team · Revision: 0f48d2965c05 · Catalogued: 2026-10-12

Source license: MIT · LICENSE-APACHE · LICENSE-MIT · Article: Source README (format adapted)

The source README follows, with formatting adapted for this site and images replaced by source links. Feature, completion and testing claims belong to its authors and have not been independently playtested here. The Traditional Chinese translation was prepared with AI assistance.

Mudcrab

README image：CodeRabbit Pull Request Reviews
[README image：Rust](https://www.rust-lang.org/)
[README image：Engine](https://bevyengine.org/)
[README image：License: MIT](https://github.com/Mudcrab-Team/mudcrab/blob/0f48d2965c057dcfeb5ae7fe73b3b845b95dce93/LICENSE-MIT)
[README image：License: Apache 2.0](https://github.com/Mudcrab-Team/mudcrab/blob/0f48d2965c057dcfeb5ae7fe73b3b845b95dce93/LICENSE-APACHE)
[README image：CI Status](https://github.com/Mudcrab-Team/mudcrab/blob/0f48d2965c057dcfeb5ae7fe73b3b845b95dce93/README.md#-quick-start-development-setup)
[README image：Platforms](https://github.com/Mudcrab-Team/mudcrab/blob/0f48d2965c057dcfeb5ae7fe73b3b845b95dce93/docs/specs/meta/platforms.md)

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.

[!IMPORTANT]
Legal Disclaimer: Mudcrab is an independent open-source project and is not affiliated with, endorsed by, or connected to Bethesda Softworks LLC, ZeniMax Media Inc., or Microsoft Corporation. “The Elder Scrolls” and “Skyrim” are registered trademarks of Bethesda Softworks / ZeniMax Media. This repository distributes no proprietary game assets. A legally purchased copy of the original game is required to supply game data. See LEGAL.md for full legal notices.

✨ Features & Architecture Highlights

  • 🚀 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.

🏗️ Workspace Crate Architecture

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
Crate Responsibilities
launcher First-run setup wizard, game path detection, built-in mod manager UI, triggers converter progress bar, and launches the engine.
converter Heavy offline asset converter (mesh-tools, basis-universal, ddsfile, nom binary parsers).
shared Versioned contracts shared by conversion and runtime, including coordinates and the terrain cell cache.
engine Lightweight, hyper-fast game binary (Bevy 0.19+, wgpu, libsql, mlua Luau JIT).
dummy-content Procedural, synthetic asset fixtures for automated testing without proprietary game files.

🗺️ Project Roadmap

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

🚀 Quick Start (Development Setup)

Prerequisites

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

Building & Running

  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.

Repair a failed conversion without rebuilding the world

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--<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.

Asset compatibility changes

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.

GPU texture encoding

The converter copies textures whose DDS blocks a GPU can sample directly (DXT1–DXT5, BC1–BC7) into KTX2 unchanged. Everything else, mainly Skyrim’s uncompressed terrain and LOD textures, is converted on 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:

CPU encoder GPU encoder
Whole conversion 28 min 08 s 8 min 55 s
Texture stage (10,236 encoded, 22,709 copied) 20 min 37 s 1 min 29 s

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.

📚 Technical Specifications (docs/specs/)

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

🤝 Contributing

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.

⚖️ Legal Disclaimer & License

Licensing

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

Legal Notice & Trademark Disclaimer

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.

License and provenance

The README and its translation retain MIT terms. Changes comprise translation, links and formatting. Editable Markdown, the original README, LICENSE and NOTICE files are included in the linked bundle. This grants no rights to the original games, their assets or trademarks.

LICENSE-APACHE

Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

LICENSE-MIT

MIT License

Copyright (c) 2026 Mudcrab Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.