Introduction

This tutorial is aimed at beginners to T2D and will cover what goes on behind the scenes between clicking on T2D.exe and seeing the level editor on the screen. Hopefully at the end of this tutorial you will have a better understanding of Torquescript and can start adding code to your game. In the interest of time, this tutorial assumes you are slightly familiar with Torquescript, if you have questions on what global variables are, the canvas, functions, etc, please feel free to search. If you already know what they are and want to expand on this tutorial, go for it! The following was written as of Beta1.

Getting Started

What is going on behind the curtain?
The first time you load up T2D you are taken straight away to the Level Editor. It might not occur to you just now, but as you begin doing your own scripting you may ask yourself: "Self, just how did we get here?" This tutorial provides a detailed look into the startup process along with some guidance about where and how to "hook in" your own code.

As you may know, T2D and your game are composed largely of script files that end in the extensions .cs and .gui. Let's start off by going through each file in order.

Main.cs (x2!!)
Depending on your platform, go to Windows Explorer, the Finder, or your favorite Linux Desktop Environment. Navigate to your Torque 2D installation folder and find the file named main.cs at its root. Open up this file in your favorite IDE or text editor. (Torsion is a popular IDE made specifically for Torquescript on Windows, while BBEdit and XCode are both popular in Mac OS X.) The goal here is to familiarize you with Torquescript, so let's get straight to the code!

//---------------------------------------------------------------------------------------------
// Set the mods to run.
// $runWithEditors specifies whether or not the tools mod should be loaded.
// $defaultGame is the main game that will be run at startup.
// Additional mods can be specified with the -mod <mod_name> command line switch.
//---------------------------------------------------------------------------------------------
$runWithEditors = true;
$defaultGame = "T2D";
$defaultMods = "";

The code comments explain pretty well what each variable does. (NOTE: A variable starting with a dollar sign is called a "global variable." Global variables - in contrast to "local variables" - are accessible to all script code, so they're useful for tasks like configuring game options.)

The variable $runWithEditors determines whether to run the editors at startup. ($runWithEditors is set to true for now, but it will be necessary to set it to false when you package your game for release.) The $defaultGame global tells the script where to find the next piece of code to run. In this case it causes the script to load the main.cs script in the "T2D" folder.

The rest of the code in main.cs is beyond the scope of this tutorial, but feel free to read through it to see what's being loaded and initialized. For most games the code in main.cs will need no changes, so leave it alone unless you know exactly what you're doing. Be aware also that the root main.cs file may change in future versions of T2D. So if you must change it take good notes!

Okay, let's get into the T2D folder! This folder contains some special subfolders that we'll get to later, and-- what's this? Another main.cs file? Indeed it is. Open it up!

In this main.cs file we are setting up a package called "T2D." (A package is a group of functions that are grouped together and become available only when the package is activated.) There are three functions in the T2D package: loadKeyBindings, onStart, and onExit.

The loadKeyBindings function tries to initialize a script which doesn't exist (and you'll see a message to that effect in the console). Note that although the exec command fails it doesn't cause the script to stop or the game to crash. This call is included as a means for you to set up a default set of key bindings for your game.

The onStart function has a lot of good things in it, so let's check it out:

//---------------------------------------------------------------------------------------------
// onStart
// Called during engine initialization to set up this mod.
//---------------------------------------------------------------------------------------------
   function onStart()
   {
      Parent::onStart();
      echo("\n--------- Initializing MOD: T2D ---------");
      
      // Load Client Scripts.
      exec("~/data/content/sampleDatablocks.cs");
      exec("./gameScripts/game.cs");
      exec("./gameScripts/initializeT2D.cs");
            
      initializeGame();
      toggleLevelEditor();
      
      Canvas.setCursor(DefaultCursor);
   }

The echo function is used to print text - including the contents of variables - to the console. Echo is a useful tool for debugging your code.

Next there are three "exec" statements. Exec is similar to the include, require, or source directives in other scripting languages. They tell the engine to load - and execute - other script files. Whenever you add a new script file to your game you'll need to include exec("path/to/myscript.cs") or the engine won't realize it exists! (Your own exec statements won't be added to this file. There are more appropriate places to add them in, as you'll see later.)

Next the two functions initializeGame and toggleLevelEditor are called to get things rolling.

The last statement sets the mouse pointer to use the default cursor, one of many parameters defined by scripts in the common folder.

That's everything! Now we're going to take a small step back and look more in-depth at the initializeGame function. This function isn't in main.cs. Rather, you'll find it in one of the three files that were invoked by exec. Can you guess which one?

The gameScripts Folder

initializeT2D.cs
If you look in your gameScripts folder you'll see two files. Open up "initializeT2D.cs" first. As you've probably guessed the "initializeGame" function is found here.

//---------------------------------------------------------------------------------------------
// initializeGame
// Game initialization.
//---------------------------------------------------------------------------------------------
function initializeGame()
{
   // Load up Datablocks.
   exec("~/data/content/datablocks.cs");
   
   // Load up GUIs.
   exec("~/gui/mainScreen.gui");
   
   // Set The GUI.
   Canvas.setContent(mainScreenGui);
   Canvas.setCursor(DefaultCursor);
}

Here we load and execute two additional script files. The "datablocks.cs" script defines your datablocks and "mainScreen.gui" creates the default GUI. Now that the GUI has been defined we activate it by setting the content of "Canvas" to the GUI. Finally we set the default cursor once more for good measure.

(In case you were wondering, the Level Editor you see on startup is not the mainScreenGui! If you remember, in the previous main.cs file, toggleLevelEditor is called immediately after initializeGame. So for perhaps a millisecond, mainScreenGui was on the screen, and then it was replaced by the Level Editor.)

The Level Editor
This tutorial doesn't cover the level editor. Instead we'll jump straight into what happens when you click on the Launch Menu and choose "Run Game" from the Level Editor's menu bar.

Running a Game
When you select "Run Game" from the "Launch" menu the level editor GUI invokes the runGame function. RunGame is found in the levelManagement.cs file (in the tools/levelEditor/scripts folder).

function runGame()
{
   hideLevelEditor();
   setupT2DScene();
}

Short and sweet. We are doing two things here: Telling the level editor to go away and calling setupT2DScene, which will start up the main game code. Here is hideLevelEditor:

// --------------------------------------------------------------------
// Hide Level Editor.
// --------------------------------------------------------------------
function hideLevelEditor()
{
   Canvas.setContent(mainScreenGui);

   setCanvasTitle("T2D");
   
   // Set Level-Editor State.
   $LevelEditorActive = false;

   levelEditorMap.pop();
}

Notice here how easily mainScreenGui is restored. We just tell "Canvas" to start displaying it. So what is mainScreenGUI? The mainScreenGui object is the container that encompasses all our GUI objects. Here are the contents of the mainScreen.gui file:

new GuiChunkedBitmapCtrl(mainScreenGui) {
   canSaveDynamicFields = "0";
   Profile = "GuiContentProfile";
   HorizSizing = "width";
   VertSizing = "height";
   Position = "0 0";
   Extent = "1024 768";
   MinExtent = "8 8";
   canSave = "1";
   Visible = "1";
   bitmap = "~/data/images/logoblack";
   useVariable = "0";
   tile = "0";

   new t2dSceneWindow(sceneWindow2D) {
      canSaveDynamicFields = "0";
      Profile = "GuiContentProfile";
      HorizSizing = "width";
      VertSizing = "height";
      Position = "0 0";
      Extent = "1024 768";
      MinExtent = "8 8";
      canSave = "1";
      Visible = "1";
      lockMouse = "0";
      useWindowMouseEvents = "1";
      useObjectMouseEvents = "0";
   };
};

mainScreenGui is a GuiChunkedBitmapCtrl, which is a container that can also show a bitmap. This bitmap is the world famous T2D logo which you see when you choose Run Game. The second important object here is the t2dSceneWindow. SceneWindows display the content of your game, much like a TV screen displays the content of a particular channel. Here we are naming our t2dSceneWindow: sceneWindow2D.

Remember how - after calling hideLevelEditor - we called setupT2DScene? You can find setupT2DScene in your game.cs file.

//---------------------------------------------------------------------------------------------
// setupT2DScene
// This function is the starting point for all game specific code.
//---------------------------------------------------------------------------------------------
function setupT2DScene()
{
   // Create our scenegraph
   new t2dSceneGraph(t2dScene);

   // Associate Scenegraph with Window.
   sceneWindow2D.setSceneGraph( t2dScene );
   
   // Set the current camera position
   sceneWindow2D.setCurrentCameraPosition("0 0 100 75");

   // Add custom game code here...  
   
}

In this function we do three things to set up the scene for display. First, a new sceneGraph called "t2dScene" is created. Next, we tell the scene window to display t2dScene. Finally, we set up the camera to display the whole scene centered on coordinates "0 0." At the end of the function is a comment to remind you that here is where you'll add the custom code that gets your game started.

(In the near future, hopefully some more documentation will be added to explain concepts like the sceneGraph and loading levels, but for now make good use of the search function.)