Alexander Harkness 383c5c2c89 Typo Correction
2014-06-12 19:31:16 +01:00

5.5 KiB

Hello! Thanks for wanting to work on this project 😄, and I hope that this file will help you somewhat in getting all set up and running. I'll go through the basics of getting the projet environment set up, the code organization and style, and general development practices. I'll also show you some good issues to start off working on to get yourself familiarised with the code.

Minecraft Basics

If you don't play Minecraft or don't have a great knowledge of the basic systems, you should get to know them. The Minecraft Wiki is quite useful for this task, although some youtubers are also fairly good at teaching the basics and just playing is quite good too. It is possible to contribute without knowing minecraft in detail though.

I'd say that the important topics are:

  • Differnt types of blocks and how they act.
  • Mobs, what they do and how.
  • Redstone, pistons, and automation.
  • Farming.
  • Fighting, health and the hunger system.

Useful Resources

Setting up a Dev Environment



You'll need the basic C++ build tools:

  • gcc (or clang or another C compiler)
  • g++ (or clang++ or another C++ compiler)
  • make

You'll also need CMake to generate the makefile to build from.


If you use Windows, your best bet is the MSVC2008 (available as a free download in the Express edition from MS) or MSVS2013 (ditto), solution files for which can be generated with cmake. You'll also need cmake to generate the project files.

Setting up the Repo

Next, you'll need to set up the repo. You can make a fork and work on that then PR in, or I can set you up with membership for the repo so you can work on branches here (still use PRs though, they're great tools and for the first few you'll definitely need some changes). If you want membership to the repo, just create an issue and I can set you up.

Once you've cloned, you need to pull down the submodules:

git submodule init
git submodule update

After that they should come down automatically when you pull but it's not bad to refresh every once in a while.

Repo Arrangement

The MCServer repo has recently been rearranged for better code separation and other things, but basically it's split into a few areas:

  • src
    This holds all of the MCServer source code, and is where most development takes place.
    It's split into logical areas for blocks, the protocol handling and other things.
  • lib
    This holds all the 3rd party libraries for MCServer. You basically don't need to touch these, and we're thinking of switching them into submodules soon.
  • MCServer
    This folder isn't greatly named, but it contains the default plugins and environment to actually run the server. You'll find the executable (named MCServer) here and in the plugins subdir the default plugins. The config files are also stored here. Config files with .example.ini on the end are generated by the server or source control and should be left alone, instead you should copy them to a file without the example in the name which will be prioritised over the generated ones.

Code Styles

Mainly follow the code styles in CONTRIBUTING.md, which is definitely an important read.

How to Build


Follow the instructions in COMPILING.md. You probably want to build in debug mode (when you're developing) for console alerts and debugging capability, even though it's much slower for everyday use.

Basically, the process is:

cmake . -DCMAKE_BUILD_TYPE=DEBUG && make


You need to first generate a project file with cmake . -DCMAKE_BUILD_TYPE=DEBUG then execute the src/Bindings/AllToLua.bat script file, then just open the solution file in your MSVC of choice and build.

How to Run

The server can be run (on *nix) by a simple ./MCServer in the MCServer directory. On first run it will generate the world and start a server on the default port (configurable in settings.ini) so you can connect in minecraft via localhost.

Where to Get Started

There are a few fairly easy issues for you to get started with, as well as some more difficult but interesting ones.


  • #140
  • #493
  • #577
  • #381
  • #752
  • Clean up some of the compiler warnings. (Check Travis CI for a list of them.) With clang, there are over 10000 lines of warnings to clean up.

More Difficult:

  • #133
  • #134
  • #215

You may also want to write some plugins. They are written in lua, with excellent API documentation available via APIDump. The Core plugin should also help quite a bit here.

Special Things

  • MCServer uses ToLUA for the Lua API, and you'll really have to ask @madmaxoft for how to export stuff and @worktycho for how to add stuff to the auto generated bindings (he just re-worked it with CMake).
  • Ask questions as much as you like, we're here to help 😃