Difference between revisions of "MessageBox Tutorial"

Revision as of 09:37, 25 August 2007

From some problems I've run into, the Centralizing your menu exits sub-tutorial should be considered as necessary, rather than optional, when using activators.

Intro

Most of your menu needs can be taken care of with a simple token script:

Begin onAdd
  Messagebox "Your message" "Some options"
End

Begin GameMode
  if (GetButtonPressed == -1)
    return
  else
    ;do stuff
    RemoveMe
  Endif
End

Just add the token to the player whenever you want to run the menu, but be aware that this script is severely limited in functionality. There are many ways to do menus, so this guide will lead up from the simplest menu (Done!) to a fully featured menu (well, featured enough for me) that will be able to:

Use multiple choices
Run the same choice for multiple frames
Run multiple menus from one script
Make it very easy to cut and paste for each new menu
As well as some extras

Basics

First, some basic information on menus:

There are two sides to every menu – the display of the menu and catching the player's decision. You display the menu with the function MessageBox and catch the player's decision with the function GetButtonPressed. You can keep these two separated by changing a variable (i.e., "Choosing")

Where to place MessageBox and GetButtonPressed

MessageBox takes one frame to display, so you can use any block to display it. However, GetButtonPressed needs to be in a block that continuously runs (i.e., GameMode, MenuMode, ScriptEffectUpdate) and needs to be on a script that is running every frame (i.e., an activator that is in a loaded cell, a quest running every .001 seconds, etc.), until the player's decision is caught. This is because it will take at least a few frames for the player to read the menu and make a decision (as well as some other peculiarities).

Keep 'em separated

The menu will always be displayed first, followed by catching the player's decision. These are distinct parts of the script, so they will have to be kept separate. To do this, use a variable ("Choosing" will be used in this tutorial) and set it to a different number for each part. For instance, for displaying the menu you can use set Choosing to -1 to start the menu and if (Choosing == -1) to make sure the menu needs to be displayed. For catching the player's decision, you can use set Choosing to 1 and if (Choosing == 1).

GetButtonPressed returns numbers from -1 to 9

Another oddity - GetButtonPressed returns somewhat odd numbers for each decision:

-1 means no decision has been made
0 means the player selected the first option
1 for the second
...
9 for the tenth(you can have 10 options at most)

(Non-working, but insightful) Example Script for the above concepts

With those in mind, here's a basic menu script. (You may also notice that it doesn't quite work, that'll be explained afterwards.)

Short Choosing



Begin GameMode
  If (Choosing == 0)
    Messagebox "What would you like to do?" "First Option"
    Set Choosing to 1
    Return
  Else
    If (GetButtonPressed > -1) ;Player has made a decision
      If (GetButtonPressed == 0) ;First Option
        ;whatever you want to do
        Set Choosing to 0
      Endif
    Else ;if (GetButtonPressed <= -1) - no decision
      Return ;Try to catch the decision in the next frame
    Endif
  Endif
End

The variable "Choosing" is used to separate the display of the menu and the catching of the player's decision. Since it's in a GameMode block, the script will run every frame. GetButtonPressed will return -1 until the player makes a decision, in which case it will return 0 or 1, depending on the player's decision.

Avoiding Common Mistakes for More Complex Menus

There are 2 and a half problems with the above script:

Only use GetButtonPressed once

First, GetButtonPressed only returns the player's decision once. On this section of code

    If (GetButtonPressed > -1)
      If (GetButtonPressed == 0)

that means that, once the player has made a decision, GetButtonPressed will return 0 for the first line, but will return -1 for the second (this would be true for an if/elseif test as well). This can be fixed by setting a variable (for this tutorial it will be Choice) to GetButtonPressed with set Choice to GetButtonPressed. Place this line after displaying the menu, as such:

Short Choosing
Short Choice
...
  Else ;if (Choosing == 1) or menu has been shown
    Set Choice to GetButtonPressed
    If (Choice > -1) ;Player has made a decision
      If (Choice == 0) ;First Option
        ;whatever you want to do
        Set Choosing to 0
      Endif
    Else ;if (Choice <= -1) - no decision
      Return ;Try to catch the decision in the next frame
    Endif
...

Running after the player's decision is caught

The half problem – any of your code in the ;whatever you want to do section will only run for a single frame. This is good enough in most cases, however, if you need to run that section for more than one frame (i.e., waiting for another process to finish) you will have to set up things a bit differently. The reason, extending on the previous reason – GetButtonPressed will only return the player's decision once, and only for one frame. To fix this, set the variable only when GetButtonPressed returns -1, as such:

...
  else ;if (Choosing == 1) or menu has been shown
    If (Choice == -1) ;Player hasn't made a decision
      set Choice to GetButtonPressed
      return
    elseif (Choice == 0) ;Player has selected the first option
...

Starting the whole thing

The second problem is a bit more drastic – every time the player makes a decision the menu will be displayed again. This problem can be fixed by changing the If (Choosing == 0) test to If (Choosing == -1), and having a clear start to the script (i.e., OnActivate, OnAdd, etc.) that will set Choosing to -1. There are a few ways to start the script off, but my preferred method is to use a persistent activator. The advantages of a persistent activator:

There's a clear beginning to it (OnActivate)
It's easy to start (unlike a quest)
It's fast to start (harder for a quest)
It can run every frame (harder for a quest)
The variables can be global (harder for a token)
And it's simply easier to manage than a spell (if a spell is really possible at all, I haven't seen one yet) Multiple Menus in a Spell Script

The only disadvantage is that activators need to be in the same cell as the player (loaded in memory) to run, so you will have to remember to add a few lines to move the activator to the player when starting and away when finished. Of course, with some work, quests and tokens can be made to do the same, but I don't find them quite as easy to set up.

Creating Your New Menu

You'll need to set up some objects for the next script: an invisible activator, an XMarker, and your own cell:

Your own cell

Scroll down the "Cell View" window
Select "TestQuset01"
Right-click it
Select "Duplicate Cell"
Rename your new cell to something you'll remember (and don't worry about the lack of floors, it'll work just fine)

XMarker

Scroll down the "Object Window"
Select Statics
Scroll to the bottom
Double-click your cell in the "Cell View" window to open it in the "Render Window"
Drag the XMarker from the "Object Window" into the "Render Window"
Right-click the red X (XMarker) in the "Render Window"
Select edit.
In the "Reference Editor ID" box, give it a name you'll remember (in these examples it will be "YourXMarker").

Activator

Select an activator in the "Object Window"
Edit the name
Press enter (or select ok in the edit menu)
Click "Yes" when it asks if you want to create a new item
Drag your new activator into the "Render Window"
Right-click it
Give it a "Reference Editor ID"
Mark it as "Persistent Reference" and "Initially Disabled"
Place the following script on your new activator
1. Make the following script
2. In the "Object Window", right-click your new activator
3. Select Edit
4. In the "Script" pull-down box, select "YourMenuScript"

Activator Script

scn YourMenuScript
Short Choosing
Short Choice



Begin onActivate
  Set Choosing to -1
  If (GetInSameCell player == 0) ;always keep it near the player
    MoveTo player
  Endif
End



Begin GameMode
  If (Choosing == 0) ;meaning it shouldn't be running
    If (GetInSameCell YourXMarker == 0)
      MoveTo YourXMarker
    Endif


  Elseif (Choosing == -1) ;Display your menu
    Messagebox "Which option?" "First Option" "Second Option" ;...
    Set Choosing to 1
    Set Choice to GetButtonPressed
    Return

  Elseif (Choosing == 1) ;Catch the player's decision
    If (Choice == -1) ;No choice yet
      Set Choice to GetButtonPressed
      Return
    Elseif (Choice == 0) ;First Option
      ;run your code for the first decision
      Set Choosing to 0 ;to finish up
    Elseif (Choice == 1) ;Second Option
      ;run your code for the second decision
      Set Choosing to 0 ;to finish up
;... 
;Further illustrations of more options
;    Elseif (Choice == #) ;Nth Option
       ;run your code for the nth decision
;      Set Choosing to 0
;    Elseif (Choice == 9) ;Final/Tenth Option
       ;run your code for the tenth decision
;      Set Choosing to 0
    Endif
  Endif
End

Ok, no games that time. You can start your menus from any script with YourActivatorsReferenceEditorID.Activate player, 1 and this script will do the rest.

Moving Between Multiple Menus

Not only will the above code work, but it makes multiple menus easy to do. Remember that each menu has two parts: the display of the menu and catching the player's decision. So, each menu can be broken into two numbers, a negative number (-1 in the example above) and a positive number (1 in the example above). Use different numbers for each menu, and whenever you want to move to a new menu, use set Choosing to -#. Here's several examples of menu switching: (also, please note that due to wiki limitations, the messageboxes below have been given line breaks, whereas in the CS they wouldn't have one)

Short Choosing
Short Choice



Begin onActivate
  Set Choosing to -1
  If (GetInSameCell player == 0)
    MoveTo player
  Endif
End



Begin GameMode
  If (Choosing == 0) ;meaning it shouldn't be running
    If (GetInSameCell YourXMarker == 0)
      MoveTo YourXMarker
    Endif


  Elseif (Choosing == -1) ;Display your menu
    Messagebox "Would you like to donate gold or food?" "Gold" "Food"
                                                        "Blood" "Cancel"
    Set Choosing to 1
    Set Choice to GetButtonPressed
    Return

  Elseif (Choosing == 1)
    If (Choice == -1) ;No choice yet
      Set Choice to GetButtonPressed
      Return
    Elseif (Choice == 0) ;Gold
      Set Choosing to -2 ;to open the Gold menu
    Elseif (Choice == 1) ;Food
      Set Choosing to -3 ;to open the Food menu
    Elseif (Choice == 2) ;Blood
      Set Choosing to -4 ;to open the Blood menu
    Elseif (Choice == 3) ;Cancel
      Set Choosing to 0 ;to close the menus
    Endif
    Return

  Elseif (Choosing == -2) ;Gold menu
    Messagebox "How much Gold would you like to donate?" "25"
            "I've changed my mind" "I've changed my mind, I'll donate Food"
            "I've changed my mind, I'll donate Blood"
            "I've changed my mind, I won't donate anything" 
    Set Choosing to 2
    Set Choice to GetButtonPressed
    Return

  Elseif (Choosing == 2)
    If (Choice == -1) ;No choice yet
      Set Choice to GetButtonPressed
    Elseif (Choice == 0) ;25
      If (player.GetGold > 25)
        Player.RemoveItem Gold001 25
        Set Choosing to 0
      Else
        Set Choosing to -99 ;a message that the player doesn't have enough
      Endif
    Elseif (Choice == 1) ; I've changed my mind
      Set Choosing to -1 ;to return to the opening menu
    Elseif (Choice == 2) ; I've changed my mind, I'll donate food
      Set Choosing to -3 ;to open the food menu
    Elseif (Choice == 3) ; I've changed my mind, I'll donate blood
      Set Choosing to -4 ;to open the blood menu
    Elseif (Choice == 4) ; I've changed my mind, I won't donate anything
      Set Choosing to 0 ;to close the menus
    Endif
    Return

  Elseif (Choosing == -3) ;Food menu
    Messagebox "How much food would you like to donate?" "Options"
                                                         "More Options"
                                                         ...
                                                         "Cancel"
    Set Choosing to 3
    Set Choice to GetButtonPressed
    Return

  Elseif (Choosing == 3)
    If (Choice == -1) ;No choice yet
      Set Choice to GetButtonPressed
    Elseif (Choice == 0)  ;Options
...
    Elseif (Choice == 9)  ;Cancel
      Set Choosing to 0
    Endif
    Return


    Elseif (Choosing == -99) ;Player-doesn't-have-enough menu
      Messagebox "You don't have enough."
      Set Choosing to 99
      Set Choice to GetButtonPressed
      Return

    Elseif (Choosing == 99)
    If (Choice == -1) ;No choice yet
      Set Choice to GetButtonPressed
    Elseif (Choice == 0) ;player pressed "Done", return to main menu
      Set Choosing to -1
    Endif
    Return


  Endif
End

I suggest using numbers instead of other variables when setting Choosing. Numbers give more meaning than words in this case, as the negative and positive numbers separate which part of the menu you're dealing with. You can also use numbers to signify which layer of the menu you are in. For instance, -1 was the first layer in the above example. For the sub-menus of the main menu (Gold, Food, Blood), you can use -11, -12, -13. And, for example, for the sub-menus of Food you can use -121, -122, -123 such that the first number signifies the menu of the first layer, the second the menu of the second layer, etc.

Multiple Menus in a Spell Script

A spell presents several challenges for multiple menus, but it can be done. Most importantly, you will need to set a high duration on the spell (see GetButtonPressed#GameMode or MenuMode?). However, the player could still open enough menus to run down the duration, no matter how long. To cover this scenario, all of the menu variables will be copied to a persistent object (in this case, the quest MenuVariables) when the spell runs out, and the spell will be recast.

This leads to one more small problem - if the variables are left set, then every time the spell is cast the menu would start more it left off before (well, ok, this could be cool, but I'll assume it's undesirable). To solve this, all of the external menu variables will be reset when the player exits the menu.

Note also that, as of now, this hasn't been tested for multiple menus.

The quest script:

scn MenuVariablesScript

Short Choosing
Short Choice

The spell script:

Short Choosing
Short Choice



Begin SpellEffectStart
  if MenuVariables.Choosing
    Set Choosing to MenuVariables.Choosing
    Set Choice to MenuVariables.Choice
  else
    Set Choosing to -1
  endif
End



Begin SpellEffectUpdate
  If (Choosing == 0) ;meaning it shouldn't be running
    set MenuVariables.Choosing to 0
    set MenuVariables.Choice to 0


  Elseif (Choosing == -1) ;Display your menu
    Messagebox "What do you want to do?", ["Button0"], ..., ["Button8"], "Next Page"
    Set Choosing to 1
    Set Choice to GetButtonPressed

  Elseif (Choosing == 1)
    If (Choice == -1) ;No choice yet
      Set Choice to GetButtonPressed
      Return
    Elseif (Choice == 0) ;Button0
      ;Whatever you want to do
      Set Choosing to 0
...
    Elseif (Choice == 8) ;Button8
      ;Whatever you want to do
      Set Choosing to 0
    Elseif (Choice == 9) ;Next Page
      Set Choosing to -2 ;Following menu (choosing == -2)
    Endif

  Elseif (Choosing == -2) ;Gold menu
    Messagebox "What do you want to do?", ["Button0"], ..., ["Button8"], "Exit"
    Set Choosing to 2
    Set Choice to GetButtonPressed

  Elseif (Choosing == 2)
    If (Choice == -1) ;No choice yet
      Set Choice to GetButtonPressed
    Elseif (Choice == 0) ;Button0
      ;Whatever you want to do
      set Choosing to 0
    ...
    Elseif (Choice == 8) ;Button8
      ;Whatever you want to do
      Set Choosing to 0
    Elseif (Choice == 9) ;Exit
      Set Choosing to 0 ;to close the menus
    Endif


  Endif
End



begin ScriptEffectFinish
  if Choosing
    set MenuVariables.Choosing to Choosing
    set MenuVariables.Choice to Choice
    player.Cast Spell
  endif
end

Notes:

Using multiple menus, or catching a button press with GetButtonPressed in a magic effect script requires that the spell duration be more than 0 in order for GetButtonPressed to capture the button.
The ScriptEffectFinish block will always run immediately after the last running of the ScriptEffectUpdate block. Due to this, if the ScriptEffectUpdate block has a Return statement that fires at this point of the script, the ScriptEffectFinish block will not run.

Extras

That will take care of most menu systems you'll ever want to create. However, there is still more functioniality you can add to your menus. From here, you can either get it all by using the following script, or pick and choose using the mini-tutorials:
Centalizing your decision catching
Centralizing your menu exits
Running menus in both GameMode and MenuMode when your script is too large
Ensuring your menus are seen
Allowing the player to set a variable to any number
Controlling the menu system via external scripts

Applying it all

If you use want all of the above extras, your menu script will look like this: (due to wiki limitations, the large if test has been given line breaks, whereas in the CS it would all be on one line)

scn YourMenuScript

Short Choosing
Short Choice

;Centralized Menu Exiting variable
Short Reset

;GameMode and MenuMode variables
Short GMRun
Short ExitButton

;Ensuring Your Menu Is Read variables
Float MessageTimer
Short MessageButton



Begin onActivate
  If (Choosing >= 0)
    Set Choosing to -1
  Endif
  Set Reset to 1
  If (MenuMode == 0)
    Set GMRun to 1
  Endif
  If (GetInSameCell player == 0) ;always keep it near the player
    MoveTo player
  Endif
End



Begin GameMode
  If (Choosing == 0)
    Set GMRun to 0
    If (GetInSameCell YourXMarker == 0)
      MoveTo YourXMarker
    Endif
    Return
  Elseif GMRun
    Set GMRun to 0
    Set ExitButton to 0
    Messagebox "Exiting options..."
  Elseif (Choice == -1)
    If (MessageTimer > 0) || (MessageCounter > 0)
      Set Choice to GetButtonPressed
      If (Choice > -1)
        Return
      Endif
      If (MenuMode 1001 == 0)
        If (MenuMode 1004) || (MenuMode 1005) || (MenuMode 1006) ||
           (MenuMode 1010) || (MenuMode 1011) || (MenuMode 1013) ||
           (MenuMode 1015) || (MenuMode 1016) || (MenuMode 1017) ||
           (MenuMode 1018) || (MenuMode 1019) || (MenuMode 1020) ||
           (MenuMode 1021) || (MenuMode 1024) || (MenuMode 1038) ||
           (MenuMode 1039) || (MenuMode 1044) || (MenuMode 1045) ||
           (MenuMode 1046) || (MenuMode 1047) || (MenuMode 1057)
          Return
        Else
          Set MessageTimer to (MessageTimer - GetSecondsPassed)
          Set MessageCounter to (MessageCounter - 1)
        Endif
      Else ;MenuMode 1001
        Set MessageTimer to 1
        Set MessageCounter to 45
        Return
      Endif
    Else ;Display menu again
      Message "Trying menu again..."
      Set Choosing to -(Choosing)
      Messagebox "Exiting options..."
    Endif
  Elseif (Choice != ExitButton)
    Set ExitButton to 0
    Messagebox "Exiting options..."
  Endif
End



Begin MenuMode
  If (Choosing == 0)
    If Reset
      ;reset whatever you need to
      Set Reset to 0
    Endif
    If (GetInSameCell YourXMarker == 0)
      MoveTo YourXMarker
    Endif


  Elseif (Choosing > 0) && (Choice == -1) ;No choice yet
    If (MessageTimer > 0) || (MessageCounter > 0)
      Set Choice to GetButtonPressed
      If (Choice > -1)
        Return
      Endif
      If (MenuMode 1001 == 0)
        If (MenuMode 1004) || (MenuMode 1005) || (MenuMode 1006) ||
           (MenuMode 1010) || (MenuMode 1011) || (MenuMode 1013) ||
           (MenuMode 1015) || (MenuMode 1016) || (MenuMode 1017) ||
           (MenuMode 1018) || (MenuMode 1019) || (MenuMode 1020) ||
           (MenuMode 1021) || (MenuMode 1024) || (MenuMode 1038) ||
           (MenuMode 1039) || (MenuMode 1044) || (MenuMode 1045) ||
           (MenuMode 1046) || (MenuMode 1047) || (MenuMode 1057)
          Return
        Else
          Set MessageTimer to (MessageTimer - GetSecondsPassed)
          Set MessageCounter to (MessageCounter - 1)
          Return
        Endif
      Else ;MenuMode 1001
        Set MessageTimer to 1
        Set MessageCounter to 45
        Return
      Endif
    Else ;Display menu again
      Message "Trying menu again..."
      Set Choosing to -(Choosing)
      Return
    Endif


  Elseif (Choosing == -1) ;Display your menu
    Set ExitButton to # ;1 in this example
    Messagebox "What would you like to do?" "First Option" ... "Exit Menu"
    Set Choosing to 1
    Set Choice to GetButtonPressed
    Return

  Elseif (Choosing == 1) ;Catch the player's decision
    Elseif (Choice == 0) ;First Option
      ;run your code for the first decision
      Set Choosing to 0 ;to finish up
    Elseif (Choice == 1) ;Second Option
      ;run your code for the second descision
      Set Choosing to 0 ;to finish up
    Endif


  Elseif (Choosing == -2)
...
  Endif
End