Torque includes two build systems - you can choose between the custom-built Project Generator (which goes hand-in-hand with the Project Manager GUI applet), which uses PHP to generate build files, and CMake, which has its own domain-specific language for specifying build dependencies and steps. Take your pick!
Be warned that CMake is the preferred method to generating projects, and that we support Visual Studio 2013 and later. Older versions can work, but expect to make a few changes to enable support for them.
Table of Contents
In order to compile T3D, you'll need to install the DirectX SDK (June 2010), which you can find here. It is not uncommon to experience an 'error S1023' when attempting to install the SDK. As described here this is due to the wrong version of the VS2010 redistributables being installed on your system. You'll need to uninstall them before proceeding, and the DXSDK setup will reinstall them as part of its own installation.
NOTE: UNTIL UPDATES TO THE PROJECT MANAGER ARE COMPLETE, IT IS CONSIDERED TO BE NON-FUNCTIONAL AND USED AT YOUR OWN RISK. PLEASE USE CMAKE OR OTHER METHODS BELOW
The Project Generator is a custom build system written by GarageGames specifically for Torque 3D. It uses PHP scripts to generate solution files for your compiler. It currently supports Visual Studio 2008, 2010, and Unix Makefiles (for dedicated server builds only).
This page gives you an introduction to using the Project Manager application to set up and configure projects with Torque. If you're not used to using command-line tools then this is the recommended way to manage projects with the project generator!
You can also edit the modules your project will use manually. In My Projects/Your Project/buildFiles/config are several .conf files. They are all used in different ways when the project generator creates compiler-specific solutions. projectCode.conf is where you should add extensions that apply to all builds across all platforms, rather than being platform-specific.
To run the project generator manually, without using the Project Manager, ensure you have php in your path and run this command from your project directory:
php ../../Tools/projectGenerator/projectGenerator.php buildFiles/config/project.conf
If you don't have php installed on your system, it's easier to run the generateProjects.bat script, which will use the Windows PHP executables bundled with the engine.
In order to enable the project to run on 64 bit, a few steps are required.
- Go to Build > Configuration Manager.
- Under Active Solution Platform, select <New…>
- In the pop-up window, change the Type or Select the New Platform field to be x64
- Ensure Copy Settings From is set to the Win32 project
- Next, on each project in the solution, open their properties, and ensure the Configuration Properties > General > Output Directory and Intermediate Directory fields match the Win32 project's
- On the DLL project, go to it's properties, then go to Configuration Properties > Linker > General > Additional Library Directories and change the $(DXSDK_DIR)/Lib/x86 entry to be $(DXSDK_DIR)/Lib/x64
- Lastly, go into the DLL project, and remove the asm files from platform/ and math/. They are not currently compatible with a 64bit environment.
- Any additional plugins such as physics will need to have the appropriate 64-bit includes and libs as well.
- The project is ready to be compiled for 64bit now.
Once you've installed CMake, run it and you'll see a screen something like the image below. You'll learn to be pretty familiar with this screen!
The two boxes at the top let you specify the location of your source code and the location to put build files. You should fill them in - the source location is just your regular T3D directory, and the binaries location is where you want your Visual Studio solutions to go. This should probably be something like the image below.
Once you've set your paths, you're ready to configure your project! Hit the 'configure' button in the bottom left, and you'll be asked to choose the generator for this project. CMake lets you create project files for many different compilers. Most Windows users will be using some form of Visual Studio, so go ahead and select the version appropriate to you, like in the image below.
Once you've chosen that, you'll be presented with an error message! This is CMake prompting you to enter a name for your project, though unfortunately the only way we have to implement this is by throwing an error!
Don't panic - just hit OK, and expand the 'uncategorized entries' section and edit the value of TORQUE_APP_NAME to match the project name you're working on. At this point you can also specify whether the generated projects should use relative paths. We always recommend doing this.
Once you've filled on those values, hit 'configure' again, and you should be presented with teo more categories - TORQUE and CMAKE. Go ahead and expand TORQUE and browse the options available. You shouldn't need to touch most of these unless you have special needs - for example, PhysX, Bullet, Recast navigation or Oculus Rift support.
Once you're happy with your choices, click 'generate' and CMake will output project files to the directory you chose.
If you browse to the location you asked CMake to put your binaries, you'll see something like the image below - a bunch of VS projects and a solution named after your project.
To compile your project, open up the solution, right-click the INSTALL project, and click 'build'. You only need to do this the first time.
The engine executable will be generated in the project's game folder (i.e. My Projects/<project name>/game/<project name>.exe).
To run the project from within Visual Studio you will need to right click the project name and select 'set as startup project'
cd "C:\Torque3D\My Projects\Game\buildFiles\CMake" cmake ^ -G "Visual Studio 12" ^ -T "v120_xp" ^ -DTORQUE_APP_NAME="Game" ^ -DTORQUE_SFX_VORBIS=On ^ -DTORQUE_THEORA=On ^ -DCMAKE_BUILD_TYPE=Release ^ C:\Torque3D msbuild "Game.sln" /p:PlatformToolset=v120_xp /p:Configuration=Release
Change "Visual Studio 12" to the appropriate generator for your system and 32/64-git requirements.