Last updated: 2011-01-03
This is a very basic description of how to build Wherigo™ cartridges with the WWB platform. Suggestions, improvements, rewrites (!), and translations are welcome.
There are many references in this document to the Groundspeak Wherigo builder, which is abbreviated to GWB.
If you are the kind of person who does not like to read a manual, here are some tips that might help you to get started quick and dirty:
This is the main menu of WWB. You will probably spend most of your time on the Edit screen, but you will return here at the start of each session.
To create a new cartridge, select “Create” from the dropdown list of operations. Then type a name for the cartridge in the “New name” box and click “Submit”.
To edit, delete, or write (create the .Lua file) for a cartridge, select its name in the list of cartridges, then select the appropriate operation from the dropdown list of operations, and click “Submit”. “Write” has some other options - see below.
Currently, you can have up to five cartridges stored in the database. If you want to free up a slot for a cartridge, you can make a backup copy on a local file. To do this, select the cartridge from the list, then Backup from the dropdown list, and click Submit. WWB will download the backup file to your computer. You can later restore the cartridge using the “Restore” option (specify the filename in the “Select cartridge backup file” box). Do not modify the backup file, as it has a built-in check which will prevent it being uploaded.
You can use Backup/Restore to give a copy of a cartridge to another user, like this: - Use “Copy” to make a copy of the cartridge within your account. - Use “Backup” to export the copy of the cartridge to a file. - Delete the copy - Send the backup file to the other user. When they upload it, the new copy of the cartridge will be added to their account. (The backup file doesn't contain any owner information.)
Your cartridge data is kept in a database in a format which is not readable by GWB or indeed any Lua compiler. To compile a cartridge, you have several options.
The simplest way is to use the “Compile Cartridge” option. To use this, you must have already uploaded all the media resources (typically, images) used in the cartridge. WWB will generate a .GWZ file containing the Lua file and the resources, submit it to Groundspeak’s cartridge building service, and (provided there were no errors), allow you to save the resulting .GWC file directly. If your GPS device is plugged in, you can even save it directly to that!
If you want to manage all of the media files and building of the .GWZ file yourself, you can use “Write Lua file” to generate just the Lua file. Note that you can rename the .GWZ file to .ZIP and use that directly, which makes dragging files in and out from Windows a little easier.
An intermediate step is to use “Write GWZ file”. This generates the .GWZ file including all of the media which you uploaded. You can then submit this manually to the compiler by visiting http://www.wherigo.com/cartridge/compile.aspx
When using any of the cartridge generation menu items, there are some options which you can choose:
This lets you specify the type of device for which the cartridge will be compiled. Even if you are only generating the Lua file at this stage, it’s still a good idea to specify the target device here (although the compiler will ask you for the same information later). This is especially important if you are using any kind of accented characters, as they are represented differently on the Garmin and PocketPC platforms.
When you are using compile time localization (see the section on localization ?? here ??), this field allows you to specify which language version should be included in the Lua file or the compiled cartridge. Specify 0, or leave the field blank, for the first language, 1 for the second, etc.
You can specify one of two options to move everything in your cartridge to a different starting location from the default.
If you choose “Use alternate start point”, then the cartridge will be output normally, except that every coordinate will be offset by an amount equal to the difference in latitude and longitude (and altitude!) between the regular start point (“Starting location”, on the Cartridge tab in the editor) and the “Alternative starting location”. This feature allows you to build a cartridge which is designed to be played some way from your home, and test it in, say, a local park. All of the zones will be in the same positions relative to the (alternative) start point.
If you choose “Play anywhere”, then all of the zones of the cartridge, and any items or characters which they contain, will be relocated when the cartridge is started, in such a way that their distance from the player's current location is the same as their distance from the cartridge's specified starting point.
It might seem that “Play anywhere” makes “Use alternate start point” redundant. However, “Use alternate start point” has a couple of advantages. Firstly, nothing has to happen at runtime (“Play anywhere” relies on some rather kludgy code to move everything when the cartridge starts); a “Play anywhere” cartridge .Lua file cannot be read by GWB. Secondly, if you are testing in your local park, you probably want all of your test markers to be in exactly the same place each time. So, if you are just testing a cartridge which is not intended to be released as “Play anywhere”, we recommend “Use alternate start point”.
It is a design aim of the initial version of WWB to allow the cartridge .Lua file to be readable by the Groundspeak Wherigo builder (GWB) where possible. However, there are a number of features in WWB which GWB either definitely can not, or may not be able to, handle. These include:
All of these items are, however, compatible with the cartridge compile service at http://www.wherigo.com/cartridge/compile.aspx which is the preferred way to compile cartridges which you have built with WWB.
You can choose “Groundspeak™ Builder” as the “target device” when generating the Lua file. This will leave out as much “incompatible” stuff as possible, thus allowing you to abandon Earwigo and return to GWB. We trust that you will understand that this feature has not been extensively tested.
When you start to edit a cartridge, you will see a screen with 13 tabs. Don't panic! These correspond (mostly) to objects with which you are already familiar from GWB.
Each object tab (apart from “Cartridge”) is structured in the same way. There is a main sub-tab called “List” which lets you add, copy, and delete objects of that type; a “Properties” tab which lets you modify the properties of an individual object; and, if the object can have events associated with it, an “Events” tab, where you can manage the statements which are executed when an event which is associated with the object occurs.
Save your changes often (with either of the “Submit” buttons – the AJAX one is faster, but if you have problems with it, use the regular Submit which reloads the editor code each time). If you make a mistake and want to abandon your most recent changes, just refresh the Web page and your cartridge will be back to where it was when you last pressed Submit. Even if you are using the “classic” (non-AJAX) Submit button, you can safely use the browser's “reload” function to refresh (typically by pressing F5) - if you resubmit the same data twice, WWB will ignore it the second time.
Tip: It may happen that some objects that you have created (e.g, a Message) will not be available in the drop down box on a new tab (e.g. Zones/Events). You can use the Save button to update the data base with the current information. After the save the object should be available in the drop down list. ALternatively, try switching to a different “sub tab” - say, from Properties to Events - and back again. If the dropdown list is in a statement which you're building, try the little “redraw” icon .
To add an object - say, a character - to the cartridge, select the “Characters” tab, type a name for the character in the “New name” box, and click “Add”.
Tip: The “Add” option is only available if you have unchecked all other items (characters in this example) in the list.
The new character will appear in the list. You can now perform the following operations:
Most object properties are simple values which correspond to regular browser input features such as checkboxes, dropdown lists, or text input fields.
In some cases, however, the object will have a list of items, such as the commands which a character understands, the zonepoints which make up a zone, or the statements which make up a function or an event. These items appear in a scrolling table with some options on the left of each line. These options are:
When editing statements (in function objects, or the events associated with other objects), you can use the following types of statements. Some of these are the same as in GWB, some are similar, and some are new. This section just lists the main differences compared to GWB.
If you are editing a statement or expression which references another object - for example, “Move item Pencil to Player” - you can go directly to that object (in this case, “Pencil”) by holding down Ctrl (on a Macintosh, I guess this is probably Command) while clicking on it.
In GWB, if you want to show, say, a dialog to the player, you create an event statement line “Show a dialog” and create the dialog from there. In WWB, you must create all items before you can use them. This requires a small amount of extra planning, but it generally saves you a lot of work, because you very often have to show the same messages, dialogs, etc to the player in several different circumstances. In fact WWB takes this concept further, by allowing you to reuse “Expressions” (defined conditions, such as “if the player contains Item X and zone Y is active”) and even whole statement lists (“Functions”).
On the Zone/Properties tab, you can enter multiple zonepoints in either dd.dddddº or ddºmm.mmm format. Place the comma-separated coordinate pairs (or triplets, if you're using altitude…) in the box entitled “Enter or paste coordinates here”, then click the where you want to insert them.
This was the first “easy” way to get coordinates into Earwigo, with the coordinate sets being built with tools like the GSAK Polygon Editor, but most people will probably prefer to use the direct Google Maps-based editor (see next paragraph). The “paste coordinates” interface has been retained because Google Maps isn't always 100% reliable, and also to allow you to paste coordinates which you might have uploaded from your GPS device into something “structured”.
Zones have an extra tab called “Map” which displays the zone in Google Maps and allows you to edit the points directly on the map. The instructions which appears to the left of the map are meant to be self-explanatory. You are encouraged to experiment with the drawing tools. It’s certainly possible to make an “impossible” zone – for example, one with a border which intersects itself. Don’t expect miracles. Try to keep zone boundaries to less than 200 or so points (and far fewer, if possible); with large numbers of points, Google Maps gets very slow and the Wherigo player has a lot of work to do.
One of the options on the Cartridges tab is “Obfuscate strings”. If you check this, then most of the strings in the Lua file will be replaced by “obfuscated” strings and a function call to “deobfuscate” them. (The term “obfuscate” is used, rather than “encrypt”, because we don't want anyone to have the idea that this is remotely secure.) This is intended to prevent all but the most dedicated hackers from attempting to extract the answer strings from your cartridge by simply dumping the GWC file and reading the strings.
Obfuscation comes at a price: there's the likelihood of occasional but obscure bugs, and the fact that your Lua file is hard to read. We suggest that you don't use it unless you really, really anticipate that people will attempt to hack your cartridge.
Earwigo allows you to build a cartridge which displays texts, prompts, etc, in multiple languages.
There are two possible approaches to this “localization” process:
Each approach has advantages and disadvantages. Compile-time localization gives you a cartridge which is more likely to work with any builder, and does not require any extra code to handle media. Runtime localization means that you only need one GWC file, but it will be bigger, and you will have to handle the localization of media - say, if you need a different picture of the dog for each language, because the picture contains a caption - manually. Additionally, runtime localization may not work with all player software.
(Note 2011-01-03: Runtime localization is still being developed and will be available “soon”.)
Whichever approach you choose, there are some common elements. First, when editing the cartridge, specify a “Language separator” string on the Cartridge tab (this defaults to '@@'). Then, for each text string which you include in the cartridge, separate the language versions with this separator string. For example, suppose your cartridge has a character called “Dog” and you want to be able to build English, French, and German versions. You could name the character “Dog@@Chien@@Hund”. (While you are in the editor, the first substring (“Dog”) will be used to refer to the character.)
If you don't specify “enough” separators in a string, the first (or only) language version will be used instead. That allows you to produce, say, a US English and a UK English version of the same cartridge without too much effort; you can call your characters “Dog”, “Cat”, etc, but an item could be “Colored pencil@@Coloured pencil”.
To specify compile-time localization, leave the Cartridge field which is labelled “Runtime languages (separated with language separator)” blank. Then, when generating the Lua file or compiling the cartridge, use the Cartridge language version field to specify the language version which you want.
When using compile-time localization, you can also have media resources localized at the same time. For example, if you want a different picture of the dog for each language, create a Media object for it, and create three Resources for that Media object. Assign a language number (0, 1, or 2) to each resource object. When you specify a language version when writing the Lua file or compiling the cartridge, the corresponding Resource will be associated with the Media object.
To specify runtime localization, set the Cartridge field which is labelled “Runtime languages (separated with language separator)” to a string which consists of the names of the languages in the cartridge, separated by the language separator. For example, this might be the string “English@@Francais@@Deutsch”. (It's best to avoid accented characters, as some Players do not handle them correctly in multiple-choice inputs.) Unlike compile-time localization, you don't need to do anything special when compiling the cartridge.
When the cartridge is started, the user will be prompted to choose one of the language names. Thereafter, each text in the cartridge will be “split” and the correct language version displayed.
With runtime localization, multilingual Media objects need to be handled explicitly by the cartridge author. Firstly, you need to create a separate Media object for each language version. In our example, you might create DogEn, DogFr, and DogDe as Media objects. Each of these needs just one Resource (the appropriate picture of the dog for each language). You now have to handle the following cases: