Welcome to the Wherigo Builder Tutorial!

In this tutorial, you will learn basic cartridge building skills using a sample zoo
cartridge. Each level increases in complexity; if you have never created a Wherigo cartridge,
you should begin with level one. Otherwise, select the level that best corresponds to your
learning needs.

Getting Started

If you intend to use this tutorial to create your first cartridge, you will need the
Wherigo Builder requirements. You will also need a flash player to view the tutorial files and
may want to download the Zooventure zip file for access to media and sample cartridge
code.

If you are not following the tutorials in order and would prefer to use your
own cartridge, we have outlined the lua file requirements by level. (View requirements)

Learn to use player input to add complexity and increase the interactivity of your cartridge.

ZOOVENTURE: LEVEL ONE

What to Expect
Zooventure Level One will lead you through the creation of a simple cartridge. It teaches the user how to script basic events
such as message boxes and zone/character/task visibility. Once complete, you can compile and test
your new cartridge using the Wherigo Builder emulator.

For screen resolutions of 1024x768 or lower, right click on the link to open the video in a new window

When creating a new cartridge, your first task is to provide a cartridge name and starting location.
The starting location can be created with coordinates or a physical address around which your
cartridge is centered.

Zones are the building blocks of a Wherigo experience. A zone is a virtual shape in the
real world defined by three or more waypoints. Players interact with zones primarily by entering
and exiting the shape in the real world. Events in a cartridge occur based on the player's location
in relation to the zones that you define.

Characters are objects that the player can interact with inside of a zone.
They are often used to tell a story, guide the player through a series of events or communicate information.

Tasks are an important tool for guiding the player through a cartridge. They are a non
intrusive way of telling the player where to go next and what needs to be accomplished at that
location. Tasks can also provide motivation by tracking the player's progress.

Dialog and message boxes are the principal way of communicating with a player and typically guide a
player’s experience in a cartridge. It is important to understand the difference between a message
box and dialog string. This tutorial will introduce very simple uses of each but be sure to reference the
Wherigo Advanced Concepts for additional instructions before building
a more complex cartridge.

It is best to think of a zone as a clean slate with nothing in it. For instance, in order for a player to be able to interact
with a character, the player and the character must be in the same zone. If you want a character to be available to the player
in more than one zone, you have to move the character from zone to zone as the player moves. Characters cannot be in more
than one zone at the same time.

Zones may be set visible/invisible and active/inactive. Visibility refers to whether or not the object appears on the
player's device. However, if the zones are not active, the events that happen in
those zones will not occur. Be sure to make the zones both visible and active if you want events to be executed.

Unlike zones, tasks that are visible but inactive will not appear on the player's device. Tasks only appear when they are made active.
It should also be noted that characters and items cannot be active/inactive, but only visible/invisible.

During the cartridge building process, you can publish a cartridge to your local machine and then use the
file for testing in the emulator. Using the emulator for testing is an excellent way to find immediate errors without always
having to test outside. Once you have a complete and well tested cartridge, you can publish the cartridge using the builder or
upload the file from the compile page to place it online.

ZOOVENTURE: LEVEL TWO

What to Expect
Zooventure Level Two features the same basic concepts as Zooventure Level One.
However, Level Two allows more complex interactions with characters and items.
These types of higher level events invite players to be more involved in
your cartridge.

For screen resolutions of 1024x768 or lower, right click on the link to open the video in a new window

Conditional statements are one of the most important components of a Wherigo cartridge. Without
conditional statements, cartridges would be extremely simplistic because only one set
of events could occur for any command. With conditional statements, the builder can evaluate the
player’s progress at any point in the cartridge (when entering or exiting a zone, talking to a
character, etc.) and execute a sequence of events depending on the circumstances.

For example, if the builder wanted the player to begin and end the game in the same zone, conditions
would come in handy for differentiating, upon entrance to the zone, 1) whether the player had
been there before and 2) whether the player had accomplished the necessary tasks to complete
the cartridge.

A command allows the player to interact with an item or character. Some common examples
of commands include 'Talk', 'Take' and 'Give'. In the Wherigo Builder toolset, it is up to the
cartridge author to create commands and then program what the response should be when a player
uses it.

There are three different types of commands available in the Wherigo Builder: the standalone command, the command that works with all objects,
and the command that works with specific target objects. The standalone
command is the simplest of the three as it works only with the object for which it was created,
and does not affect any other item or character. An example of a standalone command might be
'Talk.'

A command that can be used with a target ties together a select group of items and/or
characters. This is a simple and concise way to code as it means the builder only has to script interactions
that are relevant to the story line. An example of a command that can be used with a target might
be 'Give'.

The Wherigo Builder supports reciprocal relationships between objects. When a cartridge author creates a new command that has a target,
the command and its associated events are automatically created in the list of actions for the target object.
In the Zooventure sample cartridge, if the author creates a 'Give' command for the Yellow Egg and specifies that the Yellow Egg can be given to Pig, the Builder application
actually creates two commands. The first is a 'Give' command for the Yellow Egg that works with Pig as a target. The second is a 'Give' command that appears
in Pig's actions list on the Wherigo Player. The player can then access the 'Give' command from either object's menu.

When you have multiple target objects associated with a command, it is important to script an action for each target.
For instance, in the Zooventure sample cartridge, if a 'Give' command is associated with characters Chicken and Pig,
the builder must script two individual actions: one for 'Give' to Chicken, and one for 'Give' to Pig. Otherwise,
the player will see 'Give' in the Actions menu, but will be unable to interact with the characters using
this command.

Upon creating a command that is associated with a character or an item, this command will be
visible as long as your object is. However, there are also instances when you will want to hide a command.
For example, in the Zooventure sample cartridge, the Yellow Egg has a 'Take' command that allows the player to take the egg from the Chicken.
Since we do not want to show the command 'Take' once the item is moved into the player's inventory, it is best to hide this command when
the egg is taken.

ZOOVENTURE: LEVEL THREE

What to Expect
Zooventure Level Three is a good example of an advanced cartridge that includes input from
users. Encompassing all aspects of Level One and Two, Level Three contains the most interactive
examples.

For screen resolutions of 1024x768 or lower, right click on the link to open the video in a new window

Variables serve a variety of functions in the Wherigo Builder, but essentially a
variable is a container for storing data that you want to be able to reference later.
Below is an introduction to the various types of data that variables can store.

String variables are alphanumerical characters. Letters, words,
and sentences are good examples of a string. Strings can contain numbers,
but the numbers cannot be used for calculation or comparison.

Number variables are useful because you can increment or decrement
them, compare them (using operands such as , etc), and set them to any number
you want. In this cartridge, a numeric variable is used to keep track of how many
times the player talks to characters.

Flag (or boolean) variables store true or false values. They operate like a switch in
that they can only be turned on or off (set true or false) and have no in between
states. Leaving the box unchecked will automatically set a flag variable to false.

When creating an input event, the first step is to create a variable that will store
the player’s answer and to associate it with the input. It is important to choose the
correct type of variable for your input. There are three different types of
inputs that can be created in the Wherigo Builder: text, multiple choice and true/false.

In order to call an input, you must first decide when this input needs to show. In the Zooventure sample cartridge,
a puzzle is called when the player needs to find Jared the Penguin. An If-Then-Else statement is
then used to evaluate whether the player's answer matches the answer data stored in
the cartridge. It is important to have a condition for every possible type of player input
along with a set of events to be executed depending on whether the player's answer is
correct or incorrect.
Be sure to reference the Wherigo Advanced Concepts for a more in-depth example.