⚠ Cookies ⚠

GUI Scripting Part 1

So you're comfortable with the basics of AGS, and you're not afraid of scripting either. It's time to create your first GUI.

Please make sure you've read the Introduction to Scripting tutorial, and played about with it enough to be comfortable writing basic scripts.

Making a Quit GUI

As our first step into GUI-scripting land, let's do something very simple. The default Quit GUI is rather plain and boring, so let's spice it up a bit by creating our own.

The default quit GUI ... how dull

For the purposes of this tutorial, I'm going to use the "Roger's Adventure" game that we created during the Getting Started with AGS tutorial. It doesn't really matter what game you use though, the process is the same.

1. Create the GUI

Go to the "GUIs" tab in the editor. You'll notice that a new "GUI" menu appears in the menu bar; click on it, then select the "New GUI" option. This should create a new GUI (in my case, "GUI2") and select it for you.

Now, for starters "GUI2" is not exactly going to increase your script readability, so I'm going to rename it "QUITGUI". To do this, just change the name in the textbox at the top of the window, then click in the GUI List to update it.

2. Size appropriately

How big do we want our GUI to be? Well, it's only a quit dialog, so I'll go with 160x80 to start with - we can always resize it later if necessary. Remember that the GUI sizes are specified in low-res co-ordinates, so 160 represents half the width of the screen, no matter whether your game is actually 320x200 or 640x480.

In the floating window that appeared when we selected the GUIs pane, double-click the Width entry and type 160. Do the same for the Height entry and type 80. The result should look something like this:

Our new GUI ... still grey, at the moment

If you're keen-eyed, you may have noticed that the floating window has entries called "X-Position" and "Y-Position", which are both 0. Yes, these can be used to set the position of the GUI on the screen - but we'll use a scripting trick instead, which I'll explain later.

3. Customize the look of the GUI

Our GUI as it stands is just a rather dull grey rectangle. We need to add the bits and pieces that will make it into the best Quit GUI ever!

Firstly, as a quick early win, let's change the background colour. Out with the grey, in with the new! Double click "Background color" in the floating window, and change it to something more pleasant. I've got a 16-bit colour game, so I'm going to use 65232, a rather nice light yellow. If your game is 256-colour, choose an appropriate colour from the palette.

Next, the most important thing: we need some buttons.

The GUI Controls palette

Click the "Create Button" button, then draw the button onto the GUI background. You can then move it by dragging it, and resize it by dragging the bottom right hand corner.

I'm going to add two buttons and a label - a Quit button, a Play button and the label to question the user's motives for leaving.

Once you've added and positioned the controls as you want them, check the "Lock controls in position" option just above the GUI display. This ensures that you won't accidentally move the buttons later on while you're setting them up.

Now, select each control in turn, and then change its text by double-clicking the "Text" row in the floating window. It should look something like this:

The GUI is a bit more interesting now

4. Set up GUI for scripting

If you run the game right now, you'll find two problems - the Quit GUI will appear as soon as the game starts, and clicking the buttons won't do anything. We need to address those things before we can declare our GUI complete.

So, select the GUI (click in the background of the GUI where no controls are to do this) and look in the floating window. There's a "Visible" option, which is currently set to Normal - this means it will be visible on startup. Double-click it, and change it to "Popup Modal". This means that the GUI will be initially off, and that the script will have to turn it on manually when the time comes. It also means that the game will be paused from running in the background while the GUI is displayed.

Next, select the "Quit" button, and look at its "Left click" setting in the floating window. If it says "No action", change it to "Run script". Do the same with the Play button.

5. Add some script to the buttons

WARNING! The following sections of this tutorial were written for AGS 2.6 old-style scripting. GUI scripting has changed in 2.7 and this tutorial needs to be updated.

Click the "Edit Script" button at the bottom of the main window. You should see something like this:

The default GUI script

What you're looking at here is the script for dealing with clicks on all GUI controls across all the GUIs in your game. By default, there is code there to handle clicking on the various buttons on the icon bar.

This script gets called when the player clicks on a GUI button. There are two special variables available to you - interface and button. The interface variable contains the ID of the GUI that was clicked on, and button contains the button number within that GUI.

So, we can add a block of script to the bottom to deal with our GUI. Let's start by adding the overall GUI clause:

  if (interface == QUITGUI) {      }    

But wait, what are our button numbers? Go back to the GUI Editor, select the Quit button, and look at the floating window. Its title bar should say something like "GUI 2 Object 0 (button)" - in which case, the Quit button is object 0. Do the same for the Play button, and remember the numbers.

In my case, the Quit button is object 0 and the Play button is object 1, so I'm going to write the script as follows:

  if (interface == QUITGUI) {        if (button == 0) {       QuitGame(0);     }     if (button == 1) {       GUIOff(QUITGUI);     }   }    

What does our script do? First, it checks to see if the player clicked on the GUI we're interested in. If they did, it then checks to see which button was clicked on. If it was the Quit button, then QuitGame is called to exit the game. If it was the Play button, then the Quit GUI is turned off and the game resumes.

6. Add script to turn the new GUI on

This is all well and good, but we still haven't actually enabled our GUI to be turned on during the game. If you've still got the Script Editor window open, you'll notice a line (line 13 in the screenshot above) which checks for the user clicking the Quit button in the icon bar, and exits the game.

We need to change this to call up our GUI instead - so replace the "QuitGame(1);" line with a command to bring up our GUI:
GUIOn(QUITGUI);

The final content of the GUI Script window should look like this:

The GUI Script, after our edits

Close the script editor and save the changes. Run the game and try it out!

7. Tidy up the loose ends

Oops! As you'll notice, when you click the quit button, the GUI appears in the top-left hand corner. That looks messy. Now, if we wanted our GUI in a specific position, we could position it using the X-Position and Y-Position settings in the GUI Editor. However, since we just want to centre it on the screen, it's easier to use a script command.

From the Script menu in the editor, select "game_start". You'll be presented with the game's game_start function, which is called by AGS when the game is loaded up. Add a line to it that looks like this:

CentreGUI(QUITGUI);

The result should look something like this:

The global script, with our new line added

The result of doing this is that when the game starts up, AGS will position the Quit GUI in the centre of the screen. Even though it's not visible at the time, its new location will be stored for when we turn it on.

Save the script, save the game, and try it out. The GUI should now be fully functional - we're finished!

There is one other loose end, which I'll leave as an exercise for the reader. Ctrl+Q is a shortcut key for Quit, and it still brings up the old default GUI. Hint: look in on_key_press.

Go to GUI Scripting Part 2 - Making a Save/Load GUI

Return to tutorials index