TGEA 1.7 Porting Guide
of this guide is to provide a launching point for people just starting out
using TGEA 1.7, with detailed help for those moving from TGEA 1.0.3 and TGE
The High Level Directory Explanation
will provide you with a brief description of how standard TGEA 1.7 projects
(such as the ones found in GameExamples) are laid out. Structuring your project directory similar to
this is recommended, but not an absolute requirement.
actual porting guide is broken into 2 sections: Summary of Changes and
The Changes Summary is a reference of
critical code changes you should keep in mind, or use to modify your existing
projects that were created pre-1.7.
The Checklist is a simple set of steps to
follow when performing a high level transfer of your pre-1.7 projects.
For more detailed information on setting up your system for Torque development, head over to the Getting Started section of the documents.
High Level Directory Explanation
The TGEA 1.7 codebase is a unification of the TGE and TGEA codebases. The
core of the engine is based on part new code and part stable TGE/TGEA
code. The rendering engine is based on TGEA, with an updated GFX to
support d3d, “shaderized”, and fixed function rendering. The windowing
code allows multiple windows, ideal for tool development.
One of the major changes in TGEA 1.7 compared to TGE/TGEA is the project
layout. Whereas before the engine was a game and one created a new game
by modifying the single SDK project, we now are set up to support multiple
projects side by side, each treating the engine as a library. To this
end, you'll find several projects in the GameExamples directory. Each of
these is laid out the same:
- holds source art files for
- holds scripts, data, and
loadable art assets for your game.
- these are the project and
solution files for the various IDE's that are created by the Project
- files for configuring the
projects. This is one of the major places that the project can be
- source files specific to
your game. This is also the home of torqueConfig.h file, which lets
you specialize the engine per project.
- creates the project files
for all the platforms. The project generator scans the source
directories to figure out what files need to go in the project files so
you don't have to manually maintain this across all your projects.
*Note that project directories need to
be 2 deep in the TGEA directory just like above in order for the project
generator to work correctly.
For more details on folder hierarchy and what projects ship with TGEA 1.7, check out the Directory Layout section of the Getting Started Docs.
Porting from TGE/TGEA
Summary of changes before porting
from TGE/TGEA (use for reference only, a checklist for
porting is provided below)
- Changes from TGEA material
system: TGEA 1.7 has an updated gfx system which supports D3D8,
D3D9, and fixed function rendering. To support fixed function
rendering we have introduced the ProcessedMaterial class. This is
all the data associated with rendering a material instance in a particular
mode (e.g., fixed function vs shaderized). NOTE: ProcessedMaterials are
generated and used by the engine to contain the runtime data derived from
CustomMaterial and Material datablocks in your project, including
fallbacks as necessary. They are not directly created or used by the
developer or artists.
- In addition, basic materials
will be generated during shape loading if a material has not been defined.
This will simply wrap any textures referenced with a basic material, and
will not give any shadergen effects. It does keep you from having to
create a new material for any artwork that simply needs a mapTo= line
- File moves (source code): the
old engine/game directory has been removed. The files from this
directory can now be found either in engine/app or engine/T3D. The
purpose of this rearrangement is to begin separating example code from
true engine code. Thus, engine/app contains code that is essential
to creating a generic TGEA application. The files in engine/T3D,
however, are specific to creating a game in 3D. NOTE: The engine/T3D
directory contains classes such as ShapeBase, Player, and other FPS
specific game level objects for reference and example purposes. For new
projects, code that you write should be placed in the
General Engine Changes:
- Find and replace #include "game/game.h"
- Some GFX calls need to change to GFX->getDrawUtil():
- ex - GFX->clearBitmapModulation()
changes to GFX->getDrawUtil()->clearBitmapModulation()
- The RenderInst class has been
changed to a structure. Replace all class
RenderInst with struct
- .cc to .cpp: in TGE all files
used the .cc file extension. This caused some problems with Visual
Studio. In TGEA, many files were renamed to use the .cpp file
extension. In TGEA 1.7, all files use the .cpp extension. This
can cause some issues with merging and doing file compares. One
useful trick is to set your diff viewer to ignore file extensions.
General Script Changes:
- Code that uses $Con::root to
construct path names may need to be checked to make sure it still
constructs valid paths. For example, the following will not be
expanded to a valid path on TGEA, but might have worked on previous
versions of Torque: %this.setBitmap($Con::Root @
"~/client/ui/game/numbers/" @ %number @ ".png");
- The C++ console function
"createCanvas" is gone. The example apps create a script
function createCanvas which you should copy to your project (and be sure
to merge changes to the example createCanvas back into your app).
- TGEA 1.7 does not close your
application when you click the X on your window. Instead, a call is
made to the script method GuiCanvas::onWindowClose (this is in case you
have a multi-window application). To close your app when X is
clicked, call 'quit();' from within GuiCanvas::onWindowClose (as is done
in the example apps).
- Gui profiles used for text
controls must have a fontType string set, or else they will assert/crash
- StringHandle class has
changed to NetStringHandle
- An additional parameter has
been added to OnStaticModified():
- Within any subclasses of SimObject,
replace virtual void onStaticModified(const char* slotName); with virtual void onStaticModified(const char*
slotName, const char*newValue =NULL);
- See Jeff
Faust's Post for more details
- The member variable mBounds is not public anymore
- Change mBounds.extent.x to getWidth()
- Change mBounds.extent.y to getHeight()
Particle Emitter Changes:
- ClientMissionCleanup group is
now necessary. If you don't have it your particle emitters will
assert in debug and in release builds the game will probably crash.
The group must be created from scripts. Search for ClientMissionCleanup
in a TGEA 1.7 example project to see where to put it.
- If you are porting old
scripts you will need to comment out activateKeyboard/deactivateKeybaoard
calls (affects console).
global functions are gone. You will need to replace these with Canvas.getVideoMode/Canvas.getModeCount/Canvas.getMode.
- Find first/next file now
returns full system-specific absolute paths, not paths relative to the
game root as it did before. You will need to convert the paths to
relative using a command like this: %file = makeRelativePath(%file,
is now called getConnectionToServer()
- Custom shaders: if you have
written custom shaders, you should make sure that the constants used by
the engine match what your shaders are expecting. Shader Constants are
defined per project in your /<project name>/game/shaderConsts.h
- If you are using your own
game scripts, and you do not have the lighting system/shaders, you will
need to add those, or else you won't get shadows in game. Merge in
common\lighting and shaders\lightingSystem, then, in initBaseClient, add
this line: exec("./lighting/sgShaders.cs");
Console and Sim Changes:
- If you keep pointers to
ParticleEmitters in your game objects, change these to
SimObjectPtr<ParticleEmitter> so that you don't have double delete
problems. Ditto for SFXSource objects.
- The TGEA particle system has
a one texture per emitter
requirement. This means that all of your particles must share
teh same texture. For proper results, create a tiled texture and assign
texture coordinates in each particle so that each uses a different tile.
See this TDN
Particle Article for more information.
- Con::executef() only takes in
char variables as parameters now:
- ex - Con::executef(getDataBlock(), 2, name,
scriptThis()); changes to Con::executef(getDataBlock(), name, scriptThis())
- The mCross function can now
take in a pointer as a parameter:
- ex - mCross(forward, up, right);
can be mCross(forward, up,
- Location of sim files have
changed. You want to adjust your paths and includes for the following:
- sim/sceneObject.h --> sceneGraph/sceneObject.h
- sim/decalManager.h --> sceneGraph/decalmanager.h
- sim/decalManager.cpp --> sceneGraph/decalmanager.cpp
- sim/pathManager.h --> sceneGraph/pathManager.c
- sim/pathManager.cpp --> sceneGraph/pathManager.cpp
- sim/simPath.h --> sceneGraph/simPath.h
- sim/simPath.cpp --> sceneGraph/simPath.cpp
- sim/sceneObject.h --> sceneGraph/sceneObject.h
- If you were using OpenAL you
will need to update to the SFX system.
- rename AudioDescription
objects to SFXDescription in scripts
- rename AudioProfile objects
to SFXProfile objects in scripts
- Replace any #include "audio/audioDataBlock.h"
code to #include "sfx/sfxSystem.h"
- AUDIOHANDLE has changed to
- Replace all references to TypeAudioProfilePtr
- Replace all alxStop function
calls with sfxStop
- in common/client/audio.cs,
copy in the sfx functions from T3D/assets/common/gameScripts/audio
- replace all alxStopAll with
- rename alxPlay to sfxPlay
- code that used to call alxStop($sourceId)
will need to be changed to $sourceId.stop(), because sfxPlay now returns
sim objects for the sources. Or you can add this function to
sfxSystem and just change alxStop to sfxStop in the scripts:
ConsoleFunction(sfxStop, void, 2, 2, "(S32 id): stop a source, equivalent to id.stop()")
S32 id = dAtoi(argv);
SFXSource * obj;
if (Sim::findObject<SFXSource>(id, obj))
- alxGetWaveLen changes to ???
- alxSourcef changes to ???
- alxCreateSource changes to
sfxCreateSource (also check parameters to the function)
- alxSetMasterVolume changes
- call sfxStartup() somewhere
(A good place is right after Canvas is created, but make sure defaults.cs
and prefs have been executed first so that you get the user's volume
- call sfxShutdown() somewhere
(shutdownCommon() if you have it, common::onExit if you don't)
- if you have your own options
gui, merge in updateChannelVolume from common/gameScripts/options.cs
- change pref variables from
$pref::Audio to $pref::SFX. As of this writing (6/4/2007), the
following prefs are valid for SFX:
(not actually used by SFX directly, but used to save channel volume
settings and passed to sfxSetChannelVolume) ($pref::Audio)
(ditto) (formerly $pref::Audio)
(set this > 0 if you are not using hardware sound, otherwise you will
hear no sound)
- add a call to sfxSetMasterVolume
where appropriate in your scripts
- add calls to sfxSetChannelVolume
where appropriate in your scripts
- set $pref::SFX::provider to
a provider in your scripts, in defaults.cs usually. choices are
"DirectSound" or "OpenAL"
- if your SFXDescription
objects specified a "type" field to set the channel, you will
need to rename that to "channel" in the scripts, or else add
the following line to
SFXDescription::initPersistFields::addField("type", TypeS32, Offset(mChannel, SFXDescription)); // for backwards compatibility
- Each time your merge with a
new version of TGEA 1.7, you will need to manually merge source/torqueConfig.h
and source/main.cpp. Typical these files should be compared with the
appropriate 3D example or template in the TGEA tree.
- You will need to merge in the
build configurators projects.conf file with the appropriate file in your
game directory. After that you will need to re-generate your project
files as normal.
Porting/Upgrade Checklist (TGE or TGEA)
If you wish to start with a completely clean TGEA 1.7.1 project and add your code to it, try using the new project generator tool included with the latest version.
For detailed information on how to use the new tool, read through the New Project Generator Guide.
Extract all of your custom files from your original project, and place them in
the top level <MyGame>/source directory. You should not need to change
any #include lines, as all directory references are abstracted.
If you have made changes directly to stock code (Player.cpp for example), you
will have to manually merge your changes.
Once you have finished separating your changes, execute the "generateProjects.bat"
file at the top level of your project directory. This will automatically
generate .vsproj project files and a new solution file.
delete template versions of /client, /data, /server if desired
Important Note: the /common directory is still important at this stage, and we
are using it as a "wrapper" to ease the porting process.
If you have for whatever reason removed the use of the /common directory, you
will need to manually merge and adjust the calls and scripts in
the various directories. The /clientScripts/client.cs is of particular
copy over your /client, /data, and /server directories, as well as your main.cs
from your project to /scriptsAndAssets.
add $Pref::Video::MainWindowTitle = "Torque Game Engine Advanced";
$Client::MissionTypeQuery = "Any";
add loadMaterials(); after
// Default player key bindings
in scriptsAndAssets/main.cs add in
// Start up the audio system.
// Load the scripts that start it all...
Re-export all of your interiors with TGE_A 1.03
--alternatively, you can use Constructor 1.03, using the "Save as
if you have a hard coded mission file, make sure your createServer line
properly expands file names:
If you have a custom mission loading mechanism, you will need to make sure you
tracking the directory structure changes
Copy in the new waterblock from the TGEDemo (use as template) into your .mis
Change all references:
AudioDescription to SFXDescription
AudioProfile to SFXProfile
alxPlay/alxStop to sfxPlay/sfxStop
TGEA 1.7 is more stringent when it comes to namespace management, and will not
like if you name an object the same as it's underlying class, such as:
You should add the word "Object" after the token that is the same for
any objects created in your mission file (or elsewhere):
TGEA 1.7 will also warn if you have a persistent field class or superClass that
defines a namespace that already exists for this object.
PORTING FROM TGEA 1.0.3 or TGE 1.5.2:
--comment out all 4 legacy terrain shader defs in
scriptsAndAssets/client/scripts/shaders.cs to read:
new ShaderData( TerrShader )
pixVersion = 1.1;
new ShaderData( TerrBlender20Shader )
DXPixelShaderFile = "shaders/legacyTerrain/terrainBlenderPS20P.hlsl";
pixVersion = 2.0;
new ShaderData( TerrBlender11AShader )
pixVersion = 1.1;
new ShaderData( TerrBlender11BShader )
pixVersion = 1.1;