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.
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 .
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.
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:
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.
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.
If you continue to have problems
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:
--[[this is author script that should all be commented out because of the enclosing]]
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 )
--this is author script --that should all be comented --out because of the --enclosing
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).
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,
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 the Groundspeak Wherigo page and download the builder (geocaching login data required).
The theory with sound media is as follows:
In the cartridge builder you create a sound media element (e.g. OpeningDoorSoundMedia) and assign
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):
Turn a sound on or off OpeningDoorSoundMedia
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:
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.
You have to download Jeremy´s SystemBeepRecorder program (which is a sound and music generator) from the folowing link:
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). If you want, you can use something else instead of ~~; look at “Variable lead-in” on the “Cartridge” tab.
Here is an example:
setValue:item:wallet:Description => Constant:"Your wallet contains ~~var_money~~ coins."
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:
setValue:item:wallet:Description => Constant:"Your wallet contains ~~var_money * 7~~ ducats."
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:
When the human player has made his selection, insert this Lua statement:
zmediaHero = zmediaHero_male
zmediaHero = zmediaHero_female
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
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:
"Your completion code is : ~~Player.CompletionCode~~. If this code does not work, use only the first 15 digits of the code ~~Player.CompletionCode15~~ and try it again (not our fault but this should solve it ;-)"
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.
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~~."
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).
Q: My zones trigger twice or more and my objects become unusable for no obvious reason. What is going on?
A: Read this presentation to find out what causes strange Zone behavior and how to cure it.
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.
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 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.
The Garmin Oregon has a known bug that causes the device to freeze when the “Show Screen” command is used.
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 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 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 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 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 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 function.
The only known workaround is to avoid using this function (tasks do not have a command list).
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 function.
There is a workaround. Refer to Wherigo Sound for details.
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 ).
The command “Save and Quit” is ignored by the Garmin Colorado. The cartridge continues without saving.