Veloren: An Owner's Manual
This manual is the primary source of documentation for Veloren, both for users and for developers. It aims to document the features of Veloren, the manner in which it is developed, and describe the inner workings of both the game and the engine. It also aims to discuss future plans the development team has for Veloren.
What is Veloren?
Veloren is a multiplayer voxel RPG written in Rust. It is inspired by games such as Cube World, Legend of Zelda: Breath of the Wild, Dwarf Fortress and Minecraft.
Veloren is fully open-source, licensed under GPL 3. It uses original graphics, musics and other assets created by its volunteer community. Being contributor-driven, its development community and user community is one and the same: developers, players, artists and musicians come together to develop the game.
What status is the project currently in?
Veloren is currently undergoing a from-scratch rewrite. The old engine is playable and is rather fun to explore, but all new development work is focussed on the new engine.
Who develops Veloren?
Veloren is developed by a community of volunteers that have one unifying aim: creating a bright, colourful, fun world that can be explored and interacted with in unique and interesting ways.
Below, you can find community information.
The Veloren community (both developers and players) is most active on the Veloren Discord server. You can join the server using the link below:
The Veloren website contains weekly blog updates, developer information and download links. You can find it at www.veloren.net
The website also hosts a developer manual (you're probably reading it now!) at book.veloren.net
Veloren has its own subreddit. You can find it at reddit.com/r/veloren
Veloren has a Twitter page at twitter.com/velorenproject.
Veloren has a wiki site. It is accessible at wiki.veloren.net
Read this chapter for a detailed description on how to run Veloren and to avoid common pitfalls.
These are programs needed for Veloren to run on your device. Refer to Compile section for build-time dependencies.
Currently there are no runtime dependencies
Download the version for your operating system and extract it, then open the
veloren-voxygen.exe (Windows and WINE) or
veloren-voxygen (Linux) file.
You can download latest developement builds from our CI pipelines. You can launch them in the same way as releases.
Veloren can be compiled under Windows, MacOS and Linux. The following chapter will guide you through the process.
This section describes which tools you need to install on your system to compile Veloren from source.
Rust can be easily installed on all major desktop operating systems. Follow this link for installation instructions specific to your system.
Because Veloren uses the nightly version of Rust, please make sure you install it:
rustup toolchain install nightly
We have a toolchain file in the repository so you only need to have rust nightly installed and it will be chosen automatically.
On Linux Git is most likely already installed, if it isn't, use your distribution's package manager to install it.
For Windows, The 'Git for Windows' suite is a sensible way to install Git, along with a set of tools that'll make it easier for you to use.
Git LFS is a Git extension used to store large files like images and audio files. You need to install it in order to download the assets.
On Linux you can use the package manager to install Git LFS, usually the package is called
For Windows you can download an installer here.
After installation the setup needs to be completed
On Linux or Windows
git lfs install
All commands for compiling Veloren yourself are written for bash, if you run un windows use the
git bash included in the git package.
After you installed everything, continue with local repository setup
Local repository setup and maintenance
This section describes the initial setup and routine maintenance of your local repository
Download source code
Clone the repository
git clone https://gitlab.com/veloren/veloren.git
See Troubleshooting if you cloned the repo before Git LFS was setup
Change your working directory to the cloned repository
All commands in this chapter from now on should be executed from there.
Basic repo navigation
In order to try out new unmerged or unfinished features, you may want to switch to a different branch.
To switch to a developement branch
git checkout <branch_name>
To switch back to master
git checkout master
To download the latest changes and update your current branch
To download the latest changes without merging them into your local branch
The help command
Git also offers a help command with detailed information about other commands
git help <optional subcommand name>
Modifying the source code
If you want to modify the source code, refer to contributing chapter.
To discard changes you've made to the source code
git reset --hard
Keep in mind that this deletes all the changes without a way to recover them.
To discard your changes with ability to restore them later
To restore stashed changes
git stash pop
This section covers common operations used to keep your local copy working properly.
Cleaning old build files
Over time as dependencies get updated, the old compiled versions start to take up a lot of space. To delete them type
Keep in mind that cargo will need to recompile all dependencies which can take a long time.
Updating the toolchain
To update the rust toolchain
This section covers building Veloren from source and running it.
Reminder that all commands need to be run from the repo directory.
To compile and run the client
cargo run --bin veloren-voxygen
To compile and run standalone server
cargo run --bin veloren-server-cli
To compile without running, use
cargo build instead.
Optimized Release builds
By default debug builds are created which compile faster but run a bit slower than optimized release builds.
Unlike many other projects, we've set them up so they're fast enough to be playable.
If you want to get optimized builds, add the
--release flag when calling
Keep in mind that compiling Release might be very slow!
This section contains common issues and solutions.
If LFS is not installed and setup properly the lfs pointers will not be replaced with actual assets. This produces an error when running Voxygen where it complains about the validity of whatever filetype it is trying to load.
To check if Git LFS works correctly:
git lfs status
When LFS was not setup before cloning the repo
To setup LFS and download the asset files on Linux or Windows
git lfs install git lfs fetch git lfs checkout
git-lfs install git-lfs fetch git-lfs checkout
When using Mingw64 (Windows)
Git LFS fails download the files properly. The main issue seems to be that the askpass program is not spawned when using a normal CMD prompt, preventing Git LFS from authenticating via SSH to retrieve the temporary access token. Setting the SSH_ASKPASS, GIT_ASKPASS and DISPLAY variables seems to solve this issue:
SET "SSH_ASKPASS=C:\Program Files\Git\mingw64\libexec\git-core\git-gui--askpass" SET "GIT_ASKPASS=%SSH_ASKPASS%" SET "DISPLAY=required"
Migrating from submodules
If you used the previous submodules system, you can deactivate it with:
git submodule deinit --force --all
Additional Required Libraries
On Debian systems additional libraries may need to be downloaded, below is a non-exhaustive list:
And a one liner to download and install them all:
sudo apt install libglib2.0-dev libasound2-dev libcairo2-dev libpangol1.0-dev libatk1.0-dev libgtk3.0-dev
Contribute to Veloren
Everybody is welcome to fill Veloren with more creatures, help fixing bugs or just be active in the community.
How to report bugs
Veloren is written in the Rust programming language and is maintained using Git, the industry standard version control system.
Rust is a new programming language designed to be fast, safe, and well-suited to concurrent programming. We believe that these attributes make it ideal for game design. As a result, the Veloren engine is extremely quick, very rugged (you'll be hard-pressed to find unintentional crashes or bugs in the codebase), and also multi-threaded (meaning it can take advantage of multi-core CPU architectures).
Git is an industry standard version control system. It is uses to keep track of different versions of a codebase, and maintains a history of a codebase that can be viewed throughout time. It also makes contributing to the project much easier, since it helps to manage the merging and updating of the codebases maintained by each contributor.
GitLab and our workflow
The repository is located in GitLab. We use GitLab to manage the source code, assets, our website and this book. We make heavy usage of the continuous integration of GitLab, we run tests and do code reviews. Use the issue tracker of GitLab with the corresponding tags to track feature requests as well as bugs.
If you want to contribute source code, meet us at our Discord and discuss what needs to be done.
Or just prepare a MR the way you like merge.
The default way of doing so is fork the project, create a branch in your fork, make changes, and then create a Merge Request in
veloren/veloren to include your changes.
The MR should go to
Best strategy is to create a issue first and then link the MR to the issue so that reviewers know why this change is needed.
Stay active in discord as well as GitLab to answer questions over the next days.
If you contribute constantly you will get a developer role in both discord and GitLab, granting you some trust and the ability change more on your own.
This chapter describes how we use git in order to contribute to Veloren. So assuming you have a great idea, might be to change a few lines of code, or add some images, modify some models, contribute to the music or fix a translation. We keep the source of our game in Git, hosted by gitlab.
Please now get familiar with git (google) and compile the game once: Download
Then start your
You are free to create a fork of Veloren in GitLab and clone it. This is especially recommended if you have no developer rights in GitLab yet (you will get rights after some time). However you can also get access to the main repository and work in it. It has the advantage of included CI builds for all commits.
We develop in feature branches, so before you start contributing, create your own branch:
git checkout -b <some_branch_name>
In your own branch you can then create commits and push them to your branch how you like it. (see Rule For Commits)
Rules For Commits
We want our code basis to be clean and make it easy to keep track of our past, this also benefits our future productivity. So there are a few rules regarding code style everyone needs to follow to get accepted.
Split your code in reasonable sized logical chunks of work. Often a feature can be split up in smaller sizes of work, try to make use of it and structure your feature using commits. Don't just make a big commit that contains all the changes, don't make 100 commits that change one line.
Name each commit. Find a good caption for each commit and name it.
fix thingsis to unspecific, if a issue exists link it and it's title, e.g.
fixing #123 - UDP buffer overflow when to much player on server. If no issue exists, evaluate creating one. Otherwise, describe shortly but precisely what a commit is about, e.g.
fixup several issues in physics related to collisions. Tip: If you struggle finding one title that covers you whole commit, it might be better to split in in 2 parts next time.
git commit --amendin case you forgot to include something in your commit. E.g. you pushed your change and now fml is failing, than instead of creating a separate commit fixing this commit, run fml locally, run git add and then run
git commit --amendand
git push -fto fixup the incomplete commit instead of creating a new one. The same applies to smaller fixes like spelling errors introduced by yourself, fix the commit where the mistake was made instead creating a new one on top. Exception: Sometimes fmt changes their rules and untouched code becomes invalid, in case the fml failure is related to fml and not us, it's okay to use
apply fml on whole codebase. Please don't include other changes in such a commit.
Rebase on master If some time has passed since you started your feature branch, rebase it on top of master from time to time to avoid merge conflicts. First, make sure you have no uncommitted work, e.g. by creating a new commit. Run
git fetch --alland
git rebase origin/master. If it returns with no error you are fine, if it returns some, fix the errors and follow the instructions. Tip: Use
git statusto show next instructions.
Fixup your commits afterwards. In case you didn't created clean commits in the first place, you can squash and change the names now. First, count how many commits your branch contains, e.g. in
git status. Use the number in
git rebase -i HEAD~4, e.g. for 4 commits on top of master. Read the instructions in the editor. You can change a commit name by modifying the text in a line. To Squash Commit 2 and 3 into a single commit, write
squashin front of the 3rd commit, don't change the second one
Create a Merge Request
Once your feature is ready for review create MR in GitLab out of your branch from
Feel free to add additional information to the description (optional).
If you didn't not bother of Rules For Commits above, please cleanup your branch now or consider setting the "squash commits"
Then create a post in the discord and mention @Code Reviewer, someone will eventually look over the MR and will work with you together to get it merged
Veloren is designed in an extremely modular manner. You can think of it more as an ecosystem of interconnected projects than a single project. At its heart are a variety of Rust libraries (crates) hosted in the main directory.
common is a crate that contains functionality common to many parts of the project. This includes things like networking code, the physics system, voxel manipulation code and other utility code. If something occurs both client-side and server-side, it's a safe bet that it's implemented in
In Veloren, there is no single 'server program'. Instead, there are a variety of server front-end programs that make use of
server, a library that implements the server-side component of Veloren. This allows anybody to implement their own server front-end, and will permit servers with web control panels, web status interfaces, command-line interfaces, and GUI interfaces for LAN games.
This crate is a command-line only front-end for the
server crate. It's very simple, and serves as the vanilla, default front-end for Veloren servers.
client is a library that implements the client-side component of Veloren. It is not tied to any particular front-end and instead is designed to be a generic client implementation upon which graphical front-ends can be built.
chat-cli is a command-line client front-end that permits chat communication with a Veloren server from the user's console. It doesn't allow the user to control a character on a server, but it does allow the user to talk with other players via the server's chat system.
Voxygen is the best-known crate in the Veloren ecosystem, particularly to those that spend more time playing the game than developing it. It is the primary client front-end for Veloren and implements a fully 3D view of the game world. It is the reference implementation of the game and the program that virtually all users are intended to interact with.
This crate implements the world generation and simulation aspects of Veloren. It is currently used only by the
server crate, but has been kept separate from the rest of the ecosystem such that third-party tools may make use of it for things like visualising the state of a world.
Once you have the main Veloren repository cloned locally and Rust installed, it is possible to generate and view the project documentation by running the following command from the
cargo doc --open
This command will automatically open the documentation in your web browser when it has finished generating. The documentation is organised by crate and gives an overview as to what each trait/function/type is for, how it may be used, and in what scenario it is appropriate to be used for.
Generally speaking, we only require publicly-visible interfaces to be documented fully, but it is encouraged to add documentation comments to non-public interfaces too.
1) How come you chose Rust for this game? It's not exactly the most mature language for game development.
Rust may seem like an unusual choice for a project like this. It's a new language that has yet to properly prove itself in production environments, and is still undergoing relatively rapid changes. We chose Rust because it has several unique features that we believe will come to benefit the project in the long-term."
Rust is safe Code written in vanilla Rust cannot trigger undefined behaviour. Rust's design helps us avoid a plethora of bugs common in other compiled languages such as dangling pointers, buffer overflow, invalid/null pointers, data races, array bound errors, and many more. This makes it particularly suitable for a large collaborative project such as this because it makes it difficult for new code to introduce difficult to fix bugs into the codebase.
Rust is fast Rust is a compiled language that doesn't require a garbage collector, exceptions, or many of the other runtime systems that make other languages so slow. In most scenarios, well-written Rust is at least as fast (and often faster) than well-written C++.
Rust is modular Rust comes with the Cargo build system and package manager. It allows Rust to be compiled in a modular manner, borrowing other libraries (known as crates) from the rest of the Rust ecosystem with ease.
Rust is portable Rust's compiler uses LLVM to target most major hardware platforms. By using Cargo as its build system, it allows for consistent compilation across many platforms. No more searching for header files or fighting linker errors!
Rust is well-designed Rust's syntax is designed to be user-friendly (wherever it can without compromising on features) and well-suited to system programming. Its unique combination of low-level control and safety makes it perfect for building both game engines and high-level game logic.
2) Why use gitlab over github?
Gitlab has better integrated ci/cd, offers everything else the same. Both of them are only a service on top of git on the computer, so not too much different.
3) What noise function do we actually use?
Perlin, worley, simplex, value, gradient, and a few Zesterer invented
4) How can I help? I have to be part of a team? I dont have experience in Rust but really want to learn and help you guys.
Generally speaking, you can help in every area you want to. You don't have to become part of a team. But as soon as you helped a bit and showed that you are interested you will get in the respective "team".
5) How is the movement/physics/mechanics programming handled?
That's implemented in common, which is a crate for code that's common between both the server and the client (because the server needs to be the ultimate authority on physics, but the client needs to do physics prediction so that lag/latency doesn't look bad)
6) Just curious, how does animation work in this game? Like, what program do you guys use to animate and how many FPS is an average animation?
So currently animation doesn't exist, we're building up the system that'll be used to add it in though
7) Does it have all the OOP stuff you need for a project like this? Are there times when you are coding in Rust and there is something you feel could be expressed much better in C++? I originally dismissed Rust when I first encountered it since it looked like it was just C with different syntax and some functional programming stuff, but I heard recently it is supposedly much more than that.
Although Rust has features that on the surface appear to make it an object-oriented language (it has objects, methods, interfaces, etc.) it's not actually an object-oriented language. One of the common trip-ups new developers make is to try to force Rust to behave like an OO language when a particular problem is better solved in a more Rust-y way
8) What flexibility does Rust provide that Unreal Engine does not? Is it simply because Rust makes the project modular while Unreal Engine is not modular enough for open source development?
A voxel game is a rather specific kind of game. It deals with a lot of data that most engines simply aren't really designed to deal with. Along with that, a lot of the game is procedural, something that existing asset-driven engines aren't too well equipped to deal with either. An existing engine, for us, would provide relatively few advantages despite providing several pretty significant disadvantages
9) Do you guys ever want to take this project to a fundraising platform like Kickstarter so that someone can work on it full time? Is it possible that this could become a goal one day? Or will this never be a goal?
We probably won't go that route, though I guess it's hard to say anything for sure. We see this as a volunteer project. It's more likely that any fundraising we do would go towards maintaining servers and such.
10) I got a question on how to compile the game?
Everything should be described in the Compiling section.
Contribute to this book
You can find the source for this book at our GitLab, feel free to make changes, correct errors and add more content.