[!IMPORTANT]

🚧 A fresh rewrite of FerrumC is in the works

We're rebuilding FerrumC from scratch on the rework/v2-skeleton branch, and we plan to merge it into master soon. What works so far:

• A cleaner, faster core that's much easier to build on.
• A flat creative world you can join with a normal Minecraft 1.21.8 client. Blocks like logs, slabs, stairs, fences, and doors place facing the right way, and signs and chests work.
• Area edit commands such as /fill, /replace, and /undo.
• A day and night cycle, and you can watch other players turn, look around, and hold items and armor.
• Your builds are saved when you leave, rejoin, or restart the server, and you can import an existing vanilla world.
• Plugins, written in Rust, that can allow, block, or change what players build.
• A local-only web dashboard for keeping an eye on the server.

It's early, offline-mode alpha: a creative and minigame server, not survival, not vanilla-accurate, and not a drop-in replacement for Paper or Spigot. Want to follow along or lend a hand? Come poke at the branch above.

📖 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!

🔗 Project Links

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

✨ Key Features

• 🛈 Customizable server list

  

• 🚄 Extremely fast

  

• 🖥️ Highly efficient memory usage

  

• 🗂️ Straightforward Configuration

  

• 🔄 Can import existing worlds from vanilla minecraft

  

• 🌐 Compatible with vanilla Minecraft clients (Version 1.21.8)

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

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

• 💾 Crazy fast K/V database

  32 render distance*

• 🎮 Bevy ECS for smart, lockless concurrency driven by a massive community

✅ Upcoming features

• PvE mechanics, and entities.

• Web based server dashboard

• Optimizations

• Plugin support (Rust via FFI currently, other languages will be considered later)

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.

Tagged Releases

Tagged releases publish a Docker image and pre-built binaries for each supported platform. This applies to every release, so the steps below are the same regardless of version.

Docker (Recommended)

docker pull ghcr.io/ferrumc-rs/ferrumc:<version>
docker run -p 25565:25565 ghcr.io/ferrumc-rs/ferrumc:<version>

Or use Docker Compose:

services:
  ferrumc:
    image: ghcr.io/ferrumc-rs/ferrumc:<version>
    ports:
      - "25565:25565"
    restart: unless-stopped

Native Binaries

Download the binary for your platform from the Releases page, then run it directly:

# Linux/macOS
chmod +x ferrumc-*
./ferrumc-*

# Windows
.\ferrumc-*.exe

Each binary ships with a SHA256 checksum file you can use to verify the download:

# Linux/macOS
shasum -a 256 -c ferrumc-*.sha256

# Windows PowerShell
Get-FileHash ferrumc-*.exe -Algorithm SHA256

[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 implementing terrain generation?

Yes! We currently have some very rudimentary terrain generation and vanilla terrain is currently being worked on. However, we will be implementing optimizations and cutting corners to improve performance. This could lead to the world not being exactly the same as vanilla and differences may not be fixed if they would lead to performance issues that we deem to outweigh the benefits of vanilla accuracy. That being said, we will try to make it as close to vanilla as possible without sacrificing performance.

Will there be plugins? And how?

We do very much plan to have a plugin system and as of right now we are planning to use some kind of FFI (foreign function interface) to allow for plugins to be written in Rust. Plugins are not our top priority right now, and we want to make sure the API is designed well before we start implementing it to avoid breaking changes later. We are open to suggestions and ideas from the community on how to best implement this.

Will I be able to use plugins or mods from paper/spigot/bukkit/forge/fabric etc.?

No. Even if we did implement a perfect 1:1 API match for the vanilla server, the underlying implementation is still completely different. Java plugins and mods rely heavily on Java features such as reflection and dynamic class loading, which simply aren't possible in Rust. If we made a Java translation layer, it would be extremely slow and only the most basic plugins and mods would work. If a plugin or mod is basic enough to work through a translation layer, it would be much better to just rewrite it in Rust for performance and compatibility reasons.

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

📊 Stats