====== WWB ("Earwigo") basic user documentation ======

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.

===== Quick and dirty tricks =====


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:

  - You are currently allowed to have 5 cartridges in the WWB. If you have reached this limit, several functions on the Manage Cartridge page will be disabled or invisible.
  - Always set a starting location in the Cartridge tab. Some objects need a start coordinate and use the Cartridge starting location. If you do not do this you might have trouble to create certain objects.
  - Enable “Upload Media File” in the Cartridge tab. This allows you to browse your computer for media files that you intend to upload.
  - For Zones: Leave the value for “Distance range” at –1 if you don’t know how to use this value.
  - Avoid the "on click" event for Characters, Items, or Tasks. It is not supported by Garmin devices. Similarly, avoid creating per-zone commands, which also do not work on the Garmin version of the Player.
  - Your cartridge is created and ready to play when you use the “Compile Cartridge” instruction on the Manage Cartridge Page. Upload the resulting *.gwc file to the Wherigo player directory of your device (or as specified by the manufacturer ;-)).
  - If the compile ends in a Server Error 500 you might have called a function from within itself (recursive programming).  For example, for Message1 the statement “If Button 1 is pressed display Message 1” will cause this.


===== Manage cartridges =====


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.

{{:manage_w_operation_drop_down.gif|}}

==== Basic operations ====


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.

==== Backup / Restore ====


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.)

==== Writing the .Lua file ====


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:

==== Target device ====

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.

==== Cartridge language version (0-n) ====

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.

==== Relocation options ====

You can specify one of two options to move everything in your cartridge to a different starting location from the default.

=== Use alternate start point ===

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.

=== Play anywhere ===

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".

==== Compatibility with GWB ====


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:

  * "Play anywhere" option (will cause the cartridge to fail to load in GWB)
  * Function objects (may become corrupted if GWB writes out the file)
  * Lua statement code (will almost always cause the cartridge to fail to load in GWB)
  * Accented characters (GWB just ignores them)
  * Obfuscated strings

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. ;-)

===== Editing a cartridge =====


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 {{:blackredraw-12px.png|}}.

==== Managing objects ====


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:

  * To delete it, check the box next to the name and click "Delete".  You can delete multiple objects at once.  An object cannot be deleted if another object refers to it.  If this happens, a pop-up message will tell you which objects are referring to the one which you are trying to delete.
  * To copy  the object, check the box next to the name, type a new name in the "New name" box, and click "Copy".  You can only copy one object at once.
  * To edit an object, either check the box next to its name and then click the "Properties" or (if present) "Events" tab; or, just click the Properties or Events link on the same line as the object's name.

==== Editing object properties ====


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:

  * {{:blueup-12px.png|}} Moves the item up within the list (swapping its position with the item currently above it).
  * {{:bluedown-12px.png|}} Moves the item down within the list (swapping its position with the item currently below it).
  * {{:greenplus-12px.png|}} Inserts an item in the list (before the line containing the symbol).  Depending on the type of the item, this may also start editing the new item. 
  * {{:redx-12px.png|}} Deletes the item.
  * {{:blueparens-12px.png|}} For condition items within an expression, this option groups together all the items from here to the end of the list.  This is useful to be able to apply "and", "or", and "not" operators to multiple statements.
  * {{:blackredraw-12px.png|}} Redraws the table.  This option shouldn't be necessary, but the software is not perfect. :-)  It's useful if you've clicked on an element and changed your mind, and you want to get the resulting dialog box off the screen.

==== Statement types ====


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-Else: In WWB, an If-Else statement always has an Else part (but you don't have to put any statements in it), and there is no "ElseIf" construct (GWB has this, but it just confuses non-programmers even more than nesting If-Else statements).  You can move statements into and out of the If-Else as you want.  Before you can delete an If-Else, there must be no statements inside it.  The list of conditions to determine whether the If or Else part is executed, needs to be defined first as an Expression.  This requires a little planning, but it's very common to use the same list of conditions multiple times in a cartridge - for example, you've completed the cartridge if you have acquired the bell and the book and the candle, but you can find them in any order in various zones - so this could save you a lot of recoding when something changes.  It is possible to create an “empty” Expression (an Expression that has a name but no logic behind it).  This is output in the Lua file as the value "true" (without the quotes).
  * Call function: this allows you to call a Function object, passing in a single parameter.  You probably need to be slightly familiar with Lua to use parameters correctly.  If you just specify "nil" then your function will run with no parameters, which may be all you need, if it's just designed to perform fixed actions.  If you need more than one parameter, congratulations, you are now officially a programmer: see "Lua statement", just below here. ;-)
  * Change media/icon: replaces the image associated with a object.  Useful for when your duckling character turns into a swan.
  * Display dialog or message: One statement type for both object types.  Just remember that a "Dialog" is in fact a monolog, and that a "Message" displays buttons like a Windows dialog box, and you won't have any problems here.
  * Get input from player: ask the user a question.  How many statues can you see here?
  * Lua statement: whatever you put in the box here, gets copied to the cartridge with absolutely no checking.  If you use this statement type and your cartridge won't compile, this will be the first place to look for the error.
  * Move an element: similar to GWB.
  * Play alert sound: that would probably be "beep", then.
  * Save game: and then close, continue, or drive.  I wonder if anyone has ever used the "drive" option?
  * Set value: not every possible combination of objects which is available in GWB is supported, simply because many of them seem to be useless and would just fill up the dropdown lists.  Feedback is appreciated on this point.
  * Show a screen: one statement type covers "Standard screens" (Inventory, Items, Location, Main, Task) and object-specific screens.
  * Turn a sound on or off: Another case where two GWB statements have been combined.
  * Set status text: sets the text which appears on every screen on the target device.
  * Timer operation: choose between Start, Stop, and Tick.
  * Increment variable: there is no Decrement in WWB.  But you can increment a variable by a negative number...

==== Navigation ====


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.

==== A note on object creation ====


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").

==== Bulk input of zonepoints ====


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 {{:greenplus-12px.png|}} 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 [[http://gsak.net/google/polygoneditor.html|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".

==== Using Google Maps to edit zones ====


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.

==== Obfuscating strings ====


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.

==== Localization (multilingual cartridges) ====

=== Introduction ===

Earwigo allows you to build a cartridge which displays texts, prompts, etc, in multiple languages.

There are two possible approaches to this "localization" process:
  - Compile-time: each Lua file (and therefore, compiled GWC file) contains strings and media for one language.
  - Runtime: the Lua file contains all the strings and media for all the supported languages, and the user chooses the language when the game starts.

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".)

=== Common elements to each approach ===

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".

=== Compile-time localization ===

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 [[http://www.earwigo.net/WWB/wiki/doku.php?id=how_to&#cartridge_language_version_0-n|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.

=== Runtime localization ===

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:
  - When the cartridge starts, a specific Lua function called WWB_localize_media will be called, with one parameter: the language version (0 = first, 1 = second, etc).  You can probably use an Earwigo Function, with standard statements like If-Else and Change Media, and standard Expressions to program this function, although you can also use the "Author script" sub-tab on the "Cartridge" tab.  When building Expressions, use a variable from the Variables tab, and assign the function's parameter to the variable as the first statement of the Function.  If you don't provide the a function called WWB_localize_media (for example, because your cartridge has no Media items which need to be localized when the cartridge starts), an empty one will be provided for you.
  - If the Media item of an object (say, a Character) has to be changed during the game, and the Media to be used depends on the language (perhaps the dog puts on a mask, and the mask has a national flag pattern on it), you can write code which uses the global variable WWB_localize_n.  This contains the same value as the parameter passed to WWB_localize_media: 0 for the first language, 1 for the second, etc.  (In fact, WWB_localize_n is also available in the function WWB_localize_media.)