Ok, this one takes some prep work! You need to have your images ready before you can start (or you should, anyhow). You're gonna need one for the background of your menu, and four for each button.. yes four! Why four? Because the engine wants one for each state of the button. If in all four states you want the button to look the same, you need four copies of the same image. It may sound silly, but the naming convention is enforced for a good reason which we'll go over later. For now let's just make our images....

The four states are 'Normal', 'Inactive', 'Highlighted', and 'Down'. Your files will need the following suffixes, respectively: (none), "_i", "_h", and "_d". If that makes sense to you, great! If not, maybe an example would help:

If your image is called:
MyCrazyButton.png

Your four versions will be:
MyCrazyButton.png (normal)
MyCrazyButton_i.png (inactive)
MyCrazyButton_h.png (highlighted)
MyCrazyButton_d.png (down)

Got it? Good! Now go make three buttons: "New Level", "Load Level", and "Exit". Those plus your background image make 13 images you should have before starting. If you're still unsure (or just lazy like me) you can go ahead and download the example project and look in the '/gui/menu' folder.

Ok, now I'll assume we've all got a couple images to use here. Before we get started make sure you are in a new project (in the Level Builder: 'File>New Project...'). Now browse to your project folder and copy your 13 menu images somewhere in here (preferably in their own sub-folder).

Now press 'F10' to toggle the Gui Builder. Ok, let's get started! If you've done the Score and Time GUI Mini Tutorial, this first part should be very familiar. Create a new GUI ('File>New GUI...') named "mainMenuGui" with the default GUI Class ('GuiControl'). Select the main gui in the tree view and set the profile to 'GuiModelessDialogProfile' in the settings panel so the clear parts won't hog mouse clicks.

With our clear background ready we can focus on the part people will see. Click the 'New Control' list (the first dropdown list on the top-left of the window) and select 'GuiBitmapControl'. Move the new box towards the center and set it's profile to 'GuiTransparentProfile' so we can get rid of that nasty black border.

In the 'Misc' section of the settings panel set 'Bitmap' of the new control to the path to your background bitmap and then scale it to whatever size you want your menu to be. Try to maintain the aspect ratio - it may help to manually set the size via the settings panel (the 'Extent' field) in this case. Keep in mind we're going to have three buttons!

Right-click on your new menu background to highlight it and create a 'GuiBitmapButtonCtrl' via the 'New Control' list. The button should appear inside the menu. If it didn't, delete the button and try again making sure that the menu box was 'highlighted' in yellow/green, not 'selected'.

Now here's the tricky part for 'GuiBitmapButtonCtrl's - you set the 'Bitmap' field to the path to your image while omitting the suffixes! In keeping with our example above, the 'Bitmap' field for MyCrazyButton might be "TestProject/gui/menu/MyCrazyButton". Note the lack of a file extension in that string - that is intentional. Repeat the process for all your buttons.

At this point you should be able to hit 'F10' and test that all your button states are playing properly. If they aren't, go back and make sure your files are named properly and that you don't have a file extention in any of your 'Bitmap' fields. When testing a GUI, ignore any artifacts caused by the lack of a background image. When you actually use this GUI, you will have stuff behind it!

Ok, that was the hardest part about using a 'GuiBitmapButtonCtrl'.

You should now have three buttons on your menu: "New Game", "Load Game", and "Exit". This next part is literally exactly the same as the Main Menu With Simple Buttons Mini Tutorial, so if you've done that you're home clear and the rest should be easy!

Now here's the important part, the 'Command' field! Whatever is in this field will be run whenever the button is pressed. Because of this fact, it is important to check your 'Command' fields for syntax errors.

Rather than using global functions, we are going to use the namespace of this GUI. Set the 'Command' field of the first button to "mainMenuGui.newGame();" (note the semicolon!). As you might have guessed, the next two should be set to "mainMenuGui.loadGame();" and "mainMenuGui.exit();".

Make sure you save your new GUI in the '/gui' folder for your project and then you can close out of TGB.

Time to script! First we want to execute our .gui file from 'main.cs' so TGB will know about our GUI next time we run it. Edit your initializeProject function to look like the following:

function initializeProject()
{
   // Load up the in game gui.
   exec("~/gui/mainScreen.gui");
   
   // load the main menu gui
   exec("~/gui/mainMenuGui.gui");
   
   // Exec game scripts.
   exec("./gameScripts/game.cs");
   
   // Remove the following four lines if you would like to start the game without running the
   // level builder.
   if ($runWithEditors)
   {
      toggleLevelEditor();
      return;
   }
   
   // This is where the game starts. Right now, we are just starting the first level. You will
   // want to expand this to load up a splash screen followed by a main menu depending on the
   // specific needs of your game. Most likely, a menu button will start the actual game, which
   // is where startGame should be called from.
   startGame($levelEditor::LastLevel[$currentProject]);
}

Now we need to set up a seperate script file to handle our window commands. Let's create a new script in our '/gameScripts' folder and call it 'menuCommands.cs' to store all our menu commands. We need it to handle the three functions we gave to our buttons, and maybe some extra stuff. Lets start off with a key bound to toggle the window:

// bind key
moveMap.bindCmd(keyboard, "delete", mainMenuGui @ ".toggleMenu();", "");

// toggle the main menu
function mainMenuGui::toggleMenu(%this)
{
   if(!%this.isAwake())
   {
      Canvas.pushDialog(%this);
   }
   else
   {
      Canvas.popDialog(%this);
   }
}

Great, now let's define our button functions:

// start a new game
function mainMenuGui::newGame(%this)
{
   // write your 'new game' code here!
   echo("New game clicked!");
}

// load a saved game
function mainMenuGui::loadGame(%this)
{
   // write your 'load game' code here!
   echo("Load Game clicked!");
}

// exit the game
function mainMenuGui::exit(%this)
{
   // exit T2D
   quit();
}

We are done with this script. Now we need to make sure it get's executed when the game is run. Save 'menuCommands.cs' and open 'game.cs'. Edit your 'startGame' function to look like this:

function startGame(%level)
{ 
   // Set The GUI.
   Canvas.setContent(mainScreenGui);
   Canvas.setCursor(DefaultCursor);
   
   moveMap.push();

   // exec game scripts
   exec("./menuCommands.cs");
   
   if( isFile( %level ) || isFile( %level @ ".dso"))
      sceneWindow2D.loadLevel(%level);
}

All done! Now load up your menu project in TGB and the 'delete' key should make the menu pop up. The New and Load buttons should spam the console (use the '~' key to check). And the Exit button should quit TGB all together!

Thanks for reading and congratulations on completing this tutorial!