com.google.android.gms.games.multiplayer.realtime.RealTimeMultiplayer |
This interface is deprecated.
Use RealTimeMultiplayerClient
instead
Entry point for real-time multiplayer functionality.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
RealTimeMultiplayer.ReliableMessageSentCallback |
This interface is deprecated.
Use RealTimeMultiplayerClient.ReliableMessageSentCallback instead
|
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
int | REAL_TIME_MESSAGE_FAILED | Return value indicating immediate failure. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Create a real-time room for the current game.
| |||||||||||
Decline an invitation for a real-time room.
| |||||||||||
Dismiss an invitation to a real-time room.
| |||||||||||
Returns an intent that will let the user select opponents to send an invitation to for a
real-time multiplayer match.
| |||||||||||
Returns an intent that will let the user select opponents to send an invitation to for a
real-time multiplayer match.
| |||||||||||
Returns an intent that will display a "waiting room" screen that shows the progress of
participants joining a real-time multiplayer room.
| |||||||||||
Join a real-time room by accepting an invitation.
| |||||||||||
Leave the specified room.
| |||||||||||
Send a message to a participant in a real-time room reliably.
| |||||||||||
Send a message to a participant in a real-time room.
| |||||||||||
Send a message to one or more participants in a real-time room.
| |||||||||||
Send a message to all participants in a real-time room, excluding the current player.
|
Return value indicating immediate failure. Returned by sendReliableMessage(GoogleApiClient, RealTimeMultiplayer.ReliableMessageSentCallback, byte[], String, String)
, sendUnreliableMessage(GoogleApiClient, byte[], String, String)
or sendUnreliableMessageToOthers(GoogleApiClient, byte[], String)
methods when the message send
operation failed due to an error.
Create a real-time room for the current game. The lifetime of the current game's connection
to the room is bound to this GoogleApiClient
's lifecycle. When the client
disconnects, the player will leave the room and any peer-to-peer connections for this player
will be torn down. The result is delivered by the callback
onRoomCreated(int, Room)
to the given RoomUpdateListener in the
RoomConfig
. The listener is called on the main thread.
leave(GoogleApiClient, RoomUpdateListener, String)
when the caller is done
with it.
Required API: API
Required Scopes: SCOPE_GAMES
Parameters | |
---|---|
apiClient |
GoogleApiClient : The GoogleApiClient to service the call. |
config |
RoomConfig : The real-time room configuration.
|
Decline an invitation for a real-time room.
Required API: API
Required Scopes: SCOPE_GAMES
Parameters | |
---|---|
apiClient |
GoogleApiClient : The GoogleApiClient to service the call. |
invitationId |
String : The ID of the invitation to decline.
|
Dismiss an invitation to a real-time room. Dismissing an invitation will not change the state of the room for the other participants.
Required API: API
Required Scopes: SCOPE_GAMES
Parameters | |
---|---|
apiClient |
GoogleApiClient : The GoogleApiClient to service the call. |
invitationId |
String : The ID of the invitation to dismiss.
|
Returns 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 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 API: API
Required Scopes: SCOPE_GAMES
See create(GoogleApiClient, RoomConfig)
Parameters | |
---|---|
apiClient |
GoogleApiClient : The GoogleApiClient to service the call. |
minPlayers |
int : The minimum number of players to select (not including the current player). |
maxPlayers |
int : The maximum number of players to select (not including the current player). |
allowAutomatch |
boolean : Whether or not to display an option for selecting automatch players. |
Returns | |
---|---|
Intent |
An Intent that can be started to display the player selector.
|
Returns 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 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(GoogleApiClient, int, int, boolean)
with the allowAutomatch
parameter set to true
.
Required API: API
Required Scopes: SCOPE_GAMES
See create(GoogleApiClient, RoomConfig)
Parameters | |
---|---|
apiClient |
GoogleApiClient : The GoogleApiClient to service the call. |
minPlayers |
int : The minimum number of players to select (not including the current player). |
maxPlayers |
int : The maximum number of players to select (not including the current player). |
Returns | |
---|---|
Intent |
An Intent that can be started to display the player selector.
|
Returns 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.
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 API: API
Required Scopes: SCOPE_GAMES
See create(GoogleApiClient, RoomConfig)
, leave(GoogleApiClient, RoomUpdateListener, String)
Parameters | |
---|---|
apiClient |
GoogleApiClient : The GoogleApiClient to service the call. |
room |
Room : The Room object to be displayed. |
minParticipantsToStart |
int : 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. |
Returns | |
---|---|
Intent |
An Intent that can be started to display the waiting room screen.
|
Join a real-time room by accepting an invitation. The lifetime of the current game's
connection to the room is bound to this GoogleApiClient
's lifecycle. When the client
disconnects, the player will leave the room and any peer-to-peer connections for this player
will be torn down. The result is delivered by the callback
onJoinedRoom(int, Room)
to the given RoomUpdateListener in the
RoomConfig
. The listener is called on the main thread.
leave(GoogleApiClient, RoomUpdateListener, String)
when the caller is done
with it.
Required API: API
Required Scopes: SCOPE_GAMES
Parameters | |
---|---|
apiClient |
GoogleApiClient : The GoogleApiClient to service the call. |
config |
RoomConfig : The real-time room configuration.
|
Leave 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)
to the given listener 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 onLeftRoom(int, String)
is received.
Required API: API
Required Scopes: SCOPE_GAMES
Parameters | |
---|---|
apiClient |
GoogleApiClient : The GoogleApiClient to service the call. |
listener |
RoomUpdateListener : The listener that is notified after the room has been left. The listener is
called on the main thread. |
roomId |
String : ID of the room to leave.
|
Send a message to a participant in a real-time room reliably. The caller will receive a
callback to report the status of the send message operation. Throws an IllegalArgumentException
if recipientParticipantId is not a valid participant or belongs to
the current player. The maximum message size supported is MAX_RELIABLE_MESSAGE_LEN
bytes.
Required API: API
Required Scopes: SCOPE_GAMES
Parameters | |
---|---|
apiClient |
GoogleApiClient : The GoogleApiClient to service the call. |
listener |
RealTimeMultiplayer.ReliableMessageSentCallback : The listener that is notified when the message has been sent. |
messageData |
byte : The message to be sent. Should be at most MAX_RELIABLE_MESSAGE_LEN bytes. |
roomId |
String : ID of the room for which the message is being sent. |
recipientParticipantId |
String : The participant ID to send the message to. |
Returns | |
---|---|
int |
The token for the message sent, which is returned in callback onRealTimeMessageSent(int, int, String) , or REAL_TIME_MESSAGE_FAILED if
the message failed to send.
|
Send a message to a participant in a real-time room. The message delivery is not reliable and
will not report status after completion. Throws an IllegalArgumentException
if
recipientParticipantId is not a valid participant or belongs to the current player. The maximum
message size supported is MAX_UNRELIABLE_MESSAGE_LEN
bytes.
Required API: API
Required Scopes: SCOPE_GAMES
Parameters | |
---|---|
apiClient |
GoogleApiClient : The GoogleApiClient to service the call. |
messageData |
byte : The message to be sent. Should be at most MAX_UNRELIABLE_MESSAGE_LEN bytes. |
roomId |
String : ID of the room for which the message is being sent. |
recipientParticipantId |
String : The participant ID to send the message to. |
Returns | |
---|---|
int |
STATUS_OK on a successful
attempt, REAL_TIME_MESSAGE_FAILED if the message failed to send.
|
Send a message to one or more participants in a real-time room. The message delivery is not
reliable and will not report status after completion. Throws an IllegalArgumentException
if any participants in recipientParticipantIds are not valid or
belong to the current player. The maximum message size supported is MAX_UNRELIABLE_MESSAGE_LEN
bytes.
Required API: API
Required Scopes: SCOPE_GAMES
Parameters | |
---|---|
apiClient |
GoogleApiClient : The GoogleApiClient to service the call. |
messageData |
byte : The message to be sent. Should be at most MAX_UNRELIABLE_MESSAGE_LEN bytes. |
roomId |
String : ID of the room for which the message is being sent. |
recipientParticipantIds |
List : One or more participant IDs to send the message to. |
Returns | |
---|---|
int |
STATUS_OK on a successful
attempt, REAL_TIME_MESSAGE_FAILED if the message failed to send.
|
Send a message 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 maximum
message size supported is MAX_UNRELIABLE_MESSAGE_LEN
bytes.
Required API: API
Required Scopes: SCOPE_GAMES
Parameters | |
---|---|
apiClient |
GoogleApiClient : The GoogleApiClient to service the call. |
messageData |
byte : The message to be sent. Should be at most MAX_UNRELIABLE_MESSAGE_LEN bytes. |
roomId |
String : ID of the room for which the message is being sent. |
Returns | |
---|---|
int |
STATUS_OK on a successful
attempt, REAL_TIME_MESSAGE_FAILED if the message failed to send.
|