Updated on 05 November 2019, Commit: 0348ac5
This is the Cuberite User's Manual. It is intended as a guide on how to operate the basics of Cuberite, as well as an introduction to some advanced features. It is organised into major sections as well as more detailed subsections and these are laid out in the Table of Contents. The first section deals with downloading, installing, and running Cuberite. The second section is an overview of configuring Cuberite. Reading those two sections is enough to get you started. The remaining sections cover more advanced features and further configuration options in greater depth.
As with Cuberite itself, this manual is in active development, and you can contribute yourself or file an issue if you find an error or ommission on the GitHub Repository. If you're using a printed version, note that the latest version of this manual is always available online.
Cuberite is a Free and Open Source (FOSS) Minecraft-compatible Game Server. Cuberite is designed with performance, configurability, and extensibility in mind, and also aims to accurately recreate most vanilla features. Cuberite is written in C++, and there is an extensive plugin system that allows for the user to write their own plugins with Lua. In fact, many of the built in commands are implemented by the Core plugin, which has its own GitHub repository and developer community. For more information on the plugin system and how to use it, as well as how to develop for it, please see Plugins.
Cuberite today is maintained by a large team of contributors and plugin developers. If you want to reward the developers for their work, you should set up a donation on Bountysource with a credit card, bitcoin or other currency.
Cuberite was created in late 2010 by FakeTruth with its original name "MCServer", as a replacement for the vanilla server, designed to be better performing and more configurable. It was soon open-sourced and developers started working.
In the summer of 2013, the main MCServer repository was moved from Google Code to GitHub, and a new build system was introduced. Several new developers also joined the project around that time, and the project began to increase in members and popularity.
As of late 2014, MCServer had a team of more than 10 regular developers, and the codebase had grown to over 125,000 lines (excluding comments, blank lines and external libraries). Many new features were also introduced in 2014:
In 2015, many new developers joined the project, and the community decided to adopt the current name of Cuberite. As of late 2015, Cuberite has over 1000 stars on GitHub.
For Windows, Linux, Raspberry Pi or Mac builds, the main download location is the official homepage, with the latest builds available. For developers who want more control over the builds they download, visit the buildserver.
On Linux, macOS, FreeBSD or Raspberry Pi, you can simply paste this command into your terminal to install Cuberite:
Once you have downloaded Cuberite, you can skip straight to Running Cuberite.
Pre-compiled builds are faster to install and easier to use than compiling the source yourself, and are recommended for beginners. However, for some unusual hardware for which no pre-compiled build exists it may be necessary to compile the code yourself. Compiling yourself also has a significant performance advantage on modern machines. If you know how to use the command line or want extra speed you should compile Cuberite yourself.
Compiling yourself takes longer and is more involved, but on modern processors can lead to a speed increase of up to 1.5 to 3x. If your operating system or hardware is not officially supported, compiling may be the only way to run Cuberite.
The automatic compilation script is recommended for *nix users. Windows users should see the Other Systems subsection for instructions. The automatic compilation script takes care of the compilation process for you. You only need to copy this command to your terminal:
The rest of this section is for those who prefer to manually compile.
Compiling on Linux and related operating systems is easy and simple, although it does require some tools before you can get started. You need a C++ compiler (Clang++ or G++), a C compiler (Clang or GCC), Git, CMake and Make. A simple command to make sure these tools are installed (Ubuntu/Debian) is:
Once the tools are installed, you should clone the Git repo:
You should then run the CMake process and compile:
Once the compilation process is finished, the Cuberite executable will be placed inside the
Server inside the repository that you downloaded. You can copy this folder anywhere you like, just make sure to copy the supporting files otherwise the server will not work properly.
For compiling on Windows or other systems, please see COMPILING.md in the main repository.
Cuberite's build process supports a large number of flags for customising the builds.
Use these flags by adding
-DFlag_name=Value to the cmake configuration command. For example to enable test
generation using the
SELF_TEST flag add:
ONto enable. Define as
ONto enable. Define as
ctestand with makefiles
make test. Define as
ONto enable. Define as
ONto enable. Define as
ONto enable. Define as
Once you have a compiled copy of Cuberite, with the supporting files (in most cases these are distributed with the executable, in a directory called Server), you can run the server and generate yourself a world. It's easy to run the server, although the method varies depending on the operating system you are using.
To run Cuberite on Windows, just double click on the executable. A command window will come up, and the world will generate.
To run Cuberite on Linux, Mac or FreeBSD, just run the executable in your shell:
Just like Vanilla, once you've started Cuberite, you can join the server on
localhost:25565, or just
localhost in your minecraft client.
Cuberite can be configured by editing various files. Below is a list of all such files:
http://<Server IP address>:8080by default.
world.inifile, each stored in
Permissions allow different players to access different commands and features.
Each plugin has its own permissions. Setting up player permissions is most easily done via the web admin.
You can also use the
rank <playername> command from the server console.
Note that there is no leading slash. The console command is not
To see the command and permissions list for the default commands, which are provided by the Core plugin,
see the Core Plugin readme.
The WebAdmin allows you to control various aspects of Cuberite, including player permissions.
webadmin.ini configuration looks like this:
In the example above, you can login to the web admin using the username
john and the password
cuberiteRocks by pointing your browser to
http://<Server IP address>:8080. If you're running your server locally, point your browser to
By default, there are three worlds:
Each world can be tweaked by editing
You can use this file to edit things like the spawn point location, the game mode, and the diffculty level.
See Configuring world.ini for details.
Plugins are an important method of customisation for Cuberite. There are many different first and third-party plugins available.
Cubrite plugins are written in Lua, and interact with the server through an extensive API. They are designed to be easy to write for anyone with basic programming experience, so if existing plugins don't fill your need you can easily write your own plugins. If you want to learn how to write your own plugins, check out the guide.
Cuberite has a plugin repository where you can upload your plugins publicly and download plugins others have released.
After downloading a plugin, you need to put it in the
You should then edit the
[Plugins] sections of the
settings.ini file and add a plugin entry there.
Below is an example of adding a plugin called
If you have read this far, you should now have enough knowledge to operate a Cuberite server. The rest of this book covers more features and further configuration options in greater depth.
It is possible to configure many different aspects of individual worlds with Cuberite. Configuration options include:
All this configuration can be done through one file. It is called
world.ini and can be found in each world's individual folder. When a world is first created by Cuberite, the file is filled out with default values that are fairly close to vanilla minecraft.
world.ini file is split into many different sections, each with a name surrounded in square brackets. For example
[SpawnPosition] is a section. Each section contains configuration options related to a specific feature of Cuberite.
Specifies the spawn point for new players. The coordinates are absolute, in blocks, and may be fractional. If any of the values are missing, Cuberite provides a default.
|X||X coordinate of the spawn point||32|
|Y||Y coordinate of the spawn point||The height of the terrain at the point (X, Z)|
|Z||Z coordinate of the spawn point||32|
This section specifies if the world is a Survival, Creative, Adventure or Spectator mode world. An administrative in-game command may override this setting temporarily.
|GameMode||0 means Survival mode, 1 means Creative mode, 2 means Adventure mode, 3 means Spectator mode||1|
This section specifies if Cuberite should save world chunks or not, as well as the compression level for world files.
|Schema||Specifies if world chunks should be saved or not. May be one of "Default", "Anvil" and "Forgetful". See table below for their description.||Default|
|CompressionFactor||How much the world files should be compressed. Lower values mean much larger file sizes, but slighly increased performance, and higher values mean slightly smaller file sizes and much lower performance. It is recommended just to keep with the default.||6|
|Default||.mca||This is just an alias for Anvil at the moment.|
|Anvil||.mca||Saves chunks. Storage is compatible with other Minecraft-related tools and programs. MCA files are stored in the "region" subfolder of the world folder, and a "level.dat" file is generated inside the world folder.|
|Forgetful||N/A||Doesn't save chunks. Changes to the world are lost as soon as the chunks are unloaded, making this useful for read-only public servers. Please note that Cuberite will still load chunks using other schemas.|
A chunk is a 16x16x256 segment of blocks. Cuberite performs a save cycle every 5 minutes.
In a save cycle, all unused chunks are saved to disk and then removed from RAM. Saves cause
a drop in memory usage. If the number of unused chunks waiting to be saved exceeds
UnusedChunkCap, Cuberite will perform an early save cycle to free RAM earlier.
If Cuberite is using too much RAM when the server is under load, lowering
from its default of 1000 may help significantly. Setting the value to 0 means chunks are always saved
immediately when they are no longer used. Alternatively, if you'd like Cuberite to maximize performance
and utilize more RAM, increase
The effect of
UnusedChunkCap will likely be unnoticable on light load, when the cap
is never being reached and save cycles are being performed in 5 minutes intervals. In contrast to that,
the effect is often significant when travelling fast and loading many chunks, such as flying
at high speed.
The optimal value varies depending on settings, system hardware, and playstyle. We currently have no official recommended value, and recommend trial and error. A more intuitive setting is planned for the future, where the exact amount of maximum RAM desired is configured.
Cuberite supports multiple worlds. Each world has its own
Additional Worlds can be added by editing
This is explained in the example below.
In the example above, 2 extra worlds are added to the server.
Note that this automatically creates 2 additional configuration files, namely
To create a nether type world, you should append the
_nether suffix to your world name,
World=myHellishWorld_nether. This creates a
world.ini preconfigured as a nether.
For end worlds, the same rules apply, append the
_the_end suffix to your world name.
Once a default
world.ini is created, you are free to tweak it to your liking.
_the_end suffixes are only used when no
and guide the server in choosing the contents of the default world.ini it's about to create.
When a world.ini is present, the suffixes do not matter any more and the dimension is dictated
Dimension option inside each
_end suffix is treated like
_the_end suffix for compatibility with previous Cuberite versions.
The rest of this section deals with linking worlds and travelling between them.
If you have the
core.portal permission, you may use the following command to travel between worlds:
/portal Worldname. To list all available worlds, use
You can easily link worlds without resorting to plugins by modifying
However, this method is limited: Each world can only be linked to 2 different worlds.
By default, the overworld is linked to two worlds: The Nether and The End.
Stepping through any Nether Portal leads to the Nether, and stepping through any End Portal leads to the End.
The behavior of Nether and End portals can be tweaked, and you can make each portal type teleport to a world of your choice.
This is done by editing the
[LinkedWorlds] section of each world's
Note that with this method, you can't make two different portals of the same type teleport you to two different worlds.
If you want such behavior, you should use a plugin. See the next subsection.
Cuberite has experimental Bungeecord support.