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 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

In Code

// 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

// 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:

// 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

// Store in cApp/cGameScreen:
std::string m_playerName = "Player";

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

Session Tracking

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

// 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:

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)