Request Reference

Table of Contents

• async.proto

  • ActionCommitedRequest

  • ActionInterruptedRequest

  • ActionRequiredRequest

  • AnswerInvitationRequest

  • AskAnyPlayerInfoRequest

  • AskPlayerInfoRequest

  • AskServerStatisticsRequest

  • AsyncAuthRequest

  • AsyncAuthRequest.UserAgent

  • AsyncBuddy

  • AsyncBuddyAddedRequest

  • AsyncBuddyList

  • AsyncBuddyListContentRequest

  • AsyncBuddyListRequest

  • AsyncBuddyManagementRequest

  • AsyncBuddyPresencePartialUpdateRequest

  • AsyncBuddyRemovedRequest

  • AsyncConnectedRequest

  • AsyncConnectionErrorRequest

  • AsyncDeviceUnlinkedRequest

  • AsyncDisconnectRequest

  • AsyncIgnore

  • AsyncIgnoreAddedRequest

  • AsyncIgnoreList

  • AsyncIgnoreListContentRequest

  • AsyncIgnoreListRequest

  • AsyncIgnoreManagementRequest

  • AsyncIgnoreRemovedRequest

  • AsyncUnlinkDeviceRequest

  • ChatHistoryEntry

  • ClientChatBlockedRequest

  • ClientChatHistoryRequest

  • ClientChatRequest

  • ClientDataRequest

  • ClockPausedRequest

  • ClockResumedRequest

  • ClocksStatusRequest

  • CommitActionRequest

  • EngageGameWithFriendsRequest

  • EnterLobbyRequest

  • ErrorRequest

  • ExitLobbyRequest

  • GameAbortedConfirmationRequest

  • GameAbortedRequest

  • GameClock

  • GameConfiguration

  • GameCreatedRequest

  • GameDetails

  • GameForfeitRequest

  • GameForfeitedRequest

  • GameList

  • GameNotification

  • GameObservedRequest

  • GameOutcomeConfirmationRequest

  • GameOutcomeRequest

  • GameOverRequest

  • GameStateUpdatedRequest

  • GameStatusReportRequest

  • GameUserDataUpdatedRequest

  • GetChatHistoryRequest

  • GetClocksRequest

  • InterruptActionErrorRequest

  • InterruptActionRequest

  • InterruptionOverRequest

  • InvitationAnsweredRequest

  • InvitationDetails

  • InvitationDetails.Confirmation

  • KarmaUpdate

  • LeaveSyncGameRequest

  • LobbyCreateGameRequest

  • LobbyEnteredRequest

  • LobbyExitedRequest

  • LobbyGameCreatedRequest

  • LobbyGameListRequest

  • LobbyJoinDeniedRequest

  • LobbyJoinGameRequest

  • LobbyLeaveGameRequest

  • LobbyNewPlayerRequest

  • LobbyPlayerInfoRequest

  • LobbyPlayerLeftGameRequest

  • LobbyPlayerListRequest

  • LobbyPlayerListRequest.PlayerList

  • LobbyStartGameDeniedRequest

  • LobbyStartGameRequest

  • MulticastChatRequest

  • MulticastDataRequest

  • ObservableGameListRequest

  • PlayerIdleProgressRequest

  • PlayerInfoRequest

  • PlayerPregameData

  • PlayerPresenceUpdateRequest

  • PlayerReplacedRequest

  • PlayerTimeoutRequest

  • RegisterPresenceRequest

  • ResumeSyncGameRequest

  • ServerStatisticsRequest

  • Session

  • SmallPlayer

  • StartObserveGameRequest

  • StatusReport

  • StatusReport.PlayerClock

  • StopObserveGameRequest

  • SubscribePresenceServiceRequest

  • SubscribeToObservableGameListRequest

  • SubscribedToObservableGameListRequest

  • SwitchedToGameRequest

  • UnregisterPresenceRequest

  • UnsubscribePresenceServiceRequest

  • UpdateUserDataRequest

  • UserDataUpdateRequiredRequest

  • UserDataUpdatedRequest

  • WhatsNewPussycatRequest

  • AsyncBuddyManagementRequest.Operation

  • AsyncConnectionErrorRequest.ConnectionError

  • AsyncIgnoreManagementRequest.Operation

  • ErrorCode

  • GameConfiguration.GameMode

  • GameConfiguration.Observers

  • GameNotification.Event

  • GameObservedRequest.Status

  • GameStatus

  • InterruptActionErrorRequest.Error

  • LobbyJoinDeniedRequest.JoinError

  • LobbyStartGameDeniedRequest.StartError

  • PlayerTimeoutRequest.PlayerStatus

• common.proto

  • PartnerToken

• game.proto

  • AccessRights

  • AccessRights.Right

  • Achievement

  • AchievementUpdate

  • Activity

  • Avatar

  • FinalScore

  • PartnerUser

  • Player

  • PlayerAchievement

  • PlayerAchievementUpdate

  • PlayerActivity

  • PlayerRankingUpdate

  • Rank

  • RankingUpdate

  • Achievement.Status

  • Achievement.Type

  • Activity.Code

• request.proto

  • Message

  • Packet

  • PingRequest

• push.proto

  • Device

  • DeviceType

  • Devices

  • Devices.Type

• Scalar Value Types

async.proto

Messages

ActionCommitedRequest

Sent back to acknowledge a client sent CommitActionRequest.

More information can be found in Standard Game Turn and Simultaneous Game Turn sections.

S -> C

• request_number: 523

• field_name: action_commited_request

In response to:

• CommitActionRequest

ActionCommitedRequest

Field	Type	Description
game_id	int64	System assigned game id
turn_index	int32	Monotonically incremented turn index after each round by the server, this should allow the client to know which request it should act on. It has the same value as provided in last CommitActionRequest, if correct
pause_time	int32	Next player’s clock will start after this delay (in seconds)

Top

ActionInterruptedRequest

Sent by the server to confirm the reception of an interruption.

More information can be found in Interruptions section.

S -> C

• request_number: 571

• field_name: action_interrupted_request

In response to:

• InterruptActionRequest

ActionInterruptedRequest

Field	Type	Description
game_id	int64	The game id where this event happened
player_id	int32	Local player id of the interrupting player
turn_index	int32	Turn index at which the interruption occurred
interruption_data	bytes	The player interrupted with these data
no_more_interruption	bool	If true, the server has stopped the interruption phase after receiving the last interruption. If false, it will continue until interruption_window_duration (cf CommitActionRequest)

Top

ActionRequiredRequest

Ask a given player to perform a game action. This makes the player the “active player”.

More information can be found in Standard Game Turn and Simultaneous Game Turn sections.

S -> C

• request_number: 500

• field_name: action_required_request

Possible Responses:

• CommitActionRequest

ActionRequiredRequest

Field	Type	Description
game_id	int64	System assigned game id
state	bytes	Client created game state
players	com.daysofwonder.Player[]	List of players in this game (in no particular order)
next_player_ids	int32[]	List of the next player local ids in turn (the receiving player will be the first one)
turn_index	int32	Monotonically incremented turn index after each round by the server. This should allow the client to know which request it should act on. Provide this value when sending a CommitActionRequest
invited_by	int32	This will be present if the game resulted from an invitation from this player. If the game resulted from an invitation, will be filled with the player’s id. Is 0 if the game was not an invitation. Combined with turn_index == 1, this can be a way to let the user know that she has been invited
player_clock	GameClock	Current player clock status
user_data	PlayerPregameData[]	Optionally sent user data. This data comes from the LobbyCreateGame and LobbyJoinGame request, or can also be updated independently by users with an UpdateUserDataRequest
interruption_data	PlayerPregameData[]	Optionally sent interruption data. This data comes from the interruption done by users with an InterruptActionRequest during an interruption turn
pause_time	int32	The player’s clock will start after this delay (in seconds). This can be used to give time to play animations of previous actions before starting decreasing clock.

Top

AnswerInvitationRequest

Sent by the client to accept or decline an invitation. The result is immutable and any other accept/decline for the same user in the game after the first one will be discarded.

More information can be found in Invitation section.

C -> S

• request_number: 540

• field_name: answer_invitation_request

In response to:

• GameCreatedRequest

Possible Responses:

• InvitationAnsweredRequest

• ErrorRequest: INVITATION_DENIED (13)

AnswerInvitationRequest

Field	Type	Description
game_id	int64	Game id of the accepted/declined invitation
accept	bool	true to accept the invitation, false otherwise
user_data	bytes	Optional user data to send this player capabilities

Top

AskAnyPlayerInfoRequest

Sent by the client when more details are needed for a given connected player. This is used for instance when clicking on a player in the buddy/ignore player list.

C -> S

• request_number: 630

• field_name: ask_any_player_info_request

Possible Responses:

• PlayerInfoRequest

• ErrorRequest

AskAnyPlayerInfoRequest

Field	Type	Description
player_id	int32	The player to ask information for

Top

AskPlayerInfoRequest

Sent by the client when more details are needed for a given player. This is used for instance when clicking on a player in the lobby player list.

More information can be found in Player Information section.

C -> S

• request_number: 605

• field_name: ask_player_info_request

Possible Responses:

• LobbyPlayerInfoRequest

• ErrorRequest

AskPlayerInfoRequest

Field	Type	Description
player_id	int32	The player to ask information for

Top

AskServerStatisticsRequest

Sent by the client when it wants to have some statistics about the server (like number of hosted games, connected clients…). When subscribe is true, the server sends a continuous stream of statistics updates.

More information can be found in Server Statistics section.

C -> S

• request_number: 408

• field_name: ask_server_statistics_request

Possible Responses:

• ServerStatisticsRequest

AskServerStatisticsRequest

Field	Type	Description
subscribe	bool	If false, the server will return statistics only once. If true, the server will send a stream of statistics message, and will stop only when the client sends an ask request with subscribe == false

Top

AsyncAuthRequest

Used to:

• either authentify a player for a given connection (should be the first packet to be sent)

• or resume a session from an existing session

You must connect using the OAuth2 Access Token provided by the REST API as described in the protocol documentation. This Access Token must have the private scope, of course.

Note : If a user logs out from her client and logs in with a different DoW account, we would have the same device token id pointing to different accounts. Thus it is possible that a given device receive notification for a different user, which is bad. Please send an AsyncUnlinkDeviceRequest before connecting with a different account / session.

More information can be found in Authentication section.

C -> S

• request_number: 400

• field_name: async_auth_request

Possible Responses:

• AsyncConnectionErrorRequest

• AsyncConnectedRequest

AsyncAuthRequest

Field	Type	Description
name	string	Player login name
partner_token	PartnerToken	Set this to authenticate with an access_token coming from the API
user_agent	AsyncAuthRequest.UserAgent	Client user agent
session	Session	If sent, then that means we want to resume a given session
game_type	string	This is required - multi game protocol requires a distinct authentication per player per game. Game types are enforced on the server, by example SW and TT are valid
device	com.daysofwonder.game.push.DeviceType	An optional device token. If sent, this will be used for push notifications. Devices are kept on the server, if the client already sent this device token it is not needed to send it at every authentication attempt (to spare some resources on the server)

Top

AsyncAuthRequest.UserAgent

AsyncAuthRequest.UserAgent

Field	Type	Description
user_agent	string	This contains the codified User Agent (Downloadable, Steam, iPad, MacOSX, Pocket…)
full_user_agent	string	This would contain the full string obeying the following format: *platform*/*ua*/*version*

Top

AsyncBuddy

This represents a buddy.

More information can be found in Buddy List section.

AsyncBuddy

Field	Type	Description
player_id	int32	Unique global id
activity	com.daysofwonder.PlayerActivity	This buddy’s current activity

Top

AsyncBuddyAddedRequest

Sent by the server when a buddy has been added.

More information can be found in Buddy List section.

S -> C

• request_number: 519

• field_name: async_buddy_added_request

In response to:

• AsyncBuddyManagementRequest

AsyncBuddyAddedRequest

Field	Type	Description
added_buddy	com.daysofwonder.Player	The full player information of the added buddy

Top

AsyncBuddyList

This represents a list of buddy.

More information can be found in Buddy List section.

AsyncBuddyList

Field	Type	Description
buddy	AsyncBuddy[]	Buddies information, contains the activities
player	com.daysofwonder.Player[]	Buddies’ Player information, order is not guaranteed to be the same as the buddy field
present	int32[]	Buddies whose global id are listed here are connected - note this is optional and this list might be empty (especially during the phase where the server doesn’t yet support presence)

Top

AsyncBuddyListContentRequest

Sent in response to a given AsyncBuddyListRequest.

S -> C

• request_number: 516

• field_name: async_buddy_list_content_request

In response to:

• AsyncBuddyListRequest

AsyncBuddyListContentRequest

Field	Type	Description
buddies	AsyncBuddyList	The current full buddy list (filtered if asked to)

Top

AsyncBuddyListRequest

Sent by the client to ask the connected user buddy list.

C -> S

• request_number: 515

• field_name: async_buddy_list_request

Possible Responses:

• AsyncBuddyListContentRequest

AsyncBuddyListRequest

Field	Type	Description
webcard_filter	string[]	Pass an optional array of webcards to filter out users that don’t have this webcard in their account

Top

AsyncBuddyManagementRequest

Sent by the client to add or remove a buddy. A player cannot add herself to her own buddy list.

More information can be found in Buddy List section.

C -> S

• request_number: 518

• field_name: async_buddy_management_request

Possible Responses:

• AsyncBuddyAddedRequest

• AsyncBuddyRemovedRequest

AsyncBuddyManagementRequest

Field	Type	Description
operation	AsyncBuddyManagementRequest.Operation	Whether to add or remove a buddy
buddy	AsyncBuddy	The buddy to be added or removed

Top

AsyncBuddyPresencePartialUpdateRequest

Despite its name, this request is sent by the server when the presence of some monitored players change.

More information can be found in Presence section.

S -> C

• request_number: 517

• field_name: async_buddy_presence_partial_update_request

AsyncBuddyPresencePartialUpdateRequest

Field	Type	Description
present	int32[]	List of present players global id, including buddies. Players not mentioned in this request have not changed. Note: due to the asynchronicity of the system, it is possible that some players id referenced in those two lists are unknown to the client (for instance, if you don’t know yet who are your buddies).
absent	int32[]	List of absent players global id

Top

AsyncBuddyRemovedRequest

Sent by the server when a buddy has been removed.

More information can be found in Buddy List section.

S -> C

• request_number: 520

• field_name: async_buddy_removed_request

In response to:

• AsyncBuddyManagementRequest

AsyncBuddyRemovedRequest

Field	Type	Description
removed_buddy	AsyncBuddy	The removed buddy

Top

AsyncConnectedRequest

Returned by the server after a successful AsyncAuthRequest.

More information can be found in Authentication section.

S -> C

• request_number: 406

• field_name: async_connected_request

In response to:

• AsyncAuthRequest

AsyncConnectedRequest

Field	Type	Description
session	Session	The current player session
player	com.daysofwonder.Player	The current player information

Top

AsyncConnectionErrorRequest

Returned from an AsyncAuthRequest if there is a failure.

More information can be found in Authentication section.

S -> C

• request_number: 407

• field_name: async_connection_error_request

In response to:

• AsyncAuthRequest

AsyncConnectionErrorRequest

Field	Type	Description
code	AsyncConnectionErrorRequest.ConnectionError	Connection error code

Top

AsyncDeviceUnlinkedRequest

Sent by the server to the client in response to a successful AsyncUnlinkDeviceRequest.

S -> C

• request_number: 413

• field_name: async_device_unlinked_request

In response to:

• AsyncUnlinkDeviceRequest

AsyncDeviceUnlinkedRequest

Field	Type	Description
device	com.daysofwonder.game.push.DeviceType	Device to unlink

Top

AsyncDisconnectRequest

When a player wants to disconnect.

More information can be found in Logging out section.

C -> S

• request_number: 401

• field_name: async_disconnect_request

AsyncIgnore

This represents an ignored player.

AsyncIgnore

Field	Type	Description
player_id	int32	Unique global id

Top

AsyncIgnoreAddedRequest

Sent by the server when an ignore have been added.

More information can be found in Ignore List section.

S -> C

• request_number: 563

• field_name: async_ignore_added_request

In response to:

• AsyncIgnoreManagementRequest

AsyncIgnoreAddedRequest

Field	Type	Description
added_ignore	com.daysofwonder.Player	The Player information of the user who has been ignored

Top

AsyncIgnoreList

This represents a list of ignored players.

AsyncIgnoreList

Field	Type	Description
ignore	AsyncIgnore[]	AsyncIgnore information list of the players being ignored
player	com.daysofwonder.Player[]	Player information of the ignored users, order is not guaranteed to be the same as the ignore field

Top

AsyncIgnoreListContentRequest

Sent in response to a given AsyncIgnoreListRequest.

More information can be found in Ignore List section.

S -> C

• request_number: 561

• field_name: async_ignore_list_content_request

In response to:

• AsyncIgnoreListRequest

AsyncIgnoreListContentRequest

Field	Type	Description
ignores	AsyncIgnoreList	The current full ignore list (filtered if asked to)

Top

AsyncIgnoreListRequest

Sent by the client to fetch the user ignore list.

More information can be found in Ignore List section.

C -> S

• request_number: 560

• field_name: async_ignore_list_request

Possible Responses:

• AsyncIgnoreListContentRequest

AsyncIgnoreManagementRequest

Sent by the client to add or remove a buddy. A player cannot add herself to her own ignore list.

More information can be found in Ignore List section.

C -> S

• request_number: 562

• field_name: async_ignore_management_request

Possible Responses:

• AsyncIgnoreAddedRequest

• AsyncIgnoreRemovedRequest

AsyncIgnoreManagementRequest

Field	Type	Description
operation	AsyncIgnoreManagementRequest.Operation	Operation to perform
ignore	AsyncIgnore	Ignored player the operation applies to

Top

AsyncIgnoreRemovedRequest

Sent by the server when an ignore has been removed.

More information can be found in Ignore List section.

S -> C

• request_number: 564

• field_name: async_ignore_removed_request

In response to:

• AsyncIgnoreManagementRequest

AsyncIgnoreRemovedRequest

Field	Type	Description
removed_ignore	AsyncIgnore	The AsyncIgnore (containing the global id) of the player who is not ignored anymore

Top

AsyncUnlinkDeviceRequest

Sent by the client to unlink a device from the current active session. The idea is that if a user logs out from her client and logs in with a different DoW account, we would have the same device token id pointing to different accounts. Thus it is possible that a given device receive notification for a different user, which is bad.

More information can be found in Logging out section.

C -> S

• request_number: 412

• field_name: async_unlink_device_request

Possible Responses:

• AsyncDeviceUnlinkedRequest

• ErrorRequest: UNKNOWN_DEVICE_TOKEN (6)

AsyncUnlinkDeviceRequest

Field	Type	Description
device	com.daysofwonder.game.push.DeviceType	The device to unlink from the player session

Top

ChatHistoryEntry

An entry of a chat history.

More information about the chat can be found in Chat section.

ChatHistoryEntry

Field	Type	Description
from	string	Sender name
text	string	Chat message
player_id	int32	For in game chat history it’s the local game id, if from the lobby it’s the global id
timestamp	int64	Unix epoch in millis when the server received the message. 0 means the timestamp was not provided by the client.
code	int32	Message code when using premade messages. 0 means the message was not premade

Top

ClientChatBlockedRequest

Sent to the MulticastChatRequest sender if her message has been blocked or if she’s been muted.

More information can be found in Chat section.

S -> C

• request_number: 526

• field_name: client_chat_blocked_request

In response to:

• MulticastChatRequest

ClientChatBlockedRequest

Field	Type	Description
game_id	int64	System assigned game id (might be 0 if coming from the lobby)
text	string	Text chat
sender	com.daysofwonder.Player	The sender player
muted	bool	After sending profanities, the sender might be muted for an arbitrary time. If muted is true, the client has been muted. Note: the server never tells a given client it has been unmuted
blocked	bool	This sender can be administratively blocked (prevented to chat) (community management), in this case blocked will be true. Normally client software shouldn’t send to the server MulticastChatRequest if she’s blocked (check the blocked and banned field in the PBGame.Player message after authentication)
code	int32	Code of the premade message sent (if multicast a code)
recipient_ids	int32[]	Recipient of the message (if specified by the original multicast chat)

Top

ClientChatHistoryRequest

Sent to in response to GetChatHistoryRequest

More information about the chat can be found in Chat section.

S -> C

• request_number: 536

• field_name: client_chat_history_request

In response to:

• GetChatHistoryRequest

ClientChatHistoryRequest

Field	Type	Description
game_id	int64	System assigned game id (might be 0 if coming from the lobby)
entry	ChatHistoryEntry[]	Chat entries in chronological order

Top

ClientChatRequest

Sent by the server in response to a MulticastChatRequest to the players of the game game_id as long as they were listed in MulticastChatRequest.recipient_ids (or to all players if recipient_ids is empty).

More information can be found in Chat section.

S -> C

• request_number: 525

• field_name: client_chat_request

In response to:

• MulticastChatRequest

ClientChatRequest

Field	Type	Description
game_id	int64	System assigned game id (might be 0 if coming from the lobby)
text	string	Text chat
sender	com.daysofwonder.Player	The sender player
profanity	bool	true if the text has been altered to remove profanities
code	int32	Code of the premade message sent (if multicast a code)
recipient_ids	int32[]	Recipient of the message (if specified by the original multicast chat)

Top

ClientDataRequest

When one of the player sent a MulticastDataRequest the server will send back a ClientDataRequest to the multicast clients.

More information can be found in Multicast section.

S -> C

• request_number: 503

• field_name: client_data_request

ClientDataRequest

Field	Type	Description
game_id	int64	System assigned game id
data	bytes	Any data that was sent by the sender
sender	com.daysofwonder.Player	Sender player

Top

ClockPausedRequest

Sent by the server when the clock has been paused.

S -> C

• request_number: 543

• field_name: clock_paused_request

ClockPausedRequest

Field	Type	Description
game_id	int64	Game id
clock	StatusReport.PlayerClock[]	Optional list of all player clocks
error	ErrorCode	If an error occurs, this field is set. Otherwise it’s not

Top

ClockResumedRequest

Sent by the server when the player clock is resumed

S -> C

• request_number: 545

• field_name: clock_resumed_request

ClockResumedRequest

Field	Type	Description
game_id	int64	Game id
clock	StatusReport.PlayerClock[]	Optional list of all player clocks
error	ErrorCode	If an error occurs, this field is set. Otherwise it’s not

Top

ClocksStatusRequest

Sent by the server in response to the GetClocksRequest.

More information can be found in Player Clocks Status section.

S -> C

• request_number: 547

• field_name: clocks_status_request

In response to:

• GetClocksRequest

ClocksStatusRequest

Field	Type	Description
game_id	int64	Game id the clocks are running in
clock	StatusReport.PlayerClock[]	List of all player clocks in the game

Top

CommitActionRequest

When a player has finished her action, she sends a CommitActionRequest with the current game state and the list of next active players in turn.

More information can be found in Standard Game Turn, Simultaneous Game Turn or Interruptions sections.

C -> S

• request_number: 501

• field_name: commit_action_request

In response to:

• ActionRequiredRequest

• PlayerTimeoutRequest

Possible Responses:

• ActionCommitedRequest

• GameStateUpdatedRequest

• ErrorRequest: NOT_YOUR_TURN (1)

• ErrorRequest: UNKNOWN_PLAYER (2)

• ErrorRequest: UNKNOWN_GAME (3)

• ErrorRequest: YOU_FORFEITED (7)

• ErrorRequest: YOU_RAN_OUT_OF_TIME (8)

• ErrorRequest: YOU_LEFT (9)

CommitActionRequest

Field	Type	Description
game_id	int64	System assigned game id
player_id	int32	Local player id of the acting player. In case of a robot hosted on a different player device, this should be the robot impersonating local player id
next_state	bytes	The next game state
next_player_ids	int32[]	The ordered list (in action order) of the next player ids. Please provide as much players as possible for robot hotswap to work correctly
next_summary_data	bytes	Summary data of the next_state field. Will end up in the StatusReport.summary_data of this game. If not provided (or with empty bytes), the next StatusReport.summary_data won’t be provided (this can be used to clear the summary data if needed)
turn_index	int32	The turn index this action is supposed to played in. It is recommended to provide it, the correct value is given by the last ActionRequiredRequest / PlayerTimeoutRequest and others
next_simultaneous	bool	Is the next turn a simultaneous turn?
simultaneous_players	int32[]	List of players required to play for the simultaneous turn
broadcast	bool	Set to true if next_state should be sent to all active players and observers (see GameStateUpdatedRequest)
interruption_window_duration	int32	Duration (in ms) for which the previous action can be interrupted by the players defined in interruption_player array. If 0, the action is not interruptible
interruption_player	int32[]	Which players are authorized to interrupt the previous action
pause_time	int32	Next player’s clock will start after this delay (in seconds)
idle_time	int32	Set a duration in seconds to override the game configuration idle_time (for this action see GameConfiguration). Set zero to use default timer if enabled in game configuration; this field has no impact if there is no game configuration idle_time defined.

Top

EngageGameWithFriendsRequest

Start an invitation to a list of friends. In return a GameCreatedRequest is sent back.

More information can be found in Invitation section.

C -> S

• request_number: 405

• field_name: engage_game_with_friends_request

Possible Responses:

• GameCreatedRequest

• ErrorRequest: INVITATION_DENIED (13)

EngageGameWithFriendsRequest

Field	Type	Description
friends	int32[]	Friends global id (add 0 to invite robots). Unless specified the server doesn’t accept an empty list or a list with only robots
configuration	GameConfiguration	Game configuration. Note: not all settings in configuration are valid for an invitation game (like for instance private or name)
user_data	bytes	This specific user data for this game. This can be used to encode this player capabilities
initial_state	bytes	In case you need to have an initial state (ie game data) when the first player has to play, fill this field
initial_summary_data	bytes	If you need to have an initial summary, for display purposes

Top

EnterLobbyRequest

Sent by the client when it wants to enter the lobby. This automatically subscribes the client to the following streams:

• chat messages

• player list updates

• games offer updates

More information can be found in Entering section.

C -> S

• request_number: 600

• field_name: enter_lobby_request

Possible Responses:

• LobbyEnteredRequest

• ErrorRequest: PLAYER_ALREADY_IN_LOBBY (10)

ErrorRequest

Sent in response to a client request that generated an error.

S -> C

• request_number: 505

• field_name: error_request

ErrorRequest

Field	Type	Description
game_id	int64	System assigned game id. Might be 0 for errors not pertaining to a game
code	ErrorCode	Error code. If 0, there was not an error but the error field was mandatory
msg	string	Error message if any
turn_index	int32	The current turn index if in a game
player_id	int32	The player who sent the original request when in a game

Top

ExitLobbyRequest

Sent by the client when it wants to exit the lobby. This automatically unsubscribes the client from all the streams of lobby updates.

More information can be found in Exiting section.

C -> S

• request_number: 602

• field_name: exit_lobby_request

Possible Responses:

• LobbyExitedRequest

GameAbortedConfirmationRequest

Sent by a client to validate it showed the abort to the players. Once all players sent this, the game will go from ABORTING state to ABORTED.

C -> S

• request_number: 531

• field_name: game_aborted_confirmation_request

In response to:

• GameAbortedRequest

GameAbortedConfirmationRequest

Field	Type	Description
game_id	int64	System assigned game id
player_id	int32	The local player id that confirms the game outcome

Top

GameAbortedRequest

Sent by the server if there’s no player (all timed out, or all withdrawn) to keep the game alive. The server goes in ABORTING state, and players will all have to send GameAbortedConfirmationRequest.

More information can be found in Abort section.

S -> C

• request_number: 530

• field_name: game_aborted_request

In response to:

• GameForfeitRequest

• LeaveSyncGameRequest

• A player timed out, and no human active players left in the game

Possible Responses:

• GameAbortedConfirmationRequest

GameAbortedRequest

Field	Type	Description
game_id	int64	System assigned game id
aborting_player_ids	int32[]	List of local player ids of the offenders
ranking_update	com.daysofwonder.PlayerRankingUpdate[]	This contains the ranking change for the players
karma_update	KarmaUpdate[]	Contains the increase/decrease of karma of a given player global id
data	bytes	Custom game data to be sent to other players

Top

GameClock

Represents a given in game player clock.

GameClock

Field	Type	Description
started_at	int64	When the player first turn started (in milliseconds since unix epoch)
last_started_at	int64	When this player clocks started last (in milliseconds since unix epoch)
remaining	int64	How many milliseconds this player has before the clock exhausts
duration	int64	How many milliseconds players are allowed to play for a full game
armed	bool	Is the clock ticking?
timestamp	int64	Timestamp of the message in number of milliseconds since the Unix epoch
paused	bool	True when this clock has been paused

Top

GameConfiguration

Represents a given game configuration.

GameConfiguration

Field	Type	Description
name	string	Valid only for lobby games
private	bool	Private games must have a password filled - valid only for lobby games
lurkable	bool	Is this game observable? Who can observe this game is defined in the observable_by field
rated	bool	Ranked game or not
min_players	int32	Minimum number of players for this game. It’s best to put min and max at the same value Valid only for lobby games
max_players	int32	Maximum number of players for this game. It’s best to put min and max at the same value Valid only for lobby games
min_karma	int32	Minimum karma to be able to join this game
first_player	int32	This will contain the human player seat number 1-based robot excluded. If 0, that means choose randomly
game_mode	GameConfiguration.GameMode	Type of game. Note: for invitation game, this mode is ignored as the game will default to ASYNCHRONOUS
timeout	int32	The player timer (in seconds)
data	bytes	Specific game data (to support options specific to a given game, like SW auto-redeploy)
require_first_user_data_round	bool	If true, this game type requires that the server initiates a first round where all players have to send their own user-data; aka a first simultaneous turn and the merger will be the first_player.
observable_by	GameConfiguration.Observers	Who is allowed to observe this game
min_rankscore	int32	Minimum of rank score to be able to join this game
main_variant	string	Contains the main variant of this game for computing ranking, you can pass an empty string if you want (if you have no variant). Please note that the underscore (‘_’) character is not allowed in variant names. If variant contains this character, it will be treated as the overall variant
extra_ranking_variants	string[]	Contains the extra variants for computing additional rankings. Even if there are some entries here, we’ll still compute the default variant ranking (ie ‘TT’ or ‘SW’). This field is optional for games without any variant. Please note that the underscore (‘_’) character is not allowed in variant names. If a variant contains this character, it will be treated as the overall variant
rules_engine_version	int32	Rules engine version, used to manage multiple versions of the game client. The server does not enforce version checks: it is the responsibility of the client to ensure it supports this given version before allowing the player to join this game
idle_time	int32	Set a duration in seconds for which the player is allowed to play her turn before being replaced by a robot (for this action). Set zero to disable this timer, in which case only the player clock will be used.

Top

GameCreatedRequest

Confirmation that a game has been created.

If the game is an invitation, all clients need to accept or decline it by sending an AnswerInvitationRequest. An invitation game can be detected by having invited_by containing the local_id of the inviter (usually first entry of the players list).

Note also that you can access the game configuration through the details field.

More information can be found in Starting the Game section.

S -> C

• request_number: 404

• field_name: game_created_request

In response to:

• EngageGameWithFriendsRequest

• LobbyJoinGameRequest: when last player joins

• LobbyStartGameRequest: early start

GameCreatedRequest

Field	Type	Description
local_player_id	int32	Your local player id
invited_by	int32	This will the local id if the game resulted from an invitation from this player. This will be 0 if the game is a lobby game
details	GameDetails	Full details about this created game

Top

GameDetails

Represents a given Game.

GameDetails

Field	Type	Description
game_id	int64	The game reference
players	com.daysofwonder.Player[]	Players in the game
configuration	GameConfiguration	Original game configuration
user_data	PlayerPregameData[]	Contains all the players user data sent in LobbyJoinGameRequest or LobbyCreateGameRequest

Top

GameForfeitRequest

Sent by the player when she wants to withdraw definitely from the current game. This might abort the whole game if all players have timed out, forfeited or left, in which case the clients will receive a GameAbortedRequest after receiving a GameForfeitedRequest.

More information can be found in Forfeit section.

C -> S

• request_number: 513

• field_name: game_forfeit_request

Possible Responses:

• GameForfeitedRequest

• ErrorRequest: UNKNOWN_GAME (3)

• ErrorRequest: NOT_YOUR_INVITATION (11)

GameForfeitRequest

Field	Type	Description
game_id	int64	System assigned game id

Top

GameForfeitedRequest

Sent by the server upon reception of a GameForfeitRequest to all the connected players, or if all players in a game have timed out.

More information can be found in Forfeit section.

S -> C

• request_number: 514

• field_name: game_forfeited_request

In response to:

• GameForfeitRequest

GameForfeitedRequest

Field	Type	Description
game_id	int64	System assigned game id
player_id	int32	The player that forfeited or aborted the game
aborted	bool	true if the game is fully aborted, false if the player forfeited

Top

GameList

List of Games, as used in the LobbyGameListRequest and ObservableGameListRequest.

GameList

Field	Type	Description
games	GameDetails[]	List of games

Top

GameNotification

This is the message that will be sent to the async players (ie players not connected to the server) as the payload parameter of the push notification when something happens in the game.

Note: the actionKey, localizedKey and localized arguments of a notification are configured in the server configuration file.

GameNotification

Field	Type	Description
game_id	int64	The ID of the game this notification was sent for
event	GameNotification.Event	Type of notification
turn_index	int32	The current turn index if in a game
recipientDowId	int32	Global player id of the recipient (to discard misplaced notifications)

Top

GameObservedRequest

Sent by the server after receiving a StartObserveGameRequest or a StopObserveGameRequest.

More information can be found in Observing a Game or Game Observation section.

S -> C

• request_number: 652

• field_name: game_observed_request

In response to:

• StartObserveGameRequest

• StopObserveGameRequest

GameObservedRequest

Field	Type	Description
game_id	int64	The game to observe / stop observing
status	GameObservedRequest.Status	If OK, the observe starts (or stops), otherwise it fails with this status
game_status	StatusReport	The latest known game status, this contains all the information about this game. This is valid only if status == OK

Top

GameOutcomeConfirmationRequest

Sent by a client to validate it displayed the outcome to the player.

More information can be found in Game Over section.

C -> S

• request_number: 522

• field_name: game_outcome_confirmation_request

In response to:

• GameOutcomeRequest

GameOutcomeConfirmationRequest

Field	Type	Description
game_id	int64	System assigned game id
player_id	int32	The local player id that confirms the game outcome

Top

GameOutcomeRequest

Sent by the server to all present players after receiving a GameOverRequest. It allows the client to display ranking updates, achievements earned, final scores. Non present players can get access to the same information in the game status report from a WhatsNewPussycatRequest.

More information can be found in Game Over section.

S -> C

• request_number: 508

• field_name: game_outcome_request

In response to:

• GameOverRequest

Possible Responses:

• GameOutcomeConfirmationRequest

GameOutcomeRequest

Field	Type	Description
game_id	int64	System assigned game id
ranking_update	com.daysofwonder.PlayerRankingUpdate[]	This contains the ranking change for the players, note there can be more than one entry per player if you submitted more than one variant in the GameOverRequest
achievements_awarded	com.daysofwonder.PlayerAchievementUpdate[]	This contains the list of awarded achievements per player
karma_update	KarmaUpdate[]	Contains the increase/decrease in karma of a given player global id
data	bytes	Custom game data to be sent to other players

Top

GameOverRequest

Sent by the last playing player to the server with the game results to signal that the game is over. The game will then be in state Outcome and send back GameOutcomeRequest. Upon a timeout or reception of GameOutcomeConfirmationRequest of all players, then the game will be in GameOver state and won’t be reported to WhatsNewPussycatRequest anymore.

More information can be found in Game Over section.

C -> S

• request_number: 507

• field_name: game_over_request

Possible Responses:

• GameOutcomeRequest

• ErrorRequest: UNKNOWN_GAME (3)

GameOverRequest

Field	Type	Description
game_id	int64	System assigned game id
achievements_awarded	com.daysofwonder.PlayerAchievementUpdate[]	This contains the list of awarded achievements per player
data	bytes	Custom game data to be sent to other players
finalScores	com.daysofwonder.FinalScore[]	Winners. This field is mandatory for all players
is_ranked	bool	Is that game ranked finally? This member is deprecated: please use GameConfiguration.rated instead
variants	string[]	Contains the extra variants for computing additional rankings, even if there are some entries here, we’ll still compute the default variant ranking (ie ‘TT’ or ‘SW’). You can still pass it as an empty string if you want. This member is deprecated, please provide variants directly in GameConfiguration

Top

GameStateUpdatedRequest

Sent by the server when it receives a CommitActionRequest from a player when the broadcast parameter is set to true. It is sent to all the present players and observers.

S -> C

• request_number: 568

• field_name: game_state_updated_request

In response to:

• CommitActionRequest

GameStateUpdatedRequest

Field	Type	Description
game_id	int64	System assigned game id
player_id	int32	Local player id of the acting player. In case of a robot hosted on a different player device, this should be the robot impersonating local player id
turn_index	int32	Monotonically incremented turn index after each round by the server, this should allow the client to know which request it should act on. It has the same value as provided in last CommitActionRequest, if correct
state	bytes	Current state of the game after last action
interruption_window_duration	int32	Define interruption window time frame (ms) of the interruptible turn for the previous action
interruption_player	int32[]	Which players are authorized to interrupt the previous action
clock	StatusReport.PlayerClock[]	List of all player clocks

Top

GameStatusReportRequest

Sent by the server in response to a WhatsNewPussycatRequest

More information can be found in Current Games Information section.

S -> C

• request_number: 512

• field_name: game_status_report_request

In response to:

• WhatsNewPussycatRequest

GameStatusReportRequest

Field	Type	Description
reports	StatusReport[]	All the game statuses

Top

GameUserDataUpdatedRequest

Sent by the server when it receives an UpdateUserDataRequest from a player when the broadcast parameter is set to true. It is sent to all the present players and observers.

More information can be found in Simultaneous Game Turn section.

S -> C

• request_number: 569

• field_name: game_user_data_updated_request

In response to:

• UpdateUserDataRequest

GameUserDataUpdatedRequest

Field	Type	Description
game_id	int64	System assigned game id
player_id	int32	Local player id of the acting player. In case of a robot hosted on a different player device, this should be the robot impersonating local player id
turn_index	int32	Monotonically incremented turn index after each round by the server, this should allow the client to know which request it should act on. It has the same value as provided in last CommitActionRequest, if correct
user_data	PlayerPregameData[]	Current user data if in simultaneous turn

Top

GetChatHistoryRequest

Sent to retrieve the chat history of the lobby or of a game.

More information about the chat can be found in Chat section.

C -> S

• request_number: 535

• field_name: get_chat_history_request

Possible Responses:

• ClientChatHistoryRequest

GetChatHistoryRequest

Field	Type	Description
game_id	int64	System assigned game id (set 0 or leave empty to get the lobby’s messages history)

Top

GetClocksRequest

Sent by the client when one client wants to get the values of the player clocks.

More information can be found in Player Clocks Status section.

C -> S

• request_number: 546

• field_name: get_clocks_request

Possible Responses:

• ClocksStatusRequest

• ErrorRequest: UNKNOWN_GAME (3)

GetClocksRequest

Field	Type	Description
game_id	int64	Game id to retrieve clocks from

Top

InterruptActionErrorRequest

Sent by the server when an error occurred during the interruption.

S -> C

• request_number: 573

• field_name: interrupt_action_error_request

In response to:

• InterruptActionRequest

InterruptActionErrorRequest

Field	Type	Description
game_id	int64	The game in which this interruption has failed
error_code	InterruptActionErrorRequest.Error	The error type

Top

InterruptActionRequest

Sent by the client during interrupted turn.

More information can be found in Interruptions section.

C -> S

• request_number: 570

• field_name: interrupt_action_request

Possible Responses:

• ActionInterruptedRequest

• InterruptActionErrorRequest

InterruptActionRequest

Field	Type	Description
game_id	int64	System assigned game id
player_id	int32	Local id of the player interrupting the action
turn_index	int32	Turn index, as provided by ActionCommitedRequest
interruption_data	bytes	Interruption is done with this data. It will be relayed by ActionInterruptedRequest, and when asking to merge with an ActionRequiredRequest
no_more_interruption	bool	If true, the server will stop the interruption phase after receiving this interruption. If false, it will continue until interruption_window_duration (cf CommitActionRequest)

Top

InterruptionOverRequest

Sent by the server to inform the end of the interruption period for this turn.

More information can be found in Interruptions section.

S -> C

• request_number: 572

• field_name: interruption_over_request

InterruptionOverRequest

Field	Type	Description
game_id	int64	The game id where this event happened
turn_index	int32	The turn index at which the interruption turn ends

Top

InvitationAnsweredRequest

Sent by the server to all participants in the invitation each time one of the players sends an AnswerInvitationRequest.

More information can be found in Invitation section.

S -> C

• request_number: 541

• field_name: invitation_answered_request

In response to:

• AnswerInvitationRequest

InvitationAnsweredRequest

Field	Type	Description
game_id	int64	Game id of the accepted/declined invitation
accept	bool	true means invitee accepted the invitation, false otherwise
invitee	com.daysofwonder.Player	Player that accepted or refused this invitation

Top

InvitationDetails

Information about an invitation.

InvitationDetails

Field	Type	Description
invited_by	int32	Player local id of the inviter (in the list of the players of the game)
confirmation	InvitationDetails.Confirmation[]	List of players that accepted (or declined) the invitation. A player not listed means that she didn’t yet confirm or decline
timeout	int64	How long this invitation is valid for (in seconds). Add this to game_started_at to know if it’s expired or not

Top

InvitationDetails.Confirmation

InvitationDetails.Confirmation

Field	Type	Description
player_id	int32	Local ID of the player who answered the invitation
accepted	bool	true if the player accepted the invitation, false otherwise

Top

KarmaUpdate

Give the change in karma of a given player_id at the end of game.

KarmaUpdate

Field	Type	Description
player_id	int32	Global ID of the player whose karma has been updated
old_karma	int32	The previous value of the karma
new_karma	int32	The current value of the karma, according to game outcome and player behavior during the game

Top

LeaveSyncGameRequest

Sent by the client to leave a synchronous game. This will allow the server to schedule a robot for this player. In response the server will broadcast a PlayerReplacedRequest.

C -> S

• request_number: 538

• field_name: leave_sync_game_request

Possible Responses:

• PlayerReplacedRequest

• ErrorRequest: UNKNOWN_GAME (3)

LeaveSyncGameRequest

Field	Type	Description
game_id	int64	The game where this event happened

Top

LobbyCreateGameRequest

Create an open game in the lobby for other players to join. The player must be in the lobby first. Note: this request might fail if the player has too many games in progress, in which case the server will return an ErrorRequest with error TOO_MANY_OFFERS.

More information can be found in Creating an Open Game section.

C -> S

• request_number: 607

• field_name: lobby_create_game_request

Possible Responses:

• LobbyGameCreatedRequest

• ErrorRequest: TOO_MANY_OFFERS (5)

LobbyCreateGameRequest

Field	Type	Description
configuration	GameConfiguration	Game configuration where to specify number of players, private data, etc…
password	string	Optional password to be used only when the game is private. A blank password is considered as ‘no password’
user_data	bytes	This specific user data for this game. This can be used to encode this player capabilities
initial_state	bytes	In case you need to have an initial state (ie game data) when the first player has to play, fill this field
initial_summary_data	bytes	If you need to have an initial summary, for display purposes

Top

LobbyEnteredRequest

Sent by the server to confirm that the client entered the lobby in response to EnterLobbyRequest.

More information can be found in Entering section.

S -> C

• request_number: 601

• field_name: lobby_entered_request

In response to:

• EnterLobbyRequest

LobbyExitedRequest

Sent by the server to confirm that the client has exited the lobby.

More information can be found in Exiting section.

S -> C

• request_number: 603

• field_name: lobby_exited_request

In response to:

• ExitLobbyRequest

LobbyGameCreatedRequest

Sent by the server after receiving a LobbyCreateGameRequest for confirmation that the operation succeeded.

More information can be found in Creating an Open Game section.

S -> C

• request_number: 608

• field_name: lobby_game_created_request

In response to:

• LobbyCreateGameRequest

LobbyGameCreatedRequest

Field	Type	Description
game	GameDetails	All the information about the given created game

Top

LobbyGameListRequest

Sent by the server from time to time to send the currently open game list.

More information can be found in Open Game List section.

S -> C

• request_number: 609

• field_name: lobby_game_list_request

LobbyGameListRequest

Field	Type	Description
game_list	bytes	This is a ‘Deflate’ compressed version of the GameList message, check zlib for a native deflate implementation

Top

LobbyJoinDeniedRequest

Sent to the joining player if the server denies the join.

More information can be found in Joining an Open Game section.

S -> C

• request_number: 612

• field_name: lobby_join_denied_request

In response to:

• LobbyJoinGameRequest

LobbyJoinDeniedRequest

Field	Type	Description
game_id	int64	Game to join
cause	LobbyJoinDeniedRequest.JoinError	Cause of the denial

Top

LobbyJoinGameRequest

Join an open game in the lobby. The player must be in the lobby first. This request can return a LobbyJoinDeniedRequest if joining is denied for instance if:

• player hasn’t enough Karma

• game is full

• player gave an incorrect private game password

• player is in the game creator ignore list

• player hasn’t enough rank score

More information can be found in Joining an Open Game section.

C -> S

• request_number: 610

• field_name: lobby_join_game_request

Possible Responses:

• LobbyNewPlayerRequest

• LobbyJoinDeniedRequest

• ErrorRequest: UNKNOWN_GAME (3)

LobbyJoinGameRequest

Field	Type	Description
game_id	int64	Game to join
password	string	Optional password to be used only when the game is private
user_data	bytes	This specific user data for this game. This can be used to encode this player capabilities

Top

LobbyLeaveGameRequest

Sent by the client to leave a waiting open game.

More information can be found in Leaving an Open Game section.

C -> S

• request_number: 613

• field_name: lobby_leave_game_request

Possible Responses:

• LobbyPlayerLeftGameRequest

• ErrorRequest: UNKNOWN_GAME (3)

LobbyLeaveGameRequest

Field	Type	Description
game_id	int64	Game to leave

Top

LobbyNewPlayerRequest

Sent to all the players present in the game (and the joining player) when a player joins a given game and she succeeds.

More information can be found in Joining an Open Game section.

S -> C

• request_number: 611

• field_name: lobby_new_player_request

In response to:

• LobbyJoinGameRequest

LobbyNewPlayerRequest

Field	Type	Description
game	GameDetails	Joined game (includes all the players)
joining_player	int32	Unique global id of the player that just joined the game (it should normally be always the last player of game.players)

Top

LobbyPlayerInfoRequest

Sent by the server in response of the AskPlayerInfoRequest when in the lobby. It contains the full details of a given player.

More information can be found in Player Information section.

S -> C

• request_number: 606

• field_name: lobby_player_info_request

In response to:

• AskPlayerInfoRequest

LobbyPlayerInfoRequest

Field	Type	Description
player	com.daysofwonder.Player	The player information asked from AskPlayerInfoRequest in the lobby. This field can be omitted if the given player is not in the lobby

Top

LobbyPlayerLeftGameRequest

Sent by the server in response to the LobbyLeaveGameRequest to all the players in the game and the leaving player.

More information can be found in Leaving an Open Game section.

S -> C

• request_number: 614

• field_name: lobby_player_left_game_request

In response to:

• LobbyLeaveGameRequest

LobbyPlayerLeftGameRequest

Field	Type	Description
game	GameDetails	Game the player just left
leaving_player	com.daysofwonder.Player	Leaving player

Top

LobbyPlayerListRequest

Sent by the server from time to time to send the whole list of Players in the lobby.

Note that the player_list field is a byte array resulting of the compression of the PlayerList message.

More information can be found in Player List section.

S -> C

• request_number: 604

• field_name: lobby_player_list_request

LobbyPlayerListRequest

Field	Type	Description
player_list	bytes	This is a ‘Deflate’ compressed version of the LobbyPlayerListRequest.PlayerList message, check zlib for a native deflate implementation

Top

LobbyPlayerListRequest.PlayerList

List of players

LobbyPlayerListRequest.PlayerList

Field	Type	Description
players	SmallPlayer[]	Simplified players

Top

LobbyStartGameDeniedRequest

Sent to the player if the server denies the start of the game.

More information can be found in Starting the Game section.

S -> C

• request_number: 616

• field_name: lobby_start_game_denied_request

In response to:

• LobbyStartGameRequest

LobbyStartGameDeniedRequest

Field	Type	Description
game_id	int64	Game to start
cause	LobbyStartGameDeniedRequest.StartError	Cause of the denial

Top

LobbyStartGameRequest

Sent by the client to start early a game irrespective of the GameConfiguration.max_players (this means that one can start a lobby game before this one is complete).

Only the game creator can start the game. It is not possible to start a game containing only the creator.

This request can return a LobbyStartGameDeniedRequest if starting is denied for instance if:

• not enough player

• game is unknown

• another player tries to start the game instead of creator

More information can be found in Starting the Game section.

C -> S

• request_number: 615

• field_name: lobby_start_game_request

Possible Responses:

• LobbyStartGameDeniedRequest

LobbyStartGameRequest

Field	Type	Description
game_id	int64	Game to start
fillWithRobots	bool	Fill with robot, you can choose to add to the max the remaining spot with a robot
data	bytes	Override game configuration data (specify which bot level, color, …)

Top

MulticastChatRequest

Sends a chat to the server, the server will then multicast the text to the other players in the given game. If no game_id is given, then the chat message is sent to the lobby (provided the connected user entered the lobby).

The code parameter indicates a premade message id. When using codes, please also provide a text value in default locale so that older clients can display something. Codes between 1 and 255 are reserved, use a higher value. The code 0 means the message was not a premade message.

More information can be found in Chat section.

C -> S

• request_number: 524

• field_name: multicast_chat_request

Possible Responses:

• ClientChatRequest

• ClientChatBlockedRequest

• ErrorRequest: UNKNOWN_GAME (3)

MulticastChatRequest

Field	Type	Description
game_id	int64	System assigned game id (do not fill to send to the lobby)
text	string	Text chat
recipient_ids	int32[]	List of local player ids that will receive the data for non empty game_id. List of global player ids that will receive the data for empty game_id (ie lobby) If empty, then the chat is broadcast to all the players present
code	int32	Code for premade messages, please also provide the text in default locale. Codes between 0 and 255 are reserved

Top

MulticastDataRequest

A player can decide to send arbitrary data to a set or subset of the players in the same game.

More information can be found in Multicast section.

C -> S

• request_number: 502

• field_name: multicast_data_request

Possible Responses:

• ClientDataRequest

• ErrorRequest: UNKNOWN_GAME (3)

MulticastDataRequest

Field	Type	Description
game_id	int64	System assigned game id
data	bytes	Any data that will be sent verbatim to the recipient_ids
recipient_ids	int32[]	List of local player ids that will receive the data
present_players_only	bool	Filter out people that are not ‘present’ at the moment. If false, then absent users will be notified by a push notification

Top

ObservableGameListRequest

Sent by the server on a regular basis to client that subscribed to it.

More information can be found in Observable Game List section.

S -> C

• request_number: 622

• field_name: observable_game_list_request

ObservableGameListRequest

Field	Type	Description
game_list	bytes	This is a ‘Deflate’ compressed version of the GameList message, check zlib for a native deflate implementation

Top

PlayerIdleProgressRequest

If an idle timer was set in game configuration, the server will send this request regularly to inform of the idle timer progress.

S -> C

• request_number: 509

• field_name: player_idle_progress_request

PlayerIdleProgressRequest

Field	Type	Description
game_id	int64	System assigned game id
player_ids	int32[]	Local ids of players that should play and still made no action
progress	int32	Percentage of the timer that has been consumed (between 0 and 100)
initial	int32	Current idle timer configured from New game or CommitRequest
remaining	int32	Approximate time remaining for this idle timer: initial * (100 - progress) / 100

Top

PlayerInfoRequest

Sent by the server in response of the AskAnyPlayerInfoRequest when not in lobby. It contains the full details of a given player.

S -> C

• request_number: 631

• field_name: player_info_request

In response to:

• AskAnyPlayerInfoRequest

PlayerInfoRequest

Field	Type	Description
player	com.daysofwonder.Player	The player information asked from AskAnyPlayerInfoRequest outside of lobby

Top

PlayerPregameData

Contains specific opaque data per player (like capabilities) that can be sent when joining/starting a game or accepting an invitation.

PlayerPregameData

Field	Type	Description
player_id	int32	Global player id
data	bytes	This player opaque data

Top

PlayerPresenceUpdateRequest

Sent by the server when one or more player presence status changes. In the current implementation, this message will contain only one presence status change (ie for only one given player).

The presence mechanism is a best effort system, so it can happen that presence/absence messages are sent while in fact the player is indeed absent/present. The client needs to keep presence information, and update presence or absence indicators based on this message (and also if it receives multicast data from a given sender).

All present/absent ids are local id to the game Presence update time resolution is 5s by default, so presence won’t be noticed until this delay.

More information can be found in Presence section.

S -> C

• request_number: 506

• field_name: player_presence_update_request

PlayerPresenceUpdateRequest

Field	Type	Description
game_id	int64	System assigned game id
present	int32[]	Those players local-game-id are now present
absent	int32[]	Those players local-game-id are now absent
in_game	int32[]	Valid when game_id is set, contains the set of players that declared being inside this game_id by sending a SwitchedToGameRequest

Top

PlayerReplacedRequest

Sent by the server when a player has been replaced by a robot, or when the player comes back (in Synchronous games).

More information can be found in Robots section.

S -> C

• request_number: 537

• field_name: player_replaced_request

In response to:

• LeaveSyncGameRequest

PlayerReplacedRequest

Field	Type	Description
game_id	int64	The game where this event happened
player_id	int32	Local id of the player that has been replaced or replaces
become_robot	bool	true when the player is replaced by a robot, false if the reverse
status	PlayerTimeoutRequest.PlayerStatus	Does this player timed out or forfeited? Valid only when become_robot is true

Top

PlayerTimeoutRequest

If the server never got a CommitActionRequest from the “active player” in the required time, or this player forfeited, this message is sent to the next player in turn with the hope that it could ever implement a bot that could take this player’s turn.

More information can be found in Robots section.

S -> C

• request_number: 504

• field_name: player_timeout_request

Possible Responses:

• CommitActionRequest

PlayerTimeoutRequest

Field	Type	Description
game_id	int64	System assigned game id
state	bytes	Last game state before timeout
offender_id	int32	Local player id of the player that timed out
players	com.daysofwonder.Player[]	List of players (in no particular order) in this game
next_player_ids	int32[]	List of the next player local ids in turn (the receiving player will be the first one)
status	PlayerTimeoutRequest.PlayerStatus	Does this player timed out or forfeited?
turn_index	int32	Monotonically incremented turn index after each round by the server, this should allow the client to know which request it should act on. It has the same value as provided in last CommitActionRequest, if correct
game_status	GameStatus	Whether we’re IN_PROGRESS or FIRST_USER_DATA_ROUND
user_data	PlayerPregameData[]	User-data sent during simultaneous turn: in case the ActionRequiredRequest merger did not respond, a robot will have to perform the merge of all user data in the latest state
interruption_data	PlayerPregameData[]	Interruption-data sent during interruption turn, in case the ActionRequiredRequest merger did not respond, a robot will have to perform the merge of all interruption data in the latest state

Top

RegisterPresenceRequest

Sent by the client to monitor the presence of a set of players. Once sent and when subscribed to the presence system, the client will receive presence changes for those players.

More information can be found in Presence section.

C -> S

• request_number: 527

• field_name: register_presence_request

RegisterPresenceRequest

Field	Type	Description
player_ids	int32[]	List of global player ids to monitor presence of

Top

ResumeSyncGameRequest

Sent by the client to rejoin a left game. In response the server will broadcast a PlayerReplacedRequest.

C -> S

• request_number: 539

• field_name: resume_sync_game_request

Possible Responses:

• PlayerReplacedRequest

• ErrorRequest: UNKNOWN_GAME (3)

ResumeSyncGameRequest

Field	Type	Description
game_id	int64	The game where this event happened

Top

ServerStatisticsRequest

Sent by the server during statistics broadcast, or after an initial AskServerStatisticsRequest

More information can be found in Server Statistics section.

S -> C

• request_number: 409

• field_name: server_statistics_request

In response to:

• AskServerStatisticsRequest

ServerStatisticsRequest

Field	Type	Description
hosted_games	int32	Total number of games running
players	int32	Total number of players engaged into those games
connected_players	int32	Total number of players currently connected

Top

Session

Documentation can be found in Session section.

Session

Field	Type	Description
id	int64	Server-assigned ID of a client session

Top

SmallPlayer

This is a smaller player structure than the regular Game.Player, this is used in the streaming of player lists. If you want more information about a player, use AskPlayerInfoRequest.

SmallPlayer

Field	Type	Description
w_w_w_id	int32	Unique global id
name	string	Player name
karma	int32	Player current karma
rank_score	double	Player current rank score (ex: 1500.00)
rank	int32	Player current rank (ex: #1)
nb_games	int32	Number of games played
language	int32	Language code of this player
partner_user	com.daysofwonder.PartnerUser	Player’s partner information given at auth
avatar	com.daysofwonder.Avatar	Player avatar

Top

StartObserveGameRequest

Send this to observe a specific game. In return the server will send the GameObservedRequest, and if successful the stream of observed events as if the player was part of the game. To stop observing a game, send a StopObserveGameRequest.

More information can be found in Observing a Game or Game Observation section.

C -> S

• request_number: 650

• field_name: start_observe_game_request

Possible Responses:

• GameObservedRequest: OK (1)

• GameObservedRequest: IN_GAME_ERROR (2)

• GameObservedRequest: NO_SUCH_GAME_ERROR (3)

• GameObservedRequest: FORBIDDEN_ERROR (4)

• GameObservedRequest: GAME_NOT_STARTED (5)

StartObserveGameRequest

Field	Type	Description
game_id	int64	The game to observe

Top

StatusReport

Game full state.

More information can be found in Current Games Information section.

StatusReport

Field	Type	Description
game_id	int64	ID of the game this report describes
status	GameStatus	Game status
data	bytes	Current data of the game as last committed
turn_id	int32	Local id of the player that must now play: ‘whose turn it is’. turn_id might refer to a player in the timed_out_players list, in which case another player might play for her (see active_player). The server has no preferences on the player that will play (anyone)
next_player_ids	int32[]	The ordered list (in action order) of the next player ids as sent by the last commit action message (the first one should be turn_id)
players	com.daysofwonder.Player[]	List of players (in no particular order) in this game
ranking_update	com.daysofwonder.PlayerRankingUpdate[]	This contains the ranking change for the players if the game is over (for karma updates, see below)
achievements_awarded	com.daysofwonder.PlayerAchievementUpdate[]	This contains the list of awarded achievements per players if the game is over
turn_timeout	int32	A timeout for this turn - this is be the clamped value (in seconds) sent during game creation
start_turn_time	int64	When the turn started for this player (in milliseconds unix timestamp). This is in fact at which time we decided to send this message
turn_index	int32	Monotonically incremented turn index after each round by the server. This should allow the client to know which request it should act on. It has the same value as provided in last CommitActionRequest, if correct
forfeiters	int32[]	Local ids of the player that forfeited (ie withdrawn)
timed_out_players	int32[]	All those players that have timed out in
configuration	GameConfiguration	This game configuration
clock	StatusReport.PlayerClock[]	List of all player clocks
active_player	int32	The player we actually expect an action from. Usually it is the same as turn_id, but this ‘active player’ is requested to play for her in case she has : * timed out (and thus is in timed_out_players list) * forfeited (and thus is in forfeiters list) * left (and thus is in left_players list)
left_players	int32[]	Local id of players that left a synchronous game and that have been replaced by a robot
user_data	PlayerPregameData[]	Optionally sent user pre-game data. Each chunk of data comes from the respective user LobbyCreateGame and LobbyJoinGame requests. Note that this list might be filled only during the first turn of the game
invitation	InvitationDetails	Details about the invitation status. This is valid only when status is WAITING_INVITATION
game_created_at	int64	Milliseconds since epoch time at which this game was created
player_user_data_updated	int32[]	List of the local player id of players that already updated their user data, in case of a game that has require_first_user_data_round at true or SIMULTANEOUS turn
summary_data	bytes	The last published summary data. This data should be kept small and should be a public summary of the data field to be displayed in things like game lists or small game summaries To publish a summary data, fill in the summary_data field in the CommitActionRequest
outcome_not_seen	int32[]	List of the players that have not yet confirmed the outcome. The UI shouldn’t present this game if the player is not in this list
karma_update	KarmaUpdate[]	Contains the increase/decrease of karma of a given player global id
interruption_window_duration	int32	Interruption window time frame (ms)
interruption_player	int32[]	Players authorized to do interruption action
interruption_remaining_duration	int32	Estimated remaining duration time of the interruption window
interruption_data	PlayerPregameData[]	When in an interruption turn: data already sent by interrupting players
player_user_data_required	int32[]	List of the local player id of players that are required to update their user data, with all players in case of a game that has require_first_user_data_round at true or this list is coming from CommitActionRequest.simultaneous_players when the simultaneous turn started.
idle_players	int32[]	Local ids of the players that are considered idle (ie players that haven’t yet sent their response after the idle timer expired)

Top

StatusReport.PlayerClock

A given player clock. The player_id is the local player id

StatusReport.PlayerClock

Field	Type	Description
player_id	int32	Local id of the player
clock	GameClock	Clock status of the player

Top

StopObserveGameRequest

Stop observing a game that the connected user was observing. This stops the stream of this game event.

More information can be found in Observing a Game or Game Observation section.

C -> S

• request_number: 651

• field_name: stop_observe_game_request

Possible Responses:

• GameObservedRequest: OK (1)

• GameObservedRequest: NO_SUCH_GAME_ERROR (3)

StopObserveGameRequest

Field	Type	Description
game_id	int64	The game to observe

Top

SubscribePresenceServiceRequest

Sent by the client to start monitoring the presence of players given by RegisterPresenceRequest. Once sent, the client will receive AsyncBuddyPresencePartialUpdateRequest whenever the presence of one or more player changes.

More information can be found in Presence section.

C -> S

• request_number: 532

• field_name: subscribe_presence_service_request

SubscribeToObservableGameListRequest

Sent by the client to start receiving the observable game list stream.

More information can be found in Observable Game List section.

C -> S

• request_number: 620

• field_name: subscribe_to_observable_game_list_request

Possible Responses:

• SubscribedToObservableGameListRequest

SubscribeToObservableGameListRequest

Field	Type	Description
subscribe	bool	true to subscribe, false to unsubscribe

Top

SubscribedToObservableGameListRequest

Sent by the server to confirm subscription or unsubscription.

More information can be found in Observable Game List section.

S -> C

• request_number: 621

• field_name: subscribed_to_observable_game_list_request

In response to:

• SubscribeToObservableGameListRequest

SubscribedToObservableGameListRequest

Field	Type	Description
subscribed	bool	true when subscribed, false when unsubscribed

Top

SwitchedToGameRequest

Sent by the client to inform the server presence system that the connected player just entered a specific game interface. Note: the server makes sure that the player can be only in one game at a time.

More information can be found in Switching to a Game section.

C -> S

• request_number: 534

• field_name: switched_to_game_request

SwitchedToGameRequest

Field	Type	Description
game_id	int64	The game id the player is switching to. In the case where the player doesn’t enter a given game but exits to another kind of UI, do not fill this value

Top

UnregisterPresenceRequest

Sent by the client to stop monitoring the presence of a player.

More information can be found in Presence section.

C -> S

• request_number: 528

• field_name: unregister_presence_request

UnregisterPresenceRequest

Field	Type	Description
player_ids	int32[]	List of global player ids to stop monitoring presence

Top

UnsubscribePresenceServiceRequest

Sent by the client to stop monitoring the presence of players given by RegisterPresenceRequest.

More information can be found in Presence section.

C -> S

• request_number: 533

• field_name: unsubscribe_presence_service_request

UpdateUserDataRequest

Sent by the client during Simultaneous turns to send data to the server.

More information can be found in Simultaneous Game Turn section.

C -> S

• request_number: 566

• field_name: update_user_data_request

Possible Responses:

• UserDataUpdatedRequest

• GameUserDataUpdatedRequest

In response to:

• UserDataUpdateRequiredRequest

UpdateUserDataRequest

Field	Type	Description
game_id	int64	System assigned game id
user_data	bytes	This specific user data for this game
player_id	int32	Who to play for (in case of hotswap)
expect_more_data	bool	Is this the last update? If true, then the player can send again a new user data which will replace the previously one sent. If false, this concludes the user data round for this user. The default (false) is to conclude the transaction for this player
broadcast	bool	Set to true if this action data should be broadcast through GameUserDataUpdatedRequest

Top

UserDataUpdateRequiredRequest

Sent by the server during Simultaneous turns to require user-data from players. This happens during simultaneous turns, or a first user data round: the server configuration for a game type specifies it (see reference.conf: first_user_data_round). Note that at this stage the game is in the state SIMULTANEOUS or FIRST_USER_DATA_ROUND.

More information can be found in Simultaneous Game Turn section.

S -> C

• request_number: 565

• field_name: user_update_data_required_request

Possible Responses:

• UpdateUserDataRequest

UserDataUpdateRequiredRequest

Field	Type	Description
game_id	int64	System assigned game id
turn_index	int32	The turn index this action is supposed to be played in. It is recommended to provide it. The correct value is passed in ActionRequiredRequest / PlayerTimeoutRequest / others
participant	int32[]	Ids of players supposed to provide UserData during this simultaneous turn
state	bytes	Last game state
pause_time	int32	The player’s clock will start after this delay (in seconds). This can be used to give time to play animations of previous actions before starting decreasing clock.

Top

UserDataUpdatedRequest

Sent by the server during Simultaneous turns to confirm user-data has been updated.

More information can be found in Simultaneous Game Turn section.

S -> C

• request_number: 567

• field_name: user_data_updated_request

In response to:

• UpdateUserDataRequest

UserDataUpdatedRequest

Field	Type	Description
game_id	int64	The game id where this event happened
user_data	bytes	This specific user data for this game
player_id	int32	Who updated

Top

WhatsNewPussycatRequest

Sent by the client to get an up-to-date status of all data of either a given game or for all games this player is part of.

More information can be found in Current Games Information section.

C -> S

• request_number: 511

• field_name: whats_new_pussycat_request

Possible Responses:

• GameStatusReportRequest

WhatsNewPussycatRequest

Field	Type	Description
game_id	int64	If not transmitted (or 0) returns messages for all current games
summary_data_only	bool	If true (defaults to false), the returned StatusReport will not provide data of the last CommitActionRequest, but only the summary_data. This is useful when you don’t need the whole data so you can request a smaller packet (for instance, for display purposes)

Top

Enums

AsyncBuddyManagementRequest.Operation

Buddy management operation type

AsyncBuddyManagementRequest.Operation

Name	Number	Description
NOOP	0	Do not use
ADD	1	Add a player to the buddy list
REMOVE	2	Remove a player from the buddy list

Top

AsyncConnectionErrorRequest.ConnectionError

List of possible errors during connection/authentication

AsyncConnectionErrorRequest.ConnectionError

Name	Number	Description
RESERVED	0	Do not use
ACCESS_DENIED	1	Wrong password or login
SERVERFULL_ERROR	2	Service is over-capacity, not accepting new connections
MAINTENANCE_MODE	3	Maintenance mode, not accepting new connections
NEED_AUTHENTICATION	4	No credentials provided
UNKNOWN_GAME_TYPE	5	This service doesn’t run this game
SERVER_ERROR	6	Unknown error from the server
BANNED	7	This player has been either temporarily or definitely banned

Top

AsyncIgnoreManagementRequest.Operation

Ignore list management operations

AsyncIgnoreManagementRequest.Operation

Name	Number	Description
NOOP	0	Do not use
ADD	1	Add a player to the ignore list
REMOVE	2	Remove a player from the ignore list

Top

ErrorCode

List of possible errors.

ErrorCode

Name	Number	Description
NO_ERROR	0	No error was encountered, but the error field was mandatory
NOT_YOUR_TURN	1	Player tried to play but it was not her turn (or she was not in the list of possible players)
UNKNOWN_PLAYER	2	An invalid player local ID has been provided in a field
UNKNOWN_GAME	3	The provided game ID does not exist, or the player is not part of this game
MAINTENANCE_MODE	4	The server cannot respond due to temporary maintenance operation
TOO_MANY_OFFERS	5	The current player reached the maximum number of games concurrently running
UNKNOWN_DEVICE_TOKEN	6	Tried to perform an action on an unknown Token (or the Token is not bound to the current player)
YOU_FORFEITED	7	Sent in response to CommitActionRequest when player has already forfeited
YOU_RAN_OUT_OF_TIME	8	Sent in response to CommitActionRequest when player has no time left to play
YOU_LEFT	9	Sent in response to CommitActionRequest when player has left the game
PLAYER_ALREADY_IN_LOBBY	10	Sent in response to EnterLobbyRequest when sent multiple times
NOT_YOUR_INVITATION	11	Sent in response to a GameForfeitRequest of an invitation if sender is not inviter
INVITATION_DENIED	13	One of the invited player has the game creator in his ignore list - the invitation is automatically cancelled
BAD_REQUEST	14	The request had invalid parameters
WRONG_STATE	15	The request was sent while the game is in a different state that doesn’t know how to process it
DUPLICATE_SESSION	16	We’re aborting this connection because another session from a different device has opened for the same user
PLAYER_NOT_IN_LOBBY	17	The current request meant something if the player was in the lobby, but she’s not anymore, request is ignored
INDEX_CONFLICT	18	The provided turn index doesn’t match the current turn index

Top

GameConfiguration.GameMode

Type of game

GameConfiguration.GameMode

Name	Number	Description
DEFAULT_MODE	0	Do not use
SYNCHRONOUS	1	Synchronous game: leaving players are replaced by a robot
ASYNCHRONOUS	2	Asynchronous game: leaving players will not be replaced, active players’ clocks will keep running

Top

GameConfiguration.Observers

Type of observers

GameConfiguration.Observers

Name	Number	Description
DEFAULT_OBSERVERS	0	Default is ALL
ALL	1	Game is observable by every user not in a creator’s ignore list
BUDDIES	2	Game is only observable by creator’s buddies
TOURNAMENT	3	Not implemented - same as ALL

Top

GameNotification.Event

GameNotification.Event

Name	Number	Description
NO_EVENT	0	Do not use
YOUR_TURN	1	Sent to the current player in a game
GAME_OVER	2	Sent to a player to inform her that the game ended. When all players saw the outcome, the game can be deleted
YOUR_TURN_INVITE	3	Sent to the current player of an invitation game
YOUR_TURN_ROBOT	4	Sent to the player selected to play a robot for another player
CONFIRM_INVITATION	5	Sent to a player that has been invited to a game so that she can confirm or deny the invitation
INVITEE_ACCEPTED	6	Sent to a player to inform her that an invitee confirmed the invitation
INVITEE_DECLINED	7	Sent to a player to inform her that an invitee denied the invitation

Top

GameObservedRequest.Status

GameObservedRequest.Status

Name	Number	Description
RESERVED	0	Do not use
OK	1	Everything is ok
IN_GAME_ERROR	2	You’re already playing in this game
NO_SUCH_GAME_ERROR	3	There’s no game with this id
FORBIDDEN_ERROR	4	This game prevented observer to observe
GAME_NOT_STARTED	5	Game has been created, but is not yet started
GAME_OVER	6	Game is now over
NOT_IN_LOBBY	7	Cannot observe a game if not in lobby

Top

GameStatus

Game internal status.

GameStatus

Name	Number	Description
RESERVED	0	Do not use
IN_PROGRESS	1	Game is running
OVER	2	Game is now over
NOT_STARTED	3	Game hasn’t started yet
ABORTED	4	Cause is player forfeited
OUTCOME	5	Game is not over yet, waiting for players to see the outcome
PLAYER_TIMEOUT	6	One (or more) player has timed out, someone needs to do something
ABORTING	7	Game is not over yet, waiting for player to see the abort notification
WAITING_INVITATION	8	Game still waits for some player confirmation
FIRST_USER_DATA_ROUND	9	For game that requires a special first user data round, it is the first state after NOT_STARTED and before IN_PROGRESS
SIMULTANEOUS	10	Game is in a simultaneous turn
INTERRUPTIBLE	11	Game is in an interruption turn

Top

InterruptActionErrorRequest.Error

Possible errors returned by the server when failing to perform an interruption

InterruptActionErrorRequest.Error

Name	Number	Description
UNKNOWN	0	An unknown error occurred
BAD_STATE	1	Provided empty interruption data
INDEX_CONFLICT	2	Wrong turn_index provided
FORBIDDEN	3	Player is not allowed to interrupt the previous action

Top

LobbyJoinDeniedRequest.JoinError

LobbyJoinDeniedRequest.JoinError

Name	Number	Description
RESERVED	0	Do not use
SERVER_ERROR	1	The server experienced an unexpected error
NOT_ENOUGH_KARMA	2	The minimum karma requirement as defined in configuration is not fulfilled
TOO_MANY_GAMES	3	The joining player already has the maximum number of games concurrently running for a single player
GAME_FULL	4	The game’s maximum number of player has already been reached
IGNORED	5	Tried to join a game where a player ignores the joining user
PASSWORD_MISMATCH	6	The provided password does not match the game password
UNKNOWN_GAME	7	There is no such open game ID in the Lobby
PLAYER_DUPLICATE	8	The joining player already is in the game’s player list
ACCESS_DENIED	9	Player is not authorized to join this game
NOT_ENOUGH_RANKSCORE	10	The minimum rankscore requirement as defined in configuration is not fulfilled
NOT_ENOUGH_RANKED_GAMES_PLAYED	11	The minimum number of ranked games played required required by the configuration is not reached

Top

LobbyStartGameDeniedRequest.StartError

LobbyStartGameDeniedRequest.StartError

Name	Number	Description
RESERVED	0	Do not use
SERVER_ERROR	1	The server experienced an unexpected error
UNKNOWN_GAME	2	Tried to start a game ID unknown to the server
NOT_ENOUGH_PLAYER	3	Not enough players to start the game (check GameConfiguration.min_players)
ACCESS_DENIED	4	If another player tries to start instead of creator

Top

PlayerTimeoutRequest.PlayerStatus

Status of an hot-swapped player

PlayerTimeoutRequest.PlayerStatus

Name	Number	Description
RESERVED	0	Do not use
TIMEOUT	1	Player ran out of time
FORFEIT	2	Player withdrew from the game
LEFT	3	Player left the game
ROBOT	4	Player is in fact a robot
IDLE	5	Player was inactive during her last turn

Top

common.proto

Messages

PartnerToken

Session token authentication.

More information can be found in Authentication with an OAuth2 access token section.

PartnerToken

Field	Type	Description
sessionToken	string	Use to authenticate with an access_token retrieved from the API
partner_user	com.daysofwonder.PartnerUser	User information relative to partner account

Top

game.proto

Messages

AccessRights

AccessRights

Field	Type	Description
rights	AccessRights.Right[]	Specific rights relative to a player

Top

AccessRights.Right

AccessRights.Right

Field	Type	Description
name	string	Name of the right
feature	string	Content of the right for the player

Top

Achievement

Achievement

Field	Type	Description
id	int32	Unique ID of the achievement
name	string	Title of the achievement
description	string	Description of the achievement
type	Achievement.Type	Kind of achievement
status	Achievement.Status	Current usage of the achievement
secret	bool	If the description should be hidden
tag	string	Alphanumerical unique identifier

Top

AchievementUpdate

AchievementUpdate

Field	Type	Description
achievement_updates	PlayerAchievementUpdate[]	List of awarded achievements

Top

Activity

Represents a type of activity.

Avatar

A player avatar description. In the order:

• if an image is provided, the avatar url is https://uploads.asmodee.net/builtin/<image>

• else, if a location is provided, then it is the avatar url

• else, if an id (strictly positive) is provided, the avatar url is https://uploads.asmodee.net/avatars/<id>

• else (nothing is provided), then a default avatar is used: https://uploads.asmodee.net/builtin/avatar-neutral.jpg

Avatar

Field	Type	Description
id	int32	Identifier for uploaded avatar (if no image or location is provided)
location	string	Avatar full url (if no image is provided)
image	string	Built-in avatar image name (with extension)

Top

FinalScore

Player position as indicated by the client at the end of a game. The rank computation uses this to order players.

FinalScore

Field	Type	Description
player_id	int32	Local player id
game_rank	int32	The game rank is used to compute global rankings. The lowest rank is the winner. More than one player can have the same game_rank
game_score	float	The game score is used to keep track of the user score in their game history.

Top

PartnerUser

Contains the information of a Player for a specific partner.

PartnerUser

Field	Type	Description
partner_id	string	ID of the partner
partner_display_name	string	User name in the partner’s system
partner_user_id	string	Unique ID of the user, in the partner’s system

Top

Player

Player record. More information can be found in Player section.

Player

Field	Type	Description
name	string	Player name
id	int32	Local player id
karma	int32	Player karma (0-100)
rank_score	double	Player ELO rank score
w_w_w_id	int32	Player unique global id
rank	int32	Player main rank
nb_games	int32	Player number of ranked games played
banned	bool	True if this player has been administratively banned for offense
blocked	bool	True if this player has been administratively prevented to chat
avatar	Avatar	Player avatar
language	int32	Player language (0- English, 1- French, 2- German)
tz	string	Player time zone
ranks	Rank[]	Player list of game variants ranks/rankscore
rights	AccessRights	Player list of online features
partner_user	PartnerUser	Player’s partner information given at auth

Top

PlayerAchievement

Player achievement.

PlayerAchievement

Field	Type	Description
achievement	Achievement	Awarded achievement
date	string	Date at which the achievement was awarded
game	string	Game the achievement belongs to

Top

PlayerAchievementUpdate

PlayerAchievementUpdate

Field	Type	Description
player_id	int32	The global id of the player whose achievements have been updated
achievements	PlayerAchievement[]	List of awarded achievements

Top

PlayerActivity

This represents an activity for a given player.

PlayerActivity

Field	Type	Description
user_id	int32	Global id of the user performing the activity
last_use	int64	Last time we detected this activity, timestamp in seconds since UNIX epoch
activity	Activity.Code	Activity integer code
client_id	string	Client used when activity changed
game_type	string	Game type (‘TT’, ‘SW’)
payload	string	String providing more information

Top

PlayerRankingUpdate

Rank evolution for a given player global id, usually given at the end of a game.

PlayerRankingUpdate

Field	Type	Description
player_id	int32	Global ID of the player whose ranking has been updated
delta	float	Difference in rankscore
old_rank_score	double	Rankscore before this update
new_rank_score	double	Rankscore now, after this update (should be old_rank_score + delta)
variant	string	Game variant in which the ranking has been updated, if relevant
old_nb_games	int32	Number of ranked games before this update
new_nb_games	int32	Number of ranked games now, after this update

Top

Rank

A player game variant rank information.

Rank

Field	Type	Description
rank	int32	Player’s rank position (lower is better, #1 is the best)
rank_score	float	Player’s ELO rankscore (higher is better, default is 1500)
name	string	Game (or variant) this ranking is from
nb_games	int32	Number of ranked games played

Top

RankingUpdate

List of ranking updates (one per player in a game usually).

RankingUpdate

Field	Type	Description
update	PlayerRankingUpdate[]	Ranking changes for players, at the outcome game

Top

Enums

Achievement.Status

Achievement.Status

Name	Number	Description
NEW	0	Achievement is in preparation and not visible/usable yet
ACTIVE	1	Achievement is valid and usable
RETIRED	2	Achievement is not awardable, but still visible in the profile

Top

Achievement.Type

Achievement.Type

Name	Number	Description
NORMAL	0	Regular achievement, most of them belong to this type
OFFICER	1	Related to Memoir’44
EVENT	3	Related to a special event (contest, tournament…)
COMMUNITY	4	Related to the Asmodee community, used by some websites

Top

Activity.Code

Activity.Code

Name	Number	Description
UNKNOWN	0	The server doesn’t know what the player is doing
DISCONNECTED	1	Player disconnected and did not update activity since then
IDLE	2	Player is connected to the server but not playing or in lobby or in any other state
LOBBY	3	Player is in the lobby
PLAYING_OFFLINE	4	Player is playing a game
PLAYING_ONLINE	5	Player is playing an online game
WAITING	6	Player is waiting for other players to start a game
OTHER	7	User is in an other app
BROWSING	8	User is browsing some page of forum, website…
OBSERVING	9	User is observing a game

Top

request.proto

Messages

Message

Network message

Message

Field	Type	Description
request_number	int32	id the underlying request
ping_request	PingRequest	777
async_auth_request	com.daysofwonder.async.AsyncAuthRequest	400
async_disconnect_request	com.daysofwonder.async.AsyncDisconnectRequest	401
game_created_request	com.daysofwonder.async.GameCreatedRequest	404
engage_game_with_friends_request	com.daysofwonder.async.EngageGameWithFriendsRequest	405
async_connected_request	com.daysofwonder.async.AsyncConnectedRequest	406
async_connection_error_request	com.daysofwonder.async.AsyncConnectionErrorRequest	407
ask_server_statistics_request	com.daysofwonder.async.AskServerStatisticsRequest	408
server_statistics_request	com.daysofwonder.async.ServerStatisticsRequest	409
async_unlink_device_request	com.daysofwonder.async.AsyncUnlinkDeviceRequest	412
async_device_unlinked_request	com.daysofwonder.async.AsyncDeviceUnlinkedRequest	413
action_required_request	com.daysofwonder.async.ActionRequiredRequest	500
commit_action_request	com.daysofwonder.async.CommitActionRequest	501
multicast_data_request	com.daysofwonder.async.MulticastDataRequest	502
client_data_request	com.daysofwonder.async.ClientDataRequest	503
player_timeout_request	com.daysofwonder.async.PlayerTimeoutRequest	504
error_request	com.daysofwonder.async.ErrorRequest	505
player_presence_update_request	com.daysofwonder.async.PlayerPresenceUpdateRequest	506
game_over_request	com.daysofwonder.async.GameOverRequest	507
game_outcome_request	com.daysofwonder.async.GameOutcomeRequest	508
player_idle_progress_request	com.daysofwonder.async.PlayerIdleProgressRequest	509
whats_new_pussycat_request	com.daysofwonder.async.WhatsNewPussycatRequest	511
game_status_report_request	com.daysofwonder.async.GameStatusReportRequest	512
game_forfeit_request	com.daysofwonder.async.GameForfeitRequest	513
game_forfeited_request	com.daysofwonder.async.GameForfeitedRequest	514
async_buddy_list_request	com.daysofwonder.async.AsyncBuddyListRequest	515
async_buddy_list_content_request	com.daysofwonder.async.AsyncBuddyListContentRequest	516
async_buddy_presence_partial_update_request	com.daysofwonder.async.AsyncBuddyPresencePartialUpdateRequest	517
async_buddy_management_request	com.daysofwonder.async.AsyncBuddyManagementRequest	518
async_buddy_added_request	com.daysofwonder.async.AsyncBuddyAddedRequest	519
async_buddy_removed_request	com.daysofwonder.async.AsyncBuddyRemovedRequest	520
game_outcome_confirmation_request	com.daysofwonder.async.GameOutcomeConfirmationRequest	522
action_commited_request	com.daysofwonder.async.ActionCommitedRequest	523
multicast_chat_request	com.daysofwonder.async.MulticastChatRequest	524
client_chat_request	com.daysofwonder.async.ClientChatRequest	525
client_chat_blocked_request	com.daysofwonder.async.ClientChatBlockedRequest	526
register_presence_request	com.daysofwonder.async.RegisterPresenceRequest	527
unregister_presence_request	com.daysofwonder.async.UnregisterPresenceRequest	528
game_aborted_request	com.daysofwonder.async.GameAbortedRequest	530
game_aborted_confirmation_request	com.daysofwonder.async.GameAbortedConfirmationRequest	531
subscribe_presence_request	com.daysofwonder.async.SubscribePresenceServiceRequest	532
unsubscribe_presence_request	com.daysofwonder.async.UnsubscribePresenceServiceRequest	533
switched_to_game_request	com.daysofwonder.async.SwitchedToGameRequest	534
get_chat_history_request	com.daysofwonder.async.GetChatHistoryRequest	535
client_chat_history_request	com.daysofwonder.async.ClientChatHistoryRequest	536
player_replaced_request	com.daysofwonder.async.PlayerReplacedRequest	537
leave_sync_game_request	com.daysofwonder.async.LeaveSyncGameRequest	538
resume_sync_game_request	com.daysofwonder.async.ResumeSyncGameRequest	539
answer_invitation_request	com.daysofwonder.async.AnswerInvitationRequest	540
invitation_answered_request	com.daysofwonder.async.InvitationAnsweredRequest	541
clock_paused_request	com.daysofwonder.async.ClockPausedRequest	543
clock_resumed_request	com.daysofwonder.async.ClockResumedRequest	545
get_clocks_request	com.daysofwonder.async.GetClocksRequest	546
clocks_status_request	com.daysofwonder.async.ClocksStatusRequest	547
async_ignore_list_request	com.daysofwonder.async.AsyncIgnoreListRequest	560
async_ignore_list_content_request	com.daysofwonder.async.AsyncIgnoreListContentRequest	561
async_ignore_management_request	com.daysofwonder.async.AsyncIgnoreManagementRequest	562
async_ignore_added_request	com.daysofwonder.async.AsyncIgnoreAddedRequest	563
async_ignore_removed_request	com.daysofwonder.async.AsyncIgnoreRemovedRequest	564
user_update_data_required_request	com.daysofwonder.async.UserDataUpdateRequiredRequest	565
update_user_data_request	com.daysofwonder.async.UpdateUserDataRequest	566
user_data_updated_request	com.daysofwonder.async.UserDataUpdatedRequest	567
game_state_updated_request	com.daysofwonder.async.GameStateUpdatedRequest	568
game_user_data_updated_request	com.daysofwonder.async.GameUserDataUpdatedRequest	569
interrupt_action_request	com.daysofwonder.async.InterruptActionRequest
action_interrupted_request	com.daysofwonder.async.ActionInterruptedRequest
interruption_over_request	com.daysofwonder.async.InterruptionOverRequest
interrupt_action_error_request	com.daysofwonder.async.InterruptActionErrorRequest
enter_lobby_request	com.daysofwonder.async.EnterLobbyRequest	600
lobby_entered_request	com.daysofwonder.async.LobbyEnteredRequest	601
exit_lobby_request	com.daysofwonder.async.ExitLobbyRequest	602
lobby_exited_request	com.daysofwonder.async.LobbyExitedRequest	603
lobby_player_list_request	com.daysofwonder.async.LobbyPlayerListRequest	604
ask_player_info_request	com.daysofwonder.async.AskPlayerInfoRequest	605
lobby_player_info_request	com.daysofwonder.async.LobbyPlayerInfoRequest	606
lobby_create_game_request	com.daysofwonder.async.LobbyCreateGameRequest	607
lobby_game_created_request	com.daysofwonder.async.LobbyGameCreatedRequest	608
lobby_game_list_request	com.daysofwonder.async.LobbyGameListRequest	609
lobby_join_game_request	com.daysofwonder.async.LobbyJoinGameRequest	610
lobby_new_player_request	com.daysofwonder.async.LobbyNewPlayerRequest	611
lobby_join_denied_request	com.daysofwonder.async.LobbyJoinDeniedRequest	612
lobby_leave_game_request	com.daysofwonder.async.LobbyLeaveGameRequest	613
lobby_player_left_game_request	com.daysofwonder.async.LobbyPlayerLeftGameRequest	614
lobby_start_game_request	com.daysofwonder.async.LobbyStartGameRequest	615
lobby_start_game_denied_request	com.daysofwonder.async.LobbyStartGameDeniedRequest	616
subscribe_to_observable_game_list_request	com.daysofwonder.async.SubscribeToObservableGameListRequest	620
subscribed_to_observable_game_list_request	com.daysofwonder.async.SubscribedToObservableGameListRequest	621
observable_game_list_request	com.daysofwonder.async.ObservableGameListRequest	622
ask_any_player_info_request	com.daysofwonder.async.AskAnyPlayerInfoRequest	630
player_info_request	com.daysofwonder.async.PlayerInfoRequest	631
start_observe_game_request	com.daysofwonder.async.StartObserveGameRequest	650
stop_observe_game_request	com.daysofwonder.async.StopObserveGameRequest	651
game_observed_request	com.daysofwonder.async.GameObservedRequest	652

Top

Packet

Packet

Field	Type	Description
id	int64	Unique client-filled identifier of the packet, returned by the server in the response if possible - it is recommended to used a monotonically incrementing integer
payload	Message	Embedded message

Top

PingRequest

Heartbeat request. Send this request regularly to the server, which will echo it back (default max heartbeat timeout is 15 seconds on the server-side). This allows the server to notice when a client is disconnected (and the reverse). This also allows to measure the round-trip time between the client and the server, and possibly alert the player if it is too large.

More information can be found in Heartbeat section.

• request_number: 777

• field_name: ping_request

PingRequest

Field	Type	Description
timestamp	int64	Timestamp at which the request has been sent

Top

push.proto

Messages

Device

A device token as given by the platform

Device

Field	Type	Description
token	bytes	Device Token

Top

DeviceType

A device token and its platform identifier

DeviceType

Field	Type	Description
token	bytes	Device Token
type	Devices.Type	Platform unique identifier

Top

Devices

Enums

Devices.Type

Type of device token

Devices.Type

Name	Number	Description
RESERVED	0	Do not use
IOS	1
GCM	2
IOS_SANDBOX	4	Development mode for IOS
STEAM	5
OSX	10
OSX_SANDBOX	11	Development mode for OSX
FCM	12

Top

Scalar Value Types

Standard protobuf types

.proto Type	Notes	C++ Type	C# Type	Java Type
double		double	double	double
float		float	float	float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	long
uint32	Uses variable-length encoding.	uint32	uint	int
uint64	Uses variable-length encoding.	uint64	ulong	long
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	long
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	uint	int
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	ulong	long
sfixed32	Always four bytes.	int32	int	int
sfixed64	Always eight bytes.	int64	long	long
bool		bool	bool	boolean
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	string	String
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	ByteString

Top