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

Veloren is a cross-platform game and can run on Windows, Linux and Mac OS.

If you're only interested in binary builds of the game, check the website at https://www.veloren.net.

(We currently don't provide official downloads of Veloren, you have to download the source code and compile it yourself, the rest of this chapter will explain how to do that.)

Installing tools

In order to compile Veloren, you'll need to install a few things.

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.

https://github.com/rust-lang/rustup.rs#working-with-nightly-rust

Git

There are many ways to install Git. For those running Linux, your system probably has Git already installed or available to install with your chosen package manager.

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.

For Mac OS, there exists other methods. I personally have not used Mac OS, so you'll likely have a better time finding instructions just by searching for 'Install Git on Mac OS'. If someone wants to contribute appropriate instructions to this page, please do.

Git LFS

You also need to make sure you have Git LFS installed. This allows us to store large files like images and audio files.

Compile Veloren

Veloren can be compiled under Windows, MacOS and Linux. Install the programs described in Toolchain. The following commands needs to be executed in Bash. If you run Windows, get familiar with git bash. Open git bash in the location you want to store Veloren (around 100 MB needed).

Download source code

Clone the repository

git clone https://gitlab.com/veloren/veloren.git

Change your working directory to the cloned repository

cd veloren

All of the following commands should be executed from the root directory of the project (usually called veloren/).

Next, check if Git LFS works correctly:

git lfs status

Nightly Rust

Veloren depends on the nightly toolchain of Rust. To switch to it for this project only:

rustup override set nightly

Start the game

This will start the actual game. You can connect to other servers or start a singleplayer server using the GUI.

cargo run --bin veloren-voxygen

You can append --release to allow more optimizations at the cost of longer compile times.

Start a dedicated server

If you want to host your own server, run:

cargo run --release --bin veloren-server-cli

This will open a server listening on 0.0.0.0:59003. At the time of writing this section there is no way to change it without modifying the source code.

Debugging

You can prepend VELOREN_LOG=info to a cargo command to give more details during runtime and RUST_BACKTRACE=1 to give more details after crashes.

For example, to start the server with more debug information, run this:

VELOREN_LOG=info RUST_BACKTRACE=1 cargo run --release --bin veloren-server-cli

Troubleshooting

Git LFS

When using Mingw64, it does not 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:

C:\src>SET "SSH_ASKPASS=C:\Program Files\Git\mingw64\libexec\git-core\git-gui--askpass"
C:\src>SET "GIT_ASKPASS=%SSH_ASKPASS%"
C:\src>SET "DISPLAY=required"

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.

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.

GitLab and forking Veloren

By now, you should have both Rust and Git installed.

The following assumes you're using bash (on Windows git bash) or something similar.

Forking the project

To work on Veloren, you first need to create your own fork of the codebase on GitLab. To do that, login or register on GitLab, and head to the main GitLab page of repository you want to fork (for example https://gitlab.com/veloren/book). Next click the fork button. You may be taken to a page asking to select a namespace you wish to fork the project to, just choose your account. You will get redirected to the page of the forked repository.

Local repository setup

Lets assume you want to modify https://gitlab.com/veloren/veloren.git. And your fork is https://gitlab.com/yourusername/veloren.git

#1 Clone your fork of the repository locally
git clone git@gitlab.com:yourusername/veloren.git
#2 Change your working directory to the cloned repository
cd veloren
#3 Add `upstream` remote to point to the main repository
git remote add upstream git@gitlab.com:veloren/veloren.git

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 here: Compiling

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.