CreepSmash Server Protokoll v1.0.0

Software Engineering I, SS12

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 MAPS
    • LIST USERS
    • LIST GAMES
    • CREATE GAME <gamename> -players <count> (-map <mapname>)? (-testgame)?
    • JOIN GAME <gamename> (-visitor [true|false])?
    • MSG (ALL | ( ( USER | TEAM ) <recipient> ) )? <message>
    • CHANGE PASSWORD <newPassword> <newPassword>
    • UPLOAD MAP
    • DOWNLOAD MAP <mapname>
    • CREATE TESTPLAYER

      Beispiel:

      SE1 CreepSmash-Server 1.0, Timeout set to 600000ms
login zenobios ******
USER NICK=zenobios EMAIL=andreas.scharf@cs.uni-kassel.de ROLE=SE
TEAM NAME=SE ID=3fb6101e
OK
help
Available commands after greeting: LOGIN, LOGOUT
User commands: ID, CHANGE PASSWORD, LIST USERS
Game management: LIST MAPS, CREATE GAME, LIST GAMES, JOIN GAME, UPLOAD MAP, DOWNLOAD MAP
Team management: LIST TEAMS
Other commands: CREATE TESTPLAYER, MSG, CHANGELOG, UPLOAD MAP, NOOP, HELP
send 'HELP <command>' for details
a successfull command will be acknowledged with an 'OK' line
an unsuccessfull command will be acknowledged with an 'ERROR' line
OK
help create testplayer
Creates a temporary user e.g. for testing purposes. This user exists at least for 24h hours or until the next server restart
Usage: "CREATE TESTPLAYER"
OK
create testplayer
TEMPORARY USER NICK=tempUser0 PASSWORD=ys8ufm
OK

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.
START_GAME keiner {"@action":"START_GAME"} Startet das spiel wenn jeder Spieler ein Starttile gewählt hat.
LEAVE_GAME keiner {"@action":"LEAVE_GAME"} Verlässt das aktuelle Spiel.
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. Der Parameter audienceerlaubt folgende Werte:ALL, USER, TEAM.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 verschicktaudience: ALL, recipient:leer -> Nachricht wird an alle User im Spiel geschickt
audience: ALL, recipient:nicht leer-> Nachricht wird nicht verschicktaudience: 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

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
CHANGE_USER_COLOR color {"@action":"CHANGE_USER_COLOR","properties":{"entry":{"key":"color","value":"FFFF00"}}} Ändert die Userfarbe.
CHOOSE_TILE tile {"@action":"CHOOSE_TILE","properties":{"entry":{"key":"tile","value":"Tile@1a3b6f"}}} Wählt das Starttile aus. tile muss eine ID sein.
CREATE_TOWER towertype, cell {"@action":"CREATE_TOWER","properties":{"entry":{"key":"towertype","value":"ROCKET"},"entry":{"key":"cell","value":"Cell@d54a23"}}} Baut einen Tower des Typs towertype auf der Zelle cell.
SELL_TOWER tower {"@action":"SELL_TOWER","properties":{"entry":{"key":"tower","value":"Tower@d43b23"}}} Der Tower tower wird verkauft. Der Verkauf bringt 75% des ursprünglichen Towerpreises ein. Es können nur eigene Tower verkauft werden.
UPGRADE_TOWER tower, level {"@action":"UPGRADE_TOWER","properties":{"entry":{"key":"tower","value":"Tower@d54a23"},"entry":{"key":"level","value":"2"}}} Wertet den Tower tower auf Level level auf.
CHANGE_TOWER_STRATEGY tower, strategy {"@action":"CHANGE_TOWER_STRATEGY","properties":{"entry":{"key":"tower","value":"Tower@5974b827"}, "entry":{"key":"strategy","value":"FASTEST"}}} Wechselt die Strategie von Tower tower auf die Strategie strategy. Es stehen folgende Strategien zur Auswahl:
CLOSEST, FASTEST, STRONGEST, FARTHEST, WEAKEST
CREATE_CREEP creeptype {"@action":"CREATE_CREEP","properties":{"entry":{"key":"creeptype","value":"RACING_MAMBA"}}} Erzeugt einen Creep vom Typ creeptype

Events

Der Server schickt Events in der Form

{"@ts":"1336475335153","@src":"User@a4d93e3","@prop":"nickname","@nv":"akoch"}

In diesem Fall wurde zum Timestamp 1336475335153 von der source User@a4d93e3 die property nickname auf akoch (new value) geändert.
Wer sich die Events vom Server genauer anschaut wird feststellen, dass Werte die null sind in JSON wegoptimiert werden. In diesem Beispiel fehlt z.B. die Property @ov.

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