Protocol

General Workflow

Authentication

To authenticate, a client sends an AsyncAuthRequest to the server. The server can answer with:

blockdiag Client Server AsyncAuthRequest AsyncConnectionErrorRequest AsyncConnectedRequest error connected

When successful, the client will receive the full Player and a Session.

The client authenticates the end-user to the server with an Asmodee.net API OAuth2 access token.

Presence

To monitor presence of other users, the client needs to send their Asmodee.net player id with a RegisterPresenceRequest and subscribe to the presence stream with a SubscribePresenceServiceRequest.

Once subscribed, anytime the presence of one of the monitored participants changes, an AsyncBuddyPresencePartialUpdateRequest is sent with the state change. Note that presence events are batched, so an AsyncBuddyPresencePartialUpdateRequest can contain more than one participant presence information.

Logging out

For the user to log out of the server, the client should send an AsyncDisconnectRequest. After this, all requests coming from the client will be rejected until the next AsyncAuthRequest.

Heartbeat

The client must send regularly PingRequest to signal the server it is still connected. The server will respond with the exact same PingRequest. This allows the client to notice that the connection with the Meta-Lobby has been dropped (a TCP timeout can take a long time).

The PingRequest contains a timestamp field where you can write the local timestamp. Since the server sends back the same request, in return you’ll get the same timestamp you sent, this allows to compute the time distance between the client and the server.

Metalobby

Getting Chat room list information

It is possible at any time to get access to the list of Chat Rooms the Participant is chatting in. It is also possible to get information about only one room at a time.

To do so the client needs to send a WhatsNewRoomcatRequest, to which the server will respond with a RoomListRequest.

The returned status is a list (possibly of zero or one element) of RoomDetails. These RoomDetails contains all information about a given Chat Room, including (but not limited to):

  • Participant list

  • Room name

  • Room topic

  • …

Creating Chat Room

To create a new Chat Room, the client sends a CreateRoomRequest, with the correct RoomConfiguration and possibly initial participants.

The server can answer with an req-ml-ErrorRequest (TOO_MANY_OFFERS) if the creator has too many rooms in progress, or with a RoomCreatedRequest if it succeeded.

blockdiag Client Server CreateRoomRequest ErrorRequest RoomCreatedRequest error success

Entering room

Once the Chat Room is created, a RoomCreatedRequest is sent to all initial participants of the room, which are automatically added to the room list.

blockdiag Creator Server Participants CreateRoomRequest RoomCreatedRequest RoomCreatedRequest Room initialization success

Note

As soon as a participant enters the room, she can start chatting in it. There is no need to wait for all invitees to join the room.

Leaving room

Until the room is destroyed, it is possible for a Participant to leave a Chat Room by sending a LeaveRoomRequest. After she left, the participant cannot chat in the room anymore, unless she is invited back in.

blockdiag Client Server LeaveRoomRequest RoomLeftRequest

Note

When the creator leaves the room, the room is destroyed

In Room

Chat in room

Participants can send chat messages from a Chat Room with a RoomChatRequest specifying the roomId (available in RoomDetails after room creation). If the user is not in the specified room, or if it does not exist, it will receive a req-ml-ErrorRequest (UNKNOWN_ROOM).

blockdiag Client Server Other Clients in lobby RoomChatRequest (text='test') ClientChatRequest (text='test',sender=A) ClientChatRequest (text='test',sender=A)

If the chat message text triggers the anti-profanity filter several times in a row, the sender will be muted for a certain time, and the workflow becomes:

blockdiag Participant A Server Participant B RoomChatRequest (room_id=12,text='profanity') ClientChatBlockedRequest (room_id=12,text='<bip>',sender=A,muted=true) ClientChatBlockedRequest (room_id=12,text='<bip>',sender=A,muted=true) RoomChatRequest (room_id=12,text='message')

and no chat message is sent to the other participants.

When sending chat requests you can also specify some participants in the field recipient_ids. This is useful if you want to filter who receives the message (for instance, to implement private messaging). In a room, recipient_ids must contain local ids.

  • If recipient_ids is empty, the message will be sent to all participants of the room

  • If recipient_ids is filled, only these participants ids will receive the message (and the sender will always receive it back).

blockdiag Participant A Server Participant B Participant C RoomChatRequest (room_id=12, text='test', recipients_ids=[idB]) ClientChatRequest (room_id=12, text='test', recipients_ids=[idB], sender=A) ClientChatRequest (room_id=12, text='test', recipients_ids=[idB], sender=A) ClientChatRequest (room_id=12, text='test', recipients_ids=[idB], sender=A)

Chat codes

The server supports message codes, useful for implementing custom messages like pre-made quickchat messages, commands, emojis, special animation in the lobby…

Just fill the code integer parameter and it will be relayed. Please be aware that chat codes between 0 and 255 are reserved by the server and are not free to use. Provide a higher value. The code 0 is the “dummy code” and will behave the same way as if no code was provided.

You also have to provide a non-empty text (matching the message in default app locale) for older clients to display the message correctly, and for debugging purpose. The text will still pass through the profanity filter as usual.

Currently implemented chat codes in the Meta-Lobby:

Chat code

Description

1

Welcome message (in room)

2

Inappropriate message from a participant

3

Advertising /report command feature

4

“Thanks for your report”

5

Report cooldown (users cannot spam report)

6

Help (list of commands)

7

Meta-Lobby statistics (command /statistics)

8

In-room statistics (command /statistics)

9

Welcome message (in meta-lobby)

10 ~ 255

Reserved for future use

Chat commands

The Meta-Lobby offers a few commands, to be issued from the chat like a regular message. Currently, there are:

  • /help: displays the list of all supported commands

  • /report toto: to report the user toto (please note that no check is done server-side regarding the username)

  • /statistics: displays statistics on the meta-lobby (number of participants, number of rooms) or the current room (number of active participants, of forfeiters…)

Get Chat history

It is possible to get the history of the previous chat messages by sending a GetChatRoomHistoryRequest (by specifying a room_id). The server will send back a ClientChatRoomHistoryRequest with the latest previously exchanged messages. Note that the chat history will never display private messages.

blockdiag Participant Server GetChatRoomHistoryRequest (room_id=12) ClientChatRoomHistoryRequest (room_id=12)

Invitation

Invite new participants

It is possible to invite more buddies to the room after creation with an InviteFriendsToRoomRequest (by specifying a room_id). The details give information about the room, such as its name or topic.

blockdiag Inviter Server Invitee B Invitee C InviteFriendsToRoomRequest (room_id=12, friends=[B, C]) InvitedRoomRequest (room_id=12, invitation_by=A, details) InvitedRoomRequest (room_id=12, invitation_by=A, details)

Answer to invitation

Upon reception of an invitation, you can choose to accept or to decline it. To do so, send an AnswerInvitationRoomRequest filling the invitation_answer field.

Accept invitation: the invitee will automatically join the room. Client should then perform a GetChatRoomHistoryRequest to get the list of past messages.

blockdiag Invitee Server Participants in room InvitedRoomRequest (room_id=12, invitation_by=A, details) AnswerInvitationRoomRequest (room_id=12, invitation_answer=true) RoomJoined (room_id=12, participant) RoomJoined (room_id=12, participant)

In order to decline an invitation, simply put false as value for answer. The room admin will receive a corresponding RoomInvitationDeclinedRequest.

blockdiag Invitee Server Room admin InvitedRoomRequest (room_id=12, invitation_by=A, details) AnswerInvitationRoomRequest (room_id=12, invitation_answer=false) RoomInvitationDeclinedRequest (room_id=12, participant)

Community

Buddy list management

It is possible for a participant to get the content of her Buddy List, by sending an req-ml-AsyncBuddyListRequest. In return the server will send back an req-ml-AsyncBuddyListContentRequest containing the list of buddies.

To add a buddy, send an req-ml-AsyncBuddyManagementRequest with the operation ADD, and the Asmodee.net participant id to add. On return the server will send back an req-ml-AsyncBuddyAddedRequest.

To remove a buddy, follow the same workflow with the operation REMOVE. The server will send back an req-ml-AsyncBuddyRemovedRequest to confirm the operation.

Ignored list management

As with the Buddy List, the client can manage the Participant Ignored list. To get access to the list, send an req-ml-AsyncIgnoreListRequest, the server will return an req-ml-AsyncIgnoreListContentRequest.

To manage the ignore list, send an req-ml-AsyncIgnoreManagementRequest with the proper ADD or REMOVE operation, and the server will respond with either an req-ml-AsyncIgnoreAddedRequest or an req-ml-AsyncIgnoreRemovedRequest.