Ferrumc

<p align="center"> <img src="https://github.com/ferrumc-rs/ferrumc/blob/master/assets/README/banner.png?raw=true" alt="FerrumC Banner"> </p> <div align="center"> <img src="https://img.shields.io/github/license/ferrumc-rs/ferrumc?style=for-the-badge&color=red" alt="License"> <img src="https://img.shields.io/github/languages/code-size/ferrumc-rs/ferrumc?style=for-the-badge&color=red" alt="Code Size"> <img src="https://www.aschey.tech/tokei/github.com/ferrumc-rs/ferrumc?style=for-the-badge&color=red" alt="Lines of Code"> <img src="https://img.shields.io/badge/language-Rust-orange?style=for-the-badge&color=red" alt="Language"> <a href="https://discord.gg/qT5J8EMjwk"> <img alt="Discord" src="https://img.shields.io/discord/1277314213878173726?style=for-the-badge&logo=discord&logoColor=red&color=red&link=https%3A%2F%2Fdiscord.gg%2FqT5J8EMjwk"> </a> </div>

📖 About

FerrumC is a 1.21.8 Minecraft server implementation written from the ground up in Rust. Leveraging the power of the Rust programming language, it is completely multithreaded and offers high performance as well as amazing memory efficiency!

Visit ferrumc.com for more information. The official Docs are currently under construction, but you can join our Discord server for help or to discuss the project!

<img src="https://github.com/ferrumc-rs/ferrumc/blob/master/assets/README/in_game.png?raw=true" alt="In-game screenshot">

🔗 Project Links

• Official Website: ferrumc.com
• Documentation: docs.ferrumc.com
• Discord Community: Join our Discord
• GitHub Repository: ferrumc-rs/ferrumc

✨ Key Features

<ul> <li> <h4>🛈 Customizable server list</h4> <img src="https://github.com/ferrumc-rs/ferrumc/blob/master/assets/README/server%20list.png?raw=true" alt="Server list"> </li> <li> <h4>🚄 Extremely fast </h4> <img src="https://github.com/ferrumc-rs/ferrumc/blob/master/assets/README/mind%20boggling.gif?raw=true" alt="Mind boggling"> </li> <li> <h4>🖥️ Highly efficient memory usage</h4> <img src="https://github.com/ferrumc-rs/ferrumc/blob/master/assets/README/mem_use.png?raw=true" alt="Low memory usage"> </li> <li> <h4>🗂️ Straightforward Configuration</h4> <img src="https://github.com/ferrumc-rs/ferrumc/blob/master/assets/README/config.toml.png?raw=true" alt="Configuration"> </li> <li> <h4>🔄 Can import existing worlds from vanilla minecraft</h4> <img src="https://github.com/ferrumc-rs/ferrumc/blob/master/assets/README/chunk_importing.gif?raw=true" alt="Configuration"> </li> <li> <h4>🌐 Compatible with vanilla Minecraft clients (Version 1.21.8)</h4> </li> <li> <h4>📦 Fully multithreaded; Utilizes all available CPU cores, instead of a single "main" thread</h4> </li> <li> <h4>📝 Custom made network, NBT and Anvil encoding systems to allow for minimal I/O lag</h4> </li> <li> <h4>💾 Crazy fast K/V database </h4> <i>32 render distance*</i> <img src="https://github.com/ferrumc-rs/site/blob/main/public/images/chunk_loading.gif?raw=true" alt="Chunk Loading DEMO"> </li> <li> <h4>🎮 Bevy ECS for smart, lockless concurrency driven by a massive community</h4> </li> </ul> <h2>✅ Upcoming features</h2> <ul> <li> <h4>PvE mechanics, and entities.</h4> </li> <li> <h4>Web based server dashboard</h4> </li> <li> <h4>Optimizations</h4> </li> <li> <h4>Plugin support (Rust via FFI currently, other languages will be considered later)</h4> </li> </ul>

Goals

• Performance: FerrumC aims to be the fastest Minecraft server implementation available, with a focus on low latency and high throughput.
• Memory Efficiency: FerrumC is designed to use as little memory as possible while still providing a full-featured server experience.
• Not just a faster replacement: FerrumC is not intended to be a perfect match for the vanilla server. We aim to improve on the original server in ways other than just performance. This includes things like setup and usage, configurability, plugins and more. Simply speeding up the server feels like a waste of the opportunity to do something new and exciting.
• Ease of Use: While it will certainly possible to run FerrumC as the backend for highly complex servers such as Hypixel through the use of plugins, the main intended audience is the average user who wants to run a server for their friends and family. We want to make it as easy as possible to set up and run a server, while still allowing the flexibility and power that advanced users need.
• Not taking the easy route: We aren't scared of a little unsafe Rust or some raw SIMD instructions. If we need to take some risks to get the performance we want, or need to write our own versions of libraries to get the features we need, we will do it. We already have custom-made Anvil and NBT libraries that use experimental APIs and some raw assembly because the existing ones just weren't up to scratch.

🚀 Getting Started

Prerequisites

• Rust compiler (latest nightly version)
• Cargo (comes with Rust)

📥 Installation

Unfortunately, the server is not yet ready for production use. We are still in the early stages of development and are working hard to add more features and fix bugs. For now, you can either compile the server from source or download from Github Actions.

[Option 1] Download from Github Actions

1. Go to the Actions tab
2. Click on the latest build
3. Scroll all the way down to the Artifacts section
4. Download the artifact for your operating system (Windows, Linux, or macOS)
5. Follow the instructions in the Usage section

[Option 2] Compile from source

Clone and build the project.

# Clone the repository
git clone https://github.com/ferrumc-rs/ferrumc
cd ferrumc

# Build the project
cargo build --release

The binary will be in target/release/

🖥️ Usage

Usage: ferrumc.exe [OPTIONS] [COMMAND]

Commands:
setup   Sets up the config
import  Import the world data
run     Start the server (default, if no command is given)
help    Print this message or the help of the given subcommand(s)

Options:
--log <LOG>  [default: debug] [possible values: trace, debug, info, warn, error]
-h, --help       Print help

1. Move the FerrumC binary (ferrumc.exe or ferrumc depending on the OS) to your desired server directory
2. Open a terminal in that directory
3. (Optional) Generate a config file: ./ferrumc setup
   • Edit the generated config.toml file to customize your server settings
4. Run the server:
   • Windows: .\ferrumc.exe
   • Linux/macOS: ./ferrumc
   • You can change logging level by using --log=<level>:
     • e.g. .\ferrumc.exe --log=info for info level logging
     • Possible values:
       • trace (Extremely verbose)
       • debug (Default, Slightly verbose, used for debugging)
       • info (Recommended, useful information)
       • warn (Only warnings)
       • error (Only errors)

[Option 3] Use Docker

1. You need to build the image : sudo docker build -t ferrumc:yourtag .
2. Then run it : docker run --rm -it -p 25565:25565 ferrumc:yourtag

🛠️ Development

We welcome contributions! If you'd like to contribute to FerrumC, please follow these steps:

1. Fork the repository
2. Create a new branch for your feature
3. Implement your changes
4. Write or update tests as necessary
5. Submit a pull request

Please join our Discord server to get help or discuss the project! Also have a look at our CONTRIBUTING.md file for more information.

🔍 Profiling with Tracy

FerrumC supports Tracy for profiling. To use it:

1. Install and run the Tracy profiler application
2. Build and run with the tracy feature:

   cargo run --release --features tracy
   

❔ FAQ

How does this project differ from:

• Valence: Valence is a framework for building your own custom server by pulling in different components of their library. FerrumC aims to be a full replacement for the vanilla server. It's like the difference between buying the ingredients to make a meal yourself or just buying a pre-made meal.
• Minestom: Same as Valence, it's a framework to build your own server, which is different to what we are trying to do.
• Paper/Spigot/Bukkit: These are all great tools and have undoubtedly set the groundwork for projects like this to exist, but ultimately they are still somewhat bound to the original server implementation. We aim to write the entire server from the ground up, hopefully giving us a leg up.
• Pumpkin: Pumpkin aims to match the vanilla server as closely as possible, often sacrificing performance and referencing decompiled vanilla code to achieve 1:1 parity. FerrumC prioritizes performance and takes a clean-room approach, building systems from scratch using modern architecture like ECS rather than translating existing implementations.

Will we be implemen