Torque Minimal Template -- Part 5. Levels, sound and ML text

This is Part 5 of the Minimal Template series. In this resource we will be adding the ability to change levels and adding sound.

Previous resources

The other resources regarding this series are:

Torque Minimal Template -- Part 4. Retina Display
Torque Minimal Template -- Part 3. Adding objects
Torque Minimal Template -- Part 2. A C++ start function
Torque Minimal Template -- Part 1

Levels

The default template provided with Torque uses a series of script files to load and terminate levels. It all starts in this function of game.cs

function startGame(%level)
sceneWindow2D.loadLevel(%level);

Where %level is the name of a file (that is read from a XML file). In this resource an alternative way to change levels is presented.

What are Levels

For the Torque engine, levels are basically instances of t2dSceneGraph where all torque t2dSceneObject objects are managed. To avoid the unnecessary complexity to manage these instances in several script files, following is a simple function that initiates a t2dSceneGraph instance with a t2dSceneGraph class name, and automatically sets everything needed (like camera size). It can be used to load other levels. In this resource a complete project is shown.

The loadSceneGraph function

function loadSceneGraph( %scenegraph_name )
{
   //delete the previous scenegraph
   deleteSceneGraph();

   if ( $pref::iDevice::ScreenOrientation  == $iDevice::constant::Landscape )
   {
      if( $platform $= "ipad" ||  ( $platform $= "windows" && $platform_simul $= "ipad") )
      {

         %scenegraph = new t2dSceneGraph( %scenegraph_name ) 
         {
            cameraPosition = "0 0";    
            cameraSize = "1024 768";    
         };
      }
      else
      {
         %scenegraph = new t2dSceneGraph( %scenegraph_name ) 
         {
            cameraPosition = "0 0";    
            cameraSize = "480 320";    
         };          
      } 
   }
   else if ( $pref::iDevice::ScreenOrientation  == $iDevice::constant::Portrait )
   {
      if( $platform $= "ipad" ||  ( $platform $= "windows" && $platform_simul $= "ipad") )
      {

         %scenegraph = new t2dSceneGraph( %scenegraph_name ) 
         {
            cameraPosition = "0 0";    
            cameraSize = "768 1024";    
         };
      }
      else
      {
         %scenegraph = new t2dSceneGraph( %scenegraph_name ) 
         {
            cameraPosition = "0 0";    
            cameraSize = "320 480";    
         };          
      } 
      
      
   }


   sceneWindow2D.setSceneGraph(%scenegraph);
   %scenegraph.performPostInit();
   %cameraPosition = sceneWindow2D.getCurrentCameraPosition();
   %cameraSize = t2dVectorSub(getWords(sceneWindow2D.getCurrentCameraArea(), 2, 3),
                              getWords(sceneWindow2D.getCurrentCameraArea(), 0, 1));
                              
   if (%scenegraph.cameraPosition !$= "")
      %cameraPosition = %scenegraph.cameraPosition;
   if (%scenegraph.cameraSize !$= "")
      %cameraSize = %scenegraph.cameraSize;
      
   sceneWindow2D.setCurrentCameraPosition(%cameraPosition, %cameraSize);

}

The deleteSceneGraph function

This function deletes the previous scene graph; it is called by loadSceneGraph. All objects from the scene are iterated and deleted.

function deleteSceneGraph()
{
   
   %scenegraph = sceneWindow2D.getSceneGraph();
   
   if (isObject(%scenegraph))
   {
      %sceneObjectList = %sceneGraph.getSceneObjectList();
      // And finally, notify all the objects that they were loaded.
      for (%i = 0; %i < getWordCount(%sceneObjectList); %i++)
      {
         %sceneObject = getWord(%sceneObjectList, %i);
         if( %sceneObject.isMethod( "onLevelEnded" ) )
            %sceneObject.onLevelEnded(%sceneGraph);
      }
      
      // Notify the scenegraph that the level ended.
      if( %sceneGraph.isMethod( "onLevelEnded" ) )
         %sceneGraph.onLevelEnded(); 
         
      %scenegraph.clearScene(true);
   }
   
   
   if (isObject(%scenegraph))
   {
      if( isObject( %scenegraph.getGlobalTileMap() ) )
         %scenegraph.getGlobalTileMap().delete();
         
      %scenegraph.delete();
   }
   
}

The Home application

Following is presented a sample application that loads 3 levels using this function. The application shows a main menu where a button is pressed that optionally loads 2 other levels. These 2 levels also have a button to return to the main menu.

Three classes are defined:

MainMenuSceneGraph

function MainMenuSceneGraph::OnAdd(%this)
{
   CreateBackground( %this );
   CreateButton( %this, "Level_01_Button",  "ButtonLevelImageMap",  0, -100,  128, 128);
   CreateButton( %this, "Level_02_Button",  "ButtonLevelImageMap", 0,  100,  128, 128);
   makeTextObject( %this, "I am in the Main menu");
}

The resources of every scene graph must be explicitly deleted as called by deleteSceneGraph

function MainMenuSceneGraph::onLevelEnded(%this)
{
   %this.clearScene();
}

SceneGraphLevel_01

function SceneGraphLevel_01::OnAdd(%this)
{
   CreateBackground( %this );
   CreateButton( %this, "ButtonHome", "ButtonHomeImageMap", 0,  170, 128, 128);
   makeTextObject( %this, "I am in Level 1");
}

SceneGraphLevel_02

function SceneGraphLevel_02::OnAdd(%this)
{
   CreateBackground( %this );
   CreateButton( %this, "ButtonHome", "ButtonHomeImageMap", 0, 170, 128, 128);
   %this.CreateGuiText();
   
}

The name of these classes are passed as parameters to the function loadSceneGraph above, like in this call made from main.cs

loadSceneGraph( MainMenuSceneGraph );

To load the other level, the mouse up function for a t2dStaticSprite instance was subclassed:

function ButtonHome::onMouseUp( %this, %modifier, %worldPosition, %clicks )
{
   %this.schedule(0, "changeLevel" );
   alxPlay("beepSound"); 
}

function ButtonHome::changeLevel(%this)
{
	loadSceneGraph( MainMenuSceneGraph );
}

So, pressing the mouse loads the other level. An utility function that defines this button was also defined, that accepts the t2dSceneGraph object (not name) as parameter.

createButton function

function createButton( %scenegraph_obj, %class, %image_map, %xpos, %ypos, %xsize, %ysize )
{
    %obj = new t2dStaticSprite() 
    { 
        scenegraph = %scenegraph_obj; 
        class = %class;
        useMouseEvents = "1";
    };
    %obj.setVisible( true );
    %obj.setImageMap( %image_map );
    %obj.setPosition( %xpos, %ypos );	
    %obj.setSize( %xsize, %ysize );
}

Loading the application, this is the result



Pressing the upper button, this level is loaded; pressing the button, the previous level is loaded




Following are the complete source files for the project. The folder structure and files are:

main.cs
scripts/menu.cs
scripts/menu.cs
scripts/level_01.cs
scripts/level_02.cs
scripts/datablocks.cs
data/images
data/audio
data/fonts

Complete project

Can be downloaded from here