New Programmers

From Hero of Allacrost Wiki
Revision as of 11:18, 8 December 2017 by Roots (talk | contribs) (Communication)
Jump to: navigation, search

If you are a programmer new to the project, this page will help you get started. You should also read or skim through the New Contributors page.


The Allacrost code is written in C++ and Lua. The Lua code is fairly easy to pickup and comprehend, so no experience with this language is required. To work in the C++ code, you should ideally have at least a year of experience with C++ or a similar object oriented language like Java or C#. You'll need to be comfortable with pointers and memory management, inheritance, encapsulation, and other common techniques. Experience with any of the libraries we use (Library Dependencies) is helpful, but you most likely will not need to know or work with any of these unless you are working directly on any of our engine components.


As a developer, constant communication with the rest of the team is very important. This is how you figure out what others are working on and leverage the experience of others to make sure you're going down the right path. You should keep other developers informed of what areas of code you are working on on a regular basis. The forums are where the majority of our discussions regarding the code take place. It is also strongly recommended that you regularly hang out on the Allacrost Discord channel.

Code Access

Our code is freely available for anyone to read and copy, as you would expect of an open source project. Read the Mercurial Repository page for information on where to find the code and how to create your own copy of the main repository. 'game 'is the main directory that you should work from ('demo' contains very old code that you should not bother with).

Developers are not given commit access until they are ready to make their first commit and that commit has been reviewed and approved by an existing developer first. This is done only for a developers first commit to make sure that they are not intending to make any destructive changes. After generating a patch file, share it on the forums for review and provided everything looks okay, you will be given commit access and can submit your first change. Your work will no longer need to be preapproved at this point.

Getting Started

Allacrost has a large code base with a lot of history to it, so diving it can be intimidating. You'll want to follow these steps to ease yourself into the code to prevent you from becoming overwhelmed.

Compile the Source

Your first step should be to compile the latest source code and get the game running on your machine. Depending on the circumstances, this may turn out to be quite a bit of work itself. Per our policies on our mercurial repository, no developer should submit code to the main repository that does not compile. However, Allacrost is a cross-platform project and sometimes source code that compiles on one machine does not work on another (though this case is rare). Furthermore, developers only maintain the build files for the platform that they do their development on, so build files on other platforms tend to get out of date when there are no active developers on that platform.

Read through the Compilation Instructions page for guidance. If you are having trouble compiling the source code, go to the programming section of the forums. Look for an existing thread first for answers, and make a new post if you are still having trouble. Your first build of the source may take some effort, so be prepared.

Check the Roadmap

The Roadmap page on the wiki maintains an updated list of all of the major tasks we need to complete for our next release. This includes not only code, but art, music, maps, and other game content. You should look to the Code section of this page to see the various features that remain to be implemented. This will give you some idea of what it is that our team needs to accomplish in the long term, and you can prepare accordingly.

Browse Documentation

The Allacrost code is well-documented, both internally (with comments) and externally (with this wiki). The Code Documentation page is your main hub for learning about the various components of the code base. The size of the Allacrost code base is on the order of hundreds of thousands of lines, and you are not expected to read through every header and source file to learn what's available and how things work. It is strongly recommended that you begin casually browsing through our code documentation pages in the wiki. Learn the different components and architecture, and get a sense of our APIs and what classes and components of the code you will need to utilize to achieve your work. Learning is an ongoing process, and hopefully you'll come to develop or understand a particular component well enough that you can contribute to this documentation as well.

The documentation on the wiki is not complete and not always up-to-date, however, so you may find that you have to study the code directly sometimes. You should first study the header files, which are almost universally well-documented and provide everything you need to know about using a particular class without bogging you down with the details of the implementation. Study the header files (*.h) thoroughly. They will almost always explain everything about a class or function that you need to know. Only look to the source file (*.cpp) if you need to understand a particular detail about the implementation.

Ask for a Simple Task

The final step is to state your desire to contribute on the forums, and ask for a simple task to be assigned to you. We always start our developers off with relatively easy and small tasks to help them get their feet wet and get some exposure to the code base. Diving head first into implementation a major feature is far too overwhelming, and we want our new contributors to feel an early sense of gratification at having completed something and seen it added into the game. Usually, a senior developer will propose more than one simple task for you to achieve and let you choose which one you'd like to do.

Once you've completed your task, you'll want to submit a pull request to the main repository. A senior developer will look over your changes to make sure that everything looks good (ie you're not changing anything you shouldn't, you're following the Code Standard, etc.). This isn't any form of severe scrutiny over your code, but is just a sanity check to make sure that you're not about to do something dangerous on your first commit.

Moving Forward

The direction you move from here is up to you. What we recommend is to continue completing small tasks, and gradually ramp up to larger and more difficult features. Most developers end up taking ownership of one area of the code, such as the scripting engine or battle mode components, and continue improving that code and adding new features. You're never going to be "stuck" with doing something and are free to work on whatever you wish.