Wherigo - spezifischer LUA-Befehlskatalog

Aus Das Wherigo-Handbuch
Wechseln zu: Navigation, Suche

Auf dieser Seite sollen Funktionen erklärt werden, die Wherigo-spezifisch sind, sich also i.d.R. auf die Wherigo-Bibliothek beziehen.

Inhaltsverzeichnis

Tabellarischer Befehlskatalog

eine tabellarische Auflistung des Befehlskatalogs wurde auf die folgende Seite ausgelagert.

tabellarischer Befehlskatalog

Einführung

Um die Inhalte dieser Seite nachvollziehen zu können, sollte man wenigstens ein kleines bisschen wissen, was die Programmiersprache Lua ist und wie sie funktioniert.

Eine m.E. gute Seite für Lua - für Einsteiger - die auch für Wherigos gut geeignet ist, ist unter [1] zu finden. Grundsätzlich funktionieren alle dort beschriebenen Basics - d.h. Sprachkonstrukte zumindest aus den Paketen math, string und tables. Es gibt allerdings manchmal playerabhängige Dinge, die man vermeiden sollte. Es ist nicht bekannt, was aus dem Paket os zuverlässig funktioniert - Datum und Uhrzeit - ja - Dateihandling - nein.

Alle Funktionen, die mit Wherigo anfangen, d.h. aus dem Paket Wherigo stammen, sind selbstverständlich Wherigo-spezifisch und nicht in der obigen Seite beschrieben. Unter der Seite [2] gibt es eine Übersicht über die bekannten Funktionen - die wichtigsten Inhalte davon werden unten beschrieben.

Für alle, die sich über diese Seite an die WIG-Programmierung herantasten, noch eine Bemerkung zum Verständnis der hier aufgeführen Beispiele:

Schreibt der Autor hier z.B. CartridgeObject.AllZObjects, dann benutzt er CartridgeObject für die Bezeichnug der Cartrigde. In eigenen Projekten heisst die natürlich anders. Für euer eigenes Projekt in URWIGO vergebt ihr diesen Namen auf der Cartridge-Seite unter identifier. Das gilt auch für die Namen anderer Objekte.

Erläuterung verschiedener Objekte der Wherigo-Bibliothek

Hier werden die wichtigsten Objekte der Wherigo-Bibliothek und deren Verwendung erläutert. In einigen Code-Beispielen - vor allem den fortgeschrittenen Beispielen mit Lua findet man diese Dinge wieder. Ansonsten sieht man vieles wieder, wenn man sich den kompletten LUA-Code einer Cartridge anschaut - auch den generierten Code von z.B. Urwigo.

Begrifflichkeiten: Die Seite [3] redet von der Wherigo class - also Klasse (aus der objektorientierten Programmierung) - benutzt wird diese in LUA wiederum mit dem Schlüsselwort require - teilweise werden unterschiedliche Begrifflichkeiten verwendet - z.b. mir persönlich gefällt Package besser, da die sog. Wherigo class aus Unterklassen, Methoden, Konstanten besteht. Weiterhin wird von Properties geredet - das sind Attribute der Klasse, auf die man zugreifen kann und die man evtl. auch verändern kann. Weiterhin gibt es auch Methoden - dies sind Funktionen die der Klasse zugeordnet sind. Events sind Methoden, die bei bestimmten Ereignissen aufgerufen werden (z.B. beim Betreten einer Zone). Alle Inhalte der Wherigo-Klasse sind über die Punkt-Notation zugänglich über das entsprechende Objekt. Für eine Cartridge wird z.B. ein Objekt angelegt, das meine_cartridge heißt. Dann ist mit meine_cartridge.Player alles zugänglich, was die Unterklasse Player enthält - meine_cartridge.Player.OriginalPoint beinhaltet z.B. immer die aktuelle GPS-Position. Bei Urwigo kann man statt meine_cartridge.Player auch direkt über Player zugreifen, da Urwigo den entsprechenden Code zur Vereinfachung generiert.

Die wichtigsten Klassen (wird hier für die Unterklassen (classes) verwendet) werden hier erläutert soweit sie bekannt sind und schon ausprobiert wurden.

Wherigo.Player

Diese Klasse ist so wichtig, sie wird als Property - d.h. Attribut der Wherigo-Klasse geführt.

Das bist du - eine ZCharacter Instanz - darin steht die Position die dein Gerät anzeigt, dein Name und sonst noch ein paar Dinge

Man kann z.B. die GPS-Genauigkeit auswerten, auswerten in welchen Zone(n !) man sich befindet, welche Items man im Inventar hat...

Wherigo.ZCartridge

Klasse für eine Wherigo-Cartridge. Es darf nur eine einzige Instanz geben - ein LUA-Code gibt immer das aktuelle Cartridge-Objekt am Ende mit return zurück - das ist einfach so - darüber muss man nicht diskutieren.

Das Cartridge Objekt enthält insgesamt einfach alles, was eine Cartridge ausmacht. Für die LUA-Programmierung ist nur wenig interessant - das wenige aber umso mehr, wenn man fortgeschrittene Dinge in der Cartridge mit LUA machen möchte. Die wichtigsten Attribute der Cartridge-Klasse sind auch von Urwigo aus zugänglich.

Attribut ZVariables

   CartridgeObject.ZVariables
     Alle in dieser table eingetragene Objekte werden gespeichert und bei einem Neustart - 
     wenn eine gespeicherte Cartridge fortgesetzt werden soll wieder geladen - d.h. wenn man in LUA eigene wichtige Variablen
     hat, dann sollten diese auch in ZVariables eingetragen werden - kann man bequem über Urwigo machen 
     (ist in diesem Wiki beschrieben)
     Ansonsten nützt einem diese Table nicht viel - ausser dass natürlich auch die Initialwerte der 
     Variablenwerte in ZVariables drin stehen.
     Ich kenne bisher keinen Anwendungsfall, der dieses benutzt

Attribut AllZObjects

   CartridgeObject.AllZObjects
     das ist eine hochinteressante table, die numerisch indiziert wird (startet von [1]...#CartridgeObject.AllZObjects)
     Alle Objekte der Cartridge (z.B. Zonen, Media-Dateien, Inputs, Characters, Tasks, Items) werden in diese Table eingetragen.
     Höchstinteressant wenn man per Namen ein Objekt bestimmen möchte - z.B. die Mediendatei mit Namen Wuerfel6. Das lässt sich dann
     prima optimieren. 
     :
     Das was nicht so dolle ist: nicht jeder Player bezeichnet seine Medienobjekte gleich - siehe z.B. Koffer-Cartridge - 
     manche Player liefern für ein Medien-Objekt statt ZMedia einfach ZObject - das sollte man beruecksichtigen, 
     wenn man ganz exakt arbeiten möchte..
     :
     ....den Typ des Objekts bekommt man als String raus, wenn man tostring(object) benutzt - man erhält dann sowas wie
     "is a ZMedia instance"
     :
     Höchst mächtige Anwendungsfälle für diese Table (es existieren hier für viele Dinge Beispiele):
     * Zonen automatisch vergrößern/verkleinern
     * Debug-Hilfsmittel
     * Umlaut-Ersetzung um Urwigo deutsche Umlautfähigkeit zu verpassen
     * Item in Items verpacken - um sich eine separate Verwaltung zu sparen
     * Media-Objekte anhand des Namens identifizieren

Events

Man kann auf Cartridge Events reagieren, es sind Events definiert für

  CartridgeObject:OnSync()  -- Speichern einer Cartridge: 
  CartridgeObject:OnRestore() --Laden einer Cartridge: 
  CartridgeObject:OnStart() --Starten einer Cartridge:
  CartridgeObject:OnEnd() --Starten einer Cartridge:

Will man solch einen Event selbst auswerten, dann schreibt folgenden Code (Bei URWIGO in "User functions"):

 function CartridgeObject:OnStart()
      -- Hiersteht dann der Code, der bei diesem Event ausgeführt werden soll
 end


Achtung - wenn man den LUA-Code benutzt, sollte man wissen, dass man die Events, die Urwigo anbietet damit überschreibt. Die Urwigo-Events - z.B. nach Cartridge Start generieren genau diesen Code (objCartridge:onStart())

Wherigo.Distance

Klasse für eine Entfernung, diese wird explizit für einige Funktionen benutzt - eine Verwendung eines reellen Zahl ist nicht zulässig.

  Instantiierung:
  dist = Wherigo.Distance(5,'m')    --Eine Instanz der Klasse Distanz mit 5 Meter initialisiert wird angelegt, 'ft' geht auch
  Zugriff auf den Wert einer Distanz-Klasse (Achtung, nur dieses Konstrukt benutzen, 
  da alle anderen Methoden nicht auf allen Playern gehen!)
  entfernung = dist:GetValue 'm'   -- für die Entfernung in Metern, 'ft' für Fuß geht auch

Wherigo.ZonePoint

sehr einfache Klasse, die eine geografische Position bildet

  Konstruktor
    Wherigo.ZonePoint(latitude, longitude, altitude)
      latitude:	Geografische Breite - also z.B. 47.345 (in Grad !)
      longitude: Geografische Länge - also z.B. 9.217 (in Grad !)
      altitude:	Höhe in Meter - kann in den meisten Fällen auch auf 0 gelassen werden
      latitude, longitude und altitude sind als Attribute auch zugreifbar
      ACHTUNG: altitude ist ein Objekt der Klasse Wherigo.Distance ! - 
      aber ausser dem Autor dieser Zeilen verwendet das wohl selten jemand - und wenn dann weiß er was er zu tun hat.

Wherigo-Funktionen und deren Verwendung

In der Klasse bzw. Package Wherigo sind verschiedenste Methoden (oder Funktionen) aufgeführt, die für die Erstellung eines Wherigo's wichtig sind.

Insbesonders Play-Anywhere-Wherigo's benötigen zwei dieser Funktionen.

VectorToPoint

VectorToPoint nimmt als Input zwei Parameter der Klasse Wherigo.ZonePoint.

Die Funktion berechnet Entfernung und Winkel vom ersten Punkt zum zweiten Punkt und gibt die Werte zurück. Für die meisten dürfte es ungewöhnlich sein, daß eine Funktion zwei Werte zurückgeben kann - LUA kann das.

  Verwendung
  z.B. innerhalb einer LUA-Funktion
  local p1 = ZonePoint(47.5,9.5,0)
  local p2 = ZonePoint(47.6,9.5,0)
  local d,b = VectorToPoint(p1, p2) --entferung und winkel von p1 nach p2
  print (b)   --müsste jetzt 0 Grad sein, da p2 nördlich von p1 liegt
  local entf = d:GetValue 'm'  --Achtung, korrekt auf Distance zugreifen!
  print (entf) --naja - wieviel sind 0,1 Grad jetzt - 
               --Erdumfang = 360Grad, ca. 11.6 km ? 

ACHTUNG, die Funktion Wherigo.VectorToPoint ist auf dem I-Phone - zumindest bis zur Wherigo-Player-Version V3.17 fehlerhaft implementiert und liefert einen um 180 Grad versetzten Winkel. Abhilfe schafft eine generell komplett in LUA geschriebene Funktion, siehe Thread im GeoClub.

Hier die Funktion: function calc_dist_bearing(pt1,pt2)

   local EARTH_RAD = 6378137.0 
   local lat1 = math.rad( pt1.latitude )
   local lat2 = math.rad( pt2.latitude )
   local lon1 = math.rad( pt1.longitude )
   local lon2 = math.rad( pt2.longitude )
   local p1 = math.cos(lat1) * math.cos(lon1) * math.cos(lat2) * math.cos(lon2)
   local p2 = math.cos(lat1) * math.sin(lon1) * math.cos(lat2) * math.sin(lon2)
   local p3 = math.sin(lat1) * math.sin(lat2)
   local distance = math.acos(p1+p2+p3)*EARTH_RAD --hier kann man bei Bedarf noch in Wherigo.Distance umwandeln 
   
   local dLon = math.rad( pt2.longitude-pt1.longitude)
   local y = math.sin(dLon) * math.cos(lat2)
   local x = math.cos(lat1)* math.sin(lat2) -
       math.sin(lat1) * math.cos(lat2) * math.cos(dLon)
   local brg = math.deg(math.atan2(y, x))
   if brg < 0 then brg = brg + 360 end
   return distance,brg

end


TranslatePoint

TranslatePoint hat als ersten Parameter eine Koordinate vom Typ ZonePoint, dann eine Entfernung vom Typ Distance und dann einen Winkel in Grad

TranslatePoint gibt eine Koordinate zurück - hier wird einfach eine Koordinatenprojektion durchgeführt - wer auf dem Wherigo-fähigen Gerät keine vernünftige Software für eine Koordinatenprojektion hat, kann sich ohne Probleme hierfür einen kleinen Wherigo basteln - bzw. den müssts eigentlich schon geben..

  Verwendung
  ..z.B. innerhalb einer LUA-Funktion
  local p
  local dist = Wherigo.Distance(100,'m')
  p = Wherigo.TranslatePoint(Player.OriginalPoint,dist,90)
  --p enthält die Koordinate, projeziert von der aktuellen Position, 
  --100 Meter nach Osten.

Dinge, die ihr vermeiden müsst, wenn eure Cartridge auf möglichst allen Playern laufen soll

Wir haben eine Seite angelegt, die solche Probleme sammelt. Du findest Sie unter: Dinge, die vermieden werden müssen, da sie zu Fehlfunktionen bzw. zu Abstürzen führen. Wenn Du in LUA programmierst, solltest du sicherheitshalber mal einen Blick auf diese Seite werfen, nicht dass du einen Programmierstil verwendest, der nicht auf allen Geräten funktioniert.

Meine Werkzeuge
Namensräume
Varianten
Aktionen
Navigation
Werkzeuge