README.md

About • Features • Getting Started • Development • License • FAQ

Warning

FerrumC is currently going through a rewrite!
Please see the v3/rewrite branch.
The dev branch (default) will not be worked on and PRs will not be accepted. If you wish to contribute, see the v3 branch.

📖 About

FerrumC is a 1.20.1 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!

✨ Key Features

• 🛈 Customizable server list

  

• 🚄 Extremely fast and adaptable update speeds

  

• 🖥️ Highly efficient memory usage

  

• 🗂️ Customizable configuration

  

• 🔄 Can import existing worlds from vanilla minecraft

  

• 🌐 Compatible with vanilla Minecraft clients (Currently only 1.20.1)

• 💪 Powerful Entity Component System to handle high entity loads

  

  ECS Block Diagram (credits: Unity)

• 📦 Fully multithreaded; Utilizes all available CPU cores, instead of a single "main" thread

• 📝 Custom made network and NBT encoding system to allow for minimal I/O lag

• 💾 Lighting fast database to ensure extremely fast world loading speeds

  Currently using LMDB

  32 render distance*

✅ Upcoming features

• Ability to view other players

• World modification (place / break blocks etc)

• Chat & Command system

• Optimizations

• Plugin support (Javascript, Rust, and other WASM support languages)

🚀 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

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. Import an existing world: Place the region files (.mca) in the folder named import then run ./ferrumc --import.
   • The location of these files is explained here.
   • If you want to modify batch size (default 150), you can use ./ferrumc --import --batch_size=<num>.
     • Basically the number of chunks to import at once, higher => faster but more CPU intensive.
     • Max is 1024, since that's the max number of chunks in a region(.mca) file.
5. 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)

Note: You can specify the directory to treat as the root directory (the place where the config files, data files, etc. live) by setting an environment variable FERRUMC_ROOT to the path of the directory. For example, I run set FERRUMC_ROOT=C:\Users\ReCor\Documents\Code\Rust\ferrumc before running the server. This is useful if you can't move the place the binary is executed from (cargo run for example).

🛠️ 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!

❔ 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: It really doesn't differ that much. We are both trying to achieve the same thing. It's also not a competition, we are both aware of each other's progress and to be honest the Pumpkin team are doing really well. We won't tolerate any disrespect towards them as they are also undertaking the same monumental task.

Will we be implementing terrain generation?

Yes! Not currently on our list of priorities and it's very unlikely that we will be able to have 1:1 terrain generation with the vanilla server, but we do plan on implementing some sort of terrain generation as soon as we can.

Will there be plugins? And how?

We do very much plan to have a plugin system and as of right now, our plan is to leverage the awesome Extism project to allow for plugins to be written in a multitude of languages (Rust, Go, JS/TS, Zig and more) while not losing out on the performance gains of native code.

What does 'FerrumC' mean?

It's a play on words. Ferrum is the Latin word for iron and it rusts. And MC (Minecraft) in the end. So it becomes Ferrumc. Get it? 😄

📜 License

This project is licensed under the MIT License - see the LICENSE.md file for details.

🌟 Star History