Settlers of Catan Server Protokoll v1.3.1

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. Dieser ist identisch mit eurem Jira-Login.
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> -maxPlayers <count> (-map <mapname>)? (-testgame)?
JOIN GAME <gamename> (-visitor [true|false])?
MSG (ALL | ( ( USER | TEAM ) <recipient> ) )? <message>
UPLOAD MAP
DOWNLOAD MAP <mapname>

CREATE TESTPLAYER
Beispiel:

SE1 SettlersOfCatan-Server 1.0, Timeout set to 3600000ms
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, 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
`ACTIVATE_KNIGHT`	id	`{"@action":"ACTIVATE_KNIGHT","properties":{"entry":{"key":"id","value":"Knight@a4d93e3"}}}`	Mit diesem Command wird der übergebene Ritter aktiviert.
`BUILD`	type, destination	`{"@action":"BUILD","properties":{"entry":[{"key":"type","value":"Settlement"},{"key":"destination","value":"Intersection@a4d93e3"}]}}`	Mit diesem Command wird das gewünsche Modelelement (type) and der entsprechenden Position (destination) gebaut.Mögliche Belegungen für type: Settlement, City, Road, Knight, CityWall Für die Destination muss jeweils die gewünschte Intersection oder Border übergeben werden.
`CHANGE_USER_COLOR`	color	`{"@action":"CHANGE_USER_COLOR","properties":{"entry":{"key":"color","value":"FFFF00"}}}`	Ändert die Userfarbe.
`CHOOSE`	id	`{"@action":"CHOOSE","properties":{"entry":{"key":"id","value":"UserAssets@a4d93e3"}}}`	Mit diesem Command wird ein Modelelement ausgewählt. Je nach Kontext kann es sich dabei um ein Feld, ein Spieler oder etwas anderes handeln. Dieser Command sollte immer dann geschickt werden, wenn ihr vom Server mit einem ‘choose(Type:{Values})’ dazu aufgefordert werdet.Mit Type wird die Art von Modelelement bestimmt, welches der Server als Antwort erwartet.Mit Values werden alle zur Zeit möglichen Werte mitgegeben. Zu beachten ist, dass Values nicht immer mitgeliefert wird. Beispiel 1: Bei einem choose(Field) müsst ihr ein Feld auswählen und dieses mit einem CHOOSE command zurückschicken Beispiel 2: Bei einem choose(UserAssets:UserAssets@a4d93e3,UserAssets@bc43c12) müsst ihr einen Spieler auswählen und dessen UserAssets mit einem CHOOSE command zurückschicken. Alle möglichen Spieler wurden hier bereits mitgeschickt.
`END_PLAY`	type	`{"@action":"END_PLAY"}`	Beendet das Ausspielen der aktuellen Karte. Das ist nicht in jedem Zustand beim Karte ausspielen möglich.
`END_TURN`	keiner	`{"@action":"END_TURN"}`	Beendet den aktuellen Zug.
`LEAVE_GAME`	keiner	`{"@action":"LEAVE_GAME"}`	Verlässt das aktuelle Spiel.
`MESSAGE`	message, (audience)?, (recipient)?	{“@action”:”MESSAGE”,”@id”:”0″,”properties”:{“entry”:[{“key”:”message”,”value”:”Hallo”},{“key”:”audience”,”value”:”USER”},{“key”:”recipient”,”value”:”zenobios”}]}}	Verschickt eine Nachricht an alle oder den angegebenen User/Team. Der Parameter `audience` erlaubt 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 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 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
`NOOP`	keiner	`{"@action":"NOOP"}`	Command der in regelmäßigen Abständen abgeschickt werden kann, um die Verbindung aufrecht zu erhalten.
`OFFER`	type	`{"@action":"OFFER","properties":{"entry":[{"key":"id","value":"Card@c5db3a2"},{"key":"user","value":"UserAssets@a4d93e3"}]}}`	Bietet einem Spieler (user) eine Karte (id) an. Das ist bei bei der Fortschrittskarte “COMMERCIAL_HARBOR” nötig.
`PLAY`	type	`{"@action":"PLAY","properties":{"entry":{"key":"id","value":"ProgressCard@a4d93e3"}}}`	Spielt die Fortschrittskarte (id) aus.
`ROLL_DIES`	keiner	`{"@action":"ROLL_DIES"}`	Führt einen Würfelwurf aus. Dieser Command sollte immer dann geschickt werden, wenn ihr vom Server mit einem ‘rollDies’ dazu aufgefordert werdet.
`START_GAME`	keiner	`{"@action":"START_GAME"}`	Startet das Spiel, wenn genügend Spieler angemeldet sind.
`TRADE`	give, take	`{"@action":"TRADE","properties":{"entry":[{"key":"give","value":"BRICK"},{"key":"take","value":"GRAIN"}]}}`	Mit diesem Command kann man mit der Bank handeln. Dazu wird mit (give) der Resourcentyp übergeben, den man eintauschen und mit (take) den Typ, den man erhalten möchte. Mögliche Belegungen für give und take: BRICK, CLOTH, COIN, GRAIN, LUMBER, ORE, PAPER, WOOL
`UPGRADE_KNIGHT`	id	`{"@action":"UPGRADE_KNIGHT","properties":{"entry":{"key":"id","value":"Knight@a4d93e3"}}}`	Mit diesem Command wird der übergebene Ritter aufgewertet.
`UPGRADE_PROGRESS`	type	`{"@action":"UPGRADE_PROGRESS","properties":{"entry":{"key":"type","value":"POLITICS"}}}`	Mit diesem Command wird der gewünschte Stadtausbau durchgeführt. Mögliche Belegungen für type: POLITICS, SCIENCE, TRADE
`USE_KNIGHT`	type	`{"@action":"USE_KNIGHT","properties":{"entry":[{"key":"id","value":"Knight@c5db3a2"},{"key":"target","value":"Intersection@a4d93e3"}]}}`	Mit diesem Command kann mit dem mit id übergebenen Knight verschiedene Aktionen ausgeführt werden. Die Belegung von target entscheidet, was passiert. Folgendes ist möglich: Wird der Robber übergeben, so wird dieser von seinem Feld vertrieben, wenn die Spielsituation regelkonform ist. Wird eine Intersection übergeben, wird der Knight dorthin bewegt, wenn die Spielsituation regelkonform ist.

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.

Nicht alle Events stehen für Modelländerungen. Während eines Spiel sendet der Server euch auch Events, auf die ihr reagieren müsst. So gibt es OK und ERROR Events, die euch zusätzliche Informationen geben oder euch auffordern mit dem Server zu interagieren.

OK Events, die eine Reaktion von euch erfordern sind wie folgt aufgebaut: {“@ts”:”1372946132672″,”@src”:”SERVER”,”@prop”:”USER_MESSAGE”,”@nv”:”OK – {type} – {message}”}. Es gibt zudem auch OK Events, die rein informellen Charakter haben und erfolgreich ausgeführte Commands bestätigen

ERROR Events sind immer wie folgt aufgebaut: {“@ts”:”1372946132685″,”@src”:”SERVER”,”@prop”:”USER_MESSAGE”,”@nv”:”ERROR: {type} – {message}”}

Auf welchen {type} ihr wie reagieren müsst, findet ihr oben in der Tabelle. Der Parameter {message} wird nicht immer mitgesendet.

Empfangt ihr beispielsweise ein Event wie

{"@ts":"1372946132672","@src":"SERVER","@prop":"USER_MESSAGE","@nv":"OK - rollDies"}

erwartet der Server ein ROLL_DIES command von euch

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

Software Engineering Research Group Kassel

Department of Computer Science and Electrical Engineering

May 7, 2013 Albert Zündorf

Allgemeine Informationen

Klartextprotokoll

JSON Protokoll

Commands