Porting Items from TGE/TGEA to T3D, a mini guide

I have had a few people send me emails on how I have been porting these items from TGE/TGEA into T3D. This resource will go a little into how I do the ports, the process I take (what process!) and what I look for in the final result. I will go through the steps that I take to ensure a proper conversion. There may be a better way of doing this, but this is how it works for me.

Just a little background on me before I begin. I am a senior network administrator by trade and I have been in the industry for almost 20 years. I have very little knowledge in coding and less in TorqueScript; although, I did take my first basic programming course in 8th grade. I have played with flash, Visual Basic (wrote a program or two years ago), C++ and a decent amount of command script. I am by no means a programmer/coder of any kind. I do; however, understand the logical flow of code. I guess this comes from taking more coding prep courses than actual coding courses! In December 2009, I bought into the Torque engine and began working in it for the first time. I used to play Tribes and Tribes 2 years ago, but only modded the client very little (ski scripts and the ilk) so I am barely considering this experience in the engine. I am still learning and this is one of the major reasons I have been porting the code, to learn the scripts and the engine. The scripts are the easy part, I have a fairly good grasp of the entire script side of TGEA, T3D 1.0, T3D 1.1 and AFX because of it. I tell you this so that you guys understand, I feel like I am the amateur among masters here.

For me, conversion is very simple, it's merely a matching of two different resources, trying to identify the changes and then slowly merging in the items until I have a working copy. Let's take one of the latest (and to date the hardest) ports I have attempted.

I begin the porting process by going through these steps.

1. Install flat base of whichever engine I will be porting too.

2. Download the item to be ported and make sure we have the latest version of the item.

3. Import the new engine install into my SVN server in case I make a mistake, it will be easy to simply revert to the SVN version.

4. Start by importing any engine changes. Prior to working in the scripts, we need to make sure that all engine changes are completed. For me, this is the hardest part. I use google to point out any issues that I am having and try to resolve them with similar solutions. I wish I had more to tell you on this aspect other then this!

5. Start changing directory structures for the ported item. This means making the existing structure LOOK like the new structure!
5a. Rename common TO core
5b. Rename scriptsAndAssets to scripts.
5c. Move (and rename) game/scriptsAndAssets/data to game/art
5d. Copy all the scripts from scripts/client/scripts (you renamed it remember!) to game/scripts/client
5e. Copy all the scripts from scripts/server/scripts (you renamed it remember!) to game/scripts/server
5f. Copy all the scripts from scripts/client/ui (you renamed it remember!) to game/art/gui
5h. Delete the tools directory, shaders directory and profiles directory. You will be using the T3D version of each of these. This does mean that any CUSTOM shader material will need to be replaced (Stryker IAV and the ilk)!
5i. Copy scripts/server/game.cs to scripts/server/gameCore.cs and keep BOTH!
5j. Copy scripts/server/player.cs to art/datablocks/player.cs and keep BOTH!
5k. Continue this process, matching up scripts in the old structure to the new. The only thing your doing is moving files at this stage. Your trying to line up all the files.

6. Clean up your core (common) folder and other folders, get rid of gui, scripts and other items that are not needed. Typically it is safe to delete anything under the unifiedshell and the majority of the scripts. These things are already inside of T3D and will only muddy the water. You can almost always delete a major portion of this folder. The main purpose of this step is to get to the nitty gritty of what your porting. Do not bother with things that are part of the engine. Try to get down to the items that are in need of porting.

7. Pull out Windiff, Beyond Compare or similar program and begin comparing your scripts. Watch out for player.cs, game.cs and gameCore.cs. These files have been split into multiple, TGEA -> T3D and are different based on the T3D version as well. These will be the hardest part...
7a. Compare the files, one by one, function by function, line by line. After a while you will begin to understand which functions are where and which can be ignored. Start slicing through the scripts like a hot knife through butter. Remove and replace functions in your ported code with the T3D version. If you remove the non needed code where functions have been duplicate/renamed and stick to strictly the items code you can make them add-in scripts. This is how the 3DISO kit was handled, it was far easier to remove the bogus code and exec the remaining 3DISO code then to try and merge the non needed functions.
7b. Test your changes and identify the things that are working and the things that are not. After a few ports you will begin to understand where the functions and items are and it will be a lot easier. Until then, use the find feature in windows, torsion or other IDE to try and sniff out the code.

8. When in doubt USE THE T3D version! Some times the code difference between the two looks astounding, but it really is not needed or is actually minimal. A lot of times once you have the engine in, the scripts work OOB! Other times, it is completely different and will need a custom approach (3DISO, Stryker IAV, FGE).

9. Test, test and test some more. Make a single change, not multiple, test it out, see what happens. Buy torsion, I cannot stress this enough. I have a pre-torsion and a post-torsion outlook on Torque. I bought Torque, downloaded the demo of torsion about a month later and couldn't believe I had never downloaded it before. It completely changed my ability to work in the engine and scripts. When the demo ran out, I never felt more crippled in my life. I didn't have the money at the time to buy it, so I went without for almost a month. I found myself getting angry with having to work in other tools, especially after the ease of use in Torsion. I found myself repeatedly saying, Torsion is the first thing I am buying when I get the cash. I did and I have never regretted it. It makes the porting so much easier. It can help you figure out why your engine is skipping that procedure you just wrote. You know the new one, the one thats gonna make you rich? Yeah, that one... Demo Torsion if you havn't!

10. Only change what you have to. If you have a similar function or renamed function in T3D then you had in TGEA, see if this one works. Mod your ported code to T3D, not the other way around.

11. Try porting JUST the item you want, (ie, Stryker IAV, tank, helicopter (yeah I have it working, well partially!)) and work on getting into the game as a scripted object with no additional support. Typically this means just placing the art in and the script for the specific item. Make sure to exec all scripts. Do not bother with mounting code/weapons code/flying code, etc... The main part is to get the item in game as anything other then a mesh. Since your taking it one step at a time, this is the logical approach.

12. The end result... A working port! The fact that the end game in T3D is very similar to the TGE/TGEA version. Compare the two side by side and see what needs to be changed. Focus specifically on one aspect at a time. Go for the simplest thing to implement, sometimes the harder will fall in line.

This of course is by no means a definitive answer on how to port something and is only the approach I take. The three biggest tools at my disposal are SVN, Torsion and Beyond Compare. Without them, I would not be able to complete a port. Get a SVN setup if you don't already, it's a time saver.