Aufbau der XML-Spieldateien
(Versionsstand 28.08.2022)

Wichtiger Hinweis vorneweg: Aktualität der Daten

Die hier behandelten Tags beziehen sich auf die Programmversion, die zum Zeitpunkt der Veröffentlichung dieses Dokuments aktuell war. Dieses Dokument wird nach Möglichkeit auf dem neusten Stand gehalten; dennoch kann es vorkommen, dass einige bereits umgesetzten Tags oder Attribute hier nicht aufgelistet werden.
Umgekehrt wird eine Programmversion erst dann für die Öffentlichkeit freigegeben, wenn sie stabil zu laufen scheint. Daher sind möglicherweise einige hier aufgeführten Tags in der aktuell im Netz erhältlichen Programmversion noch nicht umgesetzt. Orientieren Sie sich dazu bitte an der Version dieses Dokumentes, die dem Download-Paket beigelegt ist. Dieses passt stets zu der Version des Programmes (wie üblich ohne Garantie auf Vollständigkeit und Korrektheit).

Allgemeines zu den Bezeichnungen

Formatierungshinweise

Die Formulierung der Spieldateien muss ganz strikt case (und sonstiges) sensitive erfolgen. Fast alles wird komplett klein geschrieben; Spielkartenangaben (Farbe, Wert) beginnen mit einem Großbuchstaben. Die in den id-Attributen festgelegten Namen können selbstverständlich auch Großbuchstaben enthalten, jedoch wird der Name auch hier case sensitive behandelt.
Überflüssige Leerzeichen sind (meist) nicht erlaubt. Z. B. darf sich zwischen Attributnamen, Gleichheitszeichen und Anführungszeichen kein Leerzeichen befinden, bei der Angabe der Fenstergröße darf zwischen den Zahlen und dem x kein Leerzeichen stehen usw.
Die Inhalte der Attribute dürfen keine XML-Sonderzeichen, insb. Spitzklammern oder gar Tags enthalten. Der Grund liegt im sehr einfach gebauten handgestrickten XML-Parser.
Es gibt außerdem keine Abfangroutine für fehlerhafte XML-Dateien! Eine fehlerhafte Spieldatei kann im schlimmsten Fall dazu führen, dass sich das Programm aufhängt und gewaltsam beendet werden muss.

ID-Angaben

Für Regelvarianten und Felder sowie optional auch für Aktionen ist die Angabe eines id-Attributs erforderlich. Die ID eines Feldes muss nicht eindeutig sein; manchmal ist es einfacher, mehreren Feldern dieselbe ID zuzuweisen und sie dadurch gemeinsam ansprechen zu können. Verschiedene Regelvarianten sollten dagegen sinnvollerweise keine gemeinsame ID besitzen, ebenso wie verschiedene Aktionen keine gemeinsame ID erhalten sollten. Die Eindeutigkeit wird vom Programm zwar nicht überprüft, jedoch können die entsprechenden Elemente sonst nicht korrekt angesprochen werden.
Eine ID darf aus Groß- und Kleinbuchstaben sowie Ziffern bestehen, andere Zeichen (einschließlich Umlaute, Unterstriche und Leerzeichen) sind nicht erlaubt.
Viele Tags erlauben die Interaktion mit anderen Feldern, indem eine Liste von Feld-IDs angegeben wird. Dazu werden die IDs nacheinander durch Leerzeichen getrennt aufgeführt. Dies ist der Grund dafür, dass Leerzeichen innerhalb einer ID nicht erlaubt sind.

Angaben von Kartenfarben und -werten

An verschiedenen Stellen sind Angaben zu einer Karte möglich, z. B. wenn ein Feld nur von bestimmten Karten belegt werden darf. Die Karte wird folgendermaßen angegeben:

Spielprinzipien

Grundaufbau

Die Dateien werden vom Tag <spiel>...</spiel> umschlossen. Dieser enthält die beiden Attribute Das spiel-Tag kann/muss folgende Unter-Tags beinhalten:
Es wird dringend empfohlen, bei den Tags die oben angegebene Reihenfolge einzuhalten. Der regel-Tag fällt dabei aus der Reihe, weil er immer an den Stellen eingesetzt werden muss, an denen er gebraucht wird.

Erstellen von Regelvarianten (regelwerk, regel)

Um verschiedene Regeln eines Spieles zu ermöglichen, muss zuerst das Regelwerk definiert werden. Das Regelwerk enthält eine Anzahl von regel-Tags. Diese wiederum besitzen das Attribut id (eindeutiger Bezeichner der Regelvariante) sowie als Inhalt einen beschreibenden Text.
Bei Spielstart wird eine Liste der vorhandenen Regelvarianten erstellt; hier wird der beschreibende Text jeder Variante angezeigt. Der Spieler wählt dann eine der Varianten aus.
Die Regelvariante wird eingesetzt, indem die zur Variante gehörenden Anweisungen von einem regel-Tag mit der entspechenden id umschlossen werden. Ein ausführliches Beispiel folgt im Kapitel "Hinzufügen und Entfernen von Karten".
Es können maximal neun Regelvarianten definiert werden. Weitere Varianten werden ignoriert.

Hinzufügen und Entfernen von Karten (add, sub)

Soll nicht ein Standard-Kartenset verwendet werden, dann müssen die fehlenden bzw. überflüssigen Karten per Hand hinzugefügt bzw. entfernt werden. Das Tag karten muss bereits zuvor ein Kartenset festgelegt haben. Die von add hinzugefügten Karten hängen unter Umständen vom gewählten Kartenset ab.

Auch wenn das Hinzufügen einer Farbfamilie vom Kartenset abhängt, ist es dennoch möglich, in ein Set mit 32 Karten auch Werte einzufügen, die eigentlich nicht zum Set gehören. Wenn Sie z. B. 36 Karten mit den Werte 6 bis Ass benötigen, dann können Sie entweder aus einem 52er-Set die Werte 2, 3, 4 und 5 entfernen oder zu einem 32er-Set eine Gruppe mit dem Wert 6 hinzufügen.

Beispiel: Hinzufügen einer Familie in Herz, Entfernen einer Damen-Gruppe und einer Pik 10

<add typ="familie">Herz</add>
<sub typ="familie">D</sub>
<sub typ="einzel">Pik 10</sub>

Beispiel: Spinne in zwei Regelvarianten (vier Farben bzw. zwei Farben)
Die Hälfte der hinzugefügten Karten sollen die zweite Kartenrückseite zeigen.

<regelwerk>
  <regel id="4farben">Spielvariante mit vier verschiedenen Farben</regel>
  <regel id="2farben">Spielvariante mit zwei verschiedenen Farben</regel>
</regelwerk>
<karten>104</karten>
<regel id="2farben">
  <sub typ="familie">Karo</sub>
  <sub typ="familie">Karo</sub>
  <sub typ="familie">Kreuz</sub>
  <sub typ="familie">Kreuz</sub>
  <add typ="familie">Herz</add>
  <add typ="familie" rueckseite="2">Herz</add>
  <add typ="familie">Pik</add>
  <add typ="familie" rueckseite="2">Pik</add>
</regel>

Ein Kartenset kann maximal 208 Karten enthalten; sollen zu viele Karten hinzugefügt werden, so wird diese Anweisung ignoriert. Ebenso wird das Entfernen von Karten ignoriert, die sich nicht (mehr) im Kartenset befinden.

Verwendung von Jokern

Zusätzlich zu den allgemeinen Kartenwerten kann auch ein Joker in das Spiel eingefügt werden. Ein Joker kann später jeden beliebigen Kartenwert annehmen, hält sich aber ansonsten an die Legefolgen (so ist etwa in einer Abwärtsfolge die Reihenfolge K-D-Joker-10-9 möglich, die Reihenfolge K-D-Joker-4-3 dagegen nicht). Das Umlegen eines einzelnen Jokers ist damit immer möglich, wenn überhaupt umgelegt werden kann; der Joker passt ggf. seinen Wert an die neue Situation an. Das Umlegen einer Folge ist dagegen nur dann erlaubt, wenn sich ein passender Joker-Wert finden lässt, für den die neu entstehende Folge eine sinnvolle Reihenfolge bildet.

Jede Joker-Karte, die verwendet werden soll, muss einzeln mithilfe von add eingefügt werden. Das Attribut typ wird dabei ignoriert. Das Entfernen von Jokern mithilfe von sub ist nicht möglich.

Beispiel: Kartenspiel mit 2x52 Karten und 4 Jokern

<karten>52x2</karten>
<add typ="einzel">Joker</add>
<add typ="einzel">Joker</add>
<add typ="einzel" rueckseite="2">Joker</add>
<add typ="einzel" rueckseite="2">Joker</add>

Achtung: Joker können zur Zeit nicht mit Feldern eingesetzt werden, die ein gleichzeitiges Auf- und Abbauen erlauben! Alle anderen Legefolgen werden unterstützt.

Punktesystem (punktemax, punktestart)

Das Punktesystem ermöglicht die Erstellung von Statistiken zum Spiel und gibt dem Spieler eine Rückmeldung über seine Spielleistung. Am Ende jedes Spieles wird die erzielte Punktzahl an das Verwaltungsprogramm patfinder zurückgegeben (natürlich nur, wenn es von diesem gestartet wurde).

Außerdem ist das Punktesystem erforderlich, wenn das Spiel automatisch feststellen soll, dass es gewonnen wurde. Das Tag punktemax legt fest, wie viele Punkte im Spiel maximal erreicht werden können. Sobald der Spieler diese Punktezahl erreicht oder überschreitet, gibt das Spiel eine Sieg-Meldung zurück. Wird das Spiel beendet, ohne dass die erforderliche Punktzahl erzielt wurde, dann gibt das Spiel eine Verlust-Meldung zurück. Fehlt das Tag punktemax, dann wird kein Punktesystem verwendet, und das Spiel kann nicht erkennen, wann es gewonnen wurde.

Unter Umständen soll das Spiel nicht mit 0 Punkten starten. In diesem Fall kann die Startpunktzahl mit dem Tag punktestart festgelegt werden. Auch negative Startwerte sind möglich. Beachten Sie aber, dass bei Spielende immer mindestens die Punktzahl 0 zurückgegeben wird – während spielintern auch negative Punktzahlen erlaubt sind, arbeitet das Verwaltungsprogramm nie mit negativen Werten.

Auf welche Aktionen es wie viele Punkte gibt, wird durch den punkte-Tag in der Feld-Definition festgelegt; siehe dazu Tag zur Punktevergabe. Möglich ist z. B. eine Punktevergabe für das Spielen von Karten auf bestimmte Stapel (üblicherweise die Grundkartenstapel) oder auch für das Leeren eines Stapels durch Vergabe von Negativpunkten. Für jedes Feld sind mehrere Punkteangaben erlaubt. So kann z. B. auch ein Punkt für jede Karte und ein zusätzlicher Punkt für den komplett gefüllten Stapel vergeben werden.

Felder und Aktionen

Einen der wichtigsten Bereiche nehmen die Kartenfelder ein. Ein Kartenfeld ist ein Platz, an den ein Kartenstapel gelegt werden kann. Die Regeln, unter welchen Voraussetzungen welche Karten wohin gelegt werden können, werden detailiert in der Spieledatei festgelegt. Die häufigsten Legeregeln können direkt bei der Definition eines neuen Kartenfeldes angegeben werden. Komplexere Regeln werden durch automatisierte Spielzüge (Aktionen) festgelegt. Da beide Tags sehr umfangreiche Möglichkeiten bieten, werden sie in eigenen Abschnitten erläutert.

Hinzufügen von Vorlagen und Feldern (vorlage, feld)

Mit dem Tag vorlage kann eine Feldvorlage erstellt werden. Das Tag feld stellt ein Kartenfeld zur Verfügung. Beide Tags enthalten folgende Attribute:
<vorlage id="vorlagenname" typ="vorlage" kuerzel="k">
  <!-- weitere Angaben zur Vorlage -->
</feld>
<feld id="feldname" x="32" y="6" typ="vorlage" kuerzel="k">
  <!-- weitere Angaben zum Feld -->
</feld>
Bis auf kuerzel sind alle Attribute zwingend. Die Vorlage stock hat eine besondere Bedeutung. Der Stock enthält zu Beginn alle verfügbaren Karten, muss also zwingend festgelegt werden, und es ist sehr empfehlenswert, ihn als erstes Feld festzulegen. Wird der Stock im späteren Spiel nicht mehr benötigt (z. B. weil schon zu Beginn alle Karten verteilt werden), dann können für die Koordinaten Negativwerte angegeben werden; das Feld wird dann nicht im Fenster angezeigt.
Werden nach dem Festlegen eines Stocks weitere Karten zum Spiel hinzugefügt (siehe Hinzufügen und Entfernen von Karten), dann befinden sich diese nicht im Stock, sondern noch im "Speicher". Wird anschließend ein weiterer Stock festgelegt, dann wandern die neuen Karten in diesen Stock.
stock kann nicht als Vorlage einer neuen Vorlage dienen; genauer gesagt arbeitet ein Feld nur dann korrekt als Stock, wenn als Typ stock angegeben wurde, nicht aber, wenn eine Vorlage angegeben wurde, die auf stock aufbaut.

keller stellt ein Feld zur Verfügung, auf das eine einzelne beliebige Karte gelegt werden kann. Dies ist das Standardverhalten eines Kellerplatzes. Selbstverständlich kann das Verhalten überschrieben werden. Die anderen vordefinierten Vorlagen legen lediglich das vorgegebene Kürzel für die Hilfsanzeige fest. Sie sollten den für diese Patience üblichen Bezeichnungen entsprechen.

Achtung: Feld-Inhalte, die mehrmals auftreten können (z. B. das im nächsten Abschnitt beschriebene Tag ziel) und die in einer Vorlage verwendet werden, können nicht überschrieben, sondern lediglich erweitert werden.

Spezielle Tags für das Verhalten eines Stocks

"Stockspezifisches" Verhalten wie das Geben oder die Kartenaufnahme bei leerem Stapel ist nicht an den Feldtyp gebunden, sondern wird durch weitere Unter-Tags geregelt. Diese können also auch in anderen Feldern verwendet werden. Beispiel: Definition des Stocks im Spiel "Kleine Harfe"
<feld id="stock" x="24" y="12" typ="stock">
  <ziel>abwurf</ziel>
  <quelle>abwurf</quelle>
  <wiederholung>frei</wiederholung>
  <sicht>verdeckt</sicht>
</feld>
sicht wird im Abschnitt Weitere Tags zur Feldkontrolle beschrieben.

Tags zur Bestimmung der Legefolge

Alle folgenden Tags sind optional. Je nach Art des Feldes werden bestimmte Tags benötigt oder nicht. Soll auf ein Feld gar nicht gelegt werden können, dann ist keiner der Tags notwendig.

Weitere Tags zur Feldkontrolle

Tags zur grafischen Darstellung

Manche Tags werden dazu verwendet, bestimmte Darstellungsoptionen festzulegen, und haben keine weitere spielrelevante Funktion. Dazu gehören die farbliche Markierung gesperrter Stapel, Informationsanzeigen, Randanzeige leerer Felder usw. Alle folgenden Tags sind optional.

Tag zur Punktevergabe

Punkte werden pro Feld vergeben; die Gesamtpunktzahl errechnet sich aus der Summe der Punkte aller einzelnen Felder. Die Art der Berechnung wird über das Tag punkte angegeben, der innerhalb der Felddefinition auch mehrmals auftreten darf. Die für einen Sieg erforderliche Gesamtpunktzahl wird mit punktemax und punktestart global für das ganze Spiel festgelegt; siehe dazu den Abschnitt Punktesystem.
Das Tag punkte besitzt ein optionales Attribut bedingung, welches genauer festlegt, unter welchen Bedingungen eine Punktewertung stattfindet. Wird es nicht angegeben, dann wird die Anzahl der Karten auf dem Feld gezählt. Der Inhalt des Tags gibt dann an, wie viele Punkte pro Karte auf dem Feld gezählt werden sollen. Ist die Zahl negativ, dann erhält der Spieler Punkte für das Entfernen von Karten aus diesem Feld.
Mögliche Angaben für das Attribut bedingung sind:

Beispiele

Definition eines Grundkartenstapels und eines normalen Stapels in "Spinne"

1) Grundkartenstapel
Es können Stapel farbecht absteigend von König bis Ass abgelegt werden. Automatisches Legen ist möglich; gelegte Karten können nicht mehr aufgenommen werden. Für jede abgelegte Karte gibt es einen Punkt. (Die Notwendigkeit, genau 13 Karten abzulegen, wird weiter unten bei den automatisierten Spielzügen umgesetzt.)
<feld id="g" x="32" y="6" typ="grund">
  <max>13</max>
  <richtung>stapel</richtung>
  <folgestart>K</folgestart>
  <folgefarbe>gleich</folgefarbe>
  <folgewert>ab</folgewert>
  <folgeende>A</folgeende>
  <auto>ja</auto>
  <gesperrt>ja</gesperrt>
  <punkte>1</punkte>
</feld>
2) "normaler" Stapel
Die Höchstkartenzahl von 21 ist nötig, um nicht den Fensterrahmen zu sprengen. Karten werden abwärts in beliebiger Farbfolge gelegt, allerdings können nur farbechte Stapel verschoben werden. Leere Stapel können mit einer beliebigen Karte belegt werden.
Zu Beginn werden sechs verdeckte und eine offene Karte auf den Stapel gelegt, ohne Voraussetzung an die Art der gelegten Karten.
<feld id="r1" x="1" y="1" typ="stapel">
  <max>21</max>
  <richtung>unten</richtung>
  <folgestart>frei</folgestart>
  <folgefarbe>frei</folgefarbe>
  <folgewert>ab</folgewert>
  <folgeende>A</folgeende>
  <folgeschieb>farbe</folgeschieb>
  <lege typ="verdeckt" quelle="stock" anz="6">frei</lege>
  <lege typ="offen" quelle="stock">frei</lege>
</feld>
Folgendes Beispiel bildet einen Stapel aus 13 Herz- und 13 Pik-Karten und ordnet diese zufällig an.
<feld id="r1" x="1" y="1" typ="stapel">
  <max>26</max>
  <richtung>unten</richtung>
  <lege typ="offen" quelle="stock" anz="13">Herz</lege>
  <lege typ="offen" quelle="stock" anz="13">Pik</lege>
  <sortiere richtung="mischen"></sortiere>
</feld>
Während das Mischen im oberen Fall zu einem sehr guten Ergebnis führt, werden Sortiervorgänge mit der Angabe zufall in der Regel unbefriedigend sein, da hier kein "echtes" Mischen durchgeführt wird. Das "Hineinmischen" einer einzelnen Karte in einen Stapel funktioniert dagegen sehr gut, sofern diese Karte als letztes zum Stapel hinzugefügt wurde. In folgendem Beispiel werden vier Stapel gebildet, von denen jeder genau einen König enthält. Dazu wird erst ein temporärer Reservestapel gebildet, in dem zu Beginn die Könige liegen.
<spiel name="Jedem Koenig sein eigenes Reich" fenster="40x42">
  <programm>090818</programm>
  <version>090818</version>
  <karten>52</karten>
  <feld id="stock" x="-1" y="-1" typ="stock">
  </feld>
  <feld id="temporaer" x="-1" y="-1" typ="reserve">
    <lege typ="offen" quelle="stock" anz="4">K</lege>
  </feld>
  <feld id="Nordreich" x="8" y="2" typ="stapel">
    <max>13</max>
    <richtung>rechts</richtung>
    <lege typ="offen" quelle="stock" anz="12">frei</lege>
    <lege typ="offen" quelle="temporaer">frei</lege>
    <sortiere richtung="zufall">K</sortiere>
  </feld>
  <feld id="Ostreich" x="38" y="9" typ="stapel">
    <max>13</max>
    <richtung>unten</richtung>
    <lege typ="offen" quelle="stock" anz="12">frei</lege>
    <lege typ="offen" quelle="temporaer">frei</lege>
    <sortiere richtung="zufall">K</sortiere>
  </feld>
  <feld id="Suedreich" x="32" y="40" typ="stapel">
    <max>13</max>
    <richtung>links</richtung>
    <lege typ="offen" quelle="stock" anz="12">frei</lege>
    <lege typ="offen" quelle="temporaer">frei</lege>
    <sortiere richtung="zufall">K</sortiere>
  </feld>
  <feld id="Westreich" x="2" y="33" typ="stapel">
    <max>13</max>
    <richtung>oben</richtung>
    <lege typ="offen" quelle="stock" anz="12">frei</lege>
    <lege typ="offen" quelle="temporaer">frei</lege>
    <sortiere richtung="zufall">K</sortiere>
  </feld>
</spiel>

Automatisierte Spielzüge

<aktion typ="legen" id="Aktions-ID" ruecknahme="nein">
  <bedingung feld="ziel" tag="karte" karte="1" beziehung="groesser">B</bedingung>
  <vergleich feld1="quelle" feld2="ziel" typ="farbe">gleich</vergleich>
  <aenderung feld="ziel" tag="folgewert" ziel="id">ab</aenderung>
  <lege feld="quelle" ziel="id" startpos="-1" zielpos="zufall" anz="legezahl" richtung="rueckwaerts"
        typ="offen" animation="ja" umschichten="auf" opt="erlaubt">ziel</lege>
  <sound>legen</sound>
  <warte>300</warte>
  <meldung antwort="Ja\nNein" feld="stock">Willst du neu mischen?</meldung>
  <setze id="menu">AUTO</setze>
  <spielende>verlust</spielende>
  <erfolg>naechste</erfolg>
  <misserfolg>anfang</misserfolg>
</aktion>

Es gibt vier Möglichkeiten, automatisierte Spielzüge anzugeben: beginn, aktion, abschluss und ende.

Ob ein automatisierter Zug durchgeführt wird oder nicht, wird über Bedingungen und Feld-Vergleiche überprüft. Anschließend stehen verschiedene Möglichkeiten wie das Legen von Karten und die Änderung von Feldeigenschaften zur Verfügung. In der Regel wird immer nur der erste passende Zug durchgeführt; dies kann jedoch speziell gesteuert werden.
Folgende Möglichkeiten stehen zur Verfügung:

Bedingungen

Bei Bedingungen handelt es sich in der Regel um bestimmte Feldeigenschaften. Das Attribut feld bestimmt das zu testende Feld. Dabei sind auch die Angaben quelle und ziel erlaubt. Bei einer Lege-Aktion entspricht quelle dem Feld der gelegten Karte und ziel dem Feld, auf das gelegt wurde. Bei anderen Aktionen ist eine Quellenangabe nicht erlaubt; ziel entspricht dem angeklickten Feld.

tag bestimmt die Feldeigenschaft, der überprueft werden soll. Stimmt diese Eigenschaft mit dem Inhalt des Tags überein, dann gilt die Bedingung als erfüllt. Um Feldeigenschaften daraufhin zu überprüfen, ob sie größer oder kleiner sind als ein vorgegebener Wert, kann das optionale Attribut beziehung mit einem der Werte kleiner, kleinergleich, groesser, groessergleich oder ungleich belegt werden.

Folgende Feldeigenschaften können überprüft werden:

Vergleiche

Zwei Karten können anhand ihres Kartenwertes oder ihrer Farbe verglichen werden. Die zwingenden Attribute feld1 und feld2 geben die Felder an, deren Karten verglichen werden sollen. Die optionalen Attribute karte1 und karte2 bestimmen genauer, welche der Karten verglichen werden sollen. Werden sie ausgelassen, wird die oberste Karte des Stapel herangezogen. Ein positiver Wert gibt die direkte Position an, gerechnet von der untersten Karte des Stapels. 1 bedeutet also, dass die erste Karte geprüft wird. Negative Werte geben die Zählung von der obersten Karte gerechnet an. Dabei bedeutet -1, dass die oberste Karte geprüft wird (genauso wie wenn das Attribut ausgelassen wird.) Ist der Stapel kleiner als der angegebene Wert, schlägt der Vergleich fehl.
Normalerweise wird auf Gleichheit überprüft, jedoch kann mit dem optionalen Attribut beziehung auch getestet werden, ob der gesuchte Wert kleiner, kleinergleich, groesser, groessergleich oder ungleich dem im Tag-Inhalt angegebenen Wert ist.

Das zwingende Attribut typ bestimmt die Vergleichsform:

Änderungen

Eine bestimmte Feldeigenschaft wird geändert. Das zwingende Attribut feld gibt eine durch Leerzeichen getrennte Liste an Feld-IDs an, die geändert werden sollen. Die zu ändernde Eigenschaft wird im zwingenden Attribut tag angegeben, der neue Wert im Inhalt des Tags.

Zahlenwerte (z. B. bei wiederholung oder var) können auch mit einem + oder - beginnen. Dann wird der neue Wert nicht auf die angegebene Zahl gesetzt, sondern die Zahl stattdessen zum bisherigen Wert addiert bzw. von ihm subtrahiert. Auf diese Weise kann beispielsweise die Anzahl der noch verfügbaren Wiederholungen um 1 reduziert werden.

Enthält das optionale Attribut opt den Wert tausch, dann gibt der Tag-Inhalt nicht die zu ändernde Feldeigenschaft an, sondern eine weitere ID-Liste. Der Eigenschaftswert beider Felder wird dann vertauscht. Die Vertauschung ist für einige Eigenschaften nicht einsetzbar (z. B. sperre).

Als betroffenes Feld sind wieder die Angaben quelle und ziel möglich. In diesem Fall ist noch ein weiteres Attribut ziel erlaubt. Wird hier id angegeben, dann ist nicht nur das Quell- bzw. Zielfeld von der Änderung betroffen, sondern auch jedes Feld, das dieselbe ID besitzt.

Mit aenderung können weitgehend dieselben Eigenschaften geändert werden, die man auch als Bedingung abfragen kann. Ein paar Eigenschaften können jedoch nicht geändert werden: id, kartenzahl, legezahl und karte
Statt einer Eigenschaft kann auch sortieren angegeben werden. Der Tag-Inhalt muss dann einen der beiden Werte mischen oder umdrehen beinhalten. Im ersten Fall wird der angegebene Stapel gemischt, im zweiten Fall die Kartenfolge umgedreht (rückwärts gelegt).

Für die Änderung eines Kartenwertes oder einer Kartenfarbe (z. B. startfarbe oder folgeende) besteht auch die Möglichkeit, den neuen Wert vom Wert der Quell- oder Zielkarte abhängig zu machen. Dazu dienen die Angaben zielwert, zielfarbe, quellwert und quellfarbe; Kombinationen sind nicht möglich. Die Zielkarte ist beim legen die Karte, auf die verschoben wurde, und ansonsten die angeklickte Karte. Die Quellkarte ist beim legen die verschobene Karte.

Karten legen

Mit lege werden eine oder mehrere Karten von einem Stapel auf einen anderen gelegt. Die Anweisung besitzt eine Reihe von Attributen, von denen fast alle optional sind.

Wie viele und welche Karten genau gelegt werden, hängt vom Zusammenspiel von anz, startpos und eventuell auch zielpos. Wird weder anz noch startpos angegeben, dann wird die oberste Karte des Stapels gelegt. Bei Verwendung von anz (ohne startpos) werden von der obersten Karte aus gerechnet so viele Karten gelegt wie angegeben. Bei Verwendung von startpos (ohne anz) werden alle Karten ab der angegebenen Position gelegt.

Bei Verwendung beider Attribute hat startpos Vorrang vor anz: Es werden von der angegebenen Position aus gerechnet höchstens die angegebene Zahl an Karten gelegt – besitzt der Stapel nicht ausreichend Karten, so werden weniger gelegt. Noch etwas komplizierter ist die Kombination von anz, startpos und zielpos in der Kombination mit opt="tausch". anz und startpos legen hier die Zahl der Karten fest, die vom ersten Stapel auf den zweiten gelegt werden. Genauso viele Karten werden dann auch vom zweiten Stapel an den ersten zurückgegeben, sofern dort genügend Karten zur Verfügung stehen. Ansonsten ist die zurückgegebene Menge kleiner als die erhaltene.

Beziehungen zwischen Feldern

In der Felddefinition können Beziehungen zwischen den einzelnen Feldern hergestellt und anschließend in den Aktionen verwendet werden. Eine Kette von Beziehungen könnte beispielsweise folgendermaßen aussehen:

<feld id="erstesFeld" x="2" y="2" typ="stapel">
</feld>
<feld id="zweitesFeld" x="6" y="2" typ="stapel">
  <beziehung id="vorher">erstesFeld</beziehung>
</feld>
<feld id="drittesFeld" x="10" y="2" typ="stapel">
  <beziehung id="vorher">zweitesFeld</beziehung>
</feld>

In einer Aktion kann nun statt einer Feld-ID auch ein Verknüpfung zu einem anderen Feld angegeben werden. Dazu folgt auf den Feldnamen ein Doppelkreuz # und die Bezeichnung der Verknüpfung. Sinnvoll ist dies besonders in Zusammenhang mit den Angaben quelle und ziel, da in allen anderen Fällen der gewüschte Stapel auch direkt angegeben werden könnte.

<aktion typ="klick">
  <lege feld="ziel">ziel#vorher</lege>
</aktion>

legt bei einem Klick eine Karte auf den Stapel, der mit der Verknüpfung vorher angegeben wurde. Ein Klick auf zweitesFeld würde also auf erstesFeld legen, ein Klick auf drittesFeld würde auf zweitesFeld legen. Es ist auch möglich, auf einen Link des verlinkten Feldes zuzugreifen:

<aktion typ="klick">
  <lege feld="ziel">ziel#vorher#vorher</lege>
</aktion>

Ein Klick auf drittesFeld legt damit auf den Vorgänger des Vorgängers, also auf erstesFeld.

Beziehungen müssen innerhalb eines Feldes eindeutig sein, d. h. ein Feld kann nicht zwei verschiedene Beziehungen gleichen Namens besitzen. Die angegebene Feld-ID des Bezugsfeldes muss dagegen nicht eindeutig sein. Auf obiges Beispiel bezogen: Es kann für jedes Feld nur eine einzige Beziehung vorher definiert werden; diese Feld-ID kann jedoch zu mehreren Feldern gehören. Wenn Sie für ein Feld mehrere „Vorgänger“ (mit unterschiedlicher Feld-ID) benötigen, müssen Sie mit mehreren verschiedennamigen Beziehungen arbeiten.

Beachten Sie außerdem, dass ein zu exzessiver Gebrauch von Verknüpfungen die Performance des Programms negativ beeinträchtigen kann.

Setzen globaler Parameter

setze erlaubt es, bestimmte globale Einstellungen vorzunehmen, die nicht an ein bestimmtes Feld gebunden sind. Das zwingende Attribut id gibt an, welche Einstellung betroffen ist; der Tag-Inhalt enthält den neu zu setzenden Wert.

Spezielle Anweisungen

warte hält die Spielausführung an. Der Tag-Inhalt gibt die Anzahl der Millisekunden an, welche das Spiel pausiert wird. Der Befehl kann beispielsweise bei einer Abfolge mehrerer Anweisungen verwendet werden, wenn der Spieler diese mitverfolgen können soll.

meldung gibt eine Meldung aus und wartet so lange, bis sie vom Spieler bestätigt wurde. Der Tag-Inhalt enthält die auszugebende Meldung; dabei können mehrere Zeilen durch den Zeilenumbruch \n getrennt werden. Mit dem optionalen Attribut antwort kann die Beschriftung der Antwortbuttons festgelegt werden; die einzelnen Buttons werden wiederum durch \n getrennt. Wird es ausgelassen, dann wird ein einzelnes Button mit dem Inhalt OK verwendet. Das ebenfalls optionale Attribut feld enthält die ID eines Feldes, in dessen Variable var die Nummer des betätigten Buttons gespeichert wird, beginnend mit 1 für den Button ganz links. Meldeboxen können bis zu fünf Meldungszeilen und bis zu drei Antwortbuttons enthalten.

sound ermöglicht die Ausgabe ein oder mehrerer Soundeffekte sowie die Unterdrückung des Soundeffekts. Üblicherweise wird am Ende jeder Aktion, die das lege-Tag beinhaltet, der Sound zum Kartenlegen abgespielt. Dieses Verhalten kann unerwüscht sein, wenn z. B. mehrere Karten nacheinander mit Soundeffekt gelegt werden sollen oder das Aufnehmen des Stocks simuliert werden soll. Folgende Angaben sind als Tag-Inhalt möglich:

spielende beendet das Spiel. Der Tag-Inhalt enthält einen der Werte sieg oder verlust und gibt an, ob das Spiel vom Verwaltungsprogramm als gewonnenes oder verlorenes Spiel gewertet werden soll. Das Tag kann auch bei der Abarbeitung der End-Aktionen verwendet werden; dadurch ist es möglich, ein abgebrochenes Spiel unter bestimmten Bedingungen als Sieg zu werten oder trotz erreichter Maximalpunktzahl ein verlorenes Spiel zu erhalten.

Fortsetzung

Das Tag erfolg kann einen der Werte anfang, naechste, wiederholung, ende oder die ID einer anderen Aktion enthalten. Damit wird festgelegt, wie nach der erfolgreichen Durchführung einer Aktion weiter verfahren wird. Das Programm kann angewiesen werden, in diesem Fall den Durchlauf wieder von vorn zu starten (anfang), dieselbe Aktion ein weiteres Mal zu prüfen (wiederholung) oder mit der nächsten Aktion in der Liste fortzufahren (naechste). Wird keiner dieser Werte und auch keine gültige Aktions-ID angegeben, dann wird der Durchlauf nach erfolgreicher Durchführung beendet (entspricht ende).

Das Tag misserfolg arbeitet ähnlich, nur dass hier angegeben wird, wie der Durchlauf fortgesetzt werden soll, wenn die Ausführung nicht erfolgreich war. Es können fast dieselben Werte wie unter erfolg angegeben werden. Nur die Angabe wiederholung ist nicht möglich, da dies unweigerlich zu einer Endlosschleife führen würde. Wird nichts oder eine ungültige ID angegeben, dann wird bei Misserfolg mit der nächsten Aktion fortgefahren (entspricht naechste).

Beispiele

Die Aktionen werden vor der regulären Verschiebung durchgeführt, und zwar in der angegebenen Reihenfolge. Das bedeutet: Kann auf einem Feld auf- oder abgebaut werden, und gibt es gleichzeitig eine Regelung für eine (oder mehrere) Aktionen, dann wird die erste passende Aktion durchgeführt und die Verschiebung übergangen.

Beispiel 1: Die vordersten Karten der beiden Stapel können entfernt werden, wenn sie denselben Wert besitzen.

<feld id="abwurf" x="-1" y="-1" typ="abwurf">
</feld>
<feld id="feld" x="2" y="2" typ="stapel">
  <richtung>unten</richtung>
  <lege typ="offen" quelle="stock" anz="13">frei</lege>
</feld>
<feld id="feld2" x="8" y="2" typ="stapel">
  <richtung>unten</richtung>
  <lege typ="offen" quelle="stock" anz="13">frei</lege>
</feld>
<aktion typ="legen">
  <vergleich feld1="quelle" feld2="ziel" typ="abstand">0</vergleich>
  <lege feld="quelle">abwurf1</lege>
  <lege feld="ziel">abwurf</lege>
</aktion>

Beispiel 2: Bei manchen Spielen (z. B. die Spinne) können nur komplette Reihen von 13 Karten auf den Grundkartenstapel gelegt werden. Dazu wird eine Legeaktion auf die Grundkartenstapel abgefangen, sofern weniger als 13 Karten verschoben werden sollen. Die Aktion hat keine Auswirkung außer diejenige, dass kein normales Legen stattfindet.

<aktion typ="legen">
  <bedingung feld="ziel" tag="id">g</bedingung>
  <bedingung feld="ziel" tag="legezahl" beziehung="kleiner">13</bedingung>
</aktion>

Beispiel 3: Das Tag sperre erlaubt das Sperren eines Stapels bspw. dann, wenn mindestens eines der angegebenen Felder belegt ist. Soll die Sperre nur wirksam sein, wenn alle Felder belegt sind, dann kann dazu auf eine Aktion zurückgegriffen werden. Eine Karte im Keller des folgenden Beispiels ist erst verfügbar, wenn einer der beiden Sperrstapel leer ist. Wieder wird dazu lediglich das normale Legen unterbunden.

<aktion typ="legen">
  <bedingung feld="quelle" tag="id">keller</bedingung>
  <bedingung feld="sperrfeld1" tag="kartenzahl" beziehung="groesser">0</bedingung>
  <bedingung feld="sperrfeld2" tag="kartenzahl" beziehung="groesser">0</bedingung>
</aktion>

Beispiel 4: In einem Kartenset mit 32 Karten soll das Legen einer 7 auf eine gleichfarbige Ass ermöglicht werden.

<aktion typ="legen">
  <bedingung feld="quelle" tag="karte">7</bedingung>
  <bedingung feld="ziel" tag="karte">A</bedingung>
  <vergleich feld1="quelle" feld2="ziel" typ="farbe">gleich</vergleich>
  <lege feld="quelle">ziel</lege>    
</aktion>

Beispiel 5: Nach dem Legen durch den Spieler werden alle Stapel mit der ID hilf so umgeschichtet, dass möglichst kleine oder sogar leere Stapel entstehen; die Karten werden also auf wenige Stapel konzentriert. Die Aktion wird so lange wiederholt, wie sie erfolgreich durchgeführt werden kann.

<abschluss typ="frei">
  <bedingung feld="hilf" tag="legen" umschichten="auf">hilf</bedingung>
  <lege feld="hilf" umschichten="auf" opt="erlaubt">hilf</lege>
  <erfolg>wiederholung</erfolg>
</aktion>

Beispiel 6: Verdeckt liegende Karten stehen für den Spieler nicht zur Verfügung. Soll es dem Spieler möglich sein, verdeckt liegende Karten mit einem Mausklick aufzudecken, so kann das mit einer Aktion umgesetzt werden.

<aktion typ="klick">
  <bedingung feld="ziel" tag="status">verdeckt</bedingung>
  <aenderung feld="ziel" tag="status">offen</aenderung>
</aktion>