Torque 3D's source code lives at GarageGames/Torque3D. To clone a copy of the source code, you will need a git client. We recommend the official client. Once you have installed Git, you should follow GitHub's forking tutorial to make your own repository to which you can commit your code.

The repository has two main branches: master and development. We recommend that you do not commit any of your own code into these branches, but simply pull down changes from GarageGames' repository into them. You can maintain your own branch (perhaps named after your GitHub username, or the game you're working on) and merge changes into it as you see fit.

We also have a repository for Torque 3D's Github wiki. Feel free to fork and pull-request to its master branch if you want to submit new documentation, tutorials, or make corrections to existing content.

So you want to make a pull request

Pull requests are the way that community members like you can get your code pulled into the official Torque 3D repository for everyone else to use. We accept community contributions that align with our vision for the engine - especially bug fixes, enhancements to existing features, and revisions of old, slow, or ugly code. Pull requests are the way that code gets reviewed before it's accepted into the engine - even code that we, the Steering Committee, write ourselves. For a technical tutorial on how to submit a pull request, check out this page in our wiki, or this tutorial by GitHub.

In order to ensure the quality of the engine code going into the future, we have strict rules about what code we can and cannot accept. We also have some soft guidelines that inform our decision-making progress in trickier cases.

Pull request rules

Pull requests not adhering to these rules cannot be accepted, so pay attention!

  • Obviously, your contribution cannot contain any code that is not legally compatible with Torque 3D's MIT license. In addition, to legally protect the engine and everyone affiliated with it, we require that all contributors create an account on and sign the Open Source Software Agreement there. For more information on the OSSA, please visit this page in our wiki.
  • Contributions must adhere to our code style guidelines.
  • Pull-requests against the master branch cannot be accepted. All requests must go to development, or an appropriate topic or maintenance branch.

In many cases, if any of these rules are breached, we will first ask the contributor to resubmit their pull request, or add commits to it that resolve our issues. In exceptional cases (i.e., we really really like your work), a committee member may perform that work themselves.

Pull request guidelines

Here are some of the things we look for in a great pull request. These aren't hard-and-fast rules, but following these guidelines will increase the chances that your request is pulled!

  • Our favourite requests are ones that work directly towards the goals laid out in our roadmap. We are more likely to help out and fix slightly broken pull requests if they align with our goals, and chances are your request will move faster through our process.
  • Each pull request should be focused and concise. If it has a very clear intent and a small set of changes towards a specific goal, it's easy for us to decide whether we want it, and to then test it and make sure it works as advertised and doesn't break things.
  • If you're fixing a bug, we need you to provide steps to reproduce it so we can verify that exists and that your patch actually does fix it. We'd also appreciate platform and compiler information.
  • We like each pull request to have a reasonable revision history - not too many small commits with typo fixes, for example. Sometimes, we may ask contributors to rebase large numbers of commits into a single commit before the request is pulled.

The pull request process

  1. You make a pull-request to the GarageGames/Torque3D repository.
  2. We tag the request appropriately according to its status as a new feature, a bug/fix or a defect/enhancement. The difference between the latter two is that a bug (which you may be submitting a fix for) is advertised functionality that does not work correctly, or a situation that causes a crash. A defect (or an ehnahcement to an existing feature) is simply something that could be better (for example, a performance improvement).
  3. One or more members of the Committee or the general community review your request, adding comments if they see any problems. This code-review process may take some time as we need to consider a variety of factors when considering whether a pull request is appropriate. We (and others) may point out technical flaws or suggest ways we would prefer the issue to be solved. We will also pull down your code and test it locally to verify that it does as advertised!
  4. If all goes well, the 'Final Review' label will be applied to your request. This is a formality stage that collects pull requests we feel are nearly ready to be merged, and allows reviews to focus their attention better on imminent new code. At this stage, if only one member of the Committee has been involved in reviewing the code, another must become involved.
  5. If it passes final review, your pull-request is merged! Congratulations.

We maintain an X.Y.z version scheme similar to that of Semantic Versioning. However, since our API is less well-defined, the table below describes what we mean by the three version number components.

Note that this new versioning policy is different to the one adopted by the first and second Steering Committees, and applies only to engine versions 3.5.2 and above.

Major version number
The major version number denotes a single version of our client-facing API, which refers to the script and editor capabilities exposed to binary-only users of the engine, as well as major parts of the internal C++ API, such as the class hierarchy.
Minor version number
The minor version number refers to the set of features in a given API. Across a minor version number change, we may refactor code, fix bugs, or introduce new features, but we will not make breaking changes to existing ones.
Patch number
Patches denote minor updates to stability or correctness that do not change the engine API in a significant way.

Reporting a bug

If you find a bug in the engine that you're sure you didn't cause (don't worry, we cause bugs all the time ourselves!), please use the GitHub issue tracker to let us know. Please have a bit of a look at recent issues before you do, in case someone has already noticed the same problem. And remember to provide the following information:

  • Your platform and compiler version
  • A description of what currently happens, and what should or should not happen.
  • Steps to reproduce the bug.

Requesting a new feature

We use a UserVoice forum to monitor feature requests from users. Before making a forum post or starting a new request, check to see if your feature has already been requested.