Setting up TGEA is a simple process. When you license TGEA, you get access to full engine source code. This gives you the power to make changes to the engine's functionality, should you choose to. Studying the source-code is also a great way to learn about advanced game engine programming.
Even if you download the source code now, there are steps you need to prepare your system before you work with TGEA. Make SURE you do the following:
Carefully read through the Directory Layout. Knowing where TGEA’s projects, examples, code, and data is located should be the first thing you do before you touch a single line of code or modify anything. You can go ahead and install your SDKs, drivers, and compilers, but you are encouraged to go to the Directory Layout immediately after.
Download the Latest DirectX SDK
Download the Latest Video card Drivers
Download the Windows SDK (VC2005 Express Users Only)
Download a C++ Compiler
you've downloaded the drivers and SDKs, you'll be ready to compile and modify
the TGEA source-code. Continue on with this guide to learn how.
View the Porting Guide.
to the Microsoft
DirectX 9 SDK website and download the latest version. The latest version available at the time of
writing this documentation is the March
2008 SDK. However, updated DX SDKs
are released approximately 2 or 3 times a year. If you want to use an older version, simply
Google it: “DirectX
SDK August 2007” for instance. The
first result is usually the exact location you need to visit to download the
DX SDK of your choice.
Run the DXSDK installer. When the License Agreement appears, click “Yes” to accept. You will now need to wait for the installer to extract.
When the zip utility dialog appears, make sure the “When done unzipping open: Setup.exe” is checked. Go ahead and click “Unzip.” When the unzipping is complete, click “OK” to continue
If you do not have the Microsoft .NET Framework 1.1, you will be prompted to install it. Your compiler will probably install newer .NET Frameworks, but go ahead and install this anyway.
Agree to the License to continue, and wait for the components to be installed. When the framework install is finished, we finally get to the actual DirectX SDK Installer. Click "Next" to start.
Accept the License Agreement and click “Next” to continue. When presented with the Custom Setup screen, it is highly recommended you use the default parameters for the install directory and components. Changing the components to install is only recommended for advanced DirectX developers who have done so in the past. If you change the DXSDK installation directory, be sure to remember that location as it is critical to setting up the Visual C++ compiler later in this document. Click “Next to continue.
Wait for the installer to copy the new files. If all went well, you will see the completion screen. Click “Finish.”
If you are using the Visual C++ development environment, install the debug version of the SDK. If it does not ask you which to run, you can set it up later in the Windows control panel.
Locate the DX Control Panel. You can typically find this in the DirectX SDK Start Menu->Utilities. If you deleted the start menu shortcut, you can still access it directly from the installation folder:
Go to the Direct3D tab in the DirectX Properties dialog.
Set your Debug Output Level to the 3rd or 4th.
Set the Debug/Retail D3D Runtime (upper right corner) to "Use Debug Version of Direct3D".
As you can see from the dialog, you can switch it back to use the Retail D3D libraries very easily just by changing the selection.
Depending on which Visual C++ (VC) Express compiler you install, which is used for compiling the engine code, you might need to download and install the Windows SDK. This is only a requirement for developers using VC2005 Express. VC2008 Express includes its own version of the Windows SDK, thus negating the need to download and install a separate kit.
*NOTE* - Previous documentation instructed users to download the Microsoft Platform SDK. However, as mentioned in the Platform SDK Overview, this SDK is now superseded by the Windows SDK.
VC2005 Express Users (ONLY): Start by downloading the Windows SDK found HERE.
You might be asked to validate your copy of Windows. If this happens, follow the on screen instructions provided by Microsoft. It is a relatively painless process.
Once the initial download is complete, run the Setup executable. You will first be presented with a Welcome Screen.
Click “Next”, and then on the following screen, agree to the license and click “Next” again.
The following screen allows you choose your installation directories. It is highly recommended to keep the default directories, but if you change them be sure to remember the new location. Knowing where the headers and libs are installed is critical to setting up your compiler to load/compile Torque and other applications.
Click “Next” to view the Installation Options screen, the application has already marked important components which should be installed. If you plan on creating mobile applications in the future, you can choose to install them. However, this is not related to any Torque development. For everything else, just keep the defaults.
Clicking “Next” will take you to a Begin Installation screen. From here, you can click “Back” to make changes, or “Next” to begin the download. This is your last chance to go back and review your installation options. When ready, click “Next.” You will then view a screen that shows the status of your download and installation.
When the installation is complete, click “Finish” to exit the installer. If you had any boxes checked, the resulting action will occur after the application terminates.
It is very important that you make sure your graphics drivers are up to date. If you haven't updated in at least a month, do so now. Video card manufacturers are constantly improving their drivers, and fixing problems. Updating will save you tons of time if you are coding shaders and trying to track down a bug that turns out to be a driver problem.
If you do not know how to find out what video card you have, perform the following:
Open the Control Panel (Start->Settings->Control Panel)
If you haven’t already, switch from Category View to Classic View. Find the System icon and double click on it.
When System Properties appears, click on the Hardware Tab at the top. From here, click on the Device Manager button.
In the Device Manager, Click on the Display adapters [+] symbol to view your graphics card.
Most modern video cards are made by two major companies: ATI or nVidia. If your graphics card belongs to either of the two companies, you can grab updated drivers here:
If you have an integrated graphics card, such as Intel integrated, you will need to go to the manufacturer’s website to get the latest drivers or install a beefier graphics card.
Once you've updated your DirectX SDK and video drivers, you are ready to begin working with the engine. Since you get access to the full engine source-code, the first step is to download the source.
If for some reason you still have this document, but deleted/corrupted your SDK, downloading the TGEA source-code is pretty simple. Access your account page and select the download option for TGEA. Please note: if you have any questions about materials covered in this guide, please check this before posting on the forums:
After the download is complete, run the installer. The installer is pretty straight forward: just follow the on screen directions. You can choose the location of your TGEA directory, but be sure to place it in a sensible location and remember where it’s installed.
The Directory Layout, which you should look over immediately, will use relative paths to avoid confusion if you choose to install TGEA in a non-default directory.
When it comes to compilers, you have quite a few choices. For this documentation, we are recommending Microsoft’s Visual Studio. If you have the money, you can purchase the full studio suites. Alternatively, Microsoft has started releasing a line of free compilers referred to as “Express” editions. There are currently two version available, and while you only need to download one (or have already picked one) setup for both will be provided.
Start by downloading Visual C++ 2005 from Microsoft’s Website. When visiting the site, you will see multiple compilers for various languages: C#, Visual Basic, Web Developer, etc. You want to download the Visual C++ IDE:
The download link found on this page is for a web based installation. What his means is that you will download a small setup file that will download the necessary components and install them automatically. You can locate the offline installation, but this will be a larger download and requires DVD image burning or mounting software. Keeping it simple, we will stick with the web installation.
Run the vcsetup executable to start the process. A few quick dialogs will pop up, preparing the installer. When the main page appears, click “Next” to start.
Click the box to accept the License Agreement and click "Next" to continue
When the Install Options screen appears, keep the Graphical IDE box checked. It is also highly advised to install the Microsoft MSDN. While you can access and online MSDN, it is handy to have an offline version for faster access and those rainy days when you lose internet access. Click “Next”
Review your installation options. It is recommended you keep the default install directory to avoid confusion later in development. Click “Install” to begin the download.
From here, the installer will download the necessary files. This could take a while, depending on your connection. On top of the VC compiler and MSDN, you’ll notice that the application might also download and install Microsoft .NET Framework 2.0 if you do not already have it in your system. This is a requirement for Torque development as well as non-Torque functionality being used by newer software. This would be a good time to start looking through other sections of the documentation and tutorials to start familiarizing yourself with Torque.
Once the application has finished downloading the necessary files, it will install them to your system. Again, depending on your computer specs, this could take a while. Don’t forget to check the Garage Games website for updates and resources you might find useful for your game projects.
Once finished, you will be presented with a completion screen which informs you of two important notes. One, you have 30 days to register this product. It is recommended that you go ahead and do so, as it is free and mandatory. The other note lets you know that there might be updates available for your OS and compiler that correct bugs and security issues. For each item, click on the link and follow the site directions for registration and updating. Click "Exit" on the installer to finish.
Start by downloading Visual C++ 2008 from Microsoft’s Website. When visiting the site, you will see multiple compilers for various languages: C#, Visual Basic, Web Developer, etc. You want to download the Visual C++ IDE:
Run the vcsetup executable to start the process. A few quick dialogs will pop up, preparing the installer. When the main page appears, click “Next” to start
Click the box to accept the License Agreement and click "Next" to continue
At the Installation Options screen, it is highly recommended that you enable the install for the MSDN Express. MSDN is the official documentation from Microsoft that allows you to look up functions, classes, and variables that come stock with the Microsoft Platform SDK and C++ language. While you can access an online MSDN, it is handy to have an offline version for faster access and those rainy days when you lose internet access.
Review your installation options. It is recommended you keep the default install directory to avoid confusion later in development. Click "Install"
From here, the installer will download the necessary files. This could take a while depending on your connection.On top of the VC compiler and MSDN, you'll notice that the application might also download and install Microsoft .NET Framework 3.5 if you do not already have it in your system. This is a requirement for Torque development as well as non-Torque functionality being used by newer software. The other downloads consist of libraries and frameworks necessary for development.
Once the application has finished downloading the necessary files, it will install them to your system.
*TODO – INSERT IMAGE FOR INSTALL SCREEN
When finished installing, you will be presented with a completion screen. This screen informs you that you have 30 days to register. It is recommended you go ahead and do so. Click on the link and follow the site directions for registration. Click "Exit" on the installer to finish.
After you have the source-code downloaded, you'll need to get it compiled. Compiling TGEA works just like compiling the Torque Game Engine. You can read below for instructions on compiling with Visual C++ 2005 and Visual C++ 2008. The main steps involve configuring your compiler so it can load Torque and other DirectX projects, adjusting the windows in the IDE for a better view, and running the builds (debug and release) from within the compiler.
The various iterations of Visual Studio and Visual C++ Express share common dialogs and GUIs. With that in mind, configuring both VC2005 and VC2008 will be handled in this section. If there is a drastic difference in a step, GUI appearance, or menu location, two screen shots will be provided: one for each compiler. Otherwise, one screen shot will be shown.
Go ahead and launch Microsoft Visual C++. If this is your first run, you will see one-time configuration performed by the application. The only difference between the VC2005 and VC2008 is the year shown in the dialog.
When the environment loads, you should see a startup screen and some windows which we will get to later. For now, we are focused on configuring your compiler
Our first step is to load VC’s Options. Within this menu, we can configure the IDE however we want. We can change color schemes, short keys, directories to search for libraries and headers, etc.
On the left, you will see a tree of sub-menus. Navigate down to Projects and Solutions->VC++ Directories. From here, we tell the compiler where to look for core headers and libraries we need in order to compiler Torque: namely DirectX files. So, let’s start with adding an executable file. In the top right, under “Show Directories for:”, highlight the “Executable files” option (highlighted in blue in this screen shot)
Click the folder icon between the checkmark and X. A blank line will insert itself in the list of directories. At the end of that line, you will see a series of dots […]. Click that button
The menu that opened is a file browser. Navigate to the directory you installed DirectX SDK. You need to find the following subdirectory:
Microsoft DirectX SDK(Version)/Utilities/Bin/x86/
Once you click “OK,” your directory will be successfully added, as shown below (your install path might be different):
Next, we need to add the location of DirectX SDK include files. Change the “Show directories for:” option to “Include Files”. Click the folder icon to insert a new line. Click the […] button to open the file browser. You want to point to the DX SDK Include directory:
Microsoft DirectX SDK(Version)/Include.
Click “OK” when you have found the folder.
Next, we need to point to the DX SDK libraries. Change the directory option to “Library files”. Click the folder icon to insert a line, then click the […] button to open the file browser. Point to the following DX Directory:
Microsoft DirectX SDK(Version)/Lib/x86.
Click “OK” when you have found the folder. That takes care of the bare minimum, required directories to develop a DirectX application such as TGEA. Close the options to return to the main VC window.
These next few steps are optional, almost aesthetic. You can skip ahead, or read on to learn how to organize your IDE windows. Particularly, we need to add an error window to the interface. As developers, we are all bound to insert code that generates errors. Having a readily accessible window to show us our mistakes is a good idea.
If you look in the bottom left hand of the application, you’ll see a set of tabs similar to the following screen shot:
We need to add another tab that will allow us to quickly access the error window. Go to the menu bar at the top, and click on the View->Other Windows->Error List option. Depending on any other modification you might have made previously, the Error List window will pop up (usually undocked). As you’ll see below, the window displayed directly above our bottom set of windows.
Now, you can leave this as it is, but you have just lost a decent amount of window space where your code will be displayed. You can move that window (or any other window for that matter) anywhere on the screen, and combine it with existing windows. Click the blue bar on the Error List and drag it on top of the bottom window. A blue overlay should appear. Still dragging the window, move your mouse pointer directly over the middle box surrounded by various arrow boxes. When you let go, your Error List window will be a part of your bottom set.
At this point, if you have not already looked through the various files and folder structures copied during the TGEA installation, you may want to have a look through the Directory Layout section before loading a project and compiling. If you feel comfortable with the location of your files and where your executables will be generated, go ahead and proceed with the rest of this section.
You will want to load a full TGEA solution (.sln) into a Visual C++ compiler. Let’s open up the Stronghold solution. The steps are the same for all compilers since VC 2003. This section will use the VC2008 solution and compiler, but if you are using VC2005 or lower, just navigate to the proper folder.
There are two ways to open the solution. You can double click on GameExamples/Stronghold/buildFiles/VisualStudio 2008/Stronghold.sln, which in turn launches VC2008 and automatically loads the solution.
Alternatively, you can open your compiler first. From there, you can load the solution through the menu system:
Since we just touched on the topic, let’s discuss the difference between Debug and Release mode. To switch between modes, you will want to use the quick menu option:
There are many differences between the two configurations, but to keep things general and simple here is a small breakdown:
Debug executables are larger than Release executables. This is due to the lack of embedded debugging information in the Release build.
Release executables are optimized and typically run faster than a Debug build.
While you can launch both builds from the compiler using the “Start Debugging” command, only the Debug build will properly use breakpoints and display debugging information such as variable values, memory addresses, etc.
Be sure to look through the Torque forums to see how this specifically applies to TGEA, and also browse through the MSDN for official Microsoft information.
Well, it certainly took a few steps to get to this point, but we are finally ready to build. In compiler menu, click on Build->Build Solution (F7)
Fully building a TGEA solution for the first time can take a few minutes, but you can keep track of its progress in the Output window:
As you can see, Visual Studio is compiling each project in the solution, and each code file within. If you happen to catch any warnings or errors as it scrolls, you can switch to the Error List window to see what is happening. However, a clean build will compile without problems resulting in the following image:
After the code compiles, the Visual Studio will begin the Linking process. What’s happening here is the compiler is combining files together with standard libraries to produce the executable. This usually pertains to .libs, .dlls, and .h header files.
Seeing the “Embedding Manifest” message is usually your cue to exhale or do a victory dance, as the compiling and linking processes were a success. The really important info is highlighted in the above picture: this message will tell you how many projects were just compiled, how many succeeded, and how many failed.
As stated earlier, out of the box solutions will result in perfect build. However, if we insert some bad code like this:
If another programmer is looking over your shoulder, you will get hit for writing this code, and you will also see a very angry set of messages in your Output and Error List windows:
Do not put the above code in your solution or make any other modifications just yet. If you just compiled under the Debug configuration, go ahead and switch to Release and build (vice versa if you started with Release). Now, we should run the application to see if it works.
You can run the executable found in your game directory: GameExamples/Stronghold/game/Stronghold.exe. That’s a standard method for any Windows program. Let’s do something flashier and run from the compiler: click on Debug->Start Without Debugging (ctrl+F5)
If you have followed all the setup steps found in this Getting Started document, your TGEA application will launch and you are ready to dive into development.
This section of the documentation can also be titled “What the heck did I just download?” A fresh install of TGEA will contain dozens of folders and hundreds of files. This section will give you a high level tour of what you are looking at. If you blindly rush into development without knowing how a Torque project is put together, you may paint yourself into a corner and have to start over.
Root Directory: This will be the location you choose to install TGEA. Along with the sub-folders that make up the SDK, there are a few important files to note.
· generateAllProjects.bat – Running this batch file will create all the VC projects listed in the allProjects.txt. After reading in the project list, the file will generate the projects and solutions and spit them out into the buildFiles folder of each game.
· allProjects.txt – This file contains a list of game projects and their locations in the directory.
· compileAllProjects.bat – Running this batch file will compile the VC projects listed in the allProjects.txt
· syncShrdConsts.bat – Running this batch file will copy (synch) all projects up with the same shader constants file (explained later).
Root\Documentation: Here you will find the offline documents, which you are reading right now. You can open individual pages or load the whole document.
Root\Engine: The various sub-folders, files, and libraries found in this directory make up the core source code of TGEA
Engine\bin: Contains executables useful for advanced development, doxygen document generation, nasm assembly, etc.
Engine\lib: Contains the critical libraries for compiling a Torque project. Later in development, if you wish to add custom 3rd party projects, such as PhysX or the P5 Glove SDK, this would be a good directory to add the .dlls and .libs to link to.
Engine\Source: Organized in folders by module, this directory contains all of the files that make up the TGEA source code. Once you read a little more documentation and experimentation, finding what you want will be much easier. Still, some modules are more self-explanatory than the others. For instance, the “atlas” folder will contain the classes and code pertinent to the Atlas terrain system.
*Previous Users of TGEA Note*- Some key folders you are used to coding in have been moved or renamed. The big one is that the “game” directory (containing classes for the player, AI, vehicles, camera, etc) has been renamed to T3D. Newcomers will want to spend a lot of time in this directory as well.
A full tour of the engine directory can be found in another section of the document (place link here when page is complete)
Root\GameExamples: Each folder within this directory contains a separate demo, game mod, or prototype. Each example shows off features that make TGEA stand out. This directory will most likely be where you want to create your own game folder/project.
GameExamples\AtlasDemo: This game example shows off the blended Atlas terrain feature and a simple waterblock. Loading this project, viewing the scripts, editing the mission, etc, will give you a good understanding on how to load and modify Atlas terrain.
demo is a direct
GameExamples\Forge: The Forge game mod shows off the prettier side of Torque. This has been a conference favorite for a while. Here, you can view advanced lighting, particles, and shaders at work.
GameExamples\Stronghold: In terms of game play, Stronghold has more to show than the other mods. This is your basic FPS starter kit. The core Torque systems are in full effect: networked game play, collision, projectiles, rendering effects (particles, explosions), environment (Sun, water, terrain), and more. If you want to jump right into developing a game prototype, modifying the Stronghold game might be the way to go.
GameExamples\T3D: New TGEA features are shown off in this game example. Before you even jump into the game, you can change your game character via the "Select Model" option. The mission itself shows off the new feature of having multiple, tiled Legacy terrains. While not immediately apparent, the character is reacting to interiors and the terrain using the new Polysoup collision system.
Each example game shares a common organization theme and folder hierarchy. So, for this next section we are going to dissect a specific game example and examine how a typical Torque project is organized. Let’s dig into Stronghold.
Base Directory Files – The three batch files found here perform useful automated routines that can speed up your development.
· DeleteDSOs.bat – Deletes all the .dso files (compiled script code) found in all sub-directories of the game example
· DeletePrefs.bat – Deletes all preference files in all the sub-directories of the game example. These files usually contain information such as custom screen resolutions, audio levels, and so on.
· generateProjects – Will create your Visual Studio projects and solutions for you. Considering the amount of files, folders, and libs that make up the TGEA SDK, you definitely want to use this if you have to develop a game example from scratch
source – This folder will hold source code specific to your game will be found here. This is entirely separate from the core source code used by all the game examples.
buildFiles – Each sub-folder found here contains the projects and solution you can load into your compiler. You obviously want to choose the one that supports your Visual C++ IDE. The compile.bat file is a command line application that will automatically build your solution for you, without opening your compiler If you run the file as it is, or do not pass arguments to it in the command line, it will automatically build the VC2005 project. See Compiling the TGEA Source Code for more information.
config – This directory contains configuration files that are loaded by other applications For instance, engineDoc.conf is used by Doxygen to create an engine reference document. project.conf is used by the generateProjecs.bat to determine how and what to include in the projects and solutions.
game – The game folder contains everything that makes up your game: scripts, GUIs, assets, and editors. From here on out, assume we are looking at folders inside of the game directory.
common – This directory is very similar to the scriptsAndAssets folder. You will find scripts, GUIs, and data just like in the scriptsAndAssets folder, except these are shared amongst all game mods added to your project. In other words, you can create a "Survival Horror" folder in the game directory, which is completely separate from scriptsAndAssets. Both mods will share the common scripts and folders.
profile – The scripts found in this directory are used to check your graphics card for compatibility against the engine. If you do not have a supported graphics card, or you do not have capable drivers, you will be reminded to upgrade and update.
shaders – This is the directory you should store all of your hlsl (high level shader language) files. Sub-folders are used for organization. If you have several shaders related to each other, all weather shaders for example, you can create a folder and store them there.
tools – Your GUI editor,
scriptsAndAssets – The bulk of your game content is found in this directory. Typically, this directory is broken down into three sections: client, server, and data.
client – Your client side scripts and data will be found here. This usually pertains to logic and GUIs not shared by in a multi-player game, like an Options Menu or action map script. In Stronghold, scripts and logic pertaining to input binding, GUI helper scripts, and mission downloading are stored in "scripts." GUIs and images can be found in "ui"
data – Anything related to this game play assets will be found here: 3D models (shapes), environment data (skies, environment, terrains), audio files (sound). These are usually sorted by both relevancy and data type. DTS files used to represent 3D models will be found in the “shapes” folder. DIFF files which contain building and interior geometry will be found in the “interiors” folder. OGG and WAV files for sound effects will be found in the “sound” folder. Have a look around, as the data folder is pretty straight forward.
server – Server side functionality and scripts, which every player is affected by in a multi-player session, are found here. A large portion of your time will be spent in this directory while developing your game. This folder contains the script files used to build the player (player.cs), AI (aiplayer.cs), weapons (weapon.cs & crossbow.cs), network connection (game.cs), core game logic (game.cs), and so on. Individual scripts will be addressed in later tutorials.
Setting up TGEA can be a lengthy process, but you want to have a strong foundation and stable system before you dive into development. From here, you can go to any other part of the documentation that pertains to what you want to start developing. There is no right or wrong starting point beyond this document. However, if you want to go from high level to low level, this is one recommended path:
Study the Torque Script documentation to find out what major systems are exposed to the script language. Take the time to learn the syntax, how the example games use Torque Script, and try out some of your own custom code
mixing your script modifications with the components you create with the GUI
Begin browsing and modifying the engine source code. A great way to learn how to modify the source code is to download and integrate the free GarageGames Community Resources. Not only will you get new functionality, but these mini-tours of the engine are invaluable.
Whatever path you decide to take, there is a mantra that every newcomer to TGEA and novice programmer should memorize:
“READ. READ CODE. CODE”
Read through this documentation, and regularly check the forum posts on GarageGames.com. Read the sample code and resources posted by others to get an idea of how to modify the engine. Finally, start with simple changes to the scripts and engines. Expecting to launch out of the starting gate and creating a MMORPG will only end in frustration.