From RGWiki

Using the Built-in GUIs, Counters, and Meters

The SSK project template, which you were encouraged to install above, includes a set of pre-defined GUIs, including

• "~\game\gui\splashScreen\*" - A splash screen gui that can be set-up to display multiple splash screens in sequence, each shown for different durations.
• "~\game\gui\mainMenu\*" - A main menu GUI with a Play, Options, Credits, and Quit button. The Play button is tied to the play gui (mainScreenGui), the Quit button is tied to quit(), and the other two buttons are stubbed out, but ready to go.
• "~\game\gui\*" - This directory (excluding its children) includes the standard play gui (mainScreenGui) which has been modified slightly to support the use of an optional frame and optional meters and counters.

Using The Splash Screen

To use the splash screen GUI, follow these steps:

Step #1 Enable it by opening the file "~/game/main.cs" and setting "$RG::EnableSplash" to true

///------------------------------------------------------
// Copyright Roaming Gamer, LLC.
//------------------------------------------------------
$RG_TEMPLATE::Description    = "Roaming Gamer - T2DProject Template #2 (Super Starter Kit)";
$RG_TEMPLATE::Version        = 1;
$RG_TEMPLATE::LastUpdate     = "05 AUG 2009";
 
$RG::EnableSplash   = true; 
$RG::EnableMainMenu = false;

Step #2 Run your game to verify that the three default splash screens are shown.

Step #3 Add the graphics for your own splash screen(s) to the directory: "~\game\gui\splashScreen\".

Step #4 Open the file "~\game\gui\splashScreen\splashScreen.gui" and locate this code at the top of the file

function splashScreen::onAdd( %this ) 
{
   %this.done = false;
   %this.currentSplash = 0;
   %this.maxSplash = 3;
 
   %this.splashImage[0] = expandFilename( "./GameSplash.jpg" );
   %this.splashImage[1] = expandFilename( "./RGSplash.png" );
   %this.splashImage[2] = expandFilename( "./GGSplash.jpg" );
 
   %this.splashFadeInDuration[0] = 500;
   %this.splashFadeInDuration[1] = 500;
   %this.splashFadeInDuration[2] = 500;
 
   %this.splashDuration[0] = 1000;
   %this.splashDuration[1] = 2000;
   %this.splashDuration[2] = 3000;
 
   %this.splashFadeOutDuration[0] = 500;
   %this.splashFadeOutDuration[1] = 500;
   %this.splashFadeOutDuration[2] = 500;
 
   %this.createFade();
}

Step #5 Modify the code as follows:

• If you want more or fewer than 3 screens displayed, change "%this.maxSplash = 3" to match the count you need.
• For each splash screen in order, select the graphic you need by modifying the statements that look like this (remove any you don't need):

function splashScreen::onAdd( %this ) 
   %this.splashImage[0] = expandFilename( "./GameSplash.jpg" );
   %this.splashImage[1] = expandFilename( "./RGSplash.png" );
   %this.splashImage[2] = expandFilename( "./GGSplash.jpg" );

• If you have reduced the number of splash screens, remove any of the "splashFadeInDuration", "splashDuration", and "splashFadeOutDuration" statements you don't need. The array values are one less than the screen number. i.e. "splashFadeInDuration[2]" is the number of milliseconds to display the third splash screen.

Step #6 Save your changes and run your game. As long as you made no errors in your changes, your new splash scree sequence should be displayed.

Using The Main Menu

To use the main menu GUI, follow these steps:

Step #1 Enable it by opening the file "~/game/main.cs" and setting "$RG::EnableMainMenu" to true

///------------------------------------------------------
// Copyright Roaming Gamer, LLC.
//------------------------------------------------------
$RG_TEMPLATE::Description    = "Roaming Gamer - T2DProject Template #2 (Super Starter Kit)";
$RG_TEMPLATE::Version        = 1;
$RG_TEMPLATE::LastUpdate     = "05 AUG 2009";
 
$RG::EnableSplash   = false; 
$RG::EnableMainMenu = true;

Step #2 Run your game to verify that the main menu is shown.

Step #3 (Optionally) edit the file Add the graphics for your own splash screen(s) to the directory: "~\game\gui\mainMenu\mainMenu.gui" and add hooks to your own options menu and/or credits screen.

Using The Play GUI Frames

To change the frame that is used for your game's play area, follow these steps:

Step #1 Open the file "~\game\main.cs" and locate the function "initializeProject()".

Step #2 Locate the call to "configureFrame()" in this function:

function initializeProject()
{
// ...
 
   // Select which frame to use
   mainScreenGui.configureFrame( 1, expandFilename("./gui/images/protoBack1.png") );
 
// ...

Step #3 Modify the function call to select frame number 0..3, where 0 is no frame and 1 is a style matching the images shown below. (The code above is selecting frame style #1.)

• If you selected a frame style of 0, no frame graphic is needed, so remove the second argument and the preceding comma in the call to "configureFrame()".
• If you selected a frame style other than 0, modify the "expandFilename("./gui/images/protoBack1.png")" function call to use an existing image file that matches the style you have selected.
  • See the images below for files that come with the template/kit.
  • Alternately, use one of the images below as a template and make your own image, then save that image in the directory "~/game/gui/images/".

Pre-defined Frames and Styles

Frame Style 1 Mask 600 x 450 play area dummyBack1b.png	Frame Style 1 Measures Mask dummyBack1.png	Frame Style 2 Mask 600 x 450 play area dummyBack2b.png	Frame Style 2 Measures Mask dummyBack2.png
Frame Style 3 Mask 700 x 525 play area dummyBack3b.png	Frame Style 3 Measures Mask dummyBack3.png	Simple Example Style 1 600 x 450 play area protoBack1.png

Adding Play GUI Meters and Counters

Default Meters & Counters

By default, SSK is set up to display Frame Style #1 with the "protoBack1.png" graphic. It is also configured with the meters shown to the right:

• "damageMeter" - Green vertical meter on left.
• "energyMeter" - Blue vertical meter on right.

(Also notice that two icons are shown, one for each of the meters.)

These meters and icons were added by editing the function "initializeProject()" in the file "~\game\main.cs

function initializeProject()
{
// ...
 
   // Add counters/meters to frame (gameBackground GUI)
   gameBackground.addIcon( 25, 450, 50, 50, expandFilename("./gui/images/icons/damageIcon40.png") );
   gameBackground.addVerticalBarMeter( "damageMeterBack" , 30, 75, 40, 375, "IFCFill_Red" );
   gameBackground.addVerticalBarMeter( "damageMeter" , 30, 75, 40, 375, "IFCFill_Green" );
 
   gameBackground.addIcon( 725, 450, 50, 50, expandFilename("./gui/images/icons/energyIcon40.png") );
   gameBackground.addVerticalBarMeter( "energyMeter" , 730, 75, 40, 375, "IFCFill_Blue" );
 
// ...

(By the time you read this, there may be other meters added as examples.)

I am going to do a tutorial on adding your own counter, icons, and meters, so I'm going to leave the instructions here for now. I am sure you will be able to work out the mechanics of adding your own by looking at the sample that comes with SSK. To help get you started, here are the currently supported utility function signatures:

• function gameBackground::addNumericCounter( %this, %counterName, %profile, %posX, %posY, %extX, %extY )
• function gameBackground::addLabel( %this, %labelText, %profile, %posX, %posY, %extX, %extY )
• function gameBackground::addIcon( %this, %posX, %posY, %width, %height, %iconPath )
• function gameBackground::addVerticalBarMeter( %this, %meterName, %posX, %posY, %width, %height, %profileName )
• function gameBackground::addHorizontalBarMeter( %this, %meterName, %posX, %posY, %width, %height, %profileName )

For you information, all of the following icons (and more) are included with SSK in the "~/game/gui/images/icons/" folder/directory.

Ammo Icon	Damage Icon	Energy Icon	Player Icon
Red Icon	Green Icon	Blue Icon

Using Play GUI Meters and Counters

Once you create a meter or a counter, you can simply refer to it by name and use any of these standard access methods (by type):

Vertical Meters

• function VerticalBarMeter::setValue( %this, %percent )
• function VerticalBarMeter::getValue( %this )
• function VerticalBarMeter::increment( %this, %percent )
• function VerticalBarMeter::decrement( %this, %percent )

Horizontal Meters

• function HorizontalBarMeter::setValue( %this, %percent )
• function HorizontalBarMeter::getValue( %this )
• function HorizontalBarMeter::increment( %this, %percent )
• function HorizontalBarMeter::decrement( %this, %percent )

Counters

• function NumericCounter::setValue( %this, %value )
• function NumericCounter::getValue( %this )
• function NumericCounter::increment( %this, %value )
• function NumericCounter::decrement( %this, %value )

To see this in action, try the following:

1. After installing SSK run a game.
2. After the game starts, open the console and try these commands:
   • energyMeter.setValue(0.8);
   • energyMeter.decrement(0.2);
   • energyMeter.increment(0.1);

Note: I will be writing a tutorial on how to hook these meters up to your game objects, but as of yet I haven't had time to write it. This is done via some of the behaviors supplied with SSK.