This class is deprecated.
Real-time multiplayer and Turn-based multiplayer support is being shut down on March 31,
2020. See Multiplayer
deprecation
A client to interact with real time multiplayer functionality.
Nested Class Summary
interface | RealTimeMultiplayerClient.ReliableMessageSentCallback | Callback used when the sending of a reliable message has completed. |
Inherited Field Summary
Public Method Summary
Task<Void> |
create(RoomConfig
config)
Returns a
Task
which asynchronously creates a real-time room for the current game.
|
Task<Void> |
declineInvitation(String
invitationId)
Returns a
Task
which asynchronously declines an invitation for a real-time room.
|
Task<Void> |
dismissInvitation(String
invitationId)
Returns a
Task
which asynchronously dismisses an invitation to a real-time room.
|
Task<Intent> |
getSelectOpponentsIntent(int minPlayers, int maxPlayers)
|
Task<Intent> |
getSelectOpponentsIntent(int minPlayers, int maxPlayers, boolean
allowAutomatch)
|
Task<Intent> |
getWaitingRoomIntent(Room
room, int minParticipantsToStart)
|
Task<Void> |
join(RoomConfig
config)
Returns a
Task
which asynchronously joins a real-time room by accepting an invitation.
|
Task<Void> |
leave(RoomConfig
config, String roomId)
Returns a
Task
which asynchronously leaves the specified room.
|
Task<Integer> |
sendReliableMessage(byte[] messageData, String roomId,
String
recipientParticipantId,
RealTimeMultiplayerClient.ReliableMessageSentCallback callback)
Returns a
Task
which asynchronously starts the message send operation to a participant in a
real-time room reliably.
|
Task<Void> |
sendUnreliableMessage(byte[] messageData, String roomId,
String
recipientParticipantId)
Returns a
Task
which asynchronously starts the message send operation to a participant in a
real-time room.
|
Task<Void> |
sendUnreliableMessage(byte[] messageData, String roomId,
List<String>
recipientParticipantIds)
Returns a
Task
which asynchronously starts the message send operation to one or more
participants in a real-time room.
|
Task<Void> |
sendUnreliableMessageToOthers(byte[] messageData, String roomId)
Returns a
Task
which asynchronously starts the message send operation to all participants in a
real-time room, excluding the current player.
|
Inherited Method Summary
Public Methods
public Task<Void> create (RoomConfig config)
Returns a Task
which
asynchronously creates a real-time room for the current game. The result is delivered
by the callback
onRoomCreated(int, Room)
in the RoomConfig
.
The callback is called on the main thread.
The room created by this API is a resource that needs to be released by
leave(RoomConfig, String)
when the caller is done with it.
Required Scopes: SCOPE_GAMES_LITE
Parameters
config | The real-time room configuration. |
---|
public Task<Void> declineInvitation (String invitationId)
Returns a Task
which
asynchronously declines an invitation for a real-time room.
Required Scopes: SCOPE_GAMES_LITE
Parameters
invitationId | The ID of the invitation to decline. |
---|
public Task<Void> dismissInvitation (String invitationId)
Returns a Task
which
asynchronously dismisses an invitation to a real-time room. Dismissing an invitation
will not change the state of the room for the other participants.
Required Scopes: SCOPE_GAMES_LITE
Parameters
invitationId | The ID of the invitation to dismiss. |
---|
public Task<Intent> getSelectOpponentsIntent (int minPlayers, int maxPlayers)
Returns a Task
which
asynchronously loads an Intent
that
will let the user select opponents to send an invitation to for a real-time multiplayer
match. Note that this must be invoked with
startActivityForResult(Intent, int)
, so that the identity of the calling
package can be established.
The returned Task
can fail
with a RemoteException
.
The number of players passed in should be the desired number of additional players
to select, not including the current player. So, for a game that can handle between 2
and 4 players, minPlayers
would be 1 and maxPlayers
would be
3.
Players may be preselected by specifying a list of player IDs in the EXTRA_PLAYER_IDS
extra on the returned intent.
If the user canceled, the result will be RESULT_CANCELED
.
If the user selected players, the result will be RESULT_OK
,
and the data intent will contain the selected player IDs in EXTRA_PLAYER_IDS
and the minimum and maximum numbers of additional auto-match players in
EXTRA_MIN_AUTOMATCH_PLAYERS
and
EXTRA_MAX_AUTOMATCH_PLAYERS
respectively. The player IDs in EXTRA_PLAYER_IDS
will include only the other players selected, not the current player.
This method is the equivalent of calling
getSelectOpponentsIntent(int, int, boolean)
with the
allowAutomatch
parameter set to true
.
Required Scopes: SCOPE_GAMES_LITE
Parameters
minPlayers | The minimum number of players to select (not including the current player). |
---|---|
maxPlayers | The maximum number of players to select (not including the current player). See
create(RoomConfig) |
public Task<Intent> getSelectOpponentsIntent (int minPlayers, int maxPlayers, boolean allowAutomatch)
Returns a Task
which
asynchronously loads an Intent
that
will let the user select opponents to send an invitation to for a real-time multiplayer
match. Note that this must be invoked with
startActivityForResult(Intent, int)
, so that the identity of the calling
package can be established.
The returned Task
can fail
with a RemoteException
.
The number of players passed in should be the desired number of additional players
to select, not including the current player. So, for a game that can handle between 2
and 4 players, minPlayers
would be 1 and maxPlayers
would be
3.
Players may be preselected by specifying a list of player IDs in the EXTRA_PLAYER_IDS
extra on the returned intent.
If the user canceled, the result will be RESULT_CANCELED
.
If the user selected players, the result will be RESULT_OK
,
and the data intent will contain the selected player IDs in EXTRA_PLAYER_IDS
and the minimum and maximum numbers of additional auto-match players in
EXTRA_MIN_AUTOMATCH_PLAYERS
and
EXTRA_MAX_AUTOMATCH_PLAYERS
respectively. The player IDs in EXTRA_PLAYER_IDS
will include only the other players selected, not the current player.
If the allowAutomatch
parameter is set to false
, the UI
will not display an option for selecting automatch players. Set this to
false
if your game does not support automatching.
Required Scopes: SCOPE_GAMES_LITE
Parameters
minPlayers | The minimum number of players to select (not including the current player). |
---|---|
maxPlayers | The maximum number of players to select (not including the current player). |
allowAutomatch | Whether or not to display an option for selecting automatch players. See
create(RoomConfig) |
public Task<Intent> getWaitingRoomIntent (Room room, int minParticipantsToStart)
Returns a Task
which
asynchronously loads an Intent
that
will display a "waiting room" screen that shows the progress of participants joining a
real-time multiplayer room. Note that this must be invoked with
startActivityForResult(Intent, int)
, so that the identity of the calling
package can be established.
The returned Task
can fail
with a RemoteException
.
If the necessary number of peers have connected and it's now OK to start the game,
or if the user explicitly asked to start the game now, the activity result will be
RESULT_OK
.
If the user bailed out of the waiting room screen without taking any action, the result
will be RESULT_CANCELED
.
If the user explicitly chose to leave the room, the result will be
RESULT_LEFT_ROOM
. If the room no longer exists or is otherwise invalid the
result will be
RESULT_INVALID_ROOM
.
Regardless of what the result code was, the waiting room activity will return a data
intent containing a Room
object in
EXTRA_ROOM
that represents the current state of the Room that you originally
passed as a parameter here. Note that the returned room may be null if the room no
longer exists.
If desired, the waiting room can allow the user to start playing the game even
before the room is fully connected. This is controlled by the
minParticipantsToStart
parameter: if at least that many participants
(including the current player) are connected to the room, a "Start playing" menu item
will become enabled in the waiting room UI. Setting minParticipantsToStart
to 0 means that "Start playing" will always be available, and a value of MAX_VALUE
will disable the item completely. Note: if you do allow the user to start early, you'll
need to handle that situation by explicitly telling the other connected peers that the
game is now starting; see the developer documentation for more details.
Finally, note that the waiting room itself will never explicitly take any action to
change the state of the room or its participants. So if the activity result is
RESULT_LEFT_ROOM
, it's the caller's responsibility to actually leave the
room. Or if the result is RESULT_CANCELED
,
it's the responsibility of the caller to double-check the current state of the Room and
decide whether to start the game, keep waiting, or do something else. But note that
while the waiting room is active, the state of the Room will change as
participants accept or decline invitations, and the number of participants may even
change as auto-match players get added.
Required Scopes: SCOPE_GAMES_LITE
Parameters
room | The Room
object to be displayed. |
---|---|
minParticipantsToStart | the minimum number of participants that must be connected to the room (including the current player) for the "Start playing" menu item to become enabled. |
public Task<Void> join (RoomConfig config)
Returns a Task
which
asynchronously joins a real-time room by accepting an invitation. The result is
delivered by the callback
onJoinedRoom(int, Room)
in the RoomConfig
.
The callback is called on the main thread.
The room created by this API is a resource that needs to be released by
leave(RoomConfig, String)
when the caller is done with it.
Required Scopes: SCOPE_GAMES_LITE
Parameters
config | The real-time room configuration. |
---|
public Task<Void> leave (RoomConfig config, String roomId)
Returns a Task
which
asynchronously leaves the specified room. This will disconnect the player from the
room, but allow other players to continue playing the game. The result is delivered by
the callback
onLeftRoom(int, String)
in the RoomConfig
.
The callback is called on the main thread.
After this method is called, you cannot perform any further actions on the room. You
can create or join another room only after this Task
is
complete.
Required Scopes: SCOPE_GAMES_LITE
Parameters
config | The real-time room configuration. |
---|---|
roomId | ID of the room to leave. |
public Task<Integer> sendReliableMessage (byte[] messageData, String roomId, String recipientParticipantId, RealTimeMultiplayerClient.ReliableMessageSentCallback callback)
Returns a Task
which
asynchronously starts the message send operation to a participant in a real-time room
reliably. A successful Task
will return
the message token generated for the pending message, and the caller will receive a
RealTimeMultiplayerClient.ReliableMessageSentCallback
callback to report the
status of the send message operation.
If the Task
fails, the
callback will not be called.
The returned Task
will fail
with an IllegalArgumentException
if recipientParticipantId
is not a valid participant or belongs to the
current player, or with an ApiException
with
REAL_TIME_MESSAGE_SEND_FAILED
status code if an error occurs before
generating a message token.
The maximum message size supported is
MAX_RELIABLE_MESSAGE_LEN
bytes.
Required Scopes: SCOPE_GAMES_LITE
Parameters
messageData | The message to be sent. Should be at most
MAX_RELIABLE_MESSAGE_LEN bytes. |
---|---|
roomId | ID of the room for which the message is being sent. |
recipientParticipantId | The participant ID to send the message to. |
callback | The callback that is notified when the message has been sent. |
public Task<Void> sendUnreliableMessage (byte[] messageData, String roomId, String recipientParticipantId)
Returns a Task
which
asynchronously starts the message send operation to a participant in a real-time room.
The message delivery is not reliable and will not report status after completion.
The returned Task
will fail
with an IllegalArgumentException
if recipientParticipantId
is not a valid participant or belongs to the
current player, or with an ApiException
with
REAL_TIME_MESSAGE_SEND_FAILED
status code if the message size exceeds the
MAX_UNRELIABLE_MESSAGE_LEN
.
The message is not sent if the Task
is
failed.
The maximum message size supported is
MAX_UNRELIABLE_MESSAGE_LEN
bytes.
Required Scopes: SCOPE_GAMES_LITE
Parameters
messageData | The message to be sent. Should be at most
MAX_UNRELIABLE_MESSAGE_LEN bytes. |
---|---|
roomId | ID of the room for which the message is being sent. |
recipientParticipantId | The participant ID to send the message to. |
public Task<Void> sendUnreliableMessage (byte[] messageData, String roomId, List<String> recipientParticipantIds)
Returns a Task
which
asynchronously starts the message send operation to one or more participants in a
real-time room. The message delivery is not reliable and will not report status after
completion.
The returned Task
will fail
with an IllegalArgumentException
if any participants in recipientParticipantIds are not valid or belong to the current
player, or with an ApiException
with
REAL_TIME_MESSAGE_SEND_FAILED
status code if the message size exceeds the
MAX_UNRELIABLE_MESSAGE_LEN
.
The message is not sent if the Task
is
failed.
The maximum message size supported is
MAX_UNRELIABLE_MESSAGE_LEN
bytes.
Required Scopes: SCOPE_GAMES_LITE
Parameters
messageData | The message to be sent. Should be at most
MAX_UNRELIABLE_MESSAGE_LEN bytes. |
---|---|
roomId | ID of the room for which the message is being sent. |
recipientParticipantIds | One or more participant IDs to send the message to. |
public Task<Void> sendUnreliableMessageToOthers (byte[] messageData, String roomId)
Returns a Task
which
asynchronously starts the message send operation to all participants in a real-time
room, excluding the current player. The message delivery is not reliable and will not
report status after completion.
The returned Task
will fail
with an ApiException
with
REAL_TIME_MESSAGE_SEND_FAILED
status code if the message size exceeds the
MAX_UNRELIABLE_MESSAGE_LEN
.
The message is not sent if the Task
is
failed.
The maximum message size supported is
MAX_UNRELIABLE_MESSAGE_LEN
bytes.
Required Scopes: SCOPE_GAMES_LITE
Parameters
messageData | The message to be sent. Should be at most
MAX_UNRELIABLE_MESSAGE_LEN bytes. |
---|---|
roomId | ID of the room for which the message is being sent. |