Wherigo Caches – Part 2: Building Cartridges

A quick word of warning… This is going to get geeky! If you’re not interested in creating Wherigo cartridges then this blog post really isn’t for you! 😉

Creating a Wherigo Cartridge?

I’d heard in the past that creating WherIGo cartridges is a difficult thing to do which made me ignore them for a while. To create them in the first place requires quite good computer knowledge and a basic understanding of programming, but nothing too indepth. It seems that the thing that causes the problems is not the technical requirements, but rather the buggy software that is provided to do it, and using it to create reliable cartridges that don’t crash mid-way!

As wherigo is under Groundspeak, Groundspeak created their own official “Wherigo Builder” software. This software hasn’t been updated since 2008 and is still in beta (test) version. This isn’t your only option however and I have found two other options, “Urwigo” and “Earwigo.net“. I like a challenge so I decided “How hard can it really be to create a wherigo cartridge?” Well, as there are only about 40 in the entire country, possibly a lot harder than it sounds. Surely there are other techies like me that Geocache (it is afterall considered to be quite a geeky hobby) and have the underlying programming knowledge to create a wherigo? So where are all of the wherigos???

A promising start…

I started with installing “Urwigo” as I’d heard it was a really good builder. I however felt a bit lost staring at the interface. There are some text based tutorials on the website and a demo cartridge, but having not found a wherigo cache before I wasn’t even 100% sure what they were. I thought I’d try Groundspeak’s “Wherigo Builder” and along with the flash-based tutorials online I was off to a flying start and soon grasped the concept.


I went through the tutorial and created a little zoo with two areas and a pig and a zookeeper who you can talk to! I attempted to compile the cartridge, however this failed miserably with a random error that meant nothing. I thought I’d give it a go on a different computer as I was using Windows 7 64-bit and hey-presto on Windows XP 32-bit it worked. I know that on the requirements page it doesn’t specifically say that 64-bit is supported, however a few programs you can get away with it. There is however a work around so that you can run the Wherigo builder on a 64-bit OS in the Groundspeak forums (See the post by a_snail)


Earwigo was by far the best builder (in my opinion). It’s a web-based builder meaning that your cartridges are kept safe on the internet. If you visit the webpage, however you’re not going to get very far! You need to be given access in able to use it. See the forum post here on who to contact to get access (it’s free)

Basic Wherigo Elements


The basic building blocks of creating a wherigo cartridge are zones. You can very nearly get away with ignoring most of the other concepts as long as you implement zones. A zone is an area that can be entered and exited and can occupy areas on a map. With a normal Geocache, the zone would be just 1 coordinate, e.g. N52 03.100,E000 03.100. However with a wherigo zone this coordinate could be taken as the center point of the zone, and the rest of the zone stretches out around this point. So for example, your zone could have 4 points around it which would make a square (ish). And any time the player enters this area then any of its events will be triggered.

Center Point: N52°1.762, E000°12.149
Top Left: N52°1.783, E000°12.045
Bottom Left: N52°1.761, E000°12.049
Top Right: N52°1.778, E000°12.233
Bottom Right: N52°1.719, E000°12.224

The 4 corners and center zone points


Like in any game or movie, Wherigo’s have the idea of characters. For example the characters could be a wizard, a dog, an inn keeper, etc. anything that you want. You can also build commands and attach them to characters so it’s possible to “Talk”, “Punch”, “Feel”, “Look at”, etc. for any character. It’s totally up to the game designer as to what interactions a player should have with a character. Characters can be placed in zones so that the player can only interact with them when in that zone. A character can be in multiple zones with multiple interactions.


There’s also the idea of items which can be used or retrieved and stored in an inventory. e.g. A sword, or a key. You can use an item with a character for example to use a sword to attack, or a key to open a door.


Tasks can be used to ensure that a player does something before continuing to the next step. For example The task could be to speak to the wizard, however to do so you would first have to visit the forest zone, retrieve the key, take the key to the witch to make it an enchanted key, visit the castle, give 5 gold coins to the troll who lets you in and then use the enchanted key in the door to unlock the room that the wizard is in so that you can speak to him. At which point your “Speak to the wizard” task is now complete and based on this completion you could then be assigned the next task, be allowed to a zone, be given an item, etc.


That neatly brings us onto events. Many elements of the Wherigo cartridge have events which are fired when something happened. For example, if the player enters a particular zone it can fire the “Enter” event, and then when they leave it will fire the “Exit” event. For Tasks you can have the “SetComplete” event so when a, b, and c have been completed, you execute the “SetComplete” event for a task to true, and therefore any other things in the game that only happen if that task is complete will then execute. Characters and Items don’t have quite such exciting events, however you can use Commands on them instead. The thing to try and wrap your head around when developing wherigo cartridges is that all actions in an event happen at exactly the same time, rather than sequentially. However, this isn’t as big a problem as it may sound.

Messages and Dialogs

To display text to the user we use the idea of messages and dialogs. The difference is that a message is a single piece of text, however with a dialog there are many pieces of text where the player may press “ok” after each section for the next piece of text to display. The reason for this comes back to the fact that all events happen at the same time, therefore if we had 3 messages they would all fire at exactly the same time and you wouldn’t see them in any particular order.

And the advanced features…

There’s also the idea of “Timers”, so for example, a player could have 1 minute to get to a zone before the timer runs out. If they don’t get there in time they must go back to the previous zone and then try again where the timer will restart. You can also use expressions, functions, arrays, randomness, etc. if you know a little bit about programming and want to make your cartridge more complex. There’s also the ability for an input. So you could, for example, get the player to go somewhere and read a number from a plaque then input it into their device before they are allowed to continue. Do be aware however that the more complexities that you build into a cartridge, the more likely it is to crash. Therefore a lot of testing on all possible devices that you can lay your hands on is a must.

Putting it all together

So now that we know the main building blocks of wherigo’s we can start to build a basic cartridge. I’ll use my recently published “Saffron Walden Town Trail” wherigo as an example. This is quite a simple wherigo in that it is more like an advanced multi than an adventure game.

Saffron Walden town has an official trail that takes you around the historic buildings and sites like the castle, the market square, the gardens, the art gallery, the museum etc. This would work fine as a multi (In fact I’d already done all of the planning, I just hadn’t published it) where you needed to go to each location and grab a number to construct the final coordinates, however when you got to each location you wouldn’t know much about what you were seeing. Sure you could construct a huge description where the cacher would have to scroll through it all for information about each site, but with a Wherigo you can make it far more elegant and have the relevant information pop up on the GPSr when the cacher gets to each site.

Step 1 – Work out your zones

The building blocks of this cartridge are the zones. There are 12 zones in total, 10 are the buildings that you need to visit and 2 are the car parking spots.

In Wherigo Builder there are several ways to form a zone. Firstly, you click on the zone button, followed by ‘Add’ to bring up the New Zone dialog box. Give the zone a name.

Add a zone in wherigo builder

A new zone

1a Add a zone using coordinates in Wherigo Builder

If you have visited your zones and taken coordinate readings of their center point, you can enter these into the zone. To do this, click the ‘Set…’ button. You will have to enter the coordinates in decimal notation, so I’d recommend GPS Visualizer to do the conversion. Alternatively you could use the itouchmap website which allows you to click a point anywhere in the world and it will give you the coordinates of it in decimal format. After the zone center point is created, click ‘Generate Points’ and it will ask you how large you wish to make the zone.

Specify the distance from center point

If you then click the ‘View Shape’ button, it will display what the zone looks like and the length of each side.

The size of a zone

1b Add a zone using maps in Wherigo Builder

Unfortunately in countries outside of the US the zone maps in Wherigo Builder won’t work. This means that you can’t draw your zones on the map. You can however do this in Earwigo, which I’ll come on to in a minute.

Attempting to view UK maps

1c Add a zone using an address in Wherigo Builder

Although this is probably the least accurate method of adding zones, you can actually enter an address and have it generate the zone points from that as its center point. I’d say the address look up does work surprisingly well.

Mark a center point using an address

1d Add a zone using maps in Earwigo

In my opinion Earwigo is far more user friendly for creating zones. You are able to view Google maps and drag and drop your zones as well as resizing them.

Drawing zones on a map

When you’ve created a zone you can then resize it and edit it’s shape and size by dragging and dropping points. You can also remove points or add points based on certain coordinates.

Zonepoints in Earwigo

Step 2 – Active and Visible Zones

With zones you have the option of Active/Inactive and visible/invisible. If a zone is visible then the player can see it at all times. If it is invisible then they can’t. Quite simple. However the active status of a zone is a little more complex. A zone may be visible, but set as inactive. This means that if the player wanders into it then nothing will happen. However if the zone is set to active then when they do actually visit it then any events or actions associated with that zone will fire. For the town trail Wherigo, I wanted the player to visit the zones in the order that they are laid out in the trail. This means that when the cartridge is started then zone 1 is active. Once they have visited zone 1, zone 2 becomes active. If at this point they wander into zone 3 then nothing will actually happen as it won’t be active until after they have visited zone 2. I chose to set the zones as visible/active or invisible/inactive so the players can’t see the next zone at all until they’ve visited the previous one.

2a Setting events in Wherigo Builder

In the zones section of the builder you will notice Events on the right hand side. I find that the “When the player enters a zone” and “When the player exits a zone” events come in very useful for setting the active status of zones. When a user enters zone 1 you can trigger the event to make zone 2 active and visible. When they leave zone 1, you can then make zone 1 inactive and invisible.

Setting events for zones

2b Setting events in Earwigo

The same can be done in Earwigo under the zones section in the Events tab.


Step 3 – Displaying Messages

You can display a single message to a user or choose to display a dialog. As I’ve mentioned before, all events are triggered at the same time. Therefore if you want to display more than one message to the player then you need to use a dialog.

3a Dialogs in Wherigo Builder

This can be done as an event action in the wherigo builder. You can add as many sets of text as you like. After each one the player will then press the “OK” button to move on to the next.

Dialogs in Wherigo Builder

3b Dialogs in Earwigo

Whereas in the Wherigo Builder you set up a dialog under the event actions, in Earwigo you set up the dialog elsewhere and then associate it in the event actions. This means that you can reuse a dialog elsewhere in the cartridge.

Creating a dialog

Present the dialog as part of a zone event

Step 4 – Associating Media

Messages, dialogs, zones, etc. can have media associated with them so that an image displays on the screen. In Wherigo builder there is a Media section where you can add a media object and associate a picture with it.

Adding media in Wherigo builder

The same exists in Earwigo:

Adding media in Earwigo

Both builders then allow you to assign the media to a part of the cartridge. So this means you can assign that media to a zone, character, message, dialog, item, etc.

Media Assigned

Revealing the cache

A typical wherigo cache involves a set of tasks before allowing the user to find the final cache. These tasks may involve completing a huge adventure game, or simply visiting different areas in a particular order. After the game has ended there are multiple ways to get the user to the cache. Perhaps you could simply display the coordinates as a message/dialog at the end of the cartridge, have the wherigo direct the user to the cache, or add the coordinates to the user’s inventory at the end.

Displaying the coordinates is simple to implement, however means that once the user has pressed the “OK” to the message, the coordinates vanish. The player must write the coordinates down and proceed to the cache by entering it into their GPSr.

Directing the user to the cache using a wherigo zone is another thing that’s simple to implement. Unlike simpy displaying the coordiantes this means that the coordinates are visible at all times as the wherigo will be doing the directing to the final cache zone. This however means that the user only gets an arrow and a distance to cache indicator on their GPSr, nothing fancy. The zone size will also mean that the exact location is not precise. They will be taken to an area and will have to search from there on. In this case the hint would have to be extremely good.

Adding the coordinates the the users inventory is a little trickier to implement, however is probably the safest and most accurate solution. In this case the coordinates become an “Item” with a media image associated to this. The user could then check their inventory to see the image with the coordinates on it.

Wherigo Files

When you create a wherigo, your source file is a .lua file. This is due to wherigo’s using the Lua scripting language. This isn’t a wherigo dependent language. It’s also used to script World of Warcraft interface customization and provides many scripting enhancements for other applications such as VLC Player, Wireshark, Snort, vim… Because of it being an independent language it also means that you can add functionality to cartridges that aren’t included in any builders. You could write your entire cartridge in Notepad in the lua language if you so wish!

Lua file code

The .lua source files can be compiled into .gwc files. These are the files that run on devices. If you look at a .gwc file in Notepad it is very nearly complete jibberish. This is good for us because it means if we create a cartridge anyone can’t easily open our .gwc file and copy our code or work out the final coordinates without even completing the cartridge. .gwc files are compiled versions of the .lua source files specifically for a particular device (e.g. Pocket PC, Colorado, etc.)

.gwc file contents

When you upload your cartridge to the wherigo website the format it requires is a .gwz file. You can choose to upload your gwc file and have it recompile it for you, however in my experience all I get is an error. It is however extremely simple to make a .gwz file. The Earwigo builder will create it for you, however if using Groundspeak’s Wherigo builder all you need to do is create a directory that includes the .lua file and the media files associated with your cartridge. Add all of those files to a .zip files. Then after the .zip file is created rename the extension to .gwz. So a .gwz file is just a fancy .zip file. When you upload this to the wherigo website it will then compile it to create a .gwc file, and will also compile it in each different version for each different device so that you need not worry about the compatibility settings of it. When the user chooses to download your file they will *just* get the .gwc file.

Wherigo Hacking

You’ll notice that in the excerpt of the .gwc file that I showed above you could make out some of the text. If I were to write the final cache coordinates at the end of the cartridge then by simply opening the .gwc file you would be able to read them and find the cache. Therefore I’d recommend it’s probably a better idea to include any coordinates in a photo rather than plain text as these are going to be a bit harder (but not impossible) to extract from the file.

Along with that, incase someone is able to extract the picture, another method is to ensure that the player must visit the location to get a number/numbers for the final coordinates. So put an aspect of a multi cache into the cartridge. You can have the cartridge pop up a screen telling them to get a number from a sign/plaque and then substitute it for numbers in the final coordinates. You could also have it pop up with an input box and ask them to input the number that they see in front of them before the cartridge will continue.

The earwigo builder also allows you to check an “Obfuscate strings” tick box. This means that any text (e.g. messages and dialogs) that is normally visible when you simply open a .gwc file in notepad will look jumbled. I tested this functionality on an Android, iPhone, and Garmin Oregon and all handled an obfuscated just fine. So if you want to hide any details from any text this is the best way to do it, but do test it on all devices (It doesn’t play too well in the Wherigo Builder’s emulator)

Comparing obfuscated strings with normal strings

Another good thing to know about is the “Play in emulator” option. You can stop cartridges being played on a PC through the emulator. Allowing this would mean that the player could do a trial run of the cartridge first, or if enough information is provided in the cartridge for the final coordinates to be obtained then they could actually find the cache without playing the wherigo on their device. The best thing to do is to turn this off.


Testing your cartridge is very simple on Oregons and Androids. First compile the .gwc file via Earwigo or Wherigo builder. On the Android you will need the WhereYouGo app. Put the cartridge in the whereyougo folder. On the Oregon simply put the cartridge in the wherigo folder on the device. On the iPhone you will need to upload the cartridge to the wherigo website, however ensure the ‘active’ selection is unticked so that the cartridge is visible by you only when you log in. This will allow you to access the wherigo website on your iPhone PiGo app to download the cartridge from there. I’ve tried uploading the files to my web hosting, however it won’t download it from there. The annoying thing about having to do this is that you can’t delete a cartridge after you’ve uploaded it to the site. It just lingers around. If you set it as inactive it won’t show to anyone else, however you will have it cluttering up your view!

Playing the cartridge on the iPhone

Do ensure that you test the cartridge with all common devices. I tested the cartridge about 6 times on Android and iPhone platforms and I was very successful. mjouk was very kind and lent me his Oregon so I could test a beta version of my cartridge. This worked fine also. I then handed the Oregon back and created my final version which included extra photos and the real cache coordinates. I hadn’t realised, but as I’d used Microsoft Paint in Windows 7, my cache coordinates photo had saved as a .png file. I uploaded it all, tested it on an Android and iPhone. Happy with this I submitted it only to find out that the first finder (with an Oregon) got through the cartridge fine until that final (All important!!!) photo of the cache coordinates that didn’t display! It was a quick fix, however it’s worth remembering to only include .jpg files to ensure maximum compatibility as Oregons (And probably Colorados) don’t support .png files as wherigo media!


So that’s creating Wherigo’s in a nutshell. It may look complex, but once you get into the swing of it and create a few zones and events then the rest will follow. I’d definitely recommend developing in Earwigo and test, test, test in the Wherigo Builder emulator. After that get outdoors and test, test, test on as many devices as you can lay your hands on. I’m happy to help if anyone wants any further information on building cartridges!

Posted in Essentials. Tags: . 13 Comments »

13 Responses to “Wherigo Caches – Part 2: Building Cartridges”

  1. Annemarie Says:

    Congrats on setting up your first Wherigo!!

  2. stinger503 Says:

    Thanks for this detailed guide. I may just have to make my own now!

  3. ds8300 Says:

    I can only concur. I have used the Whereigo Builder and got frustrated when my “map” generated an error. Not being a programmer and knowing that it is still an old Beta version I didn’t bother going further. Now, I can look at Earwigo as an alternative tool. More Whereigo cartiridges are needed in my part of Sweden!

    • geocass Says:

      Glad the article is of use. Definitely give Earwigo a go. It’s quite straight forward and the Wiki is very good. Just read through that and you’ll know more than enough to create a cartridge! 🙂

  4. firennice Says:

    They are a pain, but the payoff is worth it. It is fantastic to have people compliment you and get that payoff to be one of the few with an actual cartridge.
    I think there are only a half dozen in my entire state. Two are mine. Two are another cacher’s.

  5. Wherigo Experience « Geocaching with DS8300 Says:

    […] such as Urwigo and Earwigo. An excellent blog on the subject of creating Wherigos is on GeoCass […]

  6. sTeamTraen Says:

    Obfuscated strings should now work correctly on all platforms, including the Groundspeak Emulator.

  7. CACCBAG Says:

    Thanks for this – I have started trying Urwigo but like you just stared at the screen. I just requested the username and password for Earwigo so will give that a try. Your tutorial does give me hope.

  8. Ryan Ramsey Says:

    Reblogged this on TheyCallMeBeef's Blog and commented:
    Definteily something I want to do when I get time, although that doesn’t appear to be anytime soon. Saving this on my blog because this is such a great article.

  9. L'il Miss Cookie Says:

    I find earwigo much better although i got stuck near the end of the tutorial so ive not compiled one of my own yet, many say building a flow chart of what you want to happen helps the creative process? would you agree?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s