[!TIP] If you want to try protocol messages to understand how the middleware works, please use of an online websocket client such as Websocketking

Player connection protocol

The player's connection protocol is as follows.

• First, the player connects via websocket to the player_ws_port address.

• In order to authentificate, he must send a websocket message of the form:

  {"type":"connection", "id":your_id [String], "set_heartbeat": [bool]}
  

  your_id contains the id of the player. You can choose every string you want. I advise the use of UUID.

  set_heartbeat would be true if you cannot handle disconnections by setting a heartbeat in the connection. In that case, the middleware will send you {"type":"ping"} message every 5 seconds, and you will have to respond {"type":"pong"}. If you don't do that, the connection will be cancelled.

  Example of connection message: {"type":"connection", "id":"player1", "set_heartbeat":true}

[!TIP] Enable heartbeat when you cannot handle correctly disconnections of the player

• The player is now connected and will appear in orange the monitor webpage section Players. Please see 'Monitor webpage' to understand the color given.

• To disconnect properly the player. You can send:

  {"type": "disconnect_properly"}
  

  this message would allow the middleware to remove that player from the simulation if he's already in the simulation.

Message reception

When the player is connected, it would receive 2 types of messages:

• Json State
• Json Output

In this part, I will explain you what are these messages.

Json State

It is a JSON about the state of the player for the middleware. It has the following form:

{
   "type": "json_state"
   "connected": [Bool]
   "date_connection": [String]
   "id_player": [String]
   "in_game": [Bool]
}

• connected is true if the player is correcly connected to Gama.
• in_game is true if the player is in the simulation.
• date_connection is just the hour of the connection in 'HH:mm' format.
• id_player is the id the player gave in the connection message

Json Output

This JSON contains information needed by the player to interact with the simulation. It can contain for example information about its location and the locations of its neighbours. The format of the JSON is the following:

  {
     "type": "json_simulation"
     "contents": your_content,
  }

The content received depends on the GAML model.

[!NOTE] If you want to make your own game, you will have to define the form of the content you will send in the GAML model. To help understanding how it would work, the project contains several examples of different complexity.

Sending messages

Apart from the connection and disconnection messages, the player can send two types of message to influence the simulation while it's running.

Sending expression

Gama Sever allows clients to send GAML expression that can be compiled and executed. You can use this tool to send actions or informations to the experiment. You will have to follow this protocol:

{
   "type" : "expression", 
   "expr" : your_expression [String]
}

your_expression is an GAML expression that you want Gama execute it.

[!TIP] If you write $id in your expression, the middleware will replace it by the id of the player.

Sending ask

A new feature is 'Ask' Command. This avoids compilation of expression, that can be time-consuming. The 'Ask' command allows the player to send and action to the model. You will have to follow this protocol:

{
   "type": "ask",
   "action": action_to_execute [String],
   "agent": target_agent [String],
   "args": arguments_of_action [JSON]
}

[!NOTE] For more informations about 'Ask' command, please see the Gama documentation.