# Wherigo Player

A desktop application for playing Wherigo geocaching cartridges. Experience geocaching adventures directly on your computer without a GPS device or mobile app.

## Features
- ✅ **Load and execute Wherigo cartridges** (.gwc files)
- ✅ **Full game engine** with Lua 5.1.4 interpreter
- ✅ **Interactive UI** with zones, tasks, inventory, characters, and items
- ✅ **Media support** - Display images (JPEG, PNG) in dialogs and object details
- ✅ **Save/Load game state** - Pause and resume your progress
- ✅ **Completion logs** - Generate .gwl files for wherigo.com
- ✅ **Event-driven updates** - Real-time UI refresh on game state changes
- ✅ **Timer system** - Automatic countdown timers with callbacks
- ✅ **Dialog system** - Multi-page dialogs with images and buttons

## Requirements
- C++23 or newer
- wxWidgets 3.3 (for GUI)
- Lua 5.1.4 (for cartridge execution)
- CMake 3.20+

## Building

```bash
mkdir build && cd build
cmake ..
cmake --build .
```

## Getting Started
1. Download a Wherigo cartridge from [wherigo.com](https://wherigo.com)
2. Launch wxWherigo
3. Click "Open Cartridge..." and select your .gwc file
4. Click "Start Game"
5. Use the tabs to interact with zones, tasks, and items

## Keyboard Shortcuts
- **Ctrl+O** - Open cartridge
- **Ctrl+S** - Save game state
- **Ctrl+L** - Load game state
- **Ctrl+E** - Export completion log

## Documentation
- [Lua State Persistence](LUA_PERSISTENCE.md) - Save/Load system
- [Wherigo Completion](WHERIGO_COMPLETION.md) - Completion log format

## Project Structure
```
wx_wherigo/
├── main/              # Application code
│   ├── src/
│   │   ├── ui/       # User interface (cStartScreen, cGameScreen)
│   │   └── lua/      # Lua integration & game engine
│   └── include/
├── components/
│   ├── cartridge/    # .gwc parser
│   ├── storage/      # File handling
│   └── lua-5.1.4/    # Lua interpreter
```

## License
This project is licensed under the MIT License. See `LICENSE.md` for details.

## Author
Peter Siegmund (mars3142)

## Acknowledgments
- Groundspeak for the Wherigo platform
- wxWidgets team for the GUI framework
- Lua team for the scripting engine