ColdIron Server v2.1.0 Protokoll

Software Engineering I, WS1112

Der Server spricht generell ein zeilenbasiertes String Protokoll. Daher kann man eine telnet Verbindung benutzen um das Protokoll zu erkunden. Nach dem öffnen einer Konsole und der Eingabe von

 telnet se1.cs.uni-kassel.de 5000

kann man mit HELP eine Liste aller verfügbaren Befehle abrufen.

Allgemeine Informationen

  • Um sich beim Server anzumelden, benötigt man zunächst einen eigenen Login. Diesen bekommt ihr von eurem Betreuer beim nächsten Treffen.
  • Jedes erfolgreiche Kommando wird vom Server mit einem OK beendet. Fehler werden mit einer Zeile beantwortet die mit ERROR beginnt.
  • Der Server kommuniziert durch zwei verschiedene Protokollarten:
    • “Klartextprotokoll”: Bei einloggen und in der Lobby verwendet der Server ein simples “Klartextprotokoll” um mit seinen Clients zu kommunizieren.
    • JSON-Protokoll: Nach einem erfolgreichen JOIN GAME Kommando das mit OK bestätigt wurde wechselt der Server in ein JSON basiertes Protokoll, bei dem er JSON codierte Events verschickt und JSON codierte Commands erwartet.
  • Um einen Timeout zu vermeiden sollte vom Client in regelmäßigen abständen ein NOOP geschickt werden.

Klartextprotokoll

Sobald man eine Verbindung zum Server aufgebaut hat, kommuniziert dieser mit einem simplen Klartextprotokoll mit dem Client. Nicht alle Befehle sind überall verfügbar. Eine genaue Auflistung inkl. Gruppierung der Befehle liefert der HELP Befehl. Hier eine Übersicht über die verschiedenen Befehle:

  • Immer:
    • HELP <command>
  • Nach der Begrüßung vom Server:
    • LOGIN (<login>|<email>) <password>
    • LOGOUT
  • Nach dem Anmelden:
    • LIST USERS
    • LIST GAMES
    • CREATE GAME <gamename> (-players (<user>)+)? (-map <mapname>)?
    • JOIN GAME <gamename> (-visitor [true|false])?
    • MSG (ALL)? ( ( USER | TEAM ) <recipient> ) )? <message>
    • CHANGE PASSWORD <newPassword> <newPassword>

JSON Protokoll

Das Ingame JSON Protokoll kennt in Serverrichtung Commands und in Clientrichtung Events.

Commands

Die Commands müssen mindestens ein action Attribut enthalten welches folgende Werte annehmen kann (keys in Klammern sind optional):

Action Keys Beispiel Bemerkung
NOOP keiner {"@action":"NOOP"} Command der in regelmäßigen Abständen abgeschickt werden kann, um die Verbindung aufrecht zu erhalten.
CHOOSE_SECTOR sector {"@action":"CHOOSE_SECTOR","properties":{"entry":{"key":"sector","value":"Sector@1a3b6f"}}} Wählt den Startsektor aus. sector muss eine ID sein.
START_GAME keiner {"@action":"START_GAME"} Startet das spiel wenn jeder Spieler einen Startsektor gewählt hat.
LEAVE_GAME keiner {"@action":"LEAVE_GAME"} Verlässt das aktuelle Spiel.
CREATE_BUILDING sector, buildingtype {"@action":"CREATE_BUILDING","properties":{"entry":{"key":"sector","value":"Sector@d54a23"},"entry":{"key":"buildingtype","value":"STRONGHOLD"}}} Baut ein Gebäude vom Typ buildingtype im angegebenen Sektor.
DROP_BUILDING building {"@action":"DROP_BUILDING","properties":{"entry":{"key":"building","value":"Stronghold@d43b23"}}} Das Gebäude wird zerstört. Falls das Gebäude noch nicht fertig gebaut wurde, bekommt man seine Ressourcen zurück. Es können nur eigene Gebäude zerstört werden.
CREATE_UNIT building, unittype, (level)? {"@action":"CREATE_UNIT","properties":{"entry":{"key":"building","value":"Stronghold@d54a23"},"entry":{"key":"unittype","value":"PEON"},"entry":{"key":"level","value":"1"}}} Erzeugt eine Einheit vom gewünschten Typ im per ID übergebenen Gebäude mit dem gewünschten Level. Ist kein Level angegeben wird das maximal mögliche verwendet. Falls bereits eine Einheit in diesem Gebäde erzeugt wird oder das übergebene Level zu hoch für das Gebäude ist, wird ein Error erzeugt.
BUILD_UP building, peons {"@action":"BUILD_UP","properties":{"entry":{"key":"building","value":"Stronghold@5974b827"}, "entry":{"key":"peons","value":"Peon@ghz4b827,Peon@ghz4b333"}}} Veranlasst die gewählten peons am angegebenen Gebäude zu arbeiten.
MOVE_UNITS units,target {"@action":"MOVE_UNITS","properties":{"entry":{"key":"units","value":"Knight@d54a23,Swordsman@d533uf"},"entry":{"key":"target","value":"Sector@1a3b6f"}}} Versetzt die angegebenen units an das angegebene target. Peons können zu Ressourcen geschickt werden. Swordsman, Knights, Catapults und Archer können auf Sektoren geschickt werden. Archer können zusätzlich Tower besetzen.
UPGRADE building, level {"@action":"UPGRADE","properties":{"entry":{"key":"building","value":"Stronghold@5974b827"}, "entry":{"key":"level","value":"2"}}} Wertet das entsprechende Gebäude auf die gewählte Stufe auf (falls möglich)
REPAIR building, peons {"@action":"REPAIR","properties":{"entry":{"key":"building","value":"Stronghold@5974b827"}, "entry":{"key":"peons","value":"Peon@ghz4b827,Peon@ghz4b333"}}} Repariert das Gebäude building mit den angegebenen Peons.
CREATE_ALLIANCE name, (color)? {"@action":"CREATE_ALLIANCE","properties":{"entry":{"key":"name","value":"MyAlliance"}, "entry":{"key":"color","value":"FFFF00"}}} Legt eine neue Allianz mit dem übergebenen Namen und, wenn verhanden, der gewählten Farbe an. Der erzeugende User wird der Allianz automatisch hinzugefügt.
JOIN_ALLIANCE alliance {"@action":"JOIN_ALLIANCE","properties":{"entry":{"key":"alliance","value":"Alliance@1924b867"}}} Fügt den User der gewählten Allianz hinzu. Falls er sich nicht bereits in einer Allianz befindet, wechselt er in die neue Allianz.
DELETE_ALLIANCE alliance {"@action":"DELETE_ALLIANCE","properties":{"entry":{"key":"alliance","value":"Alliance@1924b867"}}} Löscht die Allianz. Dies kann nur durch ein Mitglied der Allianz erfolgen.
LEAVE_ALLIANCE keiner {"@action":"LEAVE_ALLIANCE"} Du verlässt deine Allianz, falls du dich in einer befindest.
CHANGE_ALLIANCE_COLOR alliance, color {"@action":"CHANGE_ALLIANCE_COLOR","properties":{"entry":{"key":"alliance","value":"Alliance@1924b867"}, "entry":{"key":"color","value":"FFFF00"}}} Ändert die Allianzfarbe. Dies kann nur durch ein Mitglied der Allianz erfolgen.
CHANGE_USER_COLOR color {"@action":"CHANGE_USER_COLOR","properties":{"entry":{"key":"color","value":"FFFF00"}}} Ändert die Userfarbe.
MESSAGE message, (audience)?, (recipient)? {"@action":"MESSAGE","properties":{"entry":{"key":"message","value":"Hallo"},"entry":{"key":"audience","value":"USER"},"entry":{"key":"recipient","value":"zenobios"}}} Verschickt eine Nachricht an alle oder den angegebenen User/Team/Allianz. Der Parameter audience erlaubt folgende Werte: ALL, USER, TEAM, ALLIANCE. Folgende Kombinationen von audience und recipient sind möglich:

audience: leer, recipient:leer -> Nachricht wird an alle User im Spiel geschickt
audience: leer, recipient:nicht leer -> Nachricht wird nicht verschickt

audience: ALL, recipient:leer -> Nachricht wird an alle User im Spiel geschickt
audience: ALL, recipient:nicht leer-> Nachricht wird nicht verschickt

audience: USER, recipient:leer -> Nachricht wird nicht verschickt
audience: USER, recipient:username -> Nachricht wird an user username verschickt

audience: TEAM, recipient:leer -> Nachricht wird an das eigene Team geschickt
audience: TEAM, recipient:teamname -> Nachricht wird an das Team teamname verschickt

audience: ALLIANCE, recipient:leer -> Nachricht wird an die eigene Allianz verschickt, falls der sendende User einer Allianz angehört
audience: ALLIANCE, recipient:alliancename -> Nachricht wird an die Allianz alliancename verschickt

Events, die durch diesen Command ausgelöst werden übergeben die Art der Message mit, um im Client eine Unterscheidung durchführen zu können. Mögliche Werte sind:

ERROR, MESSAGE, PUBLIC_MESSAGE, USER_MESSAGE, TEAM_MESSAGE, ALLIANCE_MESSAGE

Events

Der Server schickt Events in der Form

{"@ts":"199027638079229","@src":"Player@1f8882e","@prop":"name","@nv":"ascharf","@ov":"zenobios"}

In diesem Fall wurde zum Timestamp 199027638079229 von der source Player@1f8882e die property name von zenobios (old value) auf ascharf (new value) geändert.
Wer sich die Events vom Server genauer anschaut wird feststellen, dass Werte die null sind in JSON wegoptimiert werden.

Tipp: Das nötige Datenmodell lässt sich größtenteils aus dem Eventstream ableiten.