Upgrading to TGEA - Twice

Where we left off...
So I usually like to blog at the end of things.. so as to kind of recap my experiences along the way. Right now though, I'm smack in the middle. But I'm going on vacaction next week (Griswald Family Vacation to Walleyworld, woohoo!), and I'm piling up on the amount of things I want to write about, so I'm going forward with kicking something out today.

Last we left off, I had wasted -- err.. I mean, been doing research for the last three months digging through Truespace, Gamespace, and the torque art pipeline. I was trying to create an entirely new detailed character model and get her through the entire pipeline -- from sketch to animated model. In the end, I finally had to punt -- gamespace was just too finicky of a beast to accurately get animations out of, and I had to get back to doing real work -- writing systems. So for now, we'll continue to rely on stock assets and content packs. And I have a new appreciation for 3D artists.

SO, it was time to get back to work on Windstorm, my MMO Proof of Concept. And one of the first things I had already decided I wanted to do was to make the leap from TGE to TGEA. It was never for me a question of if I would make the leap, only a matter of when. For you see, I've made some fairly significant modifications to the engine, and everything I'd read was that TGEA was in and of itself a fairly major overhaul -- not to mention the entirely new material system, etc. So I knew the conversion was not going to be a trivial process. And brother? Let me just tell you I was not mistaken.

Rolling up our sleeves..
The first decision was whether to treat this like an upgrade to TGE, and do an integration in perforce, or to treat it as an entirely new project. Well it only took about 5 minutes of looking over the new directory structure to make that call. An entirely new project.

So the first tip I can offer for anyone out there who hasn't made the leap yet is just that -- don't think of it as an upgrade from TGE. Treat it as an entirely new product, that shares some common code with TGE. Yes, it actually is mostly common code, but the code has been moved around and reorganized so much that you'll drive any sort of merge/diff tool bonkers tryin to figure it all out.

The next thing to decide was on directory structure. My project differs slightly from the stock torque projects, but not too signficantly -- you can't differ too much or things just stop working. Too many relative path dependancies in TGE for you to stray too far. But having gone through the pain of previous integrations, I wanted to make sure I set things up in such a way tha future integrations would be as painless as possible. So here's what I did.

At the root sits Windstorm, the project subfolder. Below it, is TGE170_BASE subfolder, which mirrors the stock /Torque/TGEA_1_7_0 folder you get on installation. Now one thing I noticed is that in my ../Products/ subfolder I *didn't* have the template. This made me sad, but as my original project was based on the FPS starter kit, it would have to serve as my game directory baseline. So under /Windstorm/TGEA170_BASE/GameExamples, I removed all the examples save for Stronghold -- the renamed FPS starter kit. I then checked all that into perforce. Of course we're using revision control here bub.. we're professionals after all!

I then *branched* the TGE170_BASE subfolder in perforce, creating a new subfolder called TGE170_WORK at the same level. This is where all my modifications will go. But *now* we should have a baseline that represents the stock default installation of TGE, so that when future versions are released, we should be able to integrate them more easily.

So now my structure looks something like this...



One thing I would have done differently is not incorporate the version numbers into the names. Duh. But it's done now, and there's no going back. But this is an important lesson to consider.

Once your structures and files are set up in the version control system of your choice, it becomes a royal pain in the ass to move directories and structures around, and plays hell with revision histories, so spend some time setting it up, and make sure you are happy with it.

So directory structures set up, everything mostly in place in Perforce, it was time to start working on the actual integration.

[-- insert two weeks of work carefully comparing differences to old TGE files and new TGEA files and my changes here, including trying to figure out where the hell everything had been moved to.. -- ]

heheh.. no, I'm not kidding. It's a lot of work, and most of it painfully tedious, and just stuff you have to be careful about. I took some notes as I went along, and found some things that were incredibly useful.

First, the porting notes included in the release are golden. You absolutely must read this document from beginning to end multiple times. Pay attention to it. All the stuff it says is true!!

Additionally, this resource this thread post by James Laker had a ton of great info in it.

And beyond that, I kept some of my own notes, so I'll add them here for posterity.

-- "core/realComp.h" has gone away.

-- "gui/controls/guiBitmapButtonCtrl.h" has moved to "gui/buttons/guiBitmapButtonCtrl.h"
- along with anything else derived from button.

-- "dgl/*" - anything in dgl has gone away. All of the draw utility functions are now in GFXDrawUtil, which you get to by calling GFX->getDrawUtil();

-- GameConnection::getControlObject now returns type GameBase, instead of ShapeBase.

-- The Canvas global has gone away. You'll now need create a local variable, and get the root of your control to get the canvas, the way it's done in editTSCtrl:



-- gameconnectionmoves.cpp has been broken up and split over two classes. The definitions of Move and Movemanager have been moved to moveManager.*. There is now a moveList class, that encapsulates all of the previous old gameConnection::move* functions from before. This kids, is what we call componentization. Though I doubt that's how we spell it.

Not a lot, but maybe they'll help you.

Even after I got all the code converted, I still had a lot of work to do before I could get my avatar spawning in my game world in a satisfactory matter. Most of it had to do with mucking around with the assets and replacing old TGE versions of assets with bright shiny TGEA versions. I have some specific examples, but this blog is already running longish, so I'll save those for a future blog.

The Joke's On Me
The real beauty though, of this whole process, is that about halfway through the upgrade process, Matt Fairface and company released TGEA 1.7.1. :O

Now.. far be it from me to complain about rapid releases of much needed bug fixes and cleanup stuff. But you can imagine, after several weeks of integration work, my somewhat weary sigh as I saw this release. In fact, I decided briefly that I would just put off the TGEA 171 integration for some time to come, cause I really prefer a stable working version of my project before upgrading it.

But after the integration, even after fixing up the assets, lots of stuff in my game was still broken. None of my cursors were displaying anymore. After some investigation, I discovered this this was one of the things fixed int 171. My dedicated server was't working correctly. I was having connection issues. gfx draw utility fucntions were not working correctly... and each thing I found, turned out to be something it looked like was fixed in 171. See where this is going, right?

So, I decided it was pointless to try to spend a lot of time fixing the broken things in my game when clearly a lot of the broken things were broken in TGE170, and some other people had already spent a lot of time fixing them, and I just needed to take advantage of them.

So.. after we get back from Disneyworld, all tan and rested and out of money, I'll be tackling TGEA integration...

again. :)

Hope this was useful, or at least mildly entertaining. Until next time..

Devon out!