Wherigo Builder

What is a Wherigo cartridge, and what do I need to play one?

A cartridge is a location-based program with places, story, objects and decisions. To play one, open its .gwc file in a Wherigo-compatible phone or GPS player, including the CacheSleuth Wherigo Player.

What is the difference between Easy and Advanced mode?

Easy shows the common path for zones, items, questions, media and a small action set. Advanced shows every object, trigger, action, import, protection and checking tool. Switching modes only changes what the page presents. It does not delete or reshape the cartridge.

Why did my project open in Advanced when I chose Easy?

The project uses something Easy does not display, such as a timer, a hidden trigger, raw Lua or a longer choice list. The builder keeps Advanced open and names those features so you never edit a cartridge with invisible behavior. Your Easy preference remains saved and returns when the project no longer needs Advanced.

Do I need to know Lua?

No. The forms and actions generate the Lua for you. Advanced mode includes raw Lua as an escape hatch for behavior the visual editor does not model, and imports may preserve foreign code there. Read any raw Lua before building, but you do not need it for an ordinary cartridge.

How do zones work, and what are distance and proximity for?

A zone is a shape on the map. Its events can react when the player enters, leaves, gets near or moves away. Distance range is how far away the player starts seeing a distance to the zone. Proximity range is the nearer boundary that fires the proximity state. Use -1 to disable either range.

How do I ask the player a question and check their answer?

Create a Question in the Objects rail and write its prompt. Add an Ask a question action where the prompt belongs, then select that Question. Open the Question itself and put the follow-up actions under “When the player answers.” That handler can use an If condition to compare the player answer, ignoring case when appropriate.

Why can a multiple choice question only have three options?

Easy mode limits the list to three because later choices can fall off a small handheld screen where the player cannot tap them. Advanced mode can keep a longer imported list, but the checker warns about it. Split a longer decision into more than one question when you can.

What are items, characters, tasks, timers and variables for?

• Items are things the player can inspect, find, carry or use.
• Characters are people or creatures the player can meet and interact with.
• Tasks track objectives, progress and completion.
• Timers fire once after a delay or repeat at an interval.
• Variables remember text, numbers or true and false state between actions.

Easy keeps Items visible and hides Characters, Tasks, Timers and Variables. Switch to Advanced to create or edit those four kinds.

How do I add pictures and sounds, and what formats are safe?

Open Media, add the file, then choose that media entry from a zone, object or action. JPG, PNG and GIF pictures and WAV sound are the safest choices across players. The builder also accepts FDL and SND, which the checker treats the same way. BMP, MP3, OGG, SWF and TXT are accepted too, but support varies, so device profiles flag them: a note on Browser player, a warning on Pocket PC and Smartphone, and an error on Strictest. Test media on the oldest player you plan to support.

What is the device profile dropdown for?

It changes the size budgets and warning strictness used by Check for problems. It does not change the cartridge that gets built. Pocket PC handheld uses the measured handheld range, Smartphone player allows the largest measured cartridge, Browser player uses the build-service ceiling, and Strictest uses the tightest citable value in each row.

Why does it warn my cartridge is too big?

The selected device profile uses a size guideline, not a published device limit. A larger cartridge may still work, but smaller media can reduce memory problems on some devices. Shrink large pictures or sounds, or choose the profile for the player you actually target.

What does “the player cannot save here” mean?

A Wherigo player cannot save while a message with buttons or an input is on screen. That is a real platform constraint, not a build failure. Avoid a long unsavable stretch by ending one interaction before starting the next, for example by showing a plain message between a button choice and the next question.

What is the objects and callbacks budget, and why 170?

Generated Lua uses one local for each cartridge object and more locals for message button callbacks. Lua 5.1 allows 200 locals in one function. The builder stops at 170 so generated helpers and callbacks have headroom before the real language limit.

What is the difference between Check compile, Check for problems and Walk it through?

Check compile sends the generated Lua, without media, to the compiler and reports syntax or compiler errors. Check for problems stays in the browser and inspects structure, reachability, zones, media and the selected device budgets. Walk it through runs the generated cartridge in the Lua engine, automatically explores it, and probes save and restore behavior. Use all three before publishing.

Can I move a project between computers?

Yes. Cloud projects keep the encrypted project and, when media sync is on, its encrypted media in your account so another computer can open the complete project. Export package still creates one file you can download, back up or move without using Cloud projects.

.gwc versus .gwz: which do I upload to wherigo.com?

Upload the .gwz package to wherigo.com. It contains the Lua source and media that the site compiles for players. A .gwc is the compiled cartridge a phone, GPS device or browser player opens directly, so it is never what you upload to wherigo.com. Upload a cartridge to Wherigo.com.

How do I test on my phone?

Playtest opens the cartridge in the CacheSleuth player on this device. In Advanced mode, Test on phone builds or accepts a .gwc, uploads it to a short-lived slot, and gives you a link and QR code to open on the phone. Anyone with that temporary link can fetch the cartridge, so delete it when you finish.

What is a completion code and how do I stop people cheating?

A completion code is the value a finder submits to prove the cartridge reached its end. A literal code is readable from the file. The Protect panel can derive a code from field answers and use server verification so the final answer is not stored in the cartridge. No offline cartridge is fully emulator-proof because it runs on the player’s device, and a finder can still share a code after earning it.

Can I import a cartridge I built elsewhere?

Yes. Import accepts .gwc, .gwz and .urwigo files. A .gwz imports best because it carries Lua source, so there is no compiled-code decompilation guesswork. A foreign .gwc may lift only the structures the builder can prove and preserve the rest as raw Lua, or offer a partial project. The import report tells you what was recovered before anything replaces the project on screen.

Where do my media files live?

The builder first keeps attached media in this browser. When Cloud media sync is on, encrypted copies also use your account storage quota. In a private window, or when the browser has no storage room, local media may last only until the page closes and you may need to attach it again.

What gets uploaded, and when?

Nothing is uploaded just because you edit. Check compile sends generated Lua without media to the build service. Build .gwc and Playtest send Lua and attached media. Import .gwc asks before sending the file for decompilation. The build service deletes those uploads after 30 minutes. Cloud projects upload encrypted project JSON when you save. If you turn on media sync for that project, they also upload each media file encrypted without its filename. The project name, encrypted sizes and storage totals remain visible to the cloud service. Test on phone uploads a built .gwc to a temporary share slot only when you ask. Export commands download files to your device.