Earwigo Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Tips and Tricks ======

This section collects pieces of information that might be helpful to built a cartridge. Most of them are directly related to the [[WWB]], others are just good to know. Look at it as a collection of tips that you would typically write down to be remembered.

  * [[tips_and_tricks#How to make sure your cartridge works for all players|How to make sure your cartridge works for all players.]]
  * [[tips_and_tricks#How to find a compiler error|How to find a compiler error]]
  * [[tips_and_tricks#Uploading_your_Cartridge_to_Wherigo.com|Uploading your Cartridge to Wherigo.com]]
  * [[tips_and_tricks#Problems_publishing/downloading_your cartridge_to/from_Wherigo.com|Problems publishing/downloading your cartridge to/from Wherigo.com]]
  * [[tips_and_tricks#Zones_and_Objects_behave_unpredictable|Zones and Objects behave unpredictable]]
  * [[tips_and_tricks#How can I create a test cartridge by hand|How can I create a test cartridge by hand?]]
  * [[tips_and_tricks#Testing your cartridge in Webwigo|How do I run an emulation of the cartridge that I have created with Eaewigo?]]
  * [[tips_and_tricks#Wherigo_Sound|How do I play sounds?]]
  * [[tips_and_tricks#How do I show a value to the player|How do I show a value to the player?]]
  * [[tips_and_tricks#How can I assign media during the game|How can I assign media during the game?]]
  * [[tips_and_tricks#Completion Code|How do I create the Completion Code?]]



===== How to find a compiler error =====
 Since we do not have a full fledged compiler with standard error messages it is a little difficult to find out why the compiler comes up with an error message instead of a working cartridge ;-).

=== Apostrophe errors ===

If the error text includes "Length cannot be less  than zero.  Parameter name: length" then the error could possibly be an apostrophe in a comment.  This is valid in [[Lua]], but the compiler doesn't like them.  Check all comments for apostrophes and try compiling again.  If this doesn't work then see next section.

=== Locating other errors ===

  - Cut off the bottom "half" of the [[Lua]] file (the border between the data declarations and the event handler functions is usually a good point to start) and compile it - if that works, 
  - Replace half of the functions, recompile, and so on until the problem reappears. 
  - That usually lets you zoom in on the offending function in 2 or 3 minutes.  You can make this go very slightly faster by using [[GWB]] instead of the compiler (no need to push the test [[Lua]] file into a [[GWZ]] and upload it), but on the other hand [[GWB]] doesn't always object to every possibly syntax error, because it's not a true [[Lua]] implementation.

===== Uploading your Cartridge to Wherigo.com =====

Uploading a cartridge is slightly different from the way you normally work with earwigo. I assume that you are using the compile option of earwigo to create your own test cartridges. When it comes to publishing your cartridge this option is no longer your best choice (I will talk about side issues in a minute).

To upload your cartridge you have to create the gwz-file (look for this operation on earwigo's "manage cartridge" page) and upload the gwz-file to to wherigo.com. The gwz-file contains the lua-source and 
all the media (Garmin and Smart phone combined). The compilation is automatically done by the wherigo-page when a user downloads the cartridge (specifying his particular device type). There are also some other issues that the Wherigo-page takes care of when the user requests your file:
  * generating the player specific completion code
  * writing the Geocaching user-name into the cartridge
  * delete non apropriate media files (for example mp3 files when downloading for a Garmin devices)

==== Special Uploading Issues ====

Although the above procedure takes care of all possible devices (compiling device specific code at download time), some programmers have provided individual cartridges for specific device types. 

Before I explain how to create the device specific versions I need to stress that this procedure is a side route that is not nicely supported by the wherigo and groundspeak websites. If you follow the procedure below the user will not get his own unlock code and he will play the cartridge under the general name of "earwigo". It will be difficult for him to enter a completion code and to log the cartridge as a cache on www.geocaching.com. It might however be his only chance to play the cartridge...

You can achieve this by using the compile option of earwigo (like you typically do for your own test cartridge). If you want to provide these extra cartridge types you have to compile a gwc-file (note the difference to the above file type) for each possible device. People encountering problems with the auto compiled version (see above) might have better luck with the pre-compiled one. Don't ask me why this helps but reports do currently support the pre-compiled versions (let me know if you find out more details).

Once you have created all the different gwc-files, upload these to an ftp-site or a file deposit of your choice and provide the link in the cache/Cartridge description.


===== Problems publishing/downloading your cartridge to/from Wherigo.com =====
==== The edit fields during the upload procedure ====

The edit fields that are presented during the upload procedure are badly programmed. Several issues will cause the compiler to crash for no obvious reasons. Try to follow these rules to avoid the havoc.

  * Do not use special characters
  * This includes BBCode [URL=...], Smilies ;-), international characters (äöüßé ...), everything else including "
  * We think these characters are safe: a-z A-Z : / .
  * Keep your entries short (less is better)

If you continue to have problems
  * delete all of the fields and try again
  * if that works fill in the fields one by one and find the culprit
  * or enter just a short key word without special characters

==== Comments in Author Script ====
Comments in Earwigo are done in a way that they will not disturb the Groundspeak GWC compiler. Comments might however become a concern when they are introduced via author script. To make things worse a successful compile of your cartridge during testing is no guarantee that it will always compile in the GWC compiler. 

The problem is the download of a published cartridge from Wherigo.com.  That's caused by some code which hacks the Lua file before recompiling it.  You could use "problematic comments" in Author Script when testing, but not leave them in place when you upload the cartridge for publication. I suggest to avoid them from the beginning. Having said this, here are the currently known problems:

  - LUA compilers do accept apostrophes within comments. The GWC compiler used on the web server doesn't like apostrophes (') in a comment. (It gives an error "Length cannot be less  than zero.  Parameter name: length".)  Remove apostrophes from your comments and you should be fine.
  - If you have author script that is commented out like this
<code>
--[[this is author script
  that should all be commented 
  out because of the 
  enclosing]]
</code>

The Wherigo compiler will produce a compiler error when you try to download a published cartridge from Wherigo.com. What you need to do is to comment out every single line like this (or remove the lines completely ;-) )
<code>
--this is author script
--that should all be comented 
--out because of the 
--enclosing
</code>





===== How can I create a test cartridge by hand =====
====First step: Create a gwz file ====

  - Go to the Manage Cartridge page.
  - Select the cartridge that you want to test
  - Select the option "Write GWZ file"
  - Save the created *.gwz file to your computer
==== Second step: Upload/compile at wherigo.com ====

  - Go to [[http://www.wherigo.com/cartridge/compile.aspx|this page]]
  - Select your *.gwz file
  - Click "Compile GWZ File"
  - You will receive a *.gwc file. Use this file in the emulator for testing





===== Testing your cartridge in Webwigo =====

The easiest way to test your cartridge (and the only way to test on Apple products) is to use the online emulator Webwigo. You can do this from the Earwigo main menu (manage cartridges). 
  - select your cartridge for testing
  - select "Run in Webwigo" from the drop down list
  - click on the "Submit" button 

The transfer from Earwigo to Webwigo uses a time-out to determine connection problems. This might cause a time-out error message for very long cartridges (or cartridges with large media content). If this happens for you, 
  - compile the cartridge in Earwigo (Manage cartridgec -> Compile cartridge)
  - save the *.gwc file to a folder
  - run http://www.webwigo.net
  - click on the blank page symbol
  - load your *.gwc file
  - done! 

===== Testing your cartridge with the Groundspeak emulator =====
==== Install ====

You need to have the Groundspeak Wherigo Builder installed on your computer to do this. If you don't have the Groundspeak Wherigo Builder go to [[http://www.wherigo.com/login/default.aspx?ReturnUrl=%2fplayer%2fdownload.aspx|the Groundspeak Wherigo page]] and download the builder (geocaching login data required). 

**Warning**: 
  - The GS builder will not run on 64 bit systems. Follow the Wherigo builder [[64 bit patch]] instructions to repair the system.
  - The GS builder and emulator map have an API error. Follow the Wherigo builder [[map patch]] instructions to repair the system.

==== Emulation ====
 
  - Once you have finished your cartridge go to the Manage Cartridge Screen.
  - Select your finished (or intermediate trial) cartridge and select the action "Compile cartridge"
  - Now click on submit. This will produce a *.gwc file of your cartridge. This is the same file that will be loaded into the Wherigo Players to play the cartridge in the field. 
  - Save this *.gwc file at a convenient location. **Important:** avoid strange (accented, etc) characters in the path to this folder. The Wherigo Builder and the Wherigo Emulator will not work reliably if you have special characters in your path. The safest way to avoid trouble is to create the folder c:\Earwigo and use it for your testing.
  - Open the Groundspeak Wherigo Builder and select Tools/Emulator
  - When prompted select the folder that you have created to store your *.gwc file
  - Start the cartridge on the Emulator
  - Drag the human icon across the map to play your cartridge 

===== Wherigo Sound ===== 
The theory with sound media is as follows:

  * You create a [[tips_and_tricks#How_to_get_the_fdl_file|*.fdl file]] for Garmin devices
  * You create an mp3 file for pocket PC devices and smartphones. Please remember that there is a 512 kByte limit on the file size. Some [[mp3_file_size|advice on file length can be found here]].
  * Store the files on your PC

In the cartridge builder you create a sound media element (e.g. OpeningDoorSoundMedia) and assign 

  * the *fdl file 
  * and the mp3 file to it. 

**Remark**: Do not mix sound and picture in one Media object. Create Media objects for sound or Media objects for pictures. A mixed Media object will typically prevent the sound from playing or cause other inconsistencies.
 
When you want to play the sound, go to an Event tab that suits your needs and add the statement "Turn a sound on or off" and select the media object that contains your sounds (in our example OpeningDoorSoundMedia):

<code>
Turn a sound on or off OpeningDoorSoundMedia
</code>

When the user (the human player) downloads the cartridge from Wherigo.com he is asked to specify the target device and the compiler is supposed to automatically add the correct media to the file.
In other words:
  * He selects Garmin Colorado/Oregon as the target device and the compiler automatically creates the cartridge with the *.fdl media files
  * He selects Pocket PC as the target device and the compiler automatically creates the cartridge with mp3 files 

**Note:** If you compile your cartridge from the Earwigo "Manage Cartridge" menu you have to select the correct player manually. If you want to support different players without the Wherigo website involved you have to create a cartridge for each individual player and provide it for download.

==== How to get the fdl file ====
You have to download Jeremy´s SystemBeepRecorder program (which is a sound and music generator) from the folowing link:

http://static.groundspeak.com/installs/SystemBeepRecorder.zip

  * Unzip the file into a convenient folder
  * Run the [[http://static.groundspeak.com/installs/SystemBeepRecorder.zip|SystemBeepRecorder.exe]]
  * Load one of the sounds that is delivered with the SystemBeepRecorder (or create your own music)
  * Save as a system sound file (*fdl, this is not the preset)
  * [[tips_and_tricks#Wherigo_Sound|Specify the fdl as a media in your cartridge]] 

===== How do I show a value to the player? =====
You can include variable text in any string which is displayed when the cartridge is running (meaning, Dialog or Message strings which are displayed in event handlers, functions defined on the Functions tab, and Message callback functions; but not, for example, the initial value of the Description field of an object).  The variable text can be the result of any Lua expression.  Probably the most common use of this is to display the value of a variable.

Let's assume that you have an Earwigo variable named **money** which you use to collect money in your cartridge. If you want to show your human player the amount of money that he has gathered so far, use the ~~ symbol either side of the variable name **var_money** (here is an explanation why you have to use the [[var_ prefix|var_ prefix]]). If you want, you can use something else instead of ~~; look at "Variable lead-in" on the "Cartridge" tab.

Here is an example:
<code>
setValue:item:wallet:Description => Constant:"Your wallet contains ~~var_money~~ coins."
</code>

Then, when the wallet is displayed, its description will say something like "Your wallet contains 14 coins.".

If each coin is worth 7 ducats, you could also write:
<code>
setValue:item:wallet:Description => Constant:"Your wallet contains ~~var_money * 7~~ ducats."
</code>

===== How can I assign media during the game? =====

How can I let a player select their own media to represent them? E.g. I have a male and female graphic to depict the hero.

I can display a message ("Please choose your gender") and accept a response, but how can I change the media item that is referenced throughout the cartridge based on the response (Show a male or female media for the player)? 

**Answer**
Create three media objects: 
  - zmediaHero (nothing here) 
  - zmediaHero_male (male pic) 
  - zmediaHero_female (female pic)

When the human player has made his selection, insert this Lua statement: 
<code>
zmediaHero = zmediaHero_male 
</code>
or
<code>
zmediaHero = zmediaHero_female 
</code>

and use zmediaHero throughout the cartridge. This way all references in Messages and Dialogs will pick up the right Media object.

You still have to change Media properties of items/characters where you use this media, because they're already assigned at that point in the script 

===== Completion Code =====

Q: I am almost done creating my first cartridge. It seems to work fine, but I am struggling with the completion code. Normally this is presented at the
end, but I have no idea how to code that. I guess the display of the code could go into the "Enter" event of the final zone, but what command do I put there to do this? 

A: The completion code is automatically created by the Earwigo software when the cartridge is marked as completed (Set Value..Cartridge..Name of
Cartridge..Complete..True). Once this command is issued the code is stored in the variable: **Player.CompletionCode**.

You can now send a message with: 
<code>"Your completion code is : ~~Player.CompletionCode~~. 
If this code does not work, use only the first 15 digits of the code 
~~WWB_CompletionCode15~~
and try it again (not our fault but this should solve it ;-)" 
</code>
This message will display the completion code to the human player to write down and enter at Wherigo.com. It is also a good idea to prepare an item named Completion Code. Make this item visible when the cartridge is successfully finished. This item can be displayed when the human player opens the cartridge at home.

<code>
Move an element Item:CompletionCode => Player  (Not set)
Set value Item:CompletionCode:Visible => true
Set value Item:CompletionCode:Description => Constant:"The
completion code for www.wherigo.com is ~~Player.CompletionCode~~."
</code>
Don't forget a "Save game and continue" at the end. 

Should some of your human players report problems while entering the completion code make sure that they shorten the code to 15 digits. Superfluous digits more than 15) have to be deleted from the end of the code (example: abcdefghijklmnopqr becomes abcdefghijklmno).

===== Zones and Objects behave unpredictable =====

Q: My zones trigger twice or more and my objects become unusable for no obvious reason. What is going on?

A: Read [[http://www.earwigo.net/WWB/wiki/lib/exe/fetch.php?media=comfortzone.pdf|this presentation]] to find out what causes strange Zone behavior and how to cure it.

===== How to make sure your cartridge works for all players =====
This section does not deal with the [[WWB]] directly but the fact that the [[WWB]] offers you all options that are specified for a Wherigo cartridge might get you in trouble. Some of the specified "functions" don't work on all devices. If you want to build a cartridge that runs on PDAs, Garmin devices and on cell phones you have to avoid these "[[Critical Functions]]". This section tries to collect all known issues.

==== Commands created for a zone ====
  * **Does not work on the Garmin Colorado**
  * **Does (most likely) not work on the Garmin Oregon**
These commands are also known as OnZoneCommands. They create the possibility to have interactive zone screens by adding buttons to the zone screens. The "buttons" are also added to the event list of the zone. You could create a zone with different options when you use this function. This function is [[Critical Functions|critical]] because it does not work on all Wherigo players. 

A workaround could be to display a message after the zone has been entered and use the message buttons (if you want to offer 2 possible actions). If you want to be more sophisticated have a character appear once the zone is entered. The OnCharacterCommands are not critical.

==== Show Screen ====
  * **Does not work on the Garmin Oregon**
The Garmin Oregon has a known bug that causes the device to freeze when the "Show Screen" command is used.
  * Show Screen / Items
  * Show Screen / Characters
  * Show Screen / Zones
  * Show Screen / Tasks
will freeze the Oregon. The only "Show Screen" command that can be used is the "**Show Screen / Main**". If you want the human player to have a look at one of the "bad" screens listed above, you can use the following workaround:

Show a **Message** that asks the player to e.g. check out his Items ("Hey, Maroni has handed over his invisibility cloak to you. Check out your items to learn more about Maroni's cloak") and use the message's "**When a button is pressed**" event with the "**Show Screen / Main**" statement. 

The player will be tasked to check his items and the "**Show Screen / Main**" statement will automatically bring him to the menu that presents an items selector to him. The human player will almost automatically click on the items selector and you have solved your problem. 

==== The OnClick event for characters ====
  * **Does not work on the Garmin Colorado**
  * **Does (most likely) not work on the Garmin Oregon**
The event list for a character includes an event that is named "On Click", "When the player clicks on the character" or similar. It seems to be a very general event but it does not work on all devices and has to be labeled as a [[Critical Functions|critical function]].

A workaround is to use the character's commands and thus create buttons for the interaction with the character. If you really need the OnClick functionality you would have to create a "Click" command (I am sure you can come up with something more sophisticated).

==== The OnClick event for items ====
  * **Does not work on the Garmin Colorado**
  * **Does (most likely) not work on the Garmin Oregon**
The event list for an items includes an event that is named "On Click", "When the player clicks on the item" or similar. It seems to be a very general event but it does not work on all devices and has to be labeled as a [[Critical Functions|critical function]].

A workaround is to use the item's commands and thus create buttons for the interaction with the item. If you really need the OnClick functionality you would have to create a "Click" command (I am sure you can come up with something more sophisticated).


==== The OnClick event for tasks ====
  * **Does not work on the Garmin Colorado**
  * **Does (most likely) not work on the Garmin Oregon**
The event list for a task includes an event that is named "On Click", "When the player clicks on the task" or similar. It seems to be a very general event but it does not work on all devices and has to be labeled as a [[Critical Functions|critical function]].

The only known workaround is to avoid using this function (tasks do not have a command list).

==== Playing the alert sound ====
  * **Does not work on the Garmin Colorado**
  * **Does (most likely) not work on the Garmin Oregon**
The function is obviously intended to produce a warning sound from the player to get the attention of the operator. This does not work on some devices and has to be labeled as a [[Critical Functions|critical function]].

There is a workaround. Refer to [[tips_and_tricks#Wherigo_Sound|Wherigo Sound]] for details.


==== Long Text (Strings > 850 characters)====
  * **Does not work on the Garmin Oregon 300 and 550**
  * **Does not work on the Garmin Colorado**
  * **Might cause trouble on other devices**

It has been shown that a string (Message or Dialog) with more than 850 characters will crash the Wherigo player and the cartridge will be lost to the human player. We know that this occurs on the Colorado at a different character count than on the Oregon (if your cartridge plays on the Colorado it might still not play on the Oregon).

The problem for the cartridge developers is that the message length limit appears to be unit-specific (Colorado vs Oregon). It is quite likely that other stored information on the unit (waypoints, geocaches etc) may aggravate this issue. The current advice is to keep messages to 850 characters or less. If you need to relay more information, split the words over several linked messages or put them in a dialog. 

Keep in mind that the string limit (<850 characters) is also valid if you perform string operations such as adding a string variable to your initial string. The final string needs to be shorter than 850 characters.

It might help you to know that one single "carriage return" might insert several characters. This is actually the reason why we postulate 850 characters. If you try to create a string that targets the 850 mark, CR/LF combinations might inadvertently increase the character count .

The message length issue is most likely not the real problem that causes the devices to crash (bad garbage collection, memory allocation errors, memory leaks, ... are more likely candidates). It is however quite likely that reducing long strings (Messages or Dialogs) might cure a cartridge that does not work (no guarantee here ;-)). 

==== Save and Quit ====
The command "Save and Quit" is ignored by the Garmin Colorado. The cartridge continues without saving.