Wherigo Advanced Concepts

Links to Advanced Topics
Topics	Builder Examples	Player Examples
Message Boxes	Build a Message Box with Custom Functions	Player View of Custom Message Box
Dialogs	Build a Dialog Sequence	Player View of a Dialog Sequence
Player Input	Build an Input	Player View of an Input
Events, Conditions and Actions

Message Boxes

Message boxes are unique user interface elements that allow the cartridge author to communicate with the player. A typical message box consists of text, media and one or more buttons.

Rules regarding the attributes of a Message Box

A message box may contain text without media, a media image without text, or both text and media together.

By default, a message box always contains an 'Ok' button, which allows the player to continue after the message box has displayed on the screen. The cartridge author also has the option of defining up to two custom buttons. If any custom buttons are defined, the default 'Ok' button will not be displayed.

Message boxes can include scripts, which execute when a button is pressed. The builder can also define conditions to be evaluated when a certain button is pressed. These conditions allow a specific set of events to take place if the player presses one button, and a separate set of events to take place if the player presses a different button.

How Message Boxes work in Wherigo

In typical computer systems, a message to the player halts information processing and suspends the game until the player presses a button to resume. However, in Wherigo, a message box does not pause the cartridge. Instead, the game continues to run while the message box is still displayed on the screen. Because of this, any other user interface element (e.g. Dialog, Message Box, GetInput) that is called before a message box is closed can actually overlay or "be stacked on top of" the first message box.

The Wherigo Player automatically cancels any message box that is buried by another user interface element. This means that the message box will not remain on the screen even after all other UI elements have been closed. However, the message box script (if one exists) will still execute. The author can override this by creating a condition to specify what should happen if the 'Cancel' button is pressed. These conditions will work regardless of whether the player intentionally presses 'Cancel' or the message box is automatically canceled by the application.

Example:
     If 'Button1' is clicked on a Message Box
          Do some action 'A'
     Else If 'Cancel' is clicked on a Message Box
          Do some other action 'B'

There are three potential results of this example:

The player presses 'Button1' and the Button1 action executes (do action 'A')

The player presses 'Cancel' and the Cancel action executes. (do action 'B')

Some other UI element overlays the message box and the Cancel action executes (do action 'B')

Build a Message Box with Custom Functions

Create a new script for when the player talks to Dan the Turtle.

For the character's OnTalk event, create a new Message Box action.

        Fill in the text, choose the media
        Create Button 1 text and Button 2 text
        Click on Script to run when button clicked...

Create a script to execute when the second button is clicked.

        If Button 2 is clicked, a new message box
        will be shown to the player. Clicking Button 1 or
        cancel will not cause this message box to show.

When Button 2 is clicked, this new Message Box will be displayed.

        No button script exists and no custom buttons are
        created, so this message box will only have an 'Ok'
        button.

Player View of Custom Message Box

Player sees the character Dan the Turtle in the You See list.

Player selects the character and views its detail screen.

Player clicks on the Actions(4) button. The 'Talk To Me' action is visible along with other actions that have already been defined.

Player clicks on 'Talk To Me'. This will execute the event created for the 'Talk To Me' action, so the message box scripted earlier will be displayed. Our custom buttons will show on this screen.

Player clicks on 'Tell Me More'. This will execute the button script for the message box. In this case, Button 2 is clicked, so the script we created for this button (show a new message box) will be executed. Notice that since we did not add additional script or custom button text, this new message box displays the default 'Ok' button.

Dialog Strings

Dialog strings allow the builder to show a series of message boxes to the player. A dialog string is very similar to a message box in that each dialog may contain text and/or media. However, dialog strings do not contain customizable buttons or button script. Instead, they are presented to the player as a series of message boxes with 'Ok' buttons. One important thing to consider is that, like message boxes, dialog strings can be buried by other user interface events. However, when one message in a dialog string is canceled, the entire string (including subsequent messages that haven't displayed yet) is canceled as well.

Build a Dialog Sequence

Add a new script for when the character's 'Learn More' command is clicked by the player.

Choose show a series of Dialog messages to the player.

Dialog strings are a series of message boxes that can be sequenced in any order. Use the dialog list builder to build and manage them.

Player View of a Dialog Sequence

The character Dan the Turtle appears in the You See list.

Click on Dan the Turtle to view the detail screen for the character.

Click on the Actions(4) button to see a list of valid actions for this character. Our 'Learn More' action is contained in the list.

Click 'Learn More' to execute the 'Learn More' action script. This will display the first message in our dialog string.

Click 'Ok' and the second message appears.

Player Input

Inputs allow the cartridge author to receive information from the player. There are two kinds of inputs in the Wherigo Builder:

The player manually enters a series of numbers, letters or words.

The player selects an answer from a list of options.

How Inputs Work

A basic input usually consists of a text-based prompt (or question) for the player to respond to, an input variable and a specific input type (text, multiple choice or true/false). Inputs can also contain media.

An input is displayed as a special screen where the player can either enter data or select a multiple choice option. Any data the player enters is stored in a variable which can then be compared to the answer. The cartridge author can set different events to occur depending on whether the user enters a correct answer, an incorrect answer, or cancels the input.

Example:
Input A asks the player for a number between 1 and 4. The number that the player enters is stored in a variable 'GuessVar' that is associated with Input A. When the player enters a number and presses 'Ok', the GetInput function for Input A is executed. At this point, the cartridge can compare the player's input (stored in GuessVar) to the correct answer. Based on the results of the comparison, the cartridge author can either ask for input again or continue on with cartridge play.

Build an Input

Create an input variable to hold the player's answer.

Create an input object. This object will store the player�s input in the variable created in Step 1, show the player some helpful text and present the player with (in this case) a list of choices.

Create a script to execute when the player answers the input.

When the player chooses one of the multiple choice buttons, we check to see whether or not the player got the right answer. If the variable's data matches the text from the correct multiple choice button, then the player got the right answer. Otherwise, show a message that asks the player to try again.

The 'Try Again' message box. This will present the player with two new choices: 'Try Again' and 'Never Mind'.

In the button script: if the player chooses 'Try Again', the input screen will be displayed again. Otherwise the window closes.

Player View of an Input

Select the character from the You See list and click the Actions() button to view a list of actions for the character.

Select 'Take a Test' from the list of actions.

A window will open displaying our question text, media and three multiple choice buttons.

Our GetInput script will execute when any of the multiple choice buttons are clicked. The Player application then evaluates whether or not the correct answer was given. The player answered incorrectly, so here is the wrong answer screen with the option to try again.

When the player chooses 'Try Again', the script will reopen the GetInput screen.

If the player selects choice 3 (the correct answer), then a message box showing the corresponding text will be displayed.

Events, Conditions and Actions

Events, conditions and actions form the basis for interactivity in a cartridge. A cartridge may contain any number of zones, items, characters and media, but until these cartridge objects are linked together with interactivity, nothing will happen.

Events

A cartridge is made up of many different types of components, or objects. Some of these objects have built-in events, while others do not. For example, zones have built-in proximity, enter, exit, distance and state events, while characters and items have no predefined events of their own. Therefore, cartridge authors must create not only the objects themselves, but all of the individual events for each object as well.

Example:
A cartridge author creates a box item. The box exists in the cartridge, but players will be unable to interact with the box until the author scripts a command for it. Now, if the author creates an 'Open' command, a player will see 'Open' available in the actions list for the box and be able to click on it. The author will see an OnOpen event for the box available in the Builder and be able to create script inside it (for example, reveal the contents of the box).

Cartridge Objects That Contain Built-in Events:

Object	Event	Description
Cartridge	OnStart	When the cartridge starts
	OnEnd	When the cartridge ends
	OnRestore	When the cartridge is resumed
	OnSave	When the cartridge is saved
Zone	OnProximity	When the player is within the proximity value to a zone
	OnDistant	When the player is within the distance value of a zone
	OnEnter	When the player enters the zone shape
	OnExit	When the player exits the zone shape
	OnSetActive	When a zone has become active or inactive
Task	OnSetComplete	When the task has become complete or incomplete
	OnSetActive	When the task has become active or inactive
	OnSetCorrectState	When the task has been marked correct or incorrect
Timer	OnTick	When a timer interval has been reached
	OnStart	When a timer has started
	OnStop	When a timer has stopped
Zinput	OnGetInput	When an input variable button has been clicked (this could be an 'Ok,' 'Cancel,' or multiple choice button).

Cartridge Objects Without Built-in Events:

Items

Characters

Conditions and Actions

Conditions and actions are elements of a cartridge that allow the author to test and execute script.

Conditions

Conditional statements allow the author to test whether something is true or not. For example, an author may want to test the value of a variable or compare two variables to each other.

A cartridge contains a set of built-in conditions:

Proximity � If the player is/is not within proximity to a zone

Distance � If the player is/is not within a certain distance of a zone

Contains � An item/zone/character/player contains/does not contain an item/character/player

Compare � Compare an object property or variable to another object property, value or variable

Target � If an object is the target of an action (e.g. an object is used with another object)

Button Clicked � A special condition to test which button has been clicked on a message box

Actions

Actions provide the author a way of executing code. For example, an author may want to show the player a message. Other examples include things like setting a zone visible or marking a task complete. An action often results in the execution of an event, which may in turn cause more actions and conditions to execute. For example, an author may set a task visible when a player enters a zone. When the task becomes visible, the author can then reveal another item or character. A cartridge contains over 20 built-in actions that the author can choose to execute.

Building Events, Conditions and Actions

The author can use the Wherigo Builder application to create events, conditions and actions. The Builder contains an event builder tool that is used to structure logic script. The author can use this tool to create basic logical structure (also called If-Then-Else statements) and associate actions with each separate condition.

Wherigo Advanced Concepts

Message Boxes

Dialog Strings

Player Input

Events, Conditions and Actions

Back: Wherigo Builder Tutorial