Dialogs, Popups and all that..


Dialogs and popups are one of the key elements of any menu system and in Game Framework they are based upon the new Unity UI system. In this tutorial we will first look at some of the options available for displaying dialogs and the different basic dialog types.

Skill level: Intermediate / Complete the getting started tutorial first.
Tutorial time: 30 minutes
Implementing in your projects: 5 minutes

Note: unless otherwise stated you will find the Dialog components under \FlipwebApps\GameFramework\Scripts\UI\Dialogs\Components

Dialog Manager

Dialog Manager is at the heart of managing dialogs and popups along with DialogInstance which we will discuss later.

Within a new scene, create a gameobject called _SceneScope and add a DialogManager component. Ensure the gameobject’s Transform->Position is 0,0,0, otherwise the GUI will be offset! For now, we will just use the default Dialog Manager settings.

Dialog Manager

Showing Dialogs Once

It can be useful to show a dialog only one time, especially if we want to show some instructions or other information to the user the first time they run a game, or enter a level.

Add a ShowDialogOnce component and set Dialog Key to InfoDialogTitle Key to GeneralMessage.Info.TitleText Key to GameOver.Won, and optionally find and set a sprite into the Sprite field. The Dialog Key value is a unique key that is used to register whether this dialog is shown. The others values are default localisation keys, however here you can reference your own values (see the Getting Started Tutorial Part 1)

Show Dialog Once

Show Dialog Once Dialog

Run the game and you will see the dialog is shown however you might notice that clicking the dialog button doesn’t do anything. This is because we are missing an Event System gameobject (this is added automatically when you add a UI element directly to your scene). Stop and run again and you will see the dialog is now shown as expected.

Add an Event System gameobject (GameObject menu->UI->Event System). Clear all PlayerPrefs by enabling the Cheat Functions window (Window menu->Flip Web Apps->Cheat Functions Window) and clicking the Preferences->Reset button. Run the game again, and with the preferences reset the dialog should show and the button should work, run the game a second time and the dialog won’t show.

General Message Dialog

The dialog just shown is an example of the general message dialog. It can be displayed using the ShowDialogOnce component above, or at any point from code using the following functions:

ShowOnce(…)
ShowError(…)
ShowInfo(…)
Show(…)

These methods typically take title, text, text2 and sprite parameters that are substituted into Text / Sprite UI components on gameobjects named ph_Title, ph_Text, ph_Text2 and ph_Image if they exist. Take a look at the default GeneralMessage prefab (\FlipwebApps\GameFramework\Resources\Dialog\Default\) for an example.

Most of the methods also let you specify a callback that will be invoked once the dialog is closed and which buttons the dialog should show (e.g. Ok, Cancel, …).

To try out some of these concepts create a new c# script called GeneralMessageTest with the following content:

using UnityEngine;
using FlipWebApps.GameFramework.Scripts.UI.Dialogs.Components;

public class GeneralMessageTest : MonoBehaviour {
    void Start ()
    {
        DialogManager.Instance.Show(title: "Test Title",
            text: "Callback test",
            doneCallback: DoneCallback,
            dialogButtons: DialogInstance.DialogButtonsType.OkCancel);
    }

    public virtual void DoneCallback(DialogInstance dialogInstance)
    {
        if (dialogInstance.DialogResult == DialogInstance.DialogResultType.Ok)
            DialogManager.Instance.ShowInfo("Ok Pressed");
        else
            DialogManager.Instance.ShowInfo("Cancel Pressed");
    }
}

This script will show a dialog on the scene Start() that has Ok and Cancel buttons. There is a callback that will show a new dialog based on the result from the initial one showing what button was pressed.

Add the above script to _SceneScope and run the game a couple of times noticing how the different results are handled.

Prebuilt Dialogs

The following are the dialogs that are pre-build, both in standard format and also in all themes.

GeneralMessage – Flexible dialog for showing messages and getting response from users.
GameFeedbackDialog – A modified version of GeneralMessage for prompting and handling user feedback.
Settings – An extensible settings dialog with default support for setting background music and effect volumes
GameOver – An extensible game over dialog that shows various status information.

Your Own Dialog Design

While the standard dialog’s are designed to be fairly flexibly, there are occasions when you need to create your own custom ones (let us know if there is something you would like us to add as standard). Below we discuss some of the options available.

Themes

The Game Framework Asset Store package contains some themes (along with all the tutorials files, other samples and resources). You can use the themes to quickly re-brand your UI, or as the basis for your own creations.

In certain cases such as with GameOver and Settings it is just a case of dragging the appropriate themed prefab into your scene (see Getting Started Tutorial Part 5)

Dynamically generated dialogs such as general message need to be registered with DialogManager.

Find the DialogManager on _SceneScope. Open the Dialog Prefab Overrides property and drag the themed GeneralMessage prefab of your choice (\FlipwebApps\GameFrameworkSamples\Themes\[Theme Name]\Prefabs\Dialog) onto the GeneralMessage->Prefab field.

Dialog Manager Override

Run the scene and you will see the dialog now has a new look.

Themed Dialog

Creating Your Own

You can easily create your own dialog designs however there are a couple of important rules to follow when doing so.

You should avoid modifying any files (prefabs or otherwise) within the \FlipWebApps\ folder as these might be overwritten when you update the framework. Instead create your own copy outside this folder and reference that instead.

Loading of dynamic dialogs (e.g. General Message) and dialog content is done by checking specific locations.

  1. First a check is performed for an override with DialogManager as shown above in the section on themes.
  2. Next a check is done by name in any Resources\Dialog\ folder. If you want to always override a specific dialog with your own custom version this is where you would place your copy.
  3. Finally a check by name is done in any Resources\Dialog\Default folder this is a fallback where the standard dialog’s are placed.

Override a default dialog

The easiest way to crease a new dialog is to base it upon an existing design as these show the correct components and naming needed.

We will create a simple custom copy of the General Message dialog. Duplicate the standard General Message dialog prefab(\FlipwebApps\GameFramework\Resources\Default\Dialogs\GeneralMessage). Create a new folder \Resources\Dialog\ and move your copy of the General Message prefab into this folder. Check your new prefab has the same name as the original “GeneralMessage”.

Dialog Prefab Copy

 

On _Scene->Dialog Manager scope, clear the GeneralMessage override that we set (as that would otherwise have priority).

We have now overridden the General Message dialog based upon the override sequence presented above however you won’t notice anything yet if you run the scene as we haven’t made any modifications.

Drag your new prefab into your scene so we can edit it. Set the Dialog gameobject to active so we can see the dialog and change some of the properties such as the Panel->Image color or some of the sprites. Disable the Dialog gameobject again, apply the prefab changes and delete the prefab from the scene.

Run the game again and you should see our new prefab is used.

Dialog Prefab Modified Copy

New dialogs

Keeping new dialogs within the same framework allows us to have the same benefits within management, transition and otherwise. The procedure for create a new dialog is similar to that above. We start by cloning an existing dialog that best matches your needs, but this time you would want to give it a different name. Depending on whether you want to use it dynamically (e.g. GeneralMessage) or in place (e.g. Settings) will determine whether you put it in resources, as a prefab or just directly in your scene. You can then show it using functions in DialogManager / DialogInstance.

Check out the level / paddle select screens in Air Hockey Dreams for an example where custom dialogs are used.

Custom Content

Custom content allows use to get reuse from existing dialog’s while easily extending their functionality. This concept is used by the free prize and unlock gameobject dialogs in the Game Framework Asset Store package to re-use the basic GeneralMessage dialog to get the style, text and buttons while at the same time providing additional content that is displayed. Take a look at the Free Prize tutorial part 2 for more information on how this can be setup, and also check out the code directly in the DialogManager, DialogInstance and FreePrize manager classes.