• General
  • Installation
  • Protocol
  • Server Data
• Tutorials
• JavaDoc (API)

• Introduction
• Game Messages
  • <chat_game>
  • <chat_private>
  • <disconnect>
  • <error>
  • <game_connect>
  • <invite>
  • <new_table>
  • <request_data>
• Table Messages (all contain "table" attribute)
  • <chat_table>
  • <controller_prop>
  • <controller_obj>
  • <exit_table>
  • <game_over>
  • <join_table>
  • <next_player>
  • <offer_draw>
  • <player_state>
  • <ready_to_start>
  • <sit_down>
  • <stand_up>
  • <start_game>
• Data Messages (from server)
  • <game>
  • <user_list>
  • <user>
  • <table_list>
  • <table>
  • <model>
  • <player_list>
  • <player>
• Conclusion

All communication in JOGRE is currently sent as XML (since version 0.2). Using XML gives several advantages over normal Strings including 1) ease of use e.g. no length fields are required and 2) power e.g. easy to create nested objects.

Communication classes in JOGRE are small data objects which implement an ITransmitable interface (contains a method which converts the fields of a data object into an XML element). This XML String is transmitted across a network and the object recreated again using the contents of the XML. These classes all begin with Comm with the exception of the data classes (e.g. Table) whose primary functionality isn't communication.

If you are new to JOGRE, one of the best ways to see all communication in action is to run a JOGRE Server (/jogre/server/server.bat or /jogre/server/server.sh) and then run then log onto the server using the JOGRE Administrator client (/jogre/server/administrator.bat or /jogre/server/administrator.sh).

It illustrates the current state of the server as a GUI tree on the left with icons for tables, users and players. It also has 4 tabbed panes. The panes of interest are the "Received Messages" and the "Sent Messages" panes which displays communication between the client and server.

As you can see from the screenshot the user Dave joined a game of chess and created a new table. The user Bob connected and joined dave's game. They then started to play a game together.

The sent pane shows what the server responds back to the various users.

In JOGRE, all messages are either game messages or table messages. We will first of all discuss game messages.

Game messages are usually sent to the main JOGRE client frame (frame which contains users, tables and global message box). These base messages are concerned with transferring global chat, users logging on / off, tables being created / destroyed.

A game message is any message which does not contain a table attribute. However, the <invite> message, which is used for users inviting other users to a specified table, contains a tableNum attribute. Because it does not contain a table attribute then it isn't actually sent to a table frame.

Sends a chat message to a all users in a game. This is sent from the message box in the bottom right in a main client frame.

Client sends ...

<chat_game>message</chat_game>

Where message is a chat message.

Server replies to receiving user ...

<chat_game username="sending user">message</chat_game>

Where sending user is the person who sent the message.

Sends a chat message to a specified user on a particular game. This is sent from the JOGRE client when a user selects a user, clicks the message box and types a message into the private message box. The server then replies to the selected user.

Client sends ...

<chat_private usernameTo="receiving user">message</chat_private>

Where message is a private chat message to the receiving user.

Server replies to receiving user ...

<chat_private username="sending user">message</chat_private>

Where sending user is the person who sent the message.

Used for a client sending a disconnect request to a server. Note: if a client's connection to a server is lost then they are disconnected automatically.

Client sends ...

<disconnect/>

The client may also lose his connection to server.

Server replies to all users in game (excluding sender) ...

<disconnect username="user"/>

Where user is the username of person who has disconnected.

Used to inform a client that an error has occured

Server sends to user ...

<error status="error code"/>

Where error code can be:

• 0 (General Error) - A general error has occurred.
• 1 (Server Full) - Server is full so client cannot connect.
• 2 (Game Not Supported) - Server does not support gamekey i.e. game-version (e.g. chess-0.2)..
• 3 (User already connected) - A client is trying to log on when the same username is already connected.
• 4 (User not connected) - A client is sending messages to the server but has actually logged on yet.

Used for connecting a client to a server. The client specifies their username, gamekey (game-version) and an optional password (used in a future release of JOGRE). A client must send this message when connecting to a server other wise they cannot send any other type of data.

Client sends ...

<game_connect gameID="game_key" username="user" /> ... or in later release ...

<game_connect gameID="game_key" username="user" password="password"/>

Where:

• gameID is the game ID of the client game (game-version) e.g. chess-0.2.
• username is the username of the client trying to connect.

Server replies to sucessful client...

The successful client will receive a <game> data message showing the current user / table lists of the this game.

Otherwise, if there is a problem the server will send a <error> message.

Server replies to all users in game (excluding sender) ...

<game_connect username="username"/>

Where username is the name of the succesful user who has just connected.

An invite is slighlty more complicated process than most. This is outlined in the following diagram:

As you can see, client A sends an invite "request" to client B. Client B then sends an invite "reply" which is either an "accept" or a "decline". If client B declines the invitation then client A is informed. However, if client B accepts he is added to the player list in the server and all clients are informed.

Note: This is a game message so that is why there is a "tableNum" attribute instead of a "table".

Client A sends ...

<invite tableNum="table num" status="1" usernameTo="user to"/>

Where status is equal to 1 (request) and user to is client B.

Server replies to client B ...

<invite tableNum="table num" status="1" username="user" usernameTo="user to"/>

Where user is client A and user to is client B.

a) If Client B accepts ...

<invite tableNum="table num" status="2" username="user"/>

Where status is equal to 2 (accept) and user is client A who sent the invite.

Server replies to all clients ...

<join_table table="table num" username="user"/>

Where user is client B who has accepted the invitation.

b) If Client B declines ...

<invite tableNum="table num" status="3" username="user"/>

Where status is equal to 3 (decline) and user is client A (client who sent invite).

Server replies to client B ...

<invite tableNum="table num" status="3" username="user" usernameTo="user to"/>

Where status is equal to 3 (decline) and user is client A (client who sent invite) and user to is client B (client who received invite).

Used for requesting the creation of a new table. Although this message is responsible for table communication it is at the game level as we dont know our table number (the server creates this).

Client sends ...

<new_table isPublic="visiblity" properties="properties"/>

Where visiblity is true or false (public or private table) and properties is a comma seperated list of simple table properties e.g. properties="minPlayers=2,maxPlayers=2".

Server replies to all users in game

Server creates a new table and returns this <table> message to all users at a game.

Used for requesting data from a user. A client can request a full <game> object or smaller <user_list> or <table_list> objects.

Client sends ...

<request_data dataType="data type" />

Where dataType is game, table_list or user_list.

Server replies to client

If dataType=game Server sends <game />

If dataType=table_list Server sends <table_list />

If dataType=user_list Server sends <user_list />

Used for sending a chat message to all other users a particular table.

Client sends ...

<chat_table table="table num">message<chat_table>

Where message is table chat message.

Server replies to all users at specified table (excluding sender) ...

<chat_table table="table num" username="sending user">message<chat_table>

Where sending user is the person who sent the message.

A controller property is an easy and straightforward way to keep games in synch at a table. To send a property the controller of a game (e.g. ChessController) calls any of the sendProperty methods which are availabe in the super class JogreController. These methods can be use to send a variety of different types of key / value properties. These key / value pairs are wrapped into a controller_prop message and sent to all the other users at a table.

The other clients will receive this message through empty adapter methods e.g. recieveProperty (String key, String value). A controller such as ChessController then overrides this method and does something with the property e.g. update model. This is used in the Connent 4 tutorial for communication.

NOTE: sending / receiving object is discussed in <controller_obj>.

Client sends ...

<controller_prop table="table num" status="status" key="key" value="value"/>

Where status is equals to:

• 0 - value is of type String.
• 1 - value is of type int.
• 2 - value is of type int co-ordinate.

Examples are as follows:

• <controller_prop table="3" status="0" key="direction" value="up"/>
• <controller_prop table="6" status="1" key="move" value="23"/>
• <controller_prop table="2" status="2" key="character moves" value="-9 15"/>

Server replies to all users at specified table (excluding sender) ...

<controller_prop table="table num" status="status" key="key" value="value"/>

This is used to send objects to other players at a table and works in the same manner as a <controller_prop> message. A controller object is sent from a controller (e.g. ChessController) using the sendObject (ITransmittable object) / sendObject (XMLElement object)methods.

Controller objects are used when simple controller key / value properties are not sufficient. This ensures any complexity of nested object can be sent to other clients.

Client sends ...

<controller_obj table="table num" />
    controller object
</controller_obj>

Where controller object is a flattened object (i.e. XMLElement or Java class which implements flatten method of ITransmittable).

An example is as follows:

• <controller_obj table="2" />
      <chess_move x1="2" xy="4" x2="3" y2="7/i>"/>
  </controller_obj>

A client sends this when they exit a table. The other clients then should update the player lists in the respective table.

Client sends ...

<exit_table table="table num"/>

Server replies to all users in game (excluding sender) ...

<exit_table table="table num" username="user"/>

Where user is the person who has just closed the table down.

This is sent when a game is over. A client sends this to the server which in turn sends to the other clients playing at a table. NOTE: Later versions of this will possibly only send a game over message from the server i.e. a client doesn't declare the game over.

Client sends ...

<game_over table="table num" status="status" scoreIncrement="scoreIncrement"/>

Where status is:

• 1 (Win) - Player has won.
• 2 (Resign) - Player has resigned.
• 3 (Draw) - All players draw.

The scoreIncrement attribute isn't currently being used but will be in a jogre beta release.

Server replies to all users at specified table ...

<game_over table="table num" status="status" username="user" scoreIncrement="scoreIncrement"/>

Where the user is the client who sends the game_over message.

Used when a client wishes to join a particular table. If the client is successfully all clients connected at a game are informed.

Client sends ...

<join_table table="table num"/>

The client may also lose his connection to server.

Server replies user just joined ...

<join_table table="table num" username="user"
    <player_list/>
</join_table>

Where user is the username of person who has just joined the table and player_list is the state of the current players at the current table.

Server replies to all users in game ...

<join_table table="table num" username="user"/>

Where user is the username of person who has just joined the table.

Used in a turn based game when a player takes a turn. The client can request that their turn is next. The server then responds to all the clients at the game and informs them whose go it is.

Client sends ...

<next_player table="table num"/>

Server replies to all players at table ...

<next_player table="table num" username="user"/>

Where user is the new current user at the table.

Used when a game is in motion when a client wishes to offer the other clients a draw. This is quite similar in style to the <invite> message although it doesn't use a usernameTo. This is because the message is sent to all other players playing at a game.

Client sends ...

<offer_draw tableNum="table num" status="1"/>

Where status is equal to 1 (request).

Server replies to all players, playing at specified table excluding sender...

<offer_draw tableNum="table num" status="1" username="user"/>

Where user is client who offered the draw.

a) If a client accepts ...

<offer_draw tableNum="table num" status="2" username="user"/>

Where status is equal to 2 (accept) and user is client who offered the draw.

Server replies to all clients at specified table ...

<game_over status="status" ... />

Where status is equal to 3 (game over - draw).

b) If a client declines ...

<offer_draw tableNum="table num" status="2" username="user"/>

Where status is equal to 3 (decline) and user is client who offered the draw.

Server replies to client who sent offer of draw ...

<offer_draw tableNum="table num" status="3" username="decling user"/>

Where status is equal to 3 (decline) and declining user is the client who has declined the offer.

This messagae is sent from the server to a client when a player state changes.

Server replies to all users in game ...

<player_state table="table num" username="user" state="state"/>

Where user is the name of the user whose state is changing. The state is the new state of the player ("viewing", "seated", "ready" or "started").

If a client sits down the server sends ...

<player_state table="table num" username="user" state="state" seat="seat"/>

Where seat is the seat number of the player.

Used when a client is ready to start a game.

Client sends ...

<ready_to_start table="table num"/>

The client may also lose his connection to server.

Server replies to all users in game ...

<player_state table="table num" username="user" state="state" seat="seat num"/>

Where state should be equal to ready if player is ready to start.

Used when a client sits down on a particular seat at a table. If the seat is free the player list is updated and notifications are sent to all players at this table.

Client sends ...

<sit_down table="table num" seat="seat num"/>

The seat number is a number between 0 and (max number of seats - 1).

Server replies to all players at table ...

<player_state table="table num" username="user" state="state" seat="seat num"/>

Where state should be equal to seated if player is seated OK.

This message is sent when a user stands up at a particular table.

Client sends ...

<stand_up table="table num"/>

Server replies to all clients at game ...

<player_state table="table num" username="user" state="state"/>

Where state should be equal to viewing if player stands OK.

This message is sent to all users to inform then that a game has started.

Server replies to all players at a table ...

<start_game table="table num" curPlayer="current player"/>

Where current player is the player who starts (turned based games).

The data messages are XML versions of the data structures which is stored on the server. The server holds a list of all the games which the server supports. Each game holds a list of the users connected and a list of the tables currently being played. Each table then contains a list of players.

These data objects are always sent from the server to clients although the <request_data> message can be used to request data when needed. Note that all these data structures have read/write locks on the server to keep their integrity and each client should always have direct data mirrors of them.

This concludes the current version of the JOGRE communication protocol. The communication protocol will slowly evolve. Any changes will be reflected in this document. The JOGRE protocol is the corner stone of JOGRE and hopefully others will use it to create their own clients (e.g. JOGRE on Mobile). All constructive critisms / suggestions are most welcome. Anything that will make the protocol better and more robust will be considered. If you have any comments then contact its author Bob Marks.

NOTE: This needs updated slightly for Beta 0.3 (admin messages).