Contribute to Torque 3D

Get the Source Code

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

The repository has two main branches: Preview4_0 and development. We recommend that you do not commit any of your own code into these branches, but simply pull down changes from the TorqueGameEngines 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.

Pull-Request Guide

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 tutorial by GitHub.

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 process in trickier cases.

Pull Request Rules

  • Contributions cannot contain any code that is not legally compatible with Torque 3D's MIT license.
  • 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

  • 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, provide steps to reproduce it so we can verify that it 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 TorqueGameEngines/Torque3D repository.
  2. We tag the request appropriately according to its status as a new feature, a bug/fix, or a defect/enhancement.
  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.
  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.
  5. If it passes final review, your pull request is merged! Congratulations.

Version Policy

We maintain an X.Y.z version scheme similar to Semantic Versioning. Note that this new versioning policy applies only to engine versions 3.5.2 and above.

  • X (Major version number): Denotes a single version of our client-facing API, referring to script and editor capabilities, as well as major parts of the internal C++ API.
  • Y (Minor version number): Refers to the set of features in a given API. Changes across a minor version may include refactoring, bug fixes, or new features without breaking changes to existing ones.
  • z (Patch number): Denotes minor updates to stability or correctness that do not significantly alter the engine API.

Issues and Feature Requests

Reporting a Bug

If you find a bug in the engine that you're sure you didn't cause, please use the GitHub issue tracker to let us know. Please check recent issues to see if someone has already reported the same problem. 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