Software Challenge : Integration eines neuen Spiels

This page last changed on Jan 05, 2015 by svk.

Wenn man ein neues Spiel in die WebApp integrieren will, kann das wie folgt geschehen:

Update des Servers und Einfügen eines neuen SimpleClient

Um die Wettkampfumgebung an das neue Spiel anzupassen, muss der GameServer in "public/server/" durch einen entsprechenden neuen Server ersetzt werden, der das plugin für das neue Jahr beinhaltet. Außerdem muss ein neuer SimpleClient der als Testreferenz dient in den Ordner "public/clients/" hinzugefügt werden.

Einrichten des neuen Spiels

Mittels des Generators ./script/generate game [GameName] kann man die Basis für ein neues Spiel generieren. Dies beinhaltet zum einen die Game-Definition in der die Rahmenbedingungen des jeweiligen Spiels definiert sind (Game-Definitionen findet man in config/games/). Zudem wird ein neuer ReplayViewer erstellt (wenn man nicht "replay_viewer:false" als Option übergibt), welcher später an die neuen Gegebenenheiten angepasst werden kann. Die verfügbaren Optionen des Generators lassen sich per "./script/generate game -h" anzeigen.

Game-Definition

In der Game-Definition werden automatisch die bei der Generierung angebenene Optionen eingefügt. Man kann nun die Definition für das neue Spiel so anpassen, dass sie den Wünschen entspricht, Informationen dazu finden sich unter Spieldefinition (allgemein) und unter Finale in der Spieldefiniton beschreiben (Finale).

Die in der Game-Definition vergebene plugin_guid muss mit der im Java Spiel-Plugin genau uebereinstimmen! Sonst koennen keine Spiele ueber die Wettkampf-Anwendung gestartet werden (autom. Tests, Freundschaftsspiele, Wettkampf, Finale). Im Java Spiel-Plugin wird die GUID in der Datei server/sc/pluginJJJJ/GamePlugin.java festgelegt.

Übersetzungen in der Wettkampfanwendung

In config/locales/de.yml muss ein neuer Abschnitt mit Übersetzungen für das neue Spiel angelegt werden:

games:
...
  cartagena:
    name: Cartagena
    match_score:
      points: Punkte
      victories: Siegpunkte
    round_score:
      victory: Siegpunkte
      points: Punkte

Replay-Viewer: Struktur

Wenn nicht die Opton replay_viewer:false gewählt wurde, werden folgende Elemente erstellt:

  • /app/views/replay_viewers/game_name/_viewer.erb ist das Script, welches in die Replay-Ansicht gerendert wird. Hier findet die eigentliche Implementierung der Darstellungslogik statt, dazu siehe unten.
  • /public/images/games/viewers/game_name/* sind die Bilde für den entsprechenden Viewer (z.B. Board, Spielfiguren usw.)
  • /public/stylesheets/replay_viewers/game_name/viewer.css ist der Stylesheet für den Viewer, er definiert Aussehen, Positionierung etc. und sollte entsprechend an das neue Spiel angepasst werden.

Replay-Viewer: Darstellungs-Logik anpassen

Die grundlegenen Funktionen sind alle bereits implementiert und müssen nur im Zweifel an die neuen Gegebenheiten angepasst werden (z.B. Änderungen im CSS Format der Replays). Weitere Dinge, wie z.B. die benötigten Spiele-Elemente, können ganz einfach oben im als html eingefügt und im CSS formatiert werden.

renderTurn(element):

Ist die Hauptmethode, welche für den Viewer zu implementieren ist. Sie bekommt ein XML-Element des Replays übergeben, welches den ensprechenden Zug abbildet, der gerade dargestellt werden soll. Dementsprechend passt man nun die Methode so an, dass sie den übergeben Spielstatus im Viewer darstelllt. Um die Koordinaten zu übersetzen kann man die Funktion translate verwenden, anpassen und ersetzen wie es einem gefällt (keine weiteren Abhängigkeiten außerhalb von renderTurn).

Alle sonstigen Elemente und Aktionen (Play, Vorwärts, Rückwärts, Spielresultate am Ende) sind schon vollständig implementiert und verwenden entsprechend die renderTurn Methode zur Darstellung.

translate():

Um zu definieren wie das Feld N auf dem Board abgebildet ist, gibt es die Methode translate(x,y,width,height). Standardmäßig wird das Board als 2-dimensionales Array gesehen, jedes Feld hat entsprechend einen Index für x und y, diese übersetzt die Funktion translate einfach auf absolute Koordinaten für die Darstellung. Wie diese Informationen übersetzt werden und ob überhaupt ein 2-dimensionales Array verwendet wird, ist dem Implementierer selber überlassen, weil dies stark von dem jeweiligen Spiel anbhängig ist. Es kann sich z.B. anbieten einfach eine Liste auch Knoten zu verwenden oder ähnliches.

Replay-XML

Grundsätzlich ruft der Replay-Viewer die show-Action einer Runde mit XML Header auf. Der Controller rendert daraufhin entweder lib/replay_viewers/generic_replay.xml.erb oder wenn vorhanden lib/replay_viewers/game_name/replay.xml.erb. Wenn keine spezifischen Änderungen am XML nötig sind, so ist entsprechend keine Modifikation notwendig. Falls doch kann man einfach das game-spezifische Partial implementieren und darin das XML entsprechend den Wünschen anpassen. Dazu sei gesagt, dass zuerst die Informationen aus dem Gzip-File (dessen Pfad ist im Partial als lokale Variable replay verfügbar) gelesen werden müssen um sie dann auszugeben. Bei Umformatierungen kann man sich z.B. am Partial von HaseUndIgel orientieren, wo recht viel umsortiert wird. Grundsätzlich kann man zum Lesen und Schreiben des XML sehr gut Nokogiri::XML verwenden (siehe Hase und Igel).

Anzeige in der Webapp

Die Webapp erkennt automatisch ob am entsprechenden Pfad lib/replay_viewers/game_name/_viewer.erb ein Replay-Viewer Script vorhanden ist, wählt es entsprechend für die Anzeige der Replays aus. Sollte kein Viewer vorhanden sein, so ist die Option Replay-Anzeigen auch nicht angezeigt. Im Regelfall sind aber keine weiteren Anpassungen zur Integration eines Spiels erforderlich.

Die Größe des IFrame in dem der Viewer angezeigt wird, muss in der application.css eingestellt werden:

.replay_frame_manhattan {
  width: 815px;
  height: 710px;
}