# Wherigo Completion Log (.gwl)

## Übersicht

Der Wherigo Player kann jetzt **Completion Logs** im `.gwl`-Format (Wherigo Game Log) generieren, die auf **wherigo.com** hochgeladen werden können, um den Abschluss einer Cartridge nachzuweisen.

## Format

Das `.gwl`-Format ist ein XML-Format, das folgende Informationen enthält:

### XML-Struktur

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

## Verwendung

### Im Spiel

1. Cartridge spielen und abschließen
2. **Menü → Completion Log exportieren** (Strg+E)
3. Datei speichern (z.B. `TheOmbosIdol_completion.gwl`)
4. Auf [wherigo.com](https://www.wherigo.com) hochladen

### Im Code

```cpp
// Completion Log generieren
wxGetApp().generateCompletionLog("");  // Auto-Path

// Mit eigenem Pfad
wxGetApp().generateCompletionLog("/path/to/completion.gwl");

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

## Was wird erfasst?

### ✅ Cartridge-Informationen
- Name der Cartridge
- GUID (eindeutige ID)

### ✅ Spieler-Informationen
- Spielername (Standard: "Player")

### ✅ Session-Daten
- Startzeit (aktuell: Zeitpunkt der Generierung)
- Endzeit (aktuell: Zeitpunkt der Generierung)
- Gesamtdauer in Sekunden

### ✅ Completion Status
- `Complete` - Alle Tasks abgeschlossen
- `Incomplete` - Noch offene Tasks

### ✅ Aufgaben (Tasks)
- Name der Aufgabe
- Status (completed: true/false)
- Abschlusszeit (falls completed)

### ✅ Gesammelte Items
- Name des Items
- Zeitpunkt des Einsammelns
- **Nur Items im Spieler-Inventar**

### ✅ Besuchte Zonen
- Name der Zone
- Zeitpunkt des Besuchs
- **Nur aktive Zonen**

### ✅ Completion Code
- Eindeutiger Hash/Signatur-Code
- Basiert auf: Cartridge-GUID + Spielername + Abschlusszeit
- Format: 16-stelliger Hex-Code (z.B. `A1B2C3D4E5F67890`)

## Technische Details

### Dateipfad

Standardpfad für Completion Logs:
- **Im gleichen Verzeichnis wie die GWC-Datei**
- Format: `<GWC-Verzeichnis>/<CartridgeName>.gwl`

Beispiel:
- GWC-Datei: `/Users/name/Downloads/TheOmbosIdol.gwc`
- Completion Log: `/Users/name/Downloads/TheOmbosIdol.gwl`

Dies ermöglicht es, die Completion-Logs zusammen mit den Cartridge-Dateien zu organisieren.

### XML-Encoding
- UTF-8
- Sonderzeichen werden escaped: `&`, `<`, `>`, `"`, `'`

### Zeitformat
- ISO 8601: `YYYY-MM-DDTHH:MM:SS`
- Beispiel: `2026-02-13T16:45:00`
- Lokale Zeitzone

### Completion Code Generierung

```cpp
// Einfacher Hash-Algorithmus (für Produktion: SHA256 verwenden)
hash = hash_function(cartridgeGUID + playerName + endTime)
completionCode = sprintf("%016lX", hash)
```

## Limitierungen

### ⚠️ Session-Zeiten
Die aktuellen Start-/Endzeiten sind der **Zeitpunkt der Generierung**, nicht die tatsächliche Spielzeit. Um echte Session-Tracking zu implementieren:

```cpp
// In cApp beim Start speichern:
m_sessionStartTime = time(nullptr);

// Bei Completion verwenden:
data.startTime = m_sessionStartTime;
data.endTime = time(nullptr);
data.duration = data.endTime - data.startTime;
```

### ⚠️ Completion Code
Der aktuelle Hash-Algorithmus ist simpel. Für echte Verifikation sollte **SHA256** oder ein ähnlicher kryptografischer Hash verwendet werden.

### ⚠️ Wherigo.com Upload
Das generierte Format entspricht dem Wherigo-Standard, aber die tatsächliche Akzeptanz auf wherigo.com hängt von deren Server-seitiger Validierung ab.

## Erweiterungen

### Spielername anpassen
```cpp
// In cApp/cGame speichern:
std::string m_playerName = "Player";

// Beim Generieren verwenden:
wherigo::WherigoCompletion::generateCompletionLog(L, path, m_playerName);
```

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

### Zusätzliche Statistiken
Das `CompletionData`-Struct kann erweitert werden um:
- Anzahl der Dialoge
- Zurückgelegte Distanz
- Verwendete Hints
- Fehlversuche

### Auto-Export bei Abschluss
```cpp
// In cGame::OnTaskCompleted() oder bei Complete-Event
if (allTasksCompleted()) {
  wxGetApp().generateCompletionLog("");
  wxMessageBox("Gratulation! Completion Log wurde automatisch erstellt.");
}
```

## Beispiel-Workflow

1. **Spieler spielt Cartridge**
2. **Alle Tasks werden abgeschlossen**
3. **Spieler exportiert Log:** Menü → Completion Log exportieren
4. **Datei wird gespeichert:** `TheOmbosIdol_completion.gwl`
5. **Upload auf wherigo.com:**
   - Login auf wherigo.com
   - Zur Cartridge-Seite navigieren
   - "Log completed cartridge" Button
   - `.gwl`-Datei hochladen
   - Completion wird verifiziert und angezeigt

## Debugging

Log-Ausgaben aktivieren:
```cpp
wxLogMessage("Completion log generated: %s", filePath);
wxLogDebug("Tasks completed: %d/%d", completedCount, totalCount);
```

## Zukünftige Features

- [ ] Automatisches Tracking der Session-Zeit
- [ ] Spielername-Eingabe-Dialog
- [ ] Screenshot/Foto-Anhänge
- [ ] GPS-Koordinaten für besuchte Zonen
- [ ] Statistiken (Distanz, Zeit pro Zone, etc.)
- [ ] Automatischer Export bei Completion
- [ ] Cloud-Upload direkt aus der App
- [ ] Kryptografischer Completion Code (SHA256)