Setting up a Perforce Depot to work with TGEA
by Dusty Monk · 07/08/2008 (8:50 am) · 0 comments
I'm not going to even touch on the argument as to whether or not you should be using a revision control system -- namely because there isn't ANY reason why you shouldn't. Even if you are a single developer working on your game, the ability to have a revision history, roll back changes that go bad, and a database that serves as a safe repository for all your code are all reasons enough you shouldn't even be considering not using an RCS. The only question is which one. Personally, I prefer Perforce. It's free to use for a two user license, integrates well with Visual Studio, and provides both a web based client and several options for a windows based client, and there's always the command line options for you power users.
When I set out to write this resource, I had a hard time deciding at what level to write it. I finally decided that in order to keep it a manageable length, I'm going to assume you can go to the perforce website, download the server and client software (P4V), and get it set up and working. In other words, I'm not going to attempt to teach you how to use Perforce. What I do hope to provide you is a good suggestion for setting up your depot in such a way as to make integrating future releases of the engine as painless as possible.
All the examples I give here are using TGEA as the model, but this would work equally as well for TGE. What constitutes the "game" subfolder is slightly different between the two engines, but I'll leave it to you to make the appropriate translations.
The Initial Check In
So you've just installed TGEA, you've read through the "Getting Started" documentation, and you're all ready to run SetupNewProject.exe. Well hold on one second hoss. Let's do a little directory management before we do. First, if you're like me, you probably want your new game to be under its own roof on your hard drive, and you probably don't want that roof to be called Torque. For our example, let's say our new game project is going to be the next best WWII shooter ever, and it's called Ambush.
So we make a subfolder under the root folder called Ambush. Under that folder, make a subfolder called TGEA_Base. Inside of that folder, copy everything that is in the c:\torque\TGEA_1_7_0 subfolder (or whatever the new, pristine folder was where you installed your TGEA sdk). This leaves the TGEA sdk installation clean (which we like), and will provide the baseline in perforce for our changes. What you want to leave or keep is ultimately up to you, but I would recommend deleting the 'documentation' folder, and the 'GameExamples' folder inside of the TGEA_Base subfolder. You aren't really interested in integrating new stuff from GameExamples or documentation, and as one folder of the documentation folder has about 5000 files in it, removing it from perforce integration is just going to make your life easier. I would leave however, the Template subfolder under Projects, as you *are* interested in integrating these changes. Now it's time to get this initial baseline into Perforce.
Bring up P4V, and create a new workspace, call it something like Ambush-WS, and add a view that maps your Ambush subfolder to the depot Ambush subfolder. So your workspace should look something like this:
If you haven't made this workspace your current one, do so by choosing Connection|Choose Workspace in P4V. Now in the left hand window of P4V, click on the "Workspace" tab, navigate to the c:\ambush subfolder, r-click on this folder, and choose "Mark for Add". Once that's done, in the right hand pane, click the "Pending" tab, r-click on the default changelist, and choose Submit. Give the submission a useful description like "Initial check in of baseline", and fire away. There's likely over 3000 files in this initial check in, so it could take awhile. Once that's done, click on the "Depot" tab in the left hand panel, and you should see something that looks like this:
Make a Branch
Okay the next step is to branch from our baseline to create our working subfolder. This is the actual subfolder where you'll build your game. To do this, we perform n "integration", which is Perforce's single word they use for both integrating changes and branching the codeline. In the Depot tree, right click on the "TGEA_Base" folder, and choose "Integrate". In the dialog that comes up, click on the "Branch Specification" tab, and then click the "New" button. Call the branch specification something like "Baseline to Work", and then modify the view to read as follows:
//depot/Ambush/TGEA_Base/... //depot/Ambush/TGEA_Work/...
Substituting, obviously, your own project name. Now, I like to click "Preview" one time, and examine the log carefully, just to make sure that the files are going TO where I want them to go (TGEA_Work), and are coming "from" where I expect them to come from (TGEA_Base).
After you've previewed the branch, (or directly, if you're brave), click on Integrate and let her rip.
The integration just creates a super ginormous changelist. You still have to submit the changes to actually create the branch. So do so. Again, patience is key here.
Create your Project
Okay, so NOW you have the place where you want to create your project - it's:
C:\Ambush\TGEA_Work
Drop on over there ,and run SetupNewProject.exe, or make a copy of the Template subfolder, however you want to do it - but use this as the place to do your work. Leave TGEA_Base alone. This is important. One tip - don't name your new project the same as your root folder - it's just going to create confusion. So if your root folder was Ambush, then call the actual project something like AmbushGame.
Once your new game project is created, you can open up Dev Studio, and navigate over to C:\Ambush\TGEA_Work\Projects\AmbushGame\buildFiles\VisualStudio 2005, (or whichever flavor of dev studio you're using) and open up the solution. The FIRST thing you should do is add the solution to source control, so go over to File|Source Control|Add Solution to Source Control and do so. This creates a nice changelist, and gets Dev Studio in sync with Perforce in such a way that won't drive you crazy. Use dev studio to submit those files to perforce, and you should be good to go.
Congrats! You're ready to go make your game. Knock 'em dead tiger!
Why all this Trouble?
So yeah it's a lot of hoops to jump through - what do you gain? Well, what you gain is the ability for perforce to have a baseline by which to compare changes against when a new version of TGEA comes along. Perforce wants three things when it does an integration. It needs to know the original thing you started with. It needs to know what's changed since you branched, and it needs to know what changes you made in your branch. With this set up, we've given Perforce everything it needs to perform an integration.
Integrating a New version of TGEA
So this resource is already overly long, and this topic could be an entire resource onto itself, but I'll just go through the basic steps of what you would do to integrate a new version of the engine into your game.
1. Check out the TGEA_Base subfolder
Remember how I said leave it alone before? Well now's the time to update it. You can check out the entire folder at once, or you can walk through each subfolder and do the check out and update each folder individually - it's really up to you as to how brave you are. I would recommend though tackling one folder at a time, inside the engine level.
2. Copy over the new TGEA files on top of your baseline.
Basically, you're "updating" the baseline with all the changes the Torque programmers have worked so hard on since the last release.
3. Submit the updated baseline.
Now your TGEA base has been updated with the new version of Torque.
4. Integrate Base to Work
Remember that branch specification I had you make? Now's the reason you made it. Integrate TGEA_Base to TGEA_Work, using the branch specification you've already saved.
5. Resolve Differences
This is the long and painful part, but it's made easier by "Auto-Resolve". Just allow perforce to resolve anything that doesn't have a conflict. You'll have to manually merge any place though where your changes conflict with GG's changes.
6. Compile, build, and check.
Time to build your game with the new changes, and make any additional modifications to get things working.
7. Submit the integration.
Congratulations, you've just integrated a new version of Torque into your game.
Hope this has been helpful. Dealing with any revision control system can be a bit of a pain, but if you take steps early to make your life easier later on, the initial effort expended is almost always worth it.
When I set out to write this resource, I had a hard time deciding at what level to write it. I finally decided that in order to keep it a manageable length, I'm going to assume you can go to the perforce website, download the server and client software (P4V), and get it set up and working. In other words, I'm not going to attempt to teach you how to use Perforce. What I do hope to provide you is a good suggestion for setting up your depot in such a way as to make integrating future releases of the engine as painless as possible.
All the examples I give here are using TGEA as the model, but this would work equally as well for TGE. What constitutes the "game" subfolder is slightly different between the two engines, but I'll leave it to you to make the appropriate translations.
The Initial Check In
So you've just installed TGEA, you've read through the "Getting Started" documentation, and you're all ready to run SetupNewProject.exe. Well hold on one second hoss. Let's do a little directory management before we do. First, if you're like me, you probably want your new game to be under its own roof on your hard drive, and you probably don't want that roof to be called Torque. For our example, let's say our new game project is going to be the next best WWII shooter ever, and it's called Ambush.
So we make a subfolder under the root folder called Ambush. Under that folder, make a subfolder called TGEA_Base. Inside of that folder, copy everything that is in the c:\torque\TGEA_1_7_0 subfolder (or whatever the new, pristine folder was where you installed your TGEA sdk). This leaves the TGEA sdk installation clean (which we like), and will provide the baseline in perforce for our changes. What you want to leave or keep is ultimately up to you, but I would recommend deleting the 'documentation' folder, and the 'GameExamples' folder inside of the TGEA_Base subfolder. You aren't really interested in integrating new stuff from GameExamples or documentation, and as one folder of the documentation folder has about 5000 files in it, removing it from perforce integration is just going to make your life easier. I would leave however, the Template subfolder under Projects, as you *are* interested in integrating these changes. Now it's time to get this initial baseline into Perforce.
Bring up P4V, and create a new workspace, call it something like Ambush-WS, and add a view that maps your Ambush subfolder to the depot Ambush subfolder. So your workspace should look something like this:
If you haven't made this workspace your current one, do so by choosing Connection|Choose Workspace in P4V. Now in the left hand window of P4V, click on the "Workspace" tab, navigate to the c:\ambush subfolder, r-click on this folder, and choose "Mark for Add". Once that's done, in the right hand pane, click the "Pending" tab, r-click on the default changelist, and choose Submit. Give the submission a useful description like "Initial check in of baseline", and fire away. There's likely over 3000 files in this initial check in, so it could take awhile. Once that's done, click on the "Depot" tab in the left hand panel, and you should see something that looks like this:
Make a Branch
Okay the next step is to branch from our baseline to create our working subfolder. This is the actual subfolder where you'll build your game. To do this, we perform n "integration", which is Perforce's single word they use for both integrating changes and branching the codeline. In the Depot tree, right click on the "TGEA_Base" folder, and choose "Integrate". In the dialog that comes up, click on the "Branch Specification" tab, and then click the "New" button. Call the branch specification something like "Baseline to Work", and then modify the view to read as follows:
//depot/Ambush/TGEA_Base/... //depot/Ambush/TGEA_Work/...
Substituting, obviously, your own project name. Now, I like to click "Preview" one time, and examine the log carefully, just to make sure that the files are going TO where I want them to go (TGEA_Work), and are coming "from" where I expect them to come from (TGEA_Base).
After you've previewed the branch, (or directly, if you're brave), click on Integrate and let her rip.
The integration just creates a super ginormous changelist. You still have to submit the changes to actually create the branch. So do so. Again, patience is key here.
Create your Project
Okay, so NOW you have the place where you want to create your project - it's:
C:\Ambush\TGEA_Work
Drop on over there ,and run SetupNewProject.exe, or make a copy of the Template subfolder, however you want to do it - but use this as the place to do your work. Leave TGEA_Base alone. This is important. One tip - don't name your new project the same as your root folder - it's just going to create confusion. So if your root folder was Ambush, then call the actual project something like AmbushGame.
Once your new game project is created, you can open up Dev Studio, and navigate over to C:\Ambush\TGEA_Work\Projects\AmbushGame\buildFiles\VisualStudio 2005, (or whichever flavor of dev studio you're using) and open up the solution. The FIRST thing you should do is add the solution to source control, so go over to File|Source Control|Add Solution to Source Control and do so. This creates a nice changelist, and gets Dev Studio in sync with Perforce in such a way that won't drive you crazy. Use dev studio to submit those files to perforce, and you should be good to go.
Congrats! You're ready to go make your game. Knock 'em dead tiger!
Why all this Trouble?
So yeah it's a lot of hoops to jump through - what do you gain? Well, what you gain is the ability for perforce to have a baseline by which to compare changes against when a new version of TGEA comes along. Perforce wants three things when it does an integration. It needs to know the original thing you started with. It needs to know what's changed since you branched, and it needs to know what changes you made in your branch. With this set up, we've given Perforce everything it needs to perform an integration.
Integrating a New version of TGEA
So this resource is already overly long, and this topic could be an entire resource onto itself, but I'll just go through the basic steps of what you would do to integrate a new version of the engine into your game.
1. Check out the TGEA_Base subfolder
Remember how I said leave it alone before? Well now's the time to update it. You can check out the entire folder at once, or you can walk through each subfolder and do the check out and update each folder individually - it's really up to you as to how brave you are. I would recommend though tackling one folder at a time, inside the engine level.
2. Copy over the new TGEA files on top of your baseline.
Basically, you're "updating" the baseline with all the changes the Torque programmers have worked so hard on since the last release.
3. Submit the updated baseline.
Now your TGEA base has been updated with the new version of Torque.
4. Integrate Base to Work
Remember that branch specification I had you make? Now's the reason you made it. Integrate TGEA_Base to TGEA_Work, using the branch specification you've already saved.
5. Resolve Differences
This is the long and painful part, but it's made easier by "Auto-Resolve". Just allow perforce to resolve anything that doesn't have a conflict. You'll have to manually merge any place though where your changes conflict with GG's changes.
6. Compile, build, and check.
Time to build your game with the new changes, and make any additional modifications to get things working.
7. Submit the integration.
Congratulations, you've just integrated a new version of Torque into your game.
Hope this has been helpful. Dealing with any revision control system can be a bit of a pain, but if you take steps early to make your life easier later on, the initial effort expended is almost always worth it.
About the author
Dusty Monk is founder and president of Windstorm Studios, an independant game studio. Formerly a sr. programmer at Ensemble Studios, Dusty has worked on AAA titles such as Age of Empires II & III, and Halo Wars.
