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. For more information about Wherigo, please see this Help Center article.

Getting Started

If you intend to use this tutorial to create your first cartridge, you will need the Wherigo Builder requirements. You will also 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)

Tutorial Download Requirements

  • 1Zooventure: Level One

    Learn the basic building blocks of a Wherigo cartridge: zones, characters, tasks and media.

  • 2Zooventure: Level Two

    Learn to use conditions and actions to create basic interactions between the player and objects.

  • 3Zooventure: Level Three

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


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.

Objectives About
Create a Cartridge Name your cartridge and set a starting location.
Create Zones, Characters and Tasks Zones are areas marked by three or more coordinates in which virtual objects like characters and items reside.
Add Media A media object is a sound or image that helps build visual context for the story.
Dialog and Message Boxes Dialog strings and message boxes allow the builder to communicate text and image based information to the player.
Move Characters and Items All virtual objects must be moved to a zone in order to be available to the player.
Change Object's Status The state of an object may be set active/inactive or visible/invisible. This can be changed throughout the cartridge.
Compile and Test A cartridge must be compiled in order to be playable. The emulator allows you to test the cartridge on your computer and make changes quickly.


Create a Cartridge
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.

Create Zones, Characters and Tasks
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.

Add Media
Media consists of the imagery or sound associated with an object. Adding media is an important component in cartridge creation and can make your story or tour more engaging.

Dialog and Message Boxes
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.

Move Characters and Items
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.

Change an Object's Status
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.

Compile and Test
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.


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.

Objectives About
If-Then-Else Statements Conditional statements allow different sets of events to take place depending on the circumstances of the game or the player's actions.
A standalone command is the simplest type of command as it does not require another object to interact with.
Multiple Objects
This type of command only works with a list of items or characters that the builder defines. A reciprocal relationship with these specific objects is automatically generated.
Commands: Scripting for Multiple Objects
Scripting for multiple objects involves setting up separate conditions and actions for each target.
Hide commands This function allows the builder to make a command visible or invisible depending on the player's circumstances.


If-Then-Else Statements
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.

Commands: Standalone
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.'

Commands: Multiple Objects

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.

Commands: Scripting for Multiple Objects
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.

Hide Commands
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.


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.

Objectives About
Create and Increment Variables Variables are used to store information that is useful to the builder. Variable types include strings, numbers and flags.
Setting Up
Inputs allow for increased interactivity by accepting data from the player. Can be used to create real-world interactive puzzles and more.
Input: Scripting Calling an input prompts the player to enter data based on the information that the builder provides.


Create and Increment Variables
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.

Input: Setting Up
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.

Input: Scripting
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.