Creating UI

Overview

This tutorial will cover the basics of how to create UI using GUTS. This includes creating a button, message box, and making UI interact with world objects in-game. It will assume you already have a fundamental understanding of how to navigate and use the GUTS editor along with being familiar with Basic Scripting.

Core Concepts

Render Window

During the building of Torchlight 2 we created the concept of a Render Window. A Render Window was a way to speed up render times for groups of widgets in UI. This is why the property "Render Window" is on all UI widgets. During the building of Torchlight 2 the functionality of the property "Render Window" changed. Now you should only ever have one "Render Window" and it should be the root UI window. If you have the property "Render Window" on a child of another "Render Window" you will get all sorts of weird anomalies and you might actually slow down the UI.

• RULE: "Render Window" should only be True if it is the root window of any UI scene.

Menu Definition

If you want a menu to appear in the game you must create a menu definition object. The menu definition defines the menu’s name, how it shows up and when it shows up. The menu has to have a unique name.

• Game State Property: This property tells the menu when it is allowed to show up. There are only four states that are actually used: "Ingame", "Main Menu", "Loading" and "All".

• Menu Types and Controllers: The "Menu Type" property is for coded menus. There is no way to change the functionality of a coded menu. In most cases you will want to use controllers to make the UI interact with the game or other menus the way you want them to. If you are replacing a menu make sure you check to see if it is using a specific menu type. Most "Menu Types" can only have a single menu using them at a time. You can use as many controllers as you want.

Menu Controller

You can control other windows and find out all sorts of information about other menus with a "Menu Controller".

Step-by-Step

Creating UI and making it interact with in-game objects

1. Launch the GUTS editor and create a new mod named "UI Tutorial".
2. Select the UI Scene Manager in the lower-left of the main window.
3. Right-click on an empty space in the UI Scene Manager and add a UI Menu > Menu Definition object.
4. Select the Menu Definition Object and change the following properties in the Properties Window:
   • "Menu Name" to UITutorial.
   • "Always Visible" to True.
5. Save the file by selecting File > Save at the top of the UI Scene Manager. Since we're making a new menu we have to create the file directory. Create the following folder directory: media\UI\menus\IngameMenus\ and save the layout as "UITutorial".
6. Right-click on an empty space in the UI Scene Manager and add a UI > Button object.
7. Select the Button Object and change the following properties in the Properties Window:
   • "Render Window" to True.
   • "Horizontal" alignment to Center.
   • "Vertical" alignment to Center.
   • Select the various button states under "Images" and click the ellipsis button on the right to open the Image Selector window. Change the following properties:
     • "Clicked" to IG_BUTTON_LARGE_ROLLOVER from the "ingametexturesheets2.imageset".
     • "Disabled" to IG_BUTTON_LARGE_DISABLED from the "ingametexturesheets3.imageset".
     • "Hover" to IG_BUTTON_LARGE_ROLLOVER from the "ingametexturesheets2.imageset".
     • "Normal" to IG_BUTTON_LARGE from the "ingametexturesheets3.imageset".
8. Right-click on the button in the main Render Window. Select "Set to Image Size" from the menu that appears to resize the Button to the same dimensions as the set "Normal" image.
9. Right-click on the Button in the UI Scene Manager and add a UI > Text object.
   • The Text object should appear as a child under the Button in the UI Scene Manager. If it doesn't you can drag and drop it under the Button object to move it.
10. Select the Text Object and change the following properties in the Properties Window:
    • "Text" to Click Me.
    • "Scale Height" to 1.

      This will scale the text to the parent's height.

    • Scale Width" to 1.

      This will scale the text to the parent's width.

    • "Height" to 0.
    • "Width" to 0.
    • "Vertical Align" to Center.
    • "Horizontal Align" to Center.
11. Save the file by selecting File > Save at the top of the UI Scene Manager.
12. Package and Publish the mod.
13. Play Torchlight 2 and select the new UI mod. Create a new character and you should see the button appear in the middle of the screen when you go in to the game.
    • Note: Press the space bar to hide it. If you want the menu to stay up at all time simply change the property "Close with Keyboard" to False on the Menu Definition object.

Adding a Message Box

Next we’ll add a Message Box. For this part we will use the generic Message Box.

• Note: It's not required for this tutorial, but if you want to change the generic Message Box it is located at: menu/ui/menus/Messageboxes/modaldialog_yesno.layout

1. Right-click on an empty space in the UI Scene Manager and add a UI Logic > Message Box object.
   • Drag the newly created Message Box Object to the root of the UI Scene Manager if it's added as a child under another object.
2. Select the Message Box Object and change the following properties in the Properties Window:
   • "Message Box Name" to MODAL DIALOG YES NO.
   • "Text 0" to UI Tutorial.
   • "Text 1" to This is the UI Tutorial Message Box.
   • "Widget 0" to Dialog Title.
   • "Widget 1" to Dialog Text.
3. Right-click on an empty space in the UI Scene Manager and add a Sounds > Sound object.
4. Select the Sound Object and change the following properties in the Properties Window:
   • "Category" to EXPLOSIONS.
   • "Sound Group" to BARRELBREAK.
   • "Environmental" to False.
5. Right-click on an empty space in the UI Scene Manager and add a Logic Group object.
6. Select the Logic Group Object and click the External Tool button on the tool strip at the top of the UI Scene Manager to open the Logic Editor window.
7. Add the following existing objects in the UI Scene Manager to the Logic Editor window:
   • Message Box.
   • Sound.
   • Button.
8. Specify the following Input and Output events in the Logic Editor window:
   • "Clicked" Output on the Button Object.
   • "Show" Input and "OK" Output on the Message Box Object.
   • "Play" Input on the Sound Object.
9. Link the "Clicked" Output on the Button Object to the "Show" Input on the Message Box Object.
   • This will make the Message Box show when the Button is clicked in-game.
10. Link the "OK" Output on the Message Box Object to the "Play" Input on the Sound Object.
    • This will make the Sound play when the Message Box is clicked OK.
11. Save the file by selecting File > Save at the top of the UI Scene Manager.
12. Package and Publish the mod.
13. Play Torchlight 2 and select the new UI mod. Create a new character and click the Button to make the Message Box appear. The Sound will play when the Message Box is clicked OK.

Connect the UI to a lever/trigger in-game

Finally we’ll make the Message Box appear in-game when the Player interacts with a lever.

• Note: Most of this tutorial involves ignoring the previously created UI and setting it up again.

1. New menus require a restart of the GUTS editor in order to have them show up in the drop-down boxes – sorry. Please restart the editor.
2. Select the Layout Scene Manager in the lower-left of the main window.
3. Load the following file: media/layouts/Act1_Town/1X1Single_Room_A/Act1_Town.layout
4. Once the level is loaded move the camera in the Render Window to look where the Vanquisher is placed.
   • The Vanquisher is the female character model near the Player Start at the top of the entrance stairs.
5. Right-click on an empty space in the Layout Scene Manager and add an Units > Unit Trigger object.
6. Select the Unit Trigger Object and change the following properties in the Properties Window:
   • "Model" to Simple Lever.
7. Move the Unit Trigger to a location in the town where the Player can reach it.
   • Note: Pressing the Home key on the keyboard will snap the selected object to the ground.
8. Right-click on an empty space in the Layout Scene Manager and add a UI Logic > Message Box object.
9. Select the Message Box Object and change the following properties in the Properties Window:
   • "Message Box Name" to MODAL DIALOG YES NO.
   • "Text 0" to UI Tutorial.
   • "Text 1" to This is the UI Tutorial Message Box.
   • "Widget 0" to Dialog Title.
   • "Widget 1" to Dialog Text.
10. Save the file by selecting File > Save at the top of the Layout Scene Manager. This will bring up a window that will ask you if you want to save it in the base or the mod directory. Choose the mod directory.
11. Right-click on an empty space in the Layout Scene Manager and add a Building Blocks > Layout Link Particle object.
12. Move the Layout Link Particle Object to a location in the town near the lever Unit Trigger Object created previously.
13. Select the Layout Link Particle Object and change the following properties in the Properties Window:
    • "Layout File" to MEDIA/PARTICLES/SPELLS/FIREBALL/FIREBALLBIG.LAYOUT.
    • "Visible" to False.
    • "Start on Load" to False.
14. Right-click on an empty space in the Layout Scene Manager and add a Logic Group object.
15. Select the Logic Group Object and click the External Tool button on the tool strip at the top of the Layout Scene Manager to open the Logic Editor window.
16. Add the following objects that were just created in the Layout Scene Manager to the Logic Editor window:
    • Message Box Object.
    • Layout Link Particle Object.
    • Unit Trigger Object.
17. Specify the following Input and Output events in the Logic Editor window:
    • "Triggered" Output on the Unit Trigger Object.
    • "Show" Input and "OK" Output on the Message Box Object.
    • "Start Particle" Input on the Layout Link Particle Object.
18. Link the "Triggered" Output on the Unit Trigger Object to the "Show" Input on the Message Box Object.
    • This will make the Message Box show when the Player interacts with the lever Unit Trigger.
19. Link the "OK" Output on the Message Box Object to the "Start Particle" Input on the Layout Link Particle Object.
    • This will make the Layout Link Particle play when the Message Box is clicked OK.
20. Save the file by selecting File > Save at the top of the Layout Scene Manager.
21. Package and Publish the mod.
22. Play Torchlight 2 and select the new UI mod. Create a new character and run to the first town. Pull the lever you placed and select the green check box in the Message Box. This will make the particle appear.

Example

Download an example mod of the tutorial here:

• File:UITutorial.zip