MinApp Tutorial #1 - Adding console support

Download Code File

Series Overview
With the release of the Basic GUI Demo by James Yong, I thought it would be nice to build a series of tutorials around it. What James released is an excellent stripped down minimal application using Torque. It does nothing more than display a main menu with a background picture and an "Exit" button. That's it. It doesn't even have the standard tools and console in it. It is a perfect starting place on wich to build, and more importantly, learn.

From here on out i'm referring to this base release by James as the MinApp and each tutorial will be build upon that. The goal is to end up with a basic FPS when we're all done.

I am no expert on Torque myself, but I do have about 10 years of game development experience in general. This series of tutorials is as much to teach myself the workings of Torque as it is to teach others. We will be making this journey of discovery together and at any time I am wide open to comments and crisitiscm from the peanut gallery :)

Tutorial Overview
So now that we have the general overview of the tutorial series out of the way, let's begin with tutorial #1. This is a relatively small tutorial. The MinApp is so basic, it doesn't even have the functionality of the development console. This tutorial will add in support for that development tool. This tutorial feels a bit like a hack because we will be copying some files from the standard Torque demo application for our use, but that is simply the best way to do it. As the saying goes, don't reinvent the wheel.

Preperation
If you haven't already downloaded and "installed" the MinApp, then please do so at this point. Right now we're starting from James' original "Basic GUI Demo" so i'm not including a seperate copy for download. You can download it from the original resource here.

For the sake of this tutorial series, we are going to make just a mindset change about the "Basic GUI Demo". From here on out it will be referred to as the "MinApp" and we will be expanding and building upon it in each tutorial. So, let's rename the directory. When you unzipped it you ended up with a directory named "SimpleTorqueDemo". Let's rename that to "MinApp" or "TorqueMinApp" if you need the name Torque in there to keep your stuff organized :) Once you have done that, copy the torque exectuable and support DLLs in there.

Execution
Ok, now we should be all setup, and ready to add console support to the MinApp. To begin with, we are goign to copy over some of the files that come with the official Torque demo app from GG.

1) Copy files from original Torque demo to MinApp
Copy the following files from your original torque example common files to your minapp ones. They will be in ~/common/ui and you will be placing them in the same spot in your minapp

ConsoleDlg.gui
darkScroll.png
osxScroll.png

What does this do?
The "What does this do?" section will be used often in the tutorials and basically explains why we did what we did in the step. In this case, we are copying over the console GUI definition and some graphics. The GUI definition defines what the console looks like as well as some support code. These are all contained in the .gui file, which is a simple text file. Take a look at it in your text editor to learn more. The two .png files are simply graphics files used by the GUI. In this case, scroll bars. The Torque demos use two "variants" of GUI graphics, named "dark" and "osx". "dark" is used when running on Windows platforms, while "osx" is used when running on Macintosh platforms.

2) Modify defaultProfiles.cs
In SimpleTorqueDemo/common/ui/defaultProfiles.cs add the following code:

// JWV: Begin - Added for console functionality
if(!isObject(GuiWindowProfile)) new GuiControlProfile (GuiWindowProfile)
{
   opaque = true;
   border = 2;
   fillColor = ($platform $= "macos") ? "211 211 211" : "192 192 192";
   fillColorHL = ($platform $= "macos") ? "190 255 255" : "64 150 150";
   fillColorNA = ($platform $= "macos") ? "255 255 255" : "150 150 150";
   fontColor = ($platform $= "macos") ? "0 0 0" : "255 255 255";
   fontColorHL = ($platform $= "macos") ? "200 200 200" : "0 0 0";
   text = "GuiWindowCtrl test";
   bitmap = ($platform $= "macos") ? "./osxWindow" : "./darkWindow";
   textOffset = ($platform $= "macos") ? "5 5" : "6 6";
   hasBitmapArray = true;
   justify = ($platform $= "macos") ? "center" : "left";
};

if(!isObject(GuiScrollProfile)) new GuiControlProfile (GuiScrollProfile)
{
   opaque = true;
   fillColor = "255 255 255";
   border = 3;
   borderThickness = 2;
   borderColor = "0 0 0";
   bitmap = ($platform $= "macos") ? "./osxScroll" : "./darkScroll";
   hasBitmapArray = true;
};

if(!isObject(GuiTextEditProfile)) new GuiControlProfile (GuiTextEditProfile)
{
   opaque = true;
   fillColor = "255 255 255";
   fillColorHL = "128 128 128";
   border = 3;
   borderThickness = 2;
   borderColor = "0 0 0";
   fontColor = "0 0 0";
   fontColorHL = "255 255 255";
   fontColorNA = "128 128 128";
   textOffset = "0 2";
   autoSizeWidth = false;
   autoSizeHeight = true;
   tab = true;
   canKeyFocus = true;
};
// JWV: End - Added for console functionality

What does this do?
This adds some basic default GUI information for the Window, Scroll, and Text Edit GUI controls. The default stuff is then inherited by any controls created. Technically you could do this a different way. Instead of adding in default profile information, you could instead add the GUI properties specifically in the console GUI definition (that stuff we talked about in the .gui file), but I decided to do it this way as it was more clear for the tutorial. Its a toss up which way is more technically correct. I prefer this way since i'd most likely be using these same settings on more than one GUI control, hence the purpose of the defaults. If you had instead planned to only use these settings for the console window, then it would be better to define them specifically in the .gui for the console.

3) Modify canvas.cs
In MinApp/common/client/canvas.cs add the following code to the initCanvas() function:

// Common GUI's
// JWV: Added for Console Functionality
exec("~/ui/ConsoleDlg.gui");

// Action map for console activation
// JWV: Added for Console Functionality
GlobalActionMap.bind(keyboard, "tilde", toggleConsole);

What does this do?
The exec() statement runs the gui definition for the console window. The other statement, (GlobalActionMap) creates a keyboard binding so that when we hit the tilde it will run the toggleConsole function and .. well.. toggle the console :)

Another technical note here is that the Action map really belongs in the default binds but since this minapp doesn't have one (Yet!), it was more clear to put it in here for now.

4) Delete the .dso files from the scripts you modified (not always neccesary but I prefer to do it to make SURE the changes will take effect. This helps to avoid problems later that cause me to lose hair.) and then run the demo. Once at the pretty main menu, hit the tilde and you should see your console.

Summary
Let's just sum up what was required to add this new functionality. In a nutshell all we really had to do was make the GUI definition for the console (although it was already made for us in this case), and then add in support code to use it. The addition of the GUI Profiles that we made (in defaultProfiles.cs) really wasn't directly tied to the addition of the console, but was mainly added because we didn't already have it. That code will allow us to add more GUIs in the future.

This is the first tutorial in this series, and so i'm sure it was rather rough. I'll polish that as we move along in this series. Comments and problems with this one just speak up and i'll get this one cleaned up as well.

I haven't mapped out what the next tutorial will be, but considering our goal for the series and what there is to do, it will most likely be more GUI work. The next one will probably add in support for more of the Torque tools like the GUI editor and Mission Editors. Probably the GUI editor first now that I think about it.

An off the top of my head roadmap for this series (defintely subject to change)
1) Console Functionality
2) Torque Tools - GUI Editor
3) Torque Tools - World Editors
4) Main Menu GUI
5) Play Game GUI
6) Mission Loading
7) Spawning
8) Player Controls
9) Static Objects
10) Weapons & Collisions
11) Vehicles
12) A look at multiplayer

This is completely off the top of my head so we'll see what directions it takes.