Dieses Dokument erklärt die XML-Schnittstelle der Software-Challenge für das aktuelle Spiel.

PDF-Version dieses Dokumentes

Wir freuen uns über sämtliche Verbesserungsvorschläge.
Die Dokumentation kann direkt auf GitHub editiert werden, einzige Voraussetzung ist eine kostenlose Registrierung bei GitHub. Ist man angemeldet, kann man ein Dokument auswählen (ein guter Startpunkt ist die Datei index.md welche Verweise auf alle Sektionen der Dokumentation enthält) und dann auf den Stift oben rechts klicken. Damit wird von GitHub automatisch ein Fork und ein Pull Request erstellt.
Alternativ auch gern eine E-Mail an info@software-challenge.de oder eine Nachricht im Discord.

Spiel betreten🔖

<protocol>

Dieses Tag eröffnet die Kommunikation mit dem Server. Dann gibt es drei Möglichkeiten, einer Spielpartie beizutreten.

Beliebige Partie🔖

Betritt ein beliebige offene Spielpartie:

<join />

Sollte kein Spiel offen sein, wird automatisch ein neues erstellt. Abhängig von der Einstellung paused in server.properties wird das Spiel pausiert gestartet oder nicht.

Bestimmte Partie🔖

Einer bestimmten, bereits offenen aber noch nicht gestarteten Partie kann durch Angabe der ROOM_ID beigetreten werden:

<joinRoom roomId="ROOM_ID" />

Mit Reservierung🔖

Unter Angabe eines Reservierungscodes kann man einen reservierten Platz in einer geplanten Partie einnehmen:

<joinPrepared reservationCode="RESERVATION" />

Antwort🔖

Der Server antwortet auf einen erfolgreichen Spielbeitritt mit:

<joined roomId="ROOM_ID" />

ROOM_ID
Identifikationscode der Spielpartie

Spielverlauf🔖

Start🔖

Der Server eröffnet das Spiel mit einer Begrüßung und dem initialen Spielstatus sobald beide Spieler verbunden sind.

ROOM_ID
Identifikationscode der Spielpartie

COLOR
Spielerfarbe

STATUS
Spielstatus der Partie

<room roomId="ROOM_ID">
  <data class="welcomeMessage" color="COLOR"></data>
</room>
<room roomId="ROOM_ID">
  <data class="memento">
    STATUS
  </data>
</room>

Ablauf🔖

Der erste Spieler erhält dann eine Zugaufforderung:

<room roomId="ROOM_ID">
  <data class="moveRequest" />
</room>

Worauf dieser innerhalb der gesetzten Zeitbeschränkung mit einem Zug antwortet:

<room roomId="ROOM_ID">
  <data class="move">
    ZUG
  </data>
</room>

Nach Erhalt des Zuges sendet der Server den neuen Spielstatus an alle Spieler und dem nächsten Spieler eine Zugaufforderung. So geht es hin und her bis zum Spielergebnis.

Ende der Kommunikation🔖

Die letzte Nachricht des Servers endet mit:

</protocol>

Danach wird die Verbindung geschlossen.

Spielstatus🔖

startTeam
das Team, das als erstes dran ist

board
die Positionen der Spielfiguren - count gibt die Turmhöhe an

lastMove
der vorherige Zug - hat die selbe Struktur wie ein Zug, der gesendet wird, außer dass das Tag <lastMove> statt <move> heisst. Der vorherige Zug wird in jedem Spielstatus angegeben, ausser vor dem ersten Zug.

ambers
die Anzahl der Bernsteine pro Team

<state turn="27">
  <startTeam>ONE</startTeam>
  <board>
    <pieces>
      <entry>
        <coordinates x="0" y="0"/>
        <piece type="Moewe" team="TWO" count="1"/>
      </entry>
      <entry>
        <coordinates x="5" y="6"/>
        <piece type="Robbe" team="ONE" count="2"/>
      </entry>
    </pieces>
  </board>
  <lastMove>
    <from x="4" y="4"/>
    <to x="5" y="6"/>
  </lastMove>
  <ambers>
    <entry>
      <team>ONE</team>
      <int>1</int>
    </entry>
    <entry>
      <team>TWO</team>
      <int>0</int>
    </entry>
  </ambers>
</state>

Zug🔖

from
Koordinaten des zu ziehenden Spielsteines

to
Koordinaten des Zielfeldes

<from x="0" y="1"/>
<to x="1" y="2"/>

Spielergebnis🔖

Zum Spielende erhält jeder Spieler das Ergebnis. Es beginnt mit einer definition, die die Interpretation der Ergebnisse erklärt. Für jeden Spieler gibt es einen Eintrag in scores. Der darin enthaltene score schlüsselt sich auf in:

cause
Beitrag des Spielers zum Spielende (REGULAR, LEFT, RULE_VIOLATION, SOFT_TIMEOUT, HARD_TIMEOUT)

reason
Erklärung zu cause

part
Siegpunkte des Spielers (0 verloren, 1 unentschieden, 2 gewonnen) und weitere Punkteinträge entsprechend definition

Wenn es einen Sieger gibt, endet es mit einem winner-Tag, welches das Gewinner-Team angibt.

Hier ein Beispiel:

<room roomId="ROOM_ID">
  <data class="result">
    <definition>
      <fragment name="Siegpunkte">
        <aggregation>SUM</aggregation>
        <relevantForRanking>true</relevantForRanking>
      </fragment>
      <fragment name="∅ Punkte">
        <aggregation>AVERAGE</aggregation>
        <relevantForRanking>true</relevantForRanking>
      </fragment>
    </definition>
    <scores>
      <entry>
        <player name="rad" team="ONE"/>
        <score cause="REGULAR" reason="">
          <part>2</part>
          <part>27</part>
        </score>
      </entry>
      <entry>
        <player name="blues" team="TWO"/>
        <score cause="LEFT" reason="Player left">
          <part>0</part>
          <part>15</part>
        </score>
      </entry>
    </scores>
    <winner team="ONE"/>
  </data>
</room>