README.md

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

📖 About

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

Docs are currently under construction, but you can join our Discord server for help or to discuss the project!

✨ 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.21.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, NBT and Anvil encoding systems to allow for minimal I/O lag

• 💾 Multiple database options to finetune the server to your needs

  32 render distance*

✅ Upcoming features

• Ability to view other players

• World modification (place / break blocks etc)

• Chat & Command system

• Optimizations

• Plugin support (JVM currently, other languages will be considered later)

🚀 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: Either copy your world files to the server directory or specify the path to the world files in the config.toml file. This should be the root directory of your world files, containing the region directory as well as other folders like DIM1, playerdata, etc. The default import path is import so you should end up with a directory structure like this:

   server_directory
   ├── config.toml
   ├── ferrumc.exe
   ├── import
   │   ├── region
   │   │   ├── r.0.0.mca
   │   │   ├── r.0.1.mca
   │   │   ├── ...
   │   ├── DIM1
   │   ├── playerdata
   │   ├── ...
   

   • The location of these files is explained here.
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)

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

❔ 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 JVM to allow for plugins to be written in Kotlin, Java, or any other JVM language. We are also considering other languages such as Rust, JavaScript and possibly other native languages, but that is a fair way off for now.

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