Sonntag, 18. Dezember 2011

Wherigo Einstiegskurs


Als ich vor gut einem Jahr meinen ersten Wherigo gemacht habe, war mir eines sofort klar: „So einen Cache veröffentlichst du auch“. Aber die Sache war leichter gesagt als in der Praxis umgesetzt. Nach den ersten Versuchen mit dem Wherigo Builder von Groundspeak musste ich feststellen, dass dieses Tool nicht dasjenige sein wird, mit dem ich programmieren werde. Der Ansatz den Programmablauf als Flussdiagramm mit vorgefertigten Bausteinen zu realisieren ist zwar vielversprechend aber viel zu umständlich umgesetzt. Es sind viel zu viel Mausklicks für die einzelnen Aktionen nötig, sodass das Urteil über die Usability sehr bescheiden ausfällt. Dazu kommt dass man nach jeder Änderung speichern sollte, da der Builder regelmäßig abstürzt. Auch der Simulator ist zu kompliziert umgesetzt. Da das letzte Update nun über 3 Jahre alt ist, kann man auch nicht mehr davon ausgehen, dass das Programm noch weiterentwickelt wird.
Die Alternative habe ich im URWIGO builder gefunden, der ebenfalls mit Flussdiagramm und vorgefertigten Bausteinen arbeitet, aber mit viel weniger Mausklicks zum Erfolg führt. Die Bedienung ist recht intuitiv, sodass man nach wenigen Minuten bereits die ersten Erfolge verbuchen kann.

Download

Den Editor könnt ihr unter http://apps.yourself.cz/urwigo/setup.exe herunterladen

Abbildung 1: URWIGO builder Übersicht
Abbildung 1 zeigt die Übersicht des URWIGO builder. Auf der linken Seite sind im oberen Bereich verschiedene Bausteine definiert mit denen sich die einzelnen Programmteile zusammen klicken lassen. Im linken unteren Bereich sieht man die Objekte, die man bereits angelegt hat. Die Eigenschaften dieser Objekte sind im rechten Bereich zu sehen bzw. zu ändern, während unten ein Frame uns auf potentielle Fehler hinweist.
Das Hauptfenster dient später dazu den Programmablauf als Flussdiagramm darzustellen.

Vorbereitung

Doch bevor wir anfangen zu programmieren bedarf es, genauso wie beim klassischen Multi einiger Vorbereitung, denn die meisten Wherigos sind wie normale Multis aufgebaut, ein paar Stationen mit Aufgaben, deren Lösung zur nächsten Station bzw. zum Final führt. Wir werden in den nächsten Ausgaben sehen, wo das wirkliche Potential dieser Cachesorte liegt, für den Anfang begnügend wir uns mit der einfachen Version.
Als Gegebenheiten nehmen wir ein Haus mit lateinischer Inschrift „Errare humanum est“ (Irren ist menschlich), einen Berg sowie eine kleine Höhle.
Dazu überlegen wir uns folgende Story „Jagd nach dem Drachengold“:
Als Spieler finden wir vor der Schmiede ein altes Steinschwert, dass sich mittels lateinischem Zauberspruch aktivieren lässt. Wir ziehen damit weiter zum Berg wo wir mit Hilfe unseres Schwertes einen Drachen töten, damit der Weg frei ist zur Schatzhöhle.
Diese Miniversion der Nibelungensage ist zwar noch nicht oskarreif, dürfte für unser Tutorial aber ausreichen.
Der nächste Schritt unserer Vorbereitung besteht darin, dass wir die Koordinaten von Parkplatz, Haus, Berg und Höhle messen, sowie uns Bilder von Schwert und Drachen als auch ein Spoilerbild organisieren.
Die Koordinaten benötigen wir im Dezimalformat hddd.ddddd°.
Soweit noch nicht geschehen, ist es jetzt Zeit den URWIGO builder herunterzuladen, zu installieren und zu starten.

Erste Schritte

Für unsere Geschichte brauchen wir folgende Wherigo Objekte:
  • 3 Zonen Schmiede, Drachenberg und Schatzhoehle
  • 1 Charakter Drache
  • 2 Gegenstände Schwert und Spoiler
  • 1 Benutzereingabe für den Zauberspruch
Wir beginnen mit der Startseite. Neben dem Namen und einer kleinen Beschreibung geben wir hier auch die Startkoordinaten unseres Wherigos an. Es empfiehlt sich hier die Parkplatzkoordinaten zu nehmen.
Abbildung 2: Startbildschirm

Zonen

Als nächstes beschäftigen wir uns mit dem Anlegen der ersten Zone. Zonen stellen einen zentralen Bestandteil unseres Programmes dar und sind vergleichbar mit den Stationen eines klassischen Multis. Ein Doppelklick auf Zones in der linken Menüleiste öffnet die Übersicht der Zonen und gibt uns die Möglichkeit über den New item Button unsere erste Zone anzulegen. Im rechten Fenster geben wir neben Namen Schmiede nun auch die gemessene Koordinate ein.
Eine Zone besteht allerdings aus mindestens drei Punkten. Um diese zu erstellen klicken wir auf Edit in map und legen mittels des Google Maps Plugins 4 Punkte um die gemessene Koordinate herum. Mit einem rechten Mausklick entfernen wir noch unseren Mittelpunkt und unsere Zone ist fertig. Im Feld Border points erscheinen nur die vier gezeichneten Koordinaten. Achtet bitte darauf, dass ihr die Zonen groß genug wählt um GPS-Ungenauigkeiten auszugleichen.
Abbildung 3: Zone anlegen
Diesem Muster folgend legen wir zwei weitere Zonen Drachenberg sowie Schatzhoehle an, wobei wir bei der letzten Zone uns eines Tricks bedienen. Anstatt ein großes Viereck um die Finalkoordinate zu zeichnen, kopieren wir den Wert zweifach und ändern lediglich die letzte Stelle der Nord- bzw. Ostkoordinate. Wir bilden somit ein Minidreieck das wenige Millimeter groß ist, denn anders als bei den ersten beiden Zonen, bei deren Erreichen verschiedene Aktionen ausgeführt werden, soll der Player hier zur Tupperdose geführt werden. Doch dazu später mehr.
Während wir bei der Schmiede sowohl die Active als auch die Display Checkbox aktiv lassen, entfernen wir für den Drachenberg das Active Häkchen und deaktivieren beide Checkboxen der Schatzhoehle. Display entscheidet darüber, ob der Spieler die Zone sehen kann während die später beschriebenen Events nur ausgelöst werden, wenn Active ausgewählt wurde.

Bilder

Abbildung 4: Medien einbinden

Bevor wir nun unseren Drachen anlegen, müssen wir zunächst das dazu passende Bild einbinden. Dazu wählen wir in der linken unteren Ecke den Eintrag Media und wählen wieder New item. Nachdem wir den Namen eingeben haben wählen wir im Bereich Resources mit New item unser vorbereitetes Bild aus und wiederholen die Schritte für Schwert und Spoiler.

Personen und Gegenstände

Abbildung 5: Charakter erstellen
Die Bilder sind vorbereitet und wir wagen uns an den Drachen. Das Verfahren mit Doppelklick auf Characters und New item dürfte nun genauso bekannt sein, wie die Eingabe des Namens. Wenn wir auf das kleine Dreieck in der Image Zeile klicken, können wir dort unser Drachenbild auswählen. Als Location setzen wir Drachenberg, denn nur dort soll der Drache auftauchen.
Abbildung 6: Gegenstand erstellen
Äquivalent dazu legen wir über Items unser Schwert an. Die Location lassen wir noch offen, denn schließlich muss der Spieler es erst entzaubern, dafür bekommt es den Befehl Toete den Drachen. Da dieses Kommando erst verfügbar sein soll, wenn der Drache zu sehen ist, deaktivieren wir das Flag Enabled.
Abbildung 7: Kommando erstellen

Benutzereingaben

Irgendwann soll der Spieler auch mal aktiv werden und Text oder Zahlen eingeben. Dazu erzeugen wir einen Input (InputsNew item....) und formulieren den Text im Question Bereich.
Abbildung 8: Benutzereingabe defineren

Programmablauf

So langsam wird es Zeit unseren Wherigo mit Leben zu erfüllen. Der Programmablauf ist ereignisorientiert, d. h. erst nachdem der Spieler bestimmte Aktionen ausgeführt hat und damit definierte Events eingetreten sind werden bestimmte Programmteile aktiv.
Typische Events sind das Erreichen einer Zone, Eingabe von Antworten oder manuelles Aufrufen von Kommandos bei Personen oder Gegenständen.

Eventhandling

Unser erstes Event, dass wir behandeln wollen ist der Start des Spieles.
Dazu klicken wir auf der Hauptseite auf On start unhandelt und werden mit einem Fenster belohnt, in dem wir definieren, was passieren soll, wenn das Spiel beginnt. Wir machen es uns hier einfach und geben lediglich den Text „Gehe zur Schmiede“ aus. Dazu ziehen wir per gedrückter Maustaste aus dem linken oberen Bereich eine Message in den On start Bereich des mittleren Fensters. Anschließend können wir oben rechts den Text der Nachricht eingeben.
Abbildung 9: Eventhandling 'On start'

Betreten einer Zone

Nun wollen wir definieren, was beim Erreichen der Zone Schmiede passieren soll.Dazu wählen wir diese aus, klicken auf On enter unhandled und ziehen auch hier eine Message in das Hauptfenster, in dem wir den Spieler über das Schwert und den Zauberspruch aufklären.
Sobald dieser die Nachricht gelesen und den OK Button gedrückt hat, soll eine Eingabeaufforderung erscheinen, in die der lateinische Spruch eingegeben werden kann. Dazu ziehen wir den Input Baustein, aus dem Actions Frame in den On clicked Bereich der Message und anschließend aus dem unteren Objects and properties Frame die Eingabe Zauberspruch in den Input Baustein.
Abbildung 10: Betreten der ersten Zone
Um zu verstehen, warum es so wichtig ist, dass der Input Baustein in den On clicked Bereich und nicht darunter gezogen wird, müssen wir verstehen wie unser Programm später abgearbeitet wird. Sobald ein Event ausgelöst wird, werden die definierten Schritte ohne Unterbrechung abgearbeitet. D.h. wenn Message und Input einfach untereinander stehen würden, so würden sie direkt nacheinander angezeigt und zwar so schnell, dass der Spieler nur den Input sehen würde, da dieser die Message sofort überlagert.
Um diesen Anfängerfehler zu umgehen, setzten wir den Input in den On clicked Bereich. So gehört nur die Message zur Befehlskette, die beim Eintreten in die Schmiedezone abgearbeitet wird und erst beim Bestätigen der Nachricht durch den OK Button wird das nächste Event, nämlich On clicked ausgeführt.

Eingabe verarbeiten

Was aber fangen wir nun mit der Eingabe an? Wir unterscheiden hier zwei Fälle: Die Eingabe ist korrekt oder nicht, wobei der zweite Fall recht einfach zu behandeln ist, denn nachdem wir mittels einer weiteren Message den Spieler über die falsche Eingabe informiert haben, wiederholen wir einfach die Eingabe so lange bis die Antwort korrekt ist. Dieses Verfahren wird auch Rekursion genannt.
Abbildung 11: Eingabe verarbeiten
Bei zufriedenstellender Eingabe haben wir direkt mehrere Schritte zu erledigen. Wir deaktivieren die Schmiedezone, aktivieren die Drachenbergzone und heften den Gegenstand Schwert an den Player, denn nur wenn Charaktere bzw. Gegenstände sich in der gleichen Zone wie der Spieler befinden oder ihm angeheftet sind, kann er diese sehen und mit ihnen interagieren.
Aber der Reihe nach. Zunächst wählen wir den Input Zauberspruch und klicken auf der rechten Seite auf On get input handelt. In das sich nun öffnende Fenster ziehen wir nacheinander die Bausteine If/else, Compare und Answer und ordnen sie wie in Abbildung 11 gezeigt an.
Im Compare Baustein wurde auf der rechten Seite bereits ein Value Element eingefügt, dass wir nun mit dem gewünschten Wert „ Errare humanum est“ füllen.
Unterhalb von Compare ziehen wir einen Set Baustein, in deren linken Bereich wir die Active Eigenschaft unserer Schmiede ziehen (siehe Abbildung 12 unten links). Den Wert den wir zuweisen wollen können wir auf False lassen, denn diese Zone ist ja nicht mehr aktuell.
Mit der Drachenbergzone verfahren wir äquivalent, nur dass wir hier den Wert auf True setzen, indem wir zunächst auf den False Wert klicken und dann oben rechts das Häkchen setzen.
Nun braucht unser Ritterheld aber noch sein Schwert. Um es ihm zur Verfügung zu stellen bedienen wir uns des Move Bausteines in dem wir Schwert und Player setzen. Den Abschluss macht eine Message in der wir weitere Instruktionen ausgeben.
Mit einem Klick auf das Pluszeichen im If/else Baustein erweitern wir das Flussdiagramm, um für den Fall, dass die Antwort falsch ist, die angesprochene Rekursion zu definieren.
Abbildung 12: Eingabeverarbeitung mit Rekursion

Kommando ausführen

Wir lenken unsere Aufmerksamkeit nun auf den Drachenkampf. Dafür müssen wir beim Eintritt in die Drachenbergzone das Kommando Toete den Drachen aktiv schalten. Abbildung 12 zeigt Message und Set Bausteine für den On enter Bereich der Drachenhoehle. Was uns noch fehlt ist der Drachenkampf selbst, Dazu klicken wir auf unhandelt unterhalb des Kommando um das Execute Event zu implementieren.
Abbildung 13: Eintritt in die Drachenbergzone
Dort geben wir die Nachricht aus, dass das Untier tot und der Weg zum Schatz frei ist, Vergiss nicht die Sichtbarkeit des nun toten Drachen sowie das Kommando zu deaktivieren sowie die Zonen umzusetzen, damit der Pfeil den Spieler zum Final führt.
Abbildung 14: Kommando ausführen

Final und Spoiler

Damit die Suche nach der Dose nicht zu schwer wird, stellen wir einen Spoiler zur Verfügung. Unsere Finalzone ist aber so klein bemessen, dass sie praktisch gesehen nur auf einen Punkt zeigt. On enter wird dadurch so gut wie nie ausgelöst. Aus dieser Misere hilft uns das On proximity Event. Dies wird ausgelöst, sobald sich der Spieler im Umkreis der Zone befindet. Den Radius dieses Umkreises bestimmen wir im Feld In proximity. Sobald sich der Spieler näher als die definierten 10 Meter befindet stellen wir im mittels Move Operation den Spoiler bereit. Anschließend setzen wir das Complete Flag des Cartridges auf True und speichern das Spiel, damit der Spielstand zu wherigo.com hochgeladen und dort als erledigt markiert werden kann.
Abbildung 15: Final und Spoiler

Testen und Veröffentlichen

Programmieren und Entwickeln ist ja schön und gut, aber irgendwann wird der Moment kommen, wo wir unser Programm auch mal testen wollen. Auch dies funktioniert im URWIGO builder recht einfach. Mittels der F5 Taste, lässt sich ein Simulator starten und das Spiel auf einem virtuellen Pocket PC spielen. Die Bewegungen lassen sich durch ein Kartenfenster simulieren, auf dem man den Spieler per Maus bewegen kann. Wie aber bekomme ich das Cartridge auf reale Geräte? Zum Testen kann dies über die obere Menüleiste geschehen. Über BuildCompile cartridge (gwc) wird per Knopfdruck aus dem URWIGO Projekt ein Lua Skript erstellt und dieses zusammen mit den benötigten Bildinformationen als gwc Datei gespeichert, welche auf das gewünschte Gerät kopiert werden kann. Ebenfalls unter dem Menüpunkt Build ist der Befehl Build package (gwz) zu finden. Auch bei diesem Befehl wird ein Lua Skript erstellt und zusammen mit allen benötigten Bildern abgespeichert. Es handelt sich hierbei aber nicht um ein lauffähiges Cartridge, sondern lediglich um eine Archivdatei, die auf wherigo.com hochgeladen werden kann um sie dort der Geocachinggemeinde zur Verfügung zu stellen.
Abbildung 16: Kompilieren und Packen

Pimp my Wherigo

Um das Tutorial übersichtlich zu halten, habe ich mich mehr auf Funktion als auf Design konzentriert. Damit der Cache aber nicht nur funktioniert sondern auch Spaß bereitet, sollte man das Spiel noch ein wenig aufpeppen. Dazu empfiehlt es sich neben der Überarbeitung der ausgegebenen Nachrichten auch mehr Bilder einzusetzen. So kann der Spieler tiefer in die Geschichte eintauchen, wenn die einzelnen Zonen mit Bilder erweitert werden. Vor allem der Final dürfte durch eine schlichte Schatztruhe interessanter wirken als wenn nur der kleine rote Pfeil zu sehen ist. Bei den ausgegebenen Nachrichten kann bei der Drachengoldgeschichte ein Geschichtenerzähler, dessen Bild über der Nachricht gezeigt wird, Wunder bewirken. Bei Wherigos mit vielen zu beantworteten Fragen kann wiederum ein Professorbild bei den Inputs die Geschichte lebendiger erscheinen lassen. Bei allen Modifikation sollte man allerdings eines beachten. Perfekt wird es nie und übersichtlich sollte es auch noch bleiben. Deswegen gilt wie beim ersten ausgelegten Tradi, Mystery oder Multi, dass man es beim ersten Versuch nicht übertreiben, dafür aber ausgiebig testen, besonders auch testen lassen sollte.

Das urwigo Projekt zu diesem Tutorial als Download

Rekursion


Bei der Rekursion ruft sich ein Programmteil, meist ein Funktion, unter bestimmten Bedingungen immer wieder selbst auf. Man erspart sich dabei bestimmte Abhandlungen zu wiederholen. Bei der Wherigo Programmierung ist die wiederholende Eingabeaufforderung ein beliebtes Einsatzgebiet für die Rekursion. Entscheidend für den Erfolg der Rekursion ist die Abbruchbedingung damit wir nicht ewig in der Rekursion festhängen.

Umlaute im Wherigo


Bei der Benennung der Objekte und bei der Ausgaben von Nachrichten ist zu beachten, dass nicht alle Wherigo Player deutsche Umlaute und Sonderzeichen darstellen können. 
Genau genommen verwenden die Player verschiedene Kodierungen um Umlaute darzustellen. 

Um Lücken im Text zu vermeiden sollten man diese Sonderzeichen umschreiben. Z.B. 'Drachenhoehle'

Weitere Infos bzgl. Umlauten und Kodierungen gibt es im Geoclub

Spracheinstellung beim URWIGO builder


Als Sprachen für den URWIGO Builder werden Englisch, Deutsch und Tschechisch angeboten. Ein kurzer Versuch die Sprache auf Deutsch umzustellen zeigte aber, dass noch der ein oder andere Übersetzungsfehler vorhanden ist, weswegen ich sowohl bei meinen Cartridges als auch bei den Tutorien mit der englischen Einstellung arbeite.

Bilder für das Cartrigde vorbereiten


Bei der Vorbereitung der verwendeten Bildern empfehle ich eine Breite von 230 Pixel. Dieser Wert ist den Garmin Oregon Geräten geschuldet, die eine Displayauflösung von 240 x 400 Pixel aufweisen (wobei nicht die gesamt Breite genutzt wird) und damit eine untere Grenze bildet. Meiner Erfahrung nach arbeiten die meisten Cacher z. Zt. mit diesen Geräten bzw. mit Pocket PCs, die eine deutlich größere Auflösung besitzen.
Eine Reduzierung auf 230 Pixel schont auch die Gesamtgröße des Cartridges

Donnerstag, 14. Juli 2011

User-Input in der Endlosschleife

Wie soll die Benutzereingabe behandelt werden, wenn die Eingabe falsch ist?

Cartridge beenden und neu starten lassen, ist auf jeden Fall keine Option.

Einfach wieder den Input aufrufen ist schon besser. Aber wie kommt der Benutzer aus dieser Endlosschleife wieder heraus? Wie kann er die Eingabe abbrechen, um z.B das Cartridge zu speichern, zu einer anderen Zone zu gehen, oder irgendwelche Dialoge mit Personen führen, die ihm weiterhelfen?

Die Lösung ist nicht ganz einfach.


In der hinter den Input geschalteten MessageBox, in der informiert wird, dass die Antwort falsch ist, kann man 2 Buttons definieren. Einen für "Nochmal" und einen für "Hauptmenü".
Im OnClicked Bereich der Message kann abgefragt werden welche Button (Button1, Button2 oder Cancel) gedrückt wurde, wobei der Button Cancel im Simulator nicht angezeigt wurde.

PocketQueries mit 1000 Caches laden

Achtung: Diese Anleitung gilt für GSAK 7.

Wer schon GSAK 8 benutzt, sollte die geocaching.com api benutzen. Wie das funktioniert, werde ich demnächst hier im Blog vorführen.

Seit 1. Mai diesen Jahres können ja bekanntlich PocketQueries bis zu 1000 Caches beinhalten. Der Hacken an der Sache ist nur, dass ab 500 Caches die PQ nicht mehr automatisch per Mail geschickt wird, sondern nur noch zum Download bereit steht.

Da gibst nun Abhilfe:
Mit dem PQDL(PocketQueryDownloader) lassen sich die PocketQueries auf den Rechner herunter laden, die man dann mit dem GSAK-Macro PQLoader in eure Datenbank integrieren lässt.

Doch der Reihe nach.
Laded PQDL herunter, entpackt es in einen Order eurer Wahl, öffnet eine Kommandozeile (Windows-Start, Ausführen, cmd) und wechselt in den Installationordner.
Mit folgendem Kommando könnt ihr den Download optimieren

pqdl -u -p -oc:\tmp\PQs -e -j



Die Parameter im einzelnen:

  • u - eurer Geocaching-Nick bzw Login-Name

  • p - euer Password für den Login

  • o - Wo wollt ihr die PQs abspeichern?

  • e - sorgt für eine kurze Wartezeit zwischen den Downloads

  • j - speichert ein Journal mit den bereits geladenen PQs (damit ihr die beim nächsten Mal nicht nochmal herunter ladet



! Das Regelwerk von Groundspeak kann so ausgelegt werden, dass die Benutzung von PQDL nicht zulässig ist. Also achtet auf den -e Paramerter, der die Pausen zwischen den Downloads einfügt. Außerdem ist die Benutzung auf eigene Gefahr.

Wenn ihr die PQs heruntergeladen habt, könnt ihr sie mit dem PQLoader-Macro in euer GSAK-Datenbank bringen.
Wichtig dabei sind folgende Parameter:



Ihr müsst "Delete PQ Files after load" (linker Kreis) wählen, sowie
danach rechts, "Default Db" anklicken und die Datenbank auswählen, nach der die PQs geladen werden sollen.
Danach solltet ihr auf "Get Mail Configuration" klicken, denn dort müsst ihr unter "Local Folder" noch den Ort angeben wo ihr die PQs gespeichert habt.


Achtung: Euere PQs werden nach erfolgreichem Import gelöscht. Hat den Vorteil, dass ihr beim nächsten Start von PQLoader nur noch die neuen importiert. Wenn ihr sie noch für was anderes braucht (ausdrucken und Klo tapezieren) so kopiert sie euch vorher.

Im oberen Kreis könnt ihr noch den Speicherort für euer MyFinds-Special-PQ angeben.

Für Fragen oder Optimierung stehe ich gerne zur Verfügung. Ich arbeite weiterhin ein einem Macro, dass den Aufruf von pqdl und den Start von PQLoader (im Idealfall mit Parameterübergabe) automatisiert vornimmt. Wenn sich zufällig jn mit RunPgm auskennt, der darf mir gerne helfen. Entgegen der GSAK-Doku wartet es nämlich trotz gesezten Parameter nicht bis PQDL fertig ist.
Sobald ich das Macro fertig hab, werd ich es euch hier zur Verfügung stellen.

Viel Spaß mit euren neuen RiesenPQs

Krolock