New Programmers

From Hero of Allacrost Wiki
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[edit]

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[edit]

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[edit]

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.

Play Around[edit]

The next obvious step is to run the application and play the game yourself. You can either begin a new game and play through the first few maps, or you can load the Test Interface and instantly jump around between different game modes and maps. Learning how to access and use the test interface will be crucial for you in your development work. You can load existing tests or build your own in this interface, which will allow you to load the game with specific settings and instantly transport you to any state of the game. Here are a few examples. (1) You could define which characters are in the active party and what their experience levels are, then put this party in the middle of a scripted scene for a map. (2) You can begin a battle against a certain group of enemies when the characters have only their initial starting equipment. (3) You could load a shop with a specific set of inventory items and give the player a fixed amount of money to test making purchases of those items.

Check the Roadmap[edit]

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 for our next major release milestone.

Browse Documentation[edit]

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 (.h) 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. Only look to the source (*.cpp) files if you need to understand a particular detail about the implementation. Lua (.lua) files are used in a multitude of ways from data definitions, map files, settings configuration, event scripting, and so on.

Ask for a Simple Task[edit]

The final step is to state your desire to contribute on the forums or Discord channel, 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. Pull requests must all be approved by at least one senior developer who will look over your changes and merge them. If the approving developer finds any problems with your request (if you didn't follow the Code Standard, for example), they will comment on the request and ask you to fix it before the merge is completed.

Moving Forward[edit]

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.