wx_wherigo/WHERIGO_COMPLETION.md

# Wherigo Completion Log (.gwl)

## Overview

The Wherigo Player can now generate **Completion Logs** in `.gwl` format (Wherigo Game Log), which can be uploaded to **wherigo.com** to prove completion of a cartridge.

## Format

The `.gwl` format is an XML format that contains the following information:

### XML Structure

```xml
<?xml version="1.0" encoding="UTF-8"?>
<WherigoGameLog xmlns="http://www.groundspeak.com/wherigo/1.0">
  <Cartridge>
    <Name>The Ombos Idol</Name>
    <GUID>a1b2c3d4-e5f6-7890-abcd-ef1234567890</GUID>
  </Cartridge>
  
  <Player>
    <Name>Player</Name>
  </Player>
  
  <Session>
    <StartTime>2026-02-13T14:30:00</StartTime>
    <EndTime>2026-02-13T16:45:00</EndTime>
    <Duration>8100</Duration>
  </Session>
  
  <CompletionStatus>Complete</CompletionStatus>
  
  <Tasks>
    <Task>
      <Name>Find the Professor</Name>
      <Completed>true</Completed>
      <CompletionTime>2026-02-13T15:20:00</CompletionTime>
    </Task>
    <Task>
      <Name>Solve the Puzzle</Name>
      <Completed>true</Completed>
      <CompletionTime>2026-02-13T16:30:00</CompletionTime>
    </Task>
  </Tasks>
  
  <ItemsCollected>
    <Item>
      <Name>Key</Name>
      <FoundTime>2026-02-13T15:10:00</FoundTime>
    </Item>
    <Item>
      <Name>Map</Name>
      <FoundTime>2026-02-13T15:45:00</FoundTime>
    </Item>
  </ItemsCollected>
  
  <ZonesVisited>
    <Zone>
      <Name>Town Square</Name>
      <VisitTime>2026-02-13T14:35:00</VisitTime>
    </Zone>
    <Zone>
      <Name>Old Library</Name>
      <VisitTime>2026-02-13T15:15:00</VisitTime>
    </Zone>
  </ZonesVisited>
  
  <CompletionCode>A1B2C3D4E5F67890</CompletionCode>
</WherigoGameLog>
```

## Usage

### In-Game

1. Play and complete cartridge
2. **Menu → Export Completion Log** (Ctrl+E)
3. Save file (e.g., `Cartridge.gwl`)
4. Upload to [wherigo.com](https://www.wherigo.com)

### In Code

```cpp
// Generate completion log
wxGetApp().generateCompletionLog("");  // Auto-Path

// With custom path
wxGetApp().generateCompletionLog("/path/to/completion.gwl");

// Get path
std::string path = wxGetApp().getCompletionLogPath();
```

## What is Captured?

### ✅ Cartridge Information
- Cartridge name
- GUID (unique ID)

### ✅ Player Information
- Player name (default: "Player")

### ✅ Session Data
- Start time (currently: generation timestamp)
- End time (currently: generation timestamp)
- Total duration in seconds

### ✅ Completion Status
- `Complete` - All tasks completed
- `Incomplete` - Tasks still pending

### ✅ Tasks
- Task name
- Status (completed: true/false)
- Completion time (if completed)

### ✅ Collected Items
- Item name
- Collection timestamp
- **Only items in player inventory**

### ✅ Visited Zones
- Zone name
- Visit timestamp
- **Only active zones**

### ✅ Completion Code
- Unique hash/signature code
- Based on: Cartridge GUID + Player name + Completion time
- Format: 16-digit hex code (e.g., `A1B2C3D4E5F67890`)

## Technical Details

### File Path

Default path for completion logs:
- **In the same directory as the GWC file**
- Format: `<GWC-Directory>/<CartridgeName>.gwl`

Example:
- GWC file: `/Users/<name>/Downloads/<CartridgeName>.gwc`
- Completion log: `/Users/<name>/Downloads/<CartridgeName>.gwl`

This allows organizing completion logs together with cartridge files.

### XML Encoding
- UTF-8
- Special characters are escaped: `&`, `<`, `>`, `"`, `'`

### Time Format
- ISO 8601: `YYYY-MM-DDTHH:MM:SS`
- Example: `2026-02-13T16:45:00`
- Local timezone

### Completion Code Generation

```cpp
// Simple hash algorithm (use SHA256 for production)
hash = hash_function(cartridgeGUID + playerName + endTime)
completionCode = sprintf("%016lX", hash)
```

## Limitations

### ⚠️ Session Times
Current start/end times are the **generation timestamp**, not actual playtime. To implement real session tracking:

```cpp
// Save in cApp at start:
m_sessionStartTime = time(nullptr);

// Use at completion:
data.startTime = m_sessionStartTime;
data.endTime = time(nullptr);
data.duration = data.endTime - data.startTime;
```

### ⚠️ Completion Code
The current hash algorithm is simple. For real verification, **SHA256** or similar cryptographic hash should be used.

### ⚠️ Wherigo.com Upload
The generated format follows the Wherigo standard, but actual acceptance on wherigo.com depends on their server-side validation.

## Extensions

### Customize Player Name
```cpp
// Store in cApp/cGameScreen:
std::string m_playerName = "Player";

// Use when generating:
wherigo::WherigoCompletion::generateCompletionLog(L, path, m_playerName);
```

### Session Tracking
```cpp
class cApp {
  time_t m_sessionStartTime = 0;
  
  void startGame() {
    m_sessionStartTime = time(nullptr);
    // ...
  }
};
```

### Additional Statistics
The `CompletionData` struct can be extended with:
- Number of dialogs
- Distance traveled
- Hints used
- Failed attempts

### Auto-Export on Completion
```cpp
// In cGameScreen::OnTaskCompleted() or on Complete event
if (allTasksCompleted()) {
  wxGetApp().generateCompletionLog("");
  wxMessageBox("Congratulations! Completion log automatically created.");
}
```

## Example Workflow

1. **Player plays cartridge**
2. **All tasks completed**
3. **Player exports log:** Menu → Export Completion Log
4. **File saved:** `<CartridgeName>.gwl`
5. **Upload to wherigo.com:**
   - Login to wherigo.com
   - Navigate to cartridge page
   - Click "Log completed cartridge"
   - Upload `.gwl` file
   - Completion verified and displayed

## Debugging

Enable log output:
```cpp
wxLogMessage("Completion log generated: %s", filePath);
wxLogDebug("Tasks completed: %d/%d", completedCount, totalCount);
```

## Future Features

- [ ] Automatic session time tracking
- [ ] Player name input dialog
- [ ] Screenshot/photo attachments
- [ ] GPS coordinates for visited zones
- [ ] Statistics (distance, time per zone, etc.)
- [ ] Automatic export on completion
- [ ] Cloud upload directly from app
- [ ] Cryptographic completion code (SHA256)