contribute

Contribute

Thank you for contributing to Armory! Armory is an open source project and depends on contributions of the community. Even if you just fix a spelling issue or a add a docstring to a function, any help is greatly appreciated!

There are multiple ways you can make Armory better:

• Help developing:

  If you have an idea for a new feature or found a bug you can fix (also take a look on the currently opened issues), feel free to implement that feature or fix that bug by yourself and open a new pull request.

  There are a few issues having a good first issue label. If you are a new contributor, look out for those issues as they might be more easy than others and implementing them might help you to get a better understanding of Armory's internals.

  Also, check out the excellent Best practices for engine contributors document published by Godot engine as well as our Code Style guidelines.

• Engage in the community:

  Every active user helps to spread the word about Armory:

  • Armory Forums
  • Discord Channel
  • Add the hashtag #armory3d to your tweets about Armory

• Improve this wiki:

  For new users, the wiki is an important place to get information about Armory, so it is crucial that this place is kept up to date and improved.

Creating a pull request

• Install Git on your computer.

• Click the Fork button on top of the GitHub repository page. This will create a copy of the Armory repository on which you can work.

  

• Pick a location on your disk, open a command line in that location and clone your forked repository.

  git clone https://github.com/my_username/armory

  You need to fork the repository only once, but if you don't know how to use Git, it is the best to fork it everytime you want to open a new pull request. The old fork gets overwritten then.

• Apply your changes to your local files, then open a command line in your forked repository and push the changes:

  git add .
  git commit -m "My armory patch description"
  git push origin master

• Create a new pull request by clicking compare across forks and selecting your fork as the "head repository":

  

• Thanks for contributing!

You can also use a Git GUI client for the Git related tasks if you don't want to work from a command line. Here is a list of many clients.

A more detailed explanation can be found here: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork

Local Armory setup

When working on Armory patches, it is useful to setup the SDK locally and apply your modification there.

Note: Disable Armory Project - Flags - Cache Build to always recompile the project when you hit Play. There is no need to compile Armory itself, you will see the changes in action instantly. However, if you changed a Python script for the Armory add-on, you must restart Blender for the changes to take effect.

Armory

• Fork and clone the armory repository into blend_location/Libraries/armory, it will automatically get picked up for that project

Iron

• Fork and clone the iron repository into blend_location/Libraries/iron, it will automatically get picked up for that project

HaxeBullet

• Setup and Update Guide HaxeBullet Documentation

Full SDK

Alternatively, you can clone the whole SDK at once.

• Clone the armsdk recursively into blend_location/armsdk, it will automatically get picked up for that project - this lets you have a fully self-contained and portable project setup:

  cd blend_location
  git clone https://github.com/armory3d/armsdk.git --recurse-submodules
  

• You can also point Armory to use the armsdk at specific location

If you contribute more regularly, it might be helpful to create a local setup that lets you easily change between Armory versions. Every Git repository can have multiple "remote repositories" connected to it. If you cloned the forked Armory SDK, there will automatically be a remote called origin pointing to your fork. You can add another one pointing to this armory repository. To do this, open a command line in your local repository and write:

git remote add upstream https://github.com/armory3d/armory.git

upstream will then be the new name of that remote, you can give it any name you want.

A tutorial about working with remotes can be found here. Note that a GUI client for Git can make it much easier to work with remotes.

Each submodule of the Armory SDK can also point to different remotes, so you can easily keep track of all your forks across the Armory project structure.

Contributing docs

Docs can be edited directly on this GitHub wiki! Just click on Edit at the top of the article you want to edit. If you want to add or edit images, please open a pull request with the new/edited images here and embed them via link in your article. GitHub does not currently allow non-repository members to edit images in wiki articles.

Building API docs

API docs are built using dox. After building an empty project with Krom target selected, follow the instructions at dox readme.

Detailed build instructions can be found here.