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.

A sunset over a desert town

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.

Discord

The Veloren community (both developers and players) is most active on the Veloren Discord server. You can join the server using the link below:

https://discord.gg/BvQuGze

Website

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

Reddit

Veloren has its own subreddit. You can find it at reddit.com/r/veloren

Twitter

Veloren has a Twitter page at twitter.com/velorenproject.

Wiki

Veloren has a wiki site. It is accessible at wiki.veloren.net

Download

Read this chapter for a detailed description on how to run Veloren and to avoid common pitfalls.

Runtime dependencies

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

Releases

We provide pre-compiled versions of the game for Windows and Linux on https://www.veloren.net/welcome. You can run the Windows version on MacOS using WINE or compile a native version yourself.

Download the version for your operating system and extract it, then open the veloren-voxygen.exe (Windows and WINE) or veloren-voxygen (Linux) file.

Nightly

You can download latest developement builds from our CI pipelines. You can launch them in the same way as releases.

Compile Veloren

Veloren can be compiled under Windows, MacOS and Linux. The following chapter will guide you through the process.

Installing tools

This section describes which tools you need to install on your system to compile Veloren from source.

Rust

Rust can be easily installed on all major desktop operating systems. Follow this link for installation instructions specific to your system.

https://www.rust-lang.org/tools/install

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.

Git

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.

On recent MacOS versions you will be prompted to install Git the first time you run it. Otherwise install it using Homebrew via brew install git or MacPorts via port install git.

Git LFS

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 git-lfs.

For Windows you can download an installer here.

On MacOS you can use Homebrew via brew install git-lfs or MacPorts via port install git-lfs.

After installation the setup needs to be completed

On Linux or Windows

git lfs install

On MacOs

git-lfs install

Bash

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

Initial setup

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

cd veloren

All commands in this chapter from now on should be executed from there.

Basic repo navigation

Changing branches

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

Updating

To download the latest changes and update your current branch

git pull

To download the latest changes without merging them into your local branch

git fetch

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

git stash

To restore stashed changes

git stash pop

Maintenance

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

cargo clean

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

rustup update

Compiling Veloren

This section covers building Veloren from source and running it.
Reminder that all commands need to be run from the repo directory.

Compiling

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 cargo. Keep in mind that compiling Release might be very slow!

Troubleshooting

This section contains common issues and solutions.

Git LFS

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.

Check status

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

MacOs

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

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

Getting Started

Veloren is written in the Rust programming language and is maintained using Git, the industry standard version control system.

Why Rust?

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).

Why Git?

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 master branch. 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.

Git workflow

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 bash shell

Forking

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.

Feature Branches

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.

  1. 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.

  2. Name each commit. Find a good caption for each commit and name it. fix things is 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.

  3. Use git commit --amend in 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 --amend and git push -f to 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.

  4. 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 --all and 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 status to show next instructions.

  5. 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 squash in 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 your-branch-name to master. 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

Project Structure

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

Read the docs for this crate

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 common.

server

Read the docs for this crate

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.

server-cli

Read the docs for this crate

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

Read the docs for this crate

Similar to server, 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

Read the docs for this crate

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

Read the docs for this crate

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.

world

Read the docs for this crate

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.

RFC

Generating Docs

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 voxygen/ directory:

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.